Quick Start

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

Define the base URL once. The current OpenAPI schema uses /api/v2:

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"
}

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

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.