Quick Start

This guide shows the API flow: upload a file, create a run, and query its results.

Define the base URL once:

API_URL="https://veraquo.gradiant.org/api/v2"
API_KEY="{API_KEY}"

Upload a file

The required multipart field is file. The 201 response returns a FileResponse object containing the file identifier.

curl -X POST "$API_URL/files" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY" \
  -F 'file=@./path/to/file.webp'

Abbreviated response:

{
  "id": "{FILE_ID}",
  "filename": "file.webp",
  "url": "{FILE_URL}",
  "created_at": "2026-03-16T11:39:32Z",
  "status": "ready",
  "format": "image"
}

Before creating a run, check that the file is ready:

curl "$API_URL/files/{FILE_ID}" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY"

Only create the run when status is ready. If it is pending, query the file again later. If it is error or deleted, do not use it to create a run.

Create a run

When the file is available, create a run with file_id. Workers are optional; if omitted, the API selects the workers allowed for the user.

curl -X POST "$API_URL/runs" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "file_id": "{FILE_ID}",
    "run_schemas": null,
    "workers": null
  }'

201 response:

{
  "id": "{RUN_ID}",
  "status": "queued",
  "created_at": "2026-03-16T11:40:00Z",
  "completed_at": null,
  "file_id": "{FILE_ID}"
}

Check the status

The API has no separate /status endpoint. Query GET /runs/{run_id} until its status is ready, ok, alert, or error.

curl "$API_URL/runs/{RUN_ID}" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY"

The API defines these statuses: created, queued, processing, unprocessed, ready, error, alert, and ok.

Get results

When the run has finished, query GET /runs/{run_id}/results:

curl "$API_URL/runs/{RUN_ID}/results" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY"

Each result may include id, result, result_details, worker_name, result_file_urls, detail, created_at, started_at, completed_at, info, extra_details, and run_id.

Use GET /files/{file_id} for the original file metadata and GET /files/{file_id}/download to download a file.

Pagination and filters

List endpoints accept limit and offset. You can also sort results with order_by and order:

curl "$API_URL/files?limit=20&offset=0&order_by=created_at&order=desc" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY"

curl "$API_URL/runs/{RUN_ID}/results?limit=20&offset=0&order_by=created_at&order=desc" \
  -H 'accept: application/json' \
  -H "X-API-Key: $API_KEY"

Use the response total field to know how many items exist and increase offset to request the next page. Filters and results for an API Key remain limited to resources created with that key.

Errors and responses

• 401 Unauthorized: authentication is missing, the token or API Key is invalid, or an API Key was used for a user-only operation.
• 403 Forbidden: the credentials are valid but do not permit access to the requested resource.
• 404 Not Found: the identifier does not exist or the resource is not available to those credentials.
• 422 Unprocessable Entity: the request does not match the expected schema. The response includes a detail array with the error location and description.
• 204 No Content: the operation completed successfully and returns no body, for example when deleting a resource.

Run errors are also reported through the status field and may include additional information in detail.

Summary

1. Upload the file with POST /files and save its id.
2. Create a run with POST /runs using that file_id and save its id.
3. Query GET /runs/{run_id} until the run finishes.
4. Retrieve results with GET /runs/{run_id}/results.