> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getunblocked.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Tabs>
  <Tab title="Personal Access Token">
    Personal Access Tokens are scoped to your individual account and are ideal for personal automation, testing, and development workflows.

    <Note>
      Personal Access Tokens have a limit of **1,000 API calls per day**.
    </Note>

    <Steps>
      <Step title="Create the API Token">
        In the [Unblocked web app](/using-unblocked/on-the-web), click on **Settings** --> **API Tokens**.

        In the **Personal API Tokens** section, click on **Create Token**.

        <img src="https://mintcdn.com/unblocked/GOUKpQ80cNM-eQYm/img/personal-token-1.png?fit=max&auto=format&n=GOUKpQ80cNM-eQYm&q=85&s=2f8370f6a500750697cebbc6cc13a5ff" alt="Personal Token[]" width="2880" height="1820" data-path="img/personal-token-1.png" />
      </Step>

      <Step title="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**.

        <img src="https://mintcdn.com/unblocked/GOUKpQ80cNM-eQYm/img/personal-token-2.png?fit=max&auto=format&n=GOUKpQ80cNM-eQYm&q=85&s=ccaead6818c7c04278e9285082a76b3d" alt="Personal Token[]" width="2880" height="1820" data-path="img/personal-token-2.png" />
      </Step>

      <Step title="Copy the API Token">
        Copy the resulting API token.

        <img src="https://mintcdn.com/unblocked/GOUKpQ80cNM-eQYm/img/personal-token-3.png?fit=max&auto=format&n=GOUKpQ80cNM-eQYm&q=85&s=8ae7b033588bccf513409ad3f6254c6d" alt="Personal Token[]" width="2880" height="1820" data-path="img/personal-token-3.png" />
      </Step>
    </Steps>
  </Tab>

  <Tab title="Team Access Token">
    <Warning>
      Team Access Tokens grant access to all documents in your team's data sources. Use them carefully and rotate them regularly to maintain security.
    </Warning>

    <Steps>
      <Step title="Create the API Token">
        In the [Unblocked web app](/using-unblocked/on-the-web), click on **Settings** --> **API Tokens**.

        In the **Team API Tokens** section, click on **Create Token**.

        <img src="https://mintcdn.com/unblocked/UPT9O22gsEWNRiDD/img/team-token-1.png?fit=max&auto=format&n=UPT9O22gsEWNRiDD&q=85&s=6750d421f417fadac3731603312fc871" alt="Team Token[]" width="2880" height="1820" data-path="img/team-token-1.png" />
      </Step>

      <Step title="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**.

        <img src="https://mintcdn.com/unblocked/WrAe_ZzBHh_yDkhV/img/team-token-2.png?fit=max&auto=format&n=WrAe_ZzBHh_yDkhV&q=85&s=b67bd2f1736f215edc53401852eba6e8" alt="Team Token[]" width="2880" height="1820" data-path="img/team-token-2.png" />
      </Step>

      <Step title="Copy the API Token">
        Copy the resulting API token.

        <img src="https://mintcdn.com/unblocked/WrAe_ZzBHh_yDkhV/img/team-token-3.png?fit=max&auto=format&n=WrAe_ZzBHh_yDkhV&q=85&s=8553ab50e62f41cc68f7d0b6ab9d59d5" alt="Team Token[]" width="2880" height="1820" data-path="img/team-token-3.png" />
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

## 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.

```bash theme={null}
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.

```json theme={null}
{
  "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.

```bash theme={null}
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.

<Note>
  The Answers API is currently limited to 1000 questions per day per organization.
</Note>

### Submit a Question

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

```bash theme={null}
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:

```bash theme={null}
curl --request GET \
  --url https://getunblocked.com/api/v1/answers/12345678-abcd-123456789-123456789abc \
  --header 'Authorization: Bearer <token>'
```

While processing, the API returns:

```json theme={null}
{
  "state": "processing"
}
```

Once complete, the API returns the answer with references:

```json theme={null}
{
  "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"
      }
    ]
  }
}
```