Work Queues API

A work queue is a durable backlog of individual units of work — each an invocation of one of your tools with a payload — that the platform processes reliably, with retries, per-item timeouts, grouping, and staged ordering. Use it to fan a large job out into many independent items and track them to completion.

All Work Queues API requests require an Authorization header with your API key. These endpoints are company-scoped by the key, so — unlike the AutessaDB API — they take no resourceId query parameter. Every item that names a tool to run is checked against your key's permissions for that tool before it is accepted.

Base URL

https://api.autessa.com/clients/workqueues

Authentication

Pass your API key in the Authorization header (no "Bearer" prefix):

Authorization: your_api_key_here

cURL
curl https://api.autessa.com/clients/workqueues/progress \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "queueId": "b1a7...", "groupKey": "batch-2026-07" }'

Concepts

A queue is a named, long-lived backlog. Queues are created and configured in the Builder — where you set their concurrency, default attempt and timeout limits, and stage precedence — and you reference an existing queue by its queueId when enqueuing.

An item is one unit of work: a tool to invoke (actionToolId) and the payload of per-invocation values it runs with. Each item moves through states — PENDING, RUNNING, and then a terminal SUCCEEDED, FAILED, DEAD (failed past its maxAttempts), or CANCELLED.

A group collects related items under a shared groupKey so you can track and act on a batch as a whole. Group counters are maintained as items complete, so progress is a fast read regardless of how many items the group holds.

A stage is an optional label on an item. When a queue defines an ordered stage precedence, items in earlier-listed stages are leased for processing ahead of later stages — and any staged item is leased ahead of unstaged ones. This drives depth-first completion: a multi-stage pipeline finishes the items already in flight through their later stages before pulling new work in at the first stage. A stage is just a name to the API; the ordering comes from the queue's configured precedence list.

Enqueue Items POST`/enqueue`

Adds one or more items to a queue in a single call. Every item that sets actionToolId is authorized against your API key's permission for that tool before anything is written — if any item fails the check, the whole batch is rejected and nothing is enqueued.

Request Body

Name
queueId
Type
string
Description
ID of the queue to add items to.
Name
items
Type
array<EnqueueItem>
Description
The items to enqueue. Each has the fields below.

EnqueueItem

Name
actionToolId
Type
string
Description
ID of the tool this item invokes when it runs. Your API key must have permission for this tool.
Name
payload
Type
object
Description
Per-invocation values for the tool's @@{...} placeholders — the same kind of input you would pass when running the tool directly.
Name
groupKey
Type
string
Description
Groups this item with others under a shared key for batch tracking and group actions.
Name
stage
Type
string
Description
Optional stage label. Its effect on ordering comes from the queue's configured stage precedence.
Name
priority
Type
integer
Description
Explicit lease priority (lower is leased first). When set, it overrides any stage precedence for this item.
Name
maxAttempts
Type
integer
Description
How many times the item may run before it is marked DEAD. Defaults to the queue's configured maximum.
Name
timeoutSeconds
Type
integer
Description
Per-run timeout for this item. Defaults to the queue's configured timeout.
Name
delaySeconds
Type
integer
Description
Hold the item invisible for this many seconds before it becomes eligible to run.
Name
dedupKey
Type
string
Description
Optional idempotency key. An item whose dedupKey matches a still-live (pending or running) item already on the same queue is skipped rather than enqueued — so a retried or re-delivered enqueue never creates a duplicate. Items with no dedupKey are never deduplicated.

Response

Name
enqueued
Type
integer
Description
Number of items actually added.
Name
itemIds
Type
array<string>
Description
IDs of the enqueued items, in request order.
Name
skipped
Type
integer
Description
Number of items silently skipped as dedupKey duplicates (0 when none).
Name
errors
Type
array<string>
Description
Error messages if the batch was rejected.

