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

Create a new run

Once you have the agent ID, create a run:
curl -X POST https://api.lucidtech.ai/v1/agents/<YOUR-AGENT-ID>/runs \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{}'
Example response:
{
  "id": "cradl:organization:<YOUR-ORG-ID>/cradl:agent:<YOUR-AGENT-ID>/cradl:run:<YOUR-RUN-ID>",
  ...
}
3

Create and upload a document

Create a document and associate it with your run:
curl -X POST https://api.lucidtech.ai/v1/documents \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My invoice",
    "agentRunId": "cradl:organization:<YOUR-ORG-ID>/cradl:agent:<YOUR-AGENT-ID>/cradl:run:<YOUR-RUN-ID>"
  }'
This response includes a fileUrl that you’ll use to upload your document file:
curl -X PUT --data-binary @test.jpeg \
  https://files.api.cradl.ai/cradl:file:<YOUR-DOCUMENT-ID> \
  -H "Authorization: Bearer <YOUR-ACCESS-TOKEN>" \
  -H "Content-Type: image/jpeg"