Quickstart for the Unblocked API

The Unblocked API is a REST API that allows you to add documents to Unblocked and ask questions about your codebase programmatically.

Create an API Token

Unblocked supports two types of API tokens for authentication:

Personal Access Token
Team Access Token

Personal Access Tokens are scoped to your individual account and are ideal for personal automation, testing, and development workflows.

Personal Access Tokens have a limit of 1,000 API calls per day.

Create the API Token

In the Unblocked web app, click on Settings —> API Tokens.In the Personal API Tokens section, click on Create Token.

Configure the API Token

Fill out the token name. You can also limit the data sources that the token will have access to in the list under Data Sources.

Copy the API Token

Copy the resulting API token.

All tokens should be provided with each request to the Unblocked API using the Authorization: Bearer <token> header to authenticate the request.

Create a Collection

Next, create a collection. A collection in Unblocked is a group of related documents from various data sources, such as customer support tools, knowledge bases, and internal wikis. Multiple collections can be created to manage documents from different sources.

curl --request POST \
  --url https://getunblocked.com/api/v1/collections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Apollo",
  "description": "Documents from the Apollo customer support tool including support responses.",
  "iconUrl": "https://my.company.com/apollo/logo.svg"
}'

The Unblocked API will respond with the newly created collection along with an ID. This ID uniquely identifies the collection, and will be used for adding documents to Unblocked.

{
  "id": "12345678-abcd-123456789-123456789abc",
  "name": "Apollo",
  "description": "Documents from the Apollo customer support tool including support responses.",
  "iconUrl": "https://my.company.com/apollo/logo.svg"
}

Collections can also be created in the Unblocked web app. Once you’ve signed in, click Data Sources in the sidebar, and then the Add Data Sources section. Scroll to the documentation section and select Create a Custom Source.

Add a Document

Finally, add a document to the collection using the collection’s ID. In addition to the collection ID, provide a title, a body (in plain text or Markdown), and a URI for the document. A document is uniquely identified by its URI. The URI will be used to link to the source of a reference in an answer.

curl --request PUT \
  --url https://getunblocked.com/api/v1/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "collectionId": "12345678-abcd-123456789-123456789abc",
  "title": "Password Reset Guide",
  "body": "To reset your password, visit ...",
  "uri": "https://my.company.com/apollo/ticket/123456"
}'

Get Answers

The Answers API allows you to programmatically ask questions about your codebase and receive answers from Unblocked. The API uses an asynchronous pattern where you submit a question and then poll for the response. Responses are in Markdown format.

The Answers API is currently limited to 1000 questions per day per organization.

Submit a Question

First, submit your question using a unique questionId (must be a globally unique UUID):

curl --request PUT \
  --url https://getunblocked.com/api/v1/answers/12345678-abcd-123456789-123456789abc \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "question": "How does the user authentication system work?"
}'

The API will respond with a 204 No Content status, indicating the question has been queued for processing.

Poll for the Answer

Use the same questionId to poll for the answer:

curl --request GET \
  --url https://getunblocked.com/api/v1/answers/12345678-abcd-123456789-123456789abc \
  --header 'Authorization: Bearer <token>'

While processing, the API returns:

{
  "state": "processing"
}

Once complete, the API returns the answer with references:

{
  "state": "complete",
  "result": {
    "answer": "The user authentication system uses JWT tokens... ",
    "references": [
      {
        "htmlUrl": "https://github.com/yourorg/yourrepo/blob/main/src/auth/login.js#L42"
      }
    ]
  }
}

​Create an API Token

​Create a Collection

​Add a Document

​Get Answers

​Submit a Question

​Poll for the Answer

Create an API Token

Create a Collection

Add a Document

Get Answers

Submit a Question

Poll for the Answer