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

# Introduction

> Fundamental concepts of Cradl’s API.

> **Note**\
> You can access our API directly from the Cradl AI App without any additional credentials—just sign up to get started.

## Base URL

Cradl’s API follows REST principles and is served over HTTPS. For security, unencrypted HTTP is not supported.

All API endpoints use the following base URL:

```
https://api.cradl.ai/v1
```

## Authentication

To authenticate with Cradl’s API, use the `Authorization` header with a **Bearer token**. You can obtain an access token by making the following request:

```bash theme={null}
curl -X POST https://auth.cradl.ai/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&audience=https://api.cradl.ai/v1&client_id=<YOUR CLIENT ID>&client_secret=<YOUR SECRET>'
```

The response will include an access token:

```json theme={null}
{
  "access_token": "<YOUR-ACCESS-TOKEN>",
  ...
}
```

Use this token in **all subsequent API requests**:

```http theme={null}
Authorization: Bearer <YOUR-ACCESS-TOKEN>
```

***

## Creating a Run

<Steps>
  <Step title="Find your agent">
    You can find your agent ID in the Cradl AI UI. It will always be on the form \`cradl:agent:xxx'. Alternatively, you can list your agents using the API:

    ```bash theme={null}
    curl -X GET https://api.cradl.ai/v1/agents \
      -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>"
    ```

    Example response:

    ```json theme={null}
    {
      "agents": [
        {
          "agentId": "<YOUR-AGENT-ID>",
          ...
        }
      ],
      "nextToken": null
    }
    ```
  </Step>

  <Step title="Create a new run">
    Once you have the agent ID on the form \`cradl:agent:xxx', create a run:

    ```bash theme={null}
    curl -X POST https://api.cradl.ai/v1/agents/<YOUR-AGENT-ID>/runs \
      -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    <Tip>
      **Add variables:** Variables are additional information you can send with a run. They do not affect predictions and are returned with the rest of the agent’s output.

      Let's say you want to add some internal document Id and a customer Id for the document, just replace `-d '{}'` in the request above with:

      ```json theme={null}
        -d '{"variables": {"docId": "ABC", "customerId": "123" }}'
      ```
    </Tip>

    Example response:

    ```json theme={null}
    {
      "id": "<YOUR-ORG-ID>/<YOUR-AGENT-ID>/<YOUR-RUN-ID>",
      ...
    }
    ```
  </Step>

  <Step title="Create and upload a document">
    Create a document and associate it with your run:

    ```bash theme={null}
    curl -X POST https://api.cradl.ai/v1/documents \
      -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "My invoice",
        "agentRunId": "<YOUR-ORG-ID>/<YOUR-AGENT-ID>/<YOUR-RUN-ID>"
      }'
    ```

    This response includes a `fileUrl` on the form [https://files.api.cradl.ai/las:file:xxx](https://files.api.cradl.ai/las:file:xxx) that you’ll use to upload your document file:

    ```bash theme={null}
    curl -X PUT --data-binary @test.jpeg \
      <YOUR-FILE-URL> \
      -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
      -H "Content-Type: image/jpeg"
    ```
  </Step>
</Steps>