Ingestion API Quick Connect Guide

ADMIN PRIVILEGES REQUIRED

Overview

Use this guide to quickly connect to the Stack Internal Ingestion API and add sample plain-text content.

In broad strokes, to use the Ingestion API you will:

1. Register a custom source.
2. Create an OAuth application and access token.
3. Create a request data file with all required API fields and sample source text.
4. Send the data file to the API with the access token.

Before you begin

Several steps in this process require you to create, copy, and paste long text strings. We suggest having an empty text file or working document available. As you paste values to this document, label them clearly to avoid confusion.

Connect and configure

1. Connect a custom source.
   Follow the steps in Connect a custom source, and save the source ID you enter there.

   More info: A custom source is the source record that identifies content your organization sends through the Ingestion API. Its source ID connects every API request to that source in your Stack Internal workspace. The source ID can contain lowercase letters, numbers, and hyphens.

2. Create an OAuth application.
   Follow the API Applications guide through the "Save the application" section to create an OAuth application with the content:ingest scope. You do not need to follow the "Use the OAuth application" section.

   More info: An OAuth application identifies the integration. The user who authorizes the app must be active in the workspace where you registered the custom source.

3. Get an access token.
   Follow steps 1 through 5 in the Stack Internal API Quick Connect Guide.

   More info: The access token is linked to the OAuth application you created above. You'll supply this access token in the Authorization header for each API request. The token expires after five minutes.

Prepare a request file

1. Using the template below, create a file named ingestion-request.json.
2. Replace [API SOURCE ID] with the source ID from the custom source you registered (remove the brackets).

Request file template

{
  "source": "[API SOURCE ID]",
  "sourceId": "quick-connect-sample-001",
  "sourceUri": "urn:stackinternal:quick-connect:sample-text",
  "acls": [
    {
      "kind": "anyone",
      "provider": "stackinternal",
      "identifier": "public"
    }
  ],
  "entityType": "text-file",
  "data": {
    "representation": "archetype",
    "representationVersion": 1,
    "archetype": "document",
    "dataSchema": "com.stackoverflow.stackinternal.content.archetype.document.v1",
    "data": {
      "title": "Sample Text",
      "textContent": "This is sample content to test the Stack Internal Ingestion API.",
      "documentType": "text_file",
      "personaRefs": [],
      "sourceUri": "urn:stackinternal:quick-connect:sample-text",
      "mimeType": "text/plain",
      "language": "en",
      "sourceVersion": "1"
    }
  }
}

Send the request

1. Based on your computer's operating system, copy the appropriate curl command below and paste it into a text editor.
2. Replace [ACCESS TOKEN] with the access token you created in the API Quick Connect Guide (remove the brackets).
3. Open a terminal window.
4. Navigate to the folder that contains the ingestion-request.json file.
5. Run the curl command.

API curl command

macOS or Linux terminal

curl --include --request POST "https://api.stackinternal.com/v1/content" --header "Authorization: Bearer [ACCESS TOKEN]" --header "Content-Type: application/json" --data @ingestion-request.json

Windows PowerShell

curl.exe --include --request POST "https://api.stackinternal.com/v1/content" --header "Authorization: Bearer [ACCESS TOKEN]" --header "Content-Type: application/json" --data @ingestion-request.json

Confirm the result

If the call is successful, the API will return 201 Created and a unique contentId for the new content.

Notes

• The combination of source + sourceId must be unique for every piece of content you add with the Ingestion API. If you walk through this process again, change (or increment) the sourceId.
• This example intends one-time token use. Use the token only in a private terminal, do not save or share the command, and get a new token if it is somehow exposed outside this process.

Troubleshooting

If the API call doesn't return 201 Created, use the following values to troubleshoot.

Response	Troubleshooting steps
401 Unauthorized	Follow Step 5 of the Stack Internal API Quick Connect Guide to create a new access token, then send it in the Authorization header.
402 Payment Required	Usage credits may be exhausted.
403 Forbidden	Confirm that the OAuth application has the content:ingest scope, and that the authorizing user can access the workspace.
400 Bad Request	Confirm that source is the registered custom source ID, sourceUri is an absolute URI, and the JSON file format has not changed.
409 Conflict	An item with the same source and sourceId already exists. Change sourceId to make it unique.

For complete request fields and instructions for other API calls (for example: update, delete), see the Ingestion API reference at https://api.stackinternal.com/apis/v1/content.

Future implementation

This example cuts a few corners to get you connected to the Ingestion API quickly. Be aware of the following issues before you use the Ingestion API in a real workflow.

• sourceUri in this example is a placeholder. When you send actual data, supply an absolute URI to the resource. This could be an internet URL, local file path, or other stable source location.
• This example uses a public acls (access control list) entry. When you add private content, replace the acls values with the users, groups, or domain that should have access to the data.
• This example sends a single line of text. When sending actual content, you'll need to escape line breaks (\n), quotes ("), and backslashes (\) to avoid breaking the JSON format.

Get help

If you have questions or issues, reach out to our support team for help.