Skip to main content
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: 
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: 
{
  "access_token": "<YOUR-ACCESS-TOKEN>",
  ...
}
Use this token in all subsequent API requests: 
Authorization: Bearer <YOUR-ACCESS-TOKEN>

​
Creating a Run

1

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:
curl -X GET https://api.cradl.ai/v1/agents \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>"
Example response:
{
  "agents": [
    {
      "agentId": "<YOUR-AGENT-ID>",
      ...
    }
  ],
  "nextToken": null
}
2

Create a new run

Once you have the agent ID on the form `cradl:agent:xxx’, create a run:
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 '{}'
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:
  -d '{"variables": {"docId": "ABC", "customerId": "123" }}'
Example response:
{
  "id": "<YOUR-ORG-ID>/<YOUR-AGENT-ID>/<YOUR-RUN-ID>",
  ...
}
3

Create and upload a document

Create a document and associate it with your run:
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 that you’ll use to upload your document file:
curl -X PUT --data-binary @test.jpeg \
  <YOUR-FILE-URL> \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -H "Content-Type: image/jpeg"