Skip to main content
The Unblocked API is currently in beta and subject to breaking changes
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 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.
1

Create the API Token

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

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.Personal Token[]
3

Copy the API Token

Copy the resulting API token.Personal 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 (Preview)

The Answers API (currently in Preview) 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 only available to customers on the Enterprise plan. Contact sales at [email protected] or through Intercom to upgrade your plan.
The Answers API is in Preview and is subject to breaking changes, and is currently limited to 100 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"
      }
    ]
  }
}