Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Models Tools & Services
Solutions
Organisations Developers Internet Service Providers Managed Service Providers AI-in-a-Box
Resources
Support Documentation Blog Downloads
Company
About Research Careers Investment Opportunities Contact
Log in

API reference

All endpoints are mounted at /v1/modules/scaiqueue/ and authenticate with the standard ScaiGrid bearer token. Responses use ScaiGrid's standard envelope ({ "data": ... } for success, { "error": ... } for failures). All routes require a tenant-scoped caller — super_admin without a tenant cannot use these endpoints.

Access. Where a route below says "requires scaiqueue:x", a caller qualifies with that tenant-wide permission on an unrestricted scope, or with a scope role that includes the capability (view, publish, consume; "manage" routes inside a scope need operate, ACL routes need owner). Tenant admins and scaiqueue:manage holders qualify everywhere. Ids in the path (queue, message, rule, stream, subscription) must belong to the scope in the path, or the route returns 404. See Scopes as realms.

Scopes#

A scope is a tenant-owned namespace for queues. Creating a scope also creates five system queues: _dead_letter, _events, _audit, _integrity, _corrections.

POST /scopes#

Create a scope. Requires scaiqueue:manage, or scaiqueue:create_scopes (the caller then becomes the scope's owner).

Field Required Notes
slug yes Unique within tenant.
display_name no Defaults to slug.
description no
defaults no Object of default settings inherited by queues.
restricted no true makes the scope a closed realm: only scope members and tenant admins reach it. Default false.

GET /scopes#

List the scopes the caller can reach: every scope for tenant admins; otherwise unrestricted scopes (with tenant-wide scaiqueue:view) plus the scopes the caller has a role in. Each item carries restricted, my_role and capabilities.

GET /scopes/{scope_id}#

Fetch one scope, with my_role and capabilities. Requires view.

PATCH /scopes/{scope_id}#

Change display_name or description (requires operate), or restricted (tenant admins and scaiqueue:manage only).

POST /scopes/{scope_id}/{pause|resume|drain|archive|unarchive}#

State transitions. pause, resume and drain require operate; archive and unarchive require scaiqueue:manage, or scaiqueue:create_scopes plus the owner role on the scope. Allowed moves:

  • active → paused, draining, archived
  • paused → active, draining, archived
  • draining → archived
  • archived → active

Paused or archived scopes reject new publishes.

DELETE /scopes/{scope_id}#

Hard-delete. Scope must be archived first; deleting a scope in any other state answers 409 SCAIQUEUE_INVALID_TRANSITION. Requires scaiqueue:manage, or scaiqueue:create_scopes plus the owner role on the scope. Removes everything in the scope (queues, messages including archived ones and attachments, grants, queue ACL entries, trusts, routing rules, subscriptions, streams, schemas, HITL patterns) and returns the counts in removed. The audit log is kept.

Queues#

A queue lives in a scope and has an ordering mode (fifo, priority, deadline) and a consumer mode (competing, broadcast).

POST /scopes/{scope_id}/queues#

Create a queue. Requires scaiqueue:manage.

Field Required Notes
slug yes Unique within scope.
display_name no Defaults to slug.
description no
consumer_mode no competing (default) or broadcast.
ordering no fifo (default), priority, or deadline.
max_depth no 0 means unlimited.
overflow_policy no reject (default) or other strategies.

GET /scopes/{scope_id}/queues#

List queues in a scope. Requires scaiqueue:view.

GET /scopes/{scope_id}/queues/{queue_id}#

Fetch one queue. Requires scaiqueue:view.

GET /scopes/{scope_id}/queues/{queue_id}/stats#

Current depth_current, depth_pending, depth_claimed. Requires scaiqueue:view.

POST /scopes/{scope_id}/queues/{queue_id}/{pause|resume}#

Pause and resume. Requires scaiqueue:manage. Paused queues reject new publishes.

DELETE /scopes/{scope_id}/queues/{queue_id}#

Delete a non-system queue, with its messages (including archived ones and their attachments), subscriptions and queue ACL entries. Requires scaiqueue:manage. While the queue still holds pending or claimed messages it answers 409 SCAIQUEUE_QUEUE_NOT_EMPTY, with the counts in error.details; pass ?purge=true to delete them as well. Returns the counts in removed.

Messages#

Timestamps are UTC with an explicit offset (2026-10-15T19:41:23+00:00), in every ScaiQueue response.

Claims and visibility. A claim lasts visibility_timeout_s seconds: the value passed on claim, else the message's own (default 30). Extend it with /extend. A claim that lapses goes back to pending (or to dead_lettered once attempts reaches max_retries) the next time the queue is claimed from, listed or deleted, and can then be claimed again; completing it after that answers 409 SCAIQUEUE_NOT_CLAIMED. Claim for as long as the work really takes, for example several minutes for a human review.

Who handled a message. Message representations carry claimed_by and completed_by, each { "type", "id", "via" } or null. id is the ScaiGrid user who acted (for an API key, the key's owner). via names the application that acted for that user, when the user's token came from an RFC 8693 token exchange or was obtained by another application; it is null when the user called ScaiQueue directly. via is a record, never a right: access is always decided on the user.

POST /scopes/{scope_id}/queues/{queue_id}/messages#

Publish. Requires scaiqueue:publish.

Field Required Notes
body yes String or object; objects are JSON-serialised.
type no message_type; default task.
priority.tier no critical, high, normal (default), low, background.
priority.score no 0–1000; default 500.
labels no {key: value} map.
content_type no application/json default.
correlation_id, causation_id, parent_id no Lineage.
ttl_seconds no If set, expiry enforcer terminalises after this.
max_retries no Default 3.
visibility_timeout_s no Default 30.
idempotency_key no Replays return original message id.
hitl_spec no Object with rendering spec.

POST /scopes/{scope_id}/queues/{queue_id}/messages/claim#

Claim messages. Requires scaiqueue:consume. Body: { "batch_size": int, "visibility_timeout_s": int }. Returns a list of full message representations including body and HITL spec.

POST /scopes/{scope_id}/messages/{msg_id}/claim#

Claim one specific message, for example the item a reviewer opened. Requires scaiqueue:consume. Body: { "visibility_timeout_s": int } (optional). Returns the full message. Answers 409 SCAIQUEUE_CLAIM_FAILED when the message isn't pending, isn't visible yet (delayed or backing off; error.details.visible_at says when), or another consumer claimed it first.

POST /scopes/{scope_id}/messages/{msg_id}/complete#

Mark complete. Requires scaiqueue:consume. Body: { "response": object | null }. Emits a scaiqueue.message.completed event on the event bus carrying the original correlation_id.

POST /scopes/{scope_id}/messages/{msg_id}/fail#

Mark failed. Requires scaiqueue:consume. Body: { "reason": string }. Triggers retry or dead-letter depending on attempts vs max_retries.

POST /scopes/{scope_id}/messages/{msg_id}/release#

Return a claimed message to pending. Requires scaiqueue:consume.

POST /scopes/{scope_id}/messages/{msg_id}/extend#

Extend the visibility timeout. Requires scaiqueue:consume. Body: { "seconds": int }.

POST /scopes/{scope_id}/messages/{msg_id}/cancel#

Cancel a pending or claimed message. Requires scaiqueue:manage.

GET /scopes/{scope_id}/queues/{queue_id}/messages#

List messages in a queue. Requires scaiqueue:view. Query params: state (one of pending, claimed, completed, failed, dead_lettered, cancelled, expired), limit (default 50), cursor.

GET /scopes/{scope_id}/queues/{queue_id}/messages/{msg_id}#

Full message including body, hitl_spec, response. Requires scaiqueue:view.

GET /scopes/{scope_id}/messages?correlation_id=...#

Return every message in a correlation chain across the scope. Requires scaiqueue:view.

Routing rules#

Rules live on a scope and fire on triggers (message_published is the default). First matching rule (priority ascending) wins; rule actions move/transform messages, with a 5-hop circuit breaker.

POST /scopes/{scope_id}/routing-rules#

Create. Requires scaiqueue:manage. Body: { name, description, priority, enabled, trigger, conditions, action, source }.

GET /scopes/{scope_id}/routing-rules#

List rules in priority-ascending order. Requires scaiqueue:view.

GET /scopes/{scope_id}/routing-rules/{rule_id}#

Fetch one rule. Requires scaiqueue:view.

PATCH /scopes/{scope_id}/routing-rules/{rule_id}#

Update name, description, priority, trigger, conditions, action, enabled. Requires scaiqueue:manage.

DELETE /scopes/{scope_id}/routing-rules/{rule_id}#

Delete. Requires scaiqueue:manage.

POST /scopes/{scope_id}/routing-rules/{rule_id}/{enable|disable}#

Toggle enabled. Requires scaiqueue:manage.

POST /scopes/{scope_id}/routing-rules/test#

Dry-run rules against a hypothetical message. Body: { "trigger": "message_published", "message": { ... } }. Returns the rules that would match. Requires scaiqueue:view.

Streams#

A stream is a sequence of chunk messages that the stream service can assemble.

GET /scopes/{scope_id}/streams#

List streams, optional state filter. Requires scaiqueue:view.

GET /scopes/{scope_id}/streams/{stream_id}#

Stream metadata plus a summary of chunks. Requires scaiqueue:view.

POST /scopes/{scope_id}/streams/{stream_id}/cancel#

Cancel an open stream. Requires scaiqueue:manage.

GET /scopes/{scope_id}/streams/{stream_id}/assembled#

Assembled content (default concatenate mode). Requires scaiqueue:view.

Subscriptions#

A subscription binds a consumer (user, agent) to a queue with a filter and a delivery mode.

POST /scopes/{scope_id}/subscriptions#

Create. Requires scaiqueue:consume. Body fields include subscriber_type, subscriber_id, queue_id, filter, delivery_mode (pull default), auto_claim, max_in_flight.

GET /scopes/{scope_id}/subscriptions#

List for a scope. Requires scaiqueue:view.

GET /scopes/{scope_id}/subscriptions/{sub_id}#

Fetch one. Requires scaiqueue:view.

PATCH /scopes/{scope_id}/subscriptions/{sub_id}#

Update filter, delivery_mode, auto_claim, max_in_flight. Requires scaiqueue:manage.

DELETE /scopes/{scope_id}/subscriptions/{sub_id}#

Delete. Requires scaiqueue:manage.

POST /scopes/{scope_id}/subscriptions/{sub_id}/{pause|resume}#

Toggle active. Requires scaiqueue:manage.

POST /subscriptions/{sub_id}/check-processed#

Return a {message_id: bool} map of which message ids the subscription has already processed (Redis-backed dedup). Requires scaiqueue:consume.

Message schemas#

JSON-Schema definitions per scope. Used to validate payloads.

POST /scopes/{scope_id}/schemas#

Register a schema. Requires scaiqueue:manage. Body: { name, version, schema }.

GET /scopes/{scope_id}/schemas#

List schemas in scope. Requires scaiqueue:view.

GET /scopes/{scope_id}/schemas/{name}/{version}#

Fetch one. Requires scaiqueue:view.

POST /scopes/{scope_id}/schemas/{name}/{version}/validate#

Validate a payload. Body: { "payload": ... }. Returns { valid, errors }. Requires scaiqueue:view.

DELETE /scopes/{scope_id}/schemas/{name}/{version}#

Soft-delete (sets deprecated=true). Requires scaiqueue:manage.

HITL pattern registry#

Reusable rendering specs that messages can reference by name.

POST /scopes/{scope_id}/hitl-patterns#

Register a pattern. Requires scaiqueue:manage. Body: { name, version, spec, parameters }.

GET /scopes/{scope_id}/hitl-patterns#

List. Requires scaiqueue:view.

GET /scopes/{scope_id}/hitl-patterns/{name}/{version}#

Fetch the spec and parameters. Requires scaiqueue:view.

POST /scopes/{scope_id}/hitl-patterns/{name}/expand#

Expand a pattern with parameters (substitutes {{key}} placeholders). Body: { version, parameters }. Requires scaiqueue:view.

ACL#

Per-scope grants, per-queue ACL entries, and cross-scope trust grants. All routes require the owner role on the scope (tenant admins and scaiqueue:manage holders qualify).

GET /scopes/{scope_id}/acl#

Return { grants, queue_acl, trusted_scopes } for the scope.

POST /scopes/{scope_id}/acl/grants#

Give a user or group a role in the scope. Body: { actor_type, actor_id, role, expires_at? }.

  • actor_type: user (ScaiGrid user id; for an API key, its owner) or group (ScaiKey group id, or the local group id, stored as the ScaiKey id).
  • role: owner, operator, producer, consumer or viewer.
  • expires_at: optional ISO 8601 time in the future.

The member must belong to the scope's tenant. Granting again to the same member replaces its role.

DELETE /scopes/{scope_id}/acl/grants/{grant_id}#

Revoke a grant.

POST /scopes/{scope_id}/acl/queue-acl#

Add a per-queue ACL entry. Body: { queue_id, actor_type, actor_id, role, effect }. queue_id must be a queue in this scope; role is the action (view, publish, consume, manage); effect is allow (default, advisory) or deny (enforced: blocks that action on that queue even for callers who otherwise have it). Members as for grants.

DELETE /scopes/{scope_id}/acl/queue-acl/{entry_id}#

Remove a per-queue ACL entry.

POST /scopes/{scope_id}/acl/trusted-scopes#

Trust another scope for cross-scope routing. Body: { target_scope_id, direction, allowed_types, allowed_queues, identity_mode }. The trust is active at once only if the caller also owns the target scope; otherwise it stays pending until the target's owner accepts it with POST /scopes/{target_scope_id}/acl/trusted-scopes/{trust_id}/accept.

DELETE /scopes/{scope_id}/acl/trusted-scopes/{trust_id}#

Revoke a cross-scope trust.

Audit log#

GET /scopes/{scope_id}/audit#

Query audit events. Filters: event_type, actor_id, resource_type, correlation_id, limit (default 50). Requires scaiqueue:view.

Claiming, completing, failing and releasing a message each write an event (message.claimed, message.completed, message.failed, message.released). Every event's actor is { "type", "id", "via" }, with via as described under Messages.

GET /scopes/{scope_id}/audit/trace/{correlation_id}#

Every audit event for a correlation chain, oldest first. Requires scaiqueue:view.

GET /scopes/{scope_id}/audit/stats#

{event_type: count} aggregate over the scope. Requires scaiqueue:view.

System agents#

GET /system-agents#

Status of every system agent (visibility-timeout enforcer, expiry enforcer, archiver, dead-letter monitor, priority-aging worker): status, total_runs, total_processed, total_errors, last_run_at, last_run_duration_ms, last_error. Requires scaiqueue:view.

GDPR#

POST /tenants/{tenant_id}/data-erasure#

Submit an erasure request. Body: { mode, actor_type, actor_id } with mode of redact (default) or other supported modes. Returns a job id. Requires scaiqueue:manage.

GET /tenants/{tenant_id}/data-erasure/jobs/{job_id}#

Job status. Requires scaiqueue:manage.

POST /tenants/{tenant_id}/data-export#

Submit an export request. Requires scaiqueue:manage.

GET /tenants/{tenant_id}/data-export/jobs/{job_id}#

Job status. Requires scaiqueue:manage.

Errors#

All endpoints return ScaiGrid's standard error envelope:

json
1
2
3
4
5
6
7
8
{
  "error": {
    "code": "SCAIQUEUE_QUEUE_FULL",
    "message": "Queue depth limit reached",
    "details": { }
  },
  "meta": { "request_id": "req_..." }
}

ScaiQueue-specific codes:

Code HTTP Meaning
SCAIQUEUE_SCOPE_NOT_FOUND 404 Scope id doesn't exist or isn't visible.
SCAIQUEUE_QUEUE_NOT_FOUND 404 Queue id doesn't exist or isn't visible.
SCAIQUEUE_MESSAGE_NOT_FOUND 404 Message id doesn't exist or isn't visible.
SCAIQUEUE_SLUG_CONFLICT 409 Scope or queue slug already exists at that level.
SCAIQUEUE_CLAIM_FAILED 409 Claim raced with another consumer.
SCAIQUEUE_NOT_CLAIMED 409 Tried to complete/fail/extend a message that isn't claimed.
SCAIQUEUE_INVALID_TRANSITION 409 Disallowed state transition (e.g. resume an archived scope, delete a non-empty queue, delete a system queue).
SCAIQUEUE_QUEUE_FULL 429 Queue's max_depth reached and overflow_policy=reject.
SCAIQUEUE_RATE_LIMITED 429 Tenant-level rate limit hit.
SCAIQUEUE_IDEMPOTENCY_CONFLICT 409 Idempotency key seen with a different body.
SCAIQUEUE_SCOPE_PAUSED 409 Scope is paused or archived; no publishes accepted.
SCAIQUEUE_QUEUE_PAUSED 409 Queue is paused.
SCAIQUEUE_ATTACHMENT_ERROR 500 Attachment storage failed.
Updated 2026-10-19 16:21:00 View source (.md) rev 18