cURL
curl --request POST \
  --url 'https://api.autessa.com/clients/workqueues/enqueue' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_api_key' \
  --data '{
    "queueId": "b1a7c0de-2f3a-4c5b-9d1e-7a8b9c0d1e2f",
    "items": [
      {
        "actionToolId": "V1StGXR8Z5",
        "groupKey": "batch-2026-07",
        "stage": "extract",
        "payload": { "s3Uri": "s3://autessa-files/uploads/doc-001.pdf" },
        "dedupKey": "doc-001"
      },
      {
        "actionToolId": "V1StGXR8Z5",
        "groupKey": "batch-2026-07",
        "stage": "extract",
        "payload": { "s3Uri": "s3://autessa-files/uploads/doc-002.pdf" },
        "dedupKey": "doc-002"
      }
    ]
  }'

JSON
{
  "enqueued": 2,
  "itemIds": [
    "9f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
    "0a1b2c3d-4e5f-6071-8293-b4c5d6e7f809"
  ],
  "skipped": 0,
  "errors": []
}

Progress POST`/progress`

Returns the live counters for one group: how many of its items are in each state, per-stage totals and completions, and an overall status. This is a fast read — it consults the maintained group counters, not a scan of every item.

Request Body

Name
queueId
Type
string
Description
ID of the queue the group belongs to.
Name
groupKey
Type
string
Description
The group to report on.

Response

Name
group
Type
WorkGroup
Description
The group's counters, or null if no items have ever been enqueued under this (queueId, groupKey).
Name
errors
Type
array<string>
Description
Error messages if any occurred.

WorkGroup

Name
nTotal
Type
integer
Description
Total items enqueued in the group.
Name
nPending
Type
integer
Description
Items waiting to run.
Name
nRunning
Type
integer
Description
Items currently running.
Name
nSucceeded
Type
integer
Description
Items that completed successfully.
Name
nFailed
Type
integer
Description
Items whose latest attempt failed (and may retry).
Name
nDead
Type
integer
Description
Items that exhausted their attempts.
Name
nCancelled
Type
integer
Description
Items that were cancelled.
Name
stageCounts
Type
object
Description
Per-stage progress: a map of stage name to { "total": ..., "done": ... }.
Name
status
Type
string
Description
The group's overall status.

cURL
curl --request POST \
  --url 'https://api.autessa.com/clients/workqueues/progress' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_api_key' \
  --data '{
    "queueId": "b1a7c0de-2f3a-4c5b-9d1e-7a8b9c0d1e2f",
    "groupKey": "batch-2026-07"
  }'

JSON
{
  "group": {
    "queueId": "b1a7c0de-2f3a-4c5b-9d1e-7a8b9c0d1e2f",
    "groupKey": "batch-2026-07",
    "nTotal": 500,
    "nPending": 120,
    "nRunning": 8,
    "nSucceeded": 360,
    "nFailed": 4,
    "nDead": 2,
    "nCancelled": 6,
    "stageCounts": {
      "extract": { "total": 500, "done": 498 },
      "classify": { "total": 498, "done": 372 }
    },
    "status": "ACTIVE"
  },
  "errors": []
}

List Items POST`/items/list`

Lists items on a queue, filtered by state, stage, and/or group, with pagination. Use it to inspect individual items — their payloads, results, attempt counts, and last error.

Request Body

Name
queueId
Type
string
Description
ID of the queue to list from.
Name
state
Type
string
Description
Filter to one state: PENDING, RUNNING, SUCCEEDED, FAILED, DEAD, or CANCELLED.
Name
stage
Type
string
Description
Filter to one stage.
Name
groupKey
Type
string
Description
Filter to one group.
Name
page
Type
integer
Description
Zero-based page number. Defaults to 0.
Name
size
Type
integer
Description
Items per page. Defaults to 50.

Response

Name
items
Type
array<WorkItem>
Description
The matching items. Each carries id, queueId, groupKey, stage, state, priority, attempt, maxAttempts, actionToolId, payload, result, lastError, timeoutSeconds, visibleAt, createdAt, and completedAt.
Name
totalElements
Type
integer
Description
Total items matching the filter.
Name
totalPages
Type
integer
Description
Total pages at the requested size.
Name
page
Type
integer
Description
The page returned.
Name
errors
Type
array<string>
Description
Error messages if any occurred.

cURL
curl --request POST \
  --url 'https://api.autessa.com/clients/workqueues/items/list' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_api_key' \
  --data '{
    "queueId": "b1a7c0de-2f3a-4c5b-9d1e-7a8b9c0d1e2f",
    "groupKey": "batch-2026-07",
    "state": "DEAD",
    "page": 0,
    "size": 50
  }'

JSON
{
  "items": [
    {
      "id": "0a1b2c3d-4e5f-6071-8293-b4c5d6e7f809",
      "queueId": "b1a7c0de-2f3a-4c5b-9d1e-7a8b9c0d1e2f",
      "groupKey": "batch-2026-07",
      "stage": "extract",
      "state": "DEAD",
      "priority": 10,
      "attempt": 3,
      "maxAttempts": 3,
      "actionToolId": "V1StGXR8Z5",
      "payload": { "s3Uri": "s3://autessa-files/uploads/doc-002.pdf" },
      "result": {},
      "lastError": "Extraction timed out",
      "timeoutSeconds": 300,
      "visibleAt": "2026-07-15T14:30:00Z",
      "createdAt": "2026-07-15T14:00:00Z",
      "completedAt": "2026-07-15T14:35:10Z"
    }
  ],
  "totalElements": 2,
  "totalPages": 1,
  "page": 0,
  "errors": []
}

Retry Dead Items POST`/retry-dead`

Requeues every DEAD item in a group — resetting its attempt count and making it eligible to run again. Use it after fixing whatever caused a batch of items to exhaust their retries.

Request Body

Name
queueId
Type
string
Description
ID of the queue.
Name
groupKey
Type
string
Description
The group whose dead items to requeue.

Response

Name
count
Type
integer
Description
Number of items moved back to PENDING.
Name
errors
Type
array<string>
Description
Error messages if any occurred.

cURL
curl --request POST \
  --url 'https://api.autessa.com/clients/workqueues/retry-dead' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_api_key' \
  --data '{
    "queueId": "b1a7c0de-2f3a-4c5b-9d1e-7a8b9c0d1e2f",
    "groupKey": "batch-2026-07"
  }'

JSON
{
  "count": 2,
  "errors": []
}

Cancel Group POST`/cancel-group`

Cancels a group's outstanding work: items that are PENDING or FAILED move to CANCELLED. Items already RUNNING are left to finish, and items that have already reached a terminal state are unaffected.

Request Body

Name
queueId
Type
string
Description
ID of the queue.
Name
groupKey
Type
string
Description
The group to cancel.

Response

Name
count
Type
integer
Description
Number of items moved to CANCELLED.
Name
errors
Type
array<string>
Description
Error messages if any occurred.

cURL
curl --request POST \
  --url 'https://api.autessa.com/clients/workqueues/cancel-group' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: your_api_key' \
  --data '{
    "queueId": "b1a7c0de-2f3a-4c5b-9d1e-7a8b9c0d1e2f",
    "groupKey": "batch-2026-07"
  }'

JSON
{
  "count": 118,
  "errors": []
}

Tools API — the tools an item invokes when it runs
Document tool types — bulk-intake and per-document processing designed to run as queue items
AutessaDB API — multipart upload for the large archives a bulk-intake queue processes

Base URL​

Authentication​

Concepts​

Enqueue Items POST/enqueue​

Request Body​

Response​

Progress POST/progress​

Request Body​

Response​

List Items POST/items/list​

Request Body​

Response​

Retry Dead Items POST/retry-dead​

Request Body​

Response​

Cancel Group POST/cancel-group​

Request Body​

Response​

Related​

Base URL

Authentication

Concepts

Enqueue Items POST`/enqueue`

Request Body

Response

Progress POST`/progress`

Request Body

Response

List Items POST`/items/list`

Request Body

Response

Retry Dead Items POST`/retry-dead`

Request Body

Response

Cancel Group POST`/cancel-group`

Request Body

Response

Related