The bounded example worker handles one sample job without executing payloads or following URLs. The quickstart creates and enqueues a job, runs that worker and reads completion.
Create a queue
curl -X POST https://aisenseapi.com/services/v1/queue \
-H "Content-Type: application/json" \
-d '{}'The response returns a queue_id, created_at_timestamp, expire_timestamp, empty job counts and three tokens. Save the tokens: they are returned only at creation.
| Token | Share with | Allows |
|---|---|---|
write_token | Producers | Enqueue a job |
worker_token | Workers | Claim a payload, acknowledge, release and renew |
read_token | Observers | Read queue counts and individual jobs |
Queue and job IDs are 32 lowercase hex characters. Tokens are 64 lowercase hex characters. The queue ID alone grants no access. Every later REST request sends the appropriate token in Authorization: Bearer TOKEN. Never put a credential in a URL.
Add a job
curl -X POST https://aisenseapi.com/services/v1/queue/QUEUE_ID/jobs \
-H "Authorization: Bearer WRITE_TOKEN" \
-H "Content-Type: application/json" \
-d '{"job_key":"report:42","payload":{"report_id":42}}'Replace uppercase placeholders with your own returned values. job_key is 1 to 64 characters, starts with an ASCII letter or digit, and contains only letters, digits, periods, underscores, colons and hyphens. payload is any JSON value, including null, up to 16 KiB when encoded.
A new job returns HTTP 201 with deduplicated: false. Retry the same key and payload to receive the existing job with HTTP 200 and deduplicated: true. Changing the payload for an existing key returns HTTP 409. Completed and failed jobs keep their keys until the queue expires.
Claim the next available job
curl -X POST https://aisenseapi.com/services/v1/queue/QUEUE_ID/claim \
-H "Authorization: Bearer WORKER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"visibility_timeout":60}'visibility_timeout accepts integer seconds from 30 to 900 and defaults to 60. A successful claim includes the job ID, key, payload, status: "claimed", attempt count, expiry timestamps and a secret receipt. The receipt has 64 lowercase hex characters and identifies this claim attempt. It is disclosed only in the claim response.
When nothing is available, the response contains job: null. A claimed job stays hidden from other claims until its visibility window ends or the worker releases it. Poll with a delay when empty.
- Producer submits the job
A stable key makes enqueue retries safe.
- Worker claims and performs the work
Keep the receipt and renew if more time is needed.
- Worker acknowledges success
The job becomes completed and stays readable until the queue expires.
Acknowledge, release or renew
curl -X POST https://aisenseapi.com/services/v1/queue/QUEUE_ID/jobs/JOB_ID/ack \
-H "Authorization: Bearer WORKER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"receipt":"RECEIPT"}'| Action | Body | Effect |
|---|---|---|
ack | receipt | Mark the job completed |
release | receipt | Make it available for another attempt, if attempts remain |
renew | receipt, optional visibility_timeout | Extend the same claim within the queue expiry |
Replace ack in the example path with the action you need. An expired or superseded receipt returns HTTP 409. A successful ack can be repeated with its receipt. Ack accepts no result or callback URL. Your own application keeps any output.
Read counts and progress
curl https://aisenseapi.com/services/v1/queue/QUEUE_ID \
-H "Authorization: Bearer READ_TOKEN"
curl https://aisenseapi.com/services/v1/queue/QUEUE_ID/jobs/JOB_ID \
-H "Authorization: Bearer READ_TOKEN"Queue reads return creation and expiry times plus counts for pending, claimed, completed, failed and total. They do not list jobs. Save job IDs from enqueue responses to read individual payloads, status and attempts. Reads do not reveal role tokens or claim receipts.
Handle work that can run again
An unacknowledged job becomes available when its visibility window ends. Each claim adds one attempt. After five unsuccessful attempts it becomes failed. Renewal keeps the same attempt.
Jobs can be delivered again after a claim expires or is released. Queue expiry and the attempt limit may leave jobs unfinished. Initial delivery and exactly-once execution are not guaranteed. A worker may complete an external action and lose its claim before acknowledging it. Use the job key or ID to make that action idempotent.
One fixed 24-hour lifetime
expire_timestamp is set to creation time plus 86400 seconds. All queue data shares that deadline, including payloads, completed jobs, failed jobs and deduplication entries. No enqueue, read, claim, acknowledgment, release or renewal extends it. A visibility window is capped at the time remaining. There is no configurable TTL.
| Limit | Value |
|---|---|
| Queue and job lifetime | 24 hours from queue creation |
| Distinct jobs over that lifetime | 100, including completed and failed jobs |
| Encoded JSON payload | 16 KiB (16384 bytes) |
| Claim attempts per job | 5 |
| Visibility window | 30 to 900 seconds, default 60 |
| New queues per client IP | 20 per 24 hours, within the shared request limit |
Expired state becomes unavailable and is cleaned up. Keep your own copy of work and output that must survive this deadline.
Data and access
Tokens grant separate capabilities without checking a person's identity. Workers receive job payloads when claiming. Share each token only with the systems that need its role and keep receipts private.
The Queue service writes payload content to its JSON state files without encrypting it. It normalizes object-key ordering and JSON serialization. Do not include passwords, API keys or sensitive personal data. The queue does not execute payloads, fetch URLs, send callbacks or contact outside services. Producers submit jobs and your own workers perform the work.
The same flow through MCP
Connect to https://aisenseapi.com/mcp. Queue tools accept the role token as a tool argument. Check tools/list for availability on your server.
| Tool | Purpose |
|---|---|
create_agent_queue | Create the queue and receive three tokens |
enqueue_agent_queue_job | Submit a keyed JSON job |
claim_agent_queue_job | Claim a job with a receipt |
read_agent_queue | Read timing and counts |
read_agent_queue_job | Read one job |
ack_agent_queue_job | Record success |
release_agent_queue_job | Allow another attempt |
renew_agent_queue_job | Extend claim visibility |
Read the complete MCP argument reference.