API reference

Queues

Queues, background jobs and schedules. Send from a function binding or the REST API; a function, a URL (signed with the Standard Webhooks headers) or a pull client consumes. Retries with backoff, a dead-letter queue, cron schedules. Delivery is at least once.

GET/v1/queues

List queues#

With the plan's limits.

Credential: An API key or a dashboard session
Roles: Any role

Response

200object

queuesQueue[]required
- namestringrequired
- messagesintegerrequired
  the backlog: ready, delayed and in flight
- in_flightinteger
- delayedinteger
- bytesinteger
  stored size of the messages
- oldest_age_sinteger | null
- pausedbooleanrequired
- created_atstring (date-time)
- visibility_timeout_sinteger
  seconds a delivery may take before it is retried (default 30; alias visibility_timeout)
  at least 1
- max_retriesinteger
  retries after the first delivery (default 3); then the dead-letter queue
  0–100
- retry_delay_sinteger
  seconds before the first retry, doubling each time, at most 12 hours (default 5)
  0–43200
- retention_sinteger
  seconds a message is kept (alias retention; up to 1 day on Hobby, 14 days on Pro)
  at least 60
- delivery_delay_sinteger
  a delay for every message without its own (up to the plan's delay)
  at least 0
- dead_letter_queuestring | null
  another queue of the team that receives messages after their last retry (alias dead_letter)
- consumernull | QueueConsumer
limitsQueueLimits
- queuesinteger
- schedulesinteger
- messageBytesinteger
- batchSendMessagesinteger
- batchSendBytesinteger
- backlogBytesinteger
- retentionDaysinteger
- maxDelaySinteger
- maxVisibilitySinteger
- maxConcurrencyinteger
- maxBatchSizeinteger
- peekinteger
- dailyOpsinteger | null
  operations a day (Hobby 10,000, then 429 ops_limit); null: no daily limit

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/queues" \
  -H "Authorization: Bearer $KEY"

POST/v1/queues

Create a queue#

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Request body`application/json`

namestringrequired
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
visibility_timeout_sinteger
seconds a delivery may take before it is retried (default 30; alias visibility_timeout)
at least 1
max_retriesinteger
retries after the first delivery (default 3); then the dead-letter queue
0–100
retry_delay_sinteger
seconds before the first retry, doubling each time, at most 12 hours (default 5)
0–43200
retention_sinteger
seconds a message is kept (alias retention; up to 1 day on Hobby, 14 days on Pro)
at least 60
delivery_delay_sinteger
a delay for every message without its own (up to the plan's delay)
at least 0
dead_letter_queuestring | null
another queue of the team that receives messages after their last retry (alias dead_letter)

Response

201QueueCreated

namestringrequired
messagesintegerrequired
the backlog: ready, delayed and in flight
in_flightinteger
delayedinteger
bytesinteger
stored size of the messages
oldest_age_sinteger | null
pausedbooleanrequired
created_atstring (date-time)
visibility_timeout_sinteger
seconds a delivery may take before it is retried (default 30; alias visibility_timeout)
at least 1
max_retriesinteger
retries after the first delivery (default 3); then the dead-letter queue
0–100
retry_delay_sinteger
seconds before the first retry, doubling each time, at most 12 hours (default 5)
0–43200
retention_sinteger
seconds a message is kept (alias retention; up to 1 day on Hobby, 14 days on Pro)
at least 60
delivery_delay_sinteger
a delay for every message without its own (up to the plan's delay)
at least 0
dead_letter_queuestring | null
another queue of the team that receives messages after their last retry (alias dead_letter)
consumernull | QueueConsumer
- typestringrequired
  one of function, url, pull
- functionstring
- urlstring
- batch_sizeinteger
  1–100
- batch_wait_sinteger
  0–60
- batch_wait_msinteger
  0–60000
- max_concurrencyinteger
  deliveries at once (alias concurrency)
  at least 1

Errors

Status	Description
400	Bad request: `bad_name`, `bad_setting`, `bad_dlq`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/queues" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"emails"}'

GET/v1/queues/{name}

Get a queue#

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200Queue

namestringrequired
messagesintegerrequired
the backlog: ready, delayed and in flight
in_flightinteger
delayedinteger
bytesinteger
stored size of the messages
oldest_age_sinteger | null
pausedbooleanrequired
created_atstring (date-time)
visibility_timeout_sinteger
seconds a delivery may take before it is retried (default 30; alias visibility_timeout)
at least 1
max_retriesinteger
retries after the first delivery (default 3); then the dead-letter queue
0–100
retry_delay_sinteger
seconds before the first retry, doubling each time, at most 12 hours (default 5)
0–43200
retention_sinteger
seconds a message is kept (alias retention; up to 1 day on Hobby, 14 days on Pro)
at least 60
delivery_delay_sinteger
a delay for every message without its own (up to the plan's delay)
at least 0
dead_letter_queuestring | null
another queue of the team that receives messages after their last retry (alias dead_letter)
consumernull | QueueConsumer
- typestringrequired
  one of function, url, pull
- functionstring
- urlstring
- batch_sizeinteger
  1–100
- batch_wait_sinteger
  0–60
- batch_wait_msinteger
  0–60000
- max_concurrencyinteger
  deliveries at once (alias concurrency)
  at least 1

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/queues/emails" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/queues/{name}

Delete a queue and its messages#

Refused while a live version binds it (409 bound).

Credential: An API key or a dashboard session
Roles: owner, admin, developer
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200object

namestring
deletedboolean

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/queues/emails" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/queues/{name}

Change a queue's settings#

Settings, the dead-letter queue, and pausing delivery (sends are still accepted while paused).

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

visibility_timeout_sinteger
seconds a delivery may take before it is retried (default 30; alias visibility_timeout)
at least 1
max_retriesinteger
retries after the first delivery (default 3); then the dead-letter queue
0–100
retry_delay_sinteger
seconds before the first retry, doubling each time, at most 12 hours (default 5)
0–43200
retention_sinteger
seconds a message is kept (alias retention; up to 1 day on Hobby, 14 days on Pro)
at least 60
delivery_delay_sinteger
a delay for every message without its own (up to the plan's delay)
at least 0
dead_letter_queuestring | null
another queue of the team that receives messages after their last retry (alias dead_letter)
pausedboolean

Response

200Queue

namestringrequired
messagesintegerrequired
the backlog: ready, delayed and in flight
in_flightinteger
delayedinteger
bytesinteger
stored size of the messages
oldest_age_sinteger | null
pausedbooleanrequired
created_atstring (date-time)
visibility_timeout_sinteger
seconds a delivery may take before it is retried (default 30; alias visibility_timeout)
at least 1
max_retriesinteger
retries after the first delivery (default 3); then the dead-letter queue
0–100
retry_delay_sinteger
seconds before the first retry, doubling each time, at most 12 hours (default 5)
0–43200
retention_sinteger
seconds a message is kept (alias retention; up to 1 day on Hobby, 14 days on Pro)
at least 60
delivery_delay_sinteger
a delay for every message without its own (up to the plan's delay)
at least 0
dead_letter_queuestring | null
another queue of the team that receives messages after their last retry (alias dead_letter)
consumernull | QueueConsumer
- typestringrequired
  one of function, url, pull
- functionstring
- urlstring
- batch_sizeinteger
  1–100
- batch_wait_sinteger
  0–60
- batch_wait_msinteger
  0–60000
- max_concurrencyinteger
  deliveries at once (alias concurrency)
  at least 1

Errors

Status	Description
400	Bad request: `bad_setting`, `bad_dlq`, `nothing`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X PATCH "https://api.ibel.ai/v1/queues/emails" \
  -H "Authorization: Bearer $KEY" \
  -d '{"visibility_timeout_s":1,"max_retries":0,"retry_delay_s":0,"retention_s":60,"delivery_delay_s":0,"dead_letter_queue":"…","paused":true}'

PUT/v1/queues/{name}/consumer

Set the consumer function#

A function (its queue(batch, env, ctx) handler gets batches), a URL (each message POSTed, signed with the Standard Webhooks headers; the answer adds signing_secret, shown once) or pull.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

one of function, url or pull

functionstring
one of the team's functions or apps
urlstring
an HTTPS address; each message is POSTed to it, signed with the Standard Webhooks headers
pullboolean
true: messages wait for POST …/pull
batch_sizeinteger
1–100
batch_wait_sinteger
0–60
batch_wait_msinteger
0–60000
max_concurrencyinteger
deliveries at once (alias concurrency)
at least 1

Response

200Queue

namestringrequired
messagesintegerrequired
the backlog: ready, delayed and in flight
in_flightinteger
delayedinteger
bytesinteger
stored size of the messages
oldest_age_sinteger | null
pausedbooleanrequired
created_atstring (date-time)
visibility_timeout_sinteger
seconds a delivery may take before it is retried (default 30; alias visibility_timeout)
at least 1
max_retriesinteger
retries after the first delivery (default 3); then the dead-letter queue
0–100
retry_delay_sinteger
seconds before the first retry, doubling each time, at most 12 hours (default 5)
0–43200
retention_sinteger
seconds a message is kept (alias retention; up to 1 day on Hobby, 14 days on Pro)
at least 60
delivery_delay_sinteger
a delay for every message without its own (up to the plan's delay)
at least 0
dead_letter_queuestring | null
another queue of the team that receives messages after their last retry (alias dead_letter)
consumernull | QueueConsumer
- typestringrequired
  one of function, url, pull
- functionstring
- urlstring
- batch_sizeinteger
  1–100
- batch_wait_sinteger
  0–60
- batch_wait_msinteger
  0–60000
- max_concurrencyinteger
  deliveries at once (alias concurrency)
  at least 1

Errors

Status	Description
400	Bad request: `bad_consumer`, `bad_setting`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X PUT "https://api.ibel.ai/v1/queues/emails/consumer" \
  -H "Authorization: Bearer $KEY" \
  -d '{"function":"…","url":"https://example.com","pull":true,"batch_size":1,"batch_wait_s":0,"batch_wait_ms":0,"max_concurrency":1}'

DELETE/v1/queues/{name}/consumer

Remove the consumer#

Messages wait until a new consumer is set.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200Queue

namestringrequired
messagesintegerrequired
the backlog: ready, delayed and in flight
in_flightinteger
delayedinteger
bytesinteger
stored size of the messages
oldest_age_sinteger | null
pausedbooleanrequired
created_atstring (date-time)
visibility_timeout_sinteger
seconds a delivery may take before it is retried (default 30; alias visibility_timeout)
at least 1
max_retriesinteger
retries after the first delivery (default 3); then the dead-letter queue
0–100
retry_delay_sinteger
seconds before the first retry, doubling each time, at most 12 hours (default 5)
0–43200
retention_sinteger
seconds a message is kept (alias retention; up to 1 day on Hobby, 14 days on Pro)
at least 60
delivery_delay_sinteger
a delay for every message without its own (up to the plan's delay)
at least 0
dead_letter_queuestring | null
another queue of the team that receives messages after their last retry (alias dead_letter)
consumernull | QueueConsumer
- typestringrequired
  one of function, url, pull
- functionstring
- urlstring
- batch_sizeinteger
  1–100
- batch_wait_sinteger
  0–60
- batch_wait_msinteger
  0–60000
- max_concurrencyinteger
  deliveries at once (alias concurrency)
  at least 1

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/queues/emails/consumer" \
  -H "Authorization: Bearer $KEY"

GET/v1/queues/{name}/messages

Look at the waiting messages#

Changes nothing and delivers nothing.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
statestringquery
one of all, ready, delayed, in_flight
limitintegerquery
1–100
afterstringquery
a message id: the next page

Response

200QueuePeek

queuestring
messagesQueueMessage[]
- idstring
- bodyany
- bytesinteger
- attemptsinteger
  deliveries so far
- enqueued_atstring (date-time)
- available_atstring (date-time)
- statestring
  one of ready, delayed, in_flight
- dead_fromstring | null
  in a dead-letter queue: the queue it came from
- dead_reasonstring | null
nextstring | null

Errors

Status	Description
400	Bad request: `bad_state`, `bad_param`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/queues/emails/messages" \
  -H "Authorization: Bearer $KEY"

POST/v1/queues/{name}/messages

Send a message#

Delivery is at least once.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

bodyanyrequired
any JSON value, up to 128 KB
delay_secondsinteger
deliver after this long (alias delaySeconds; up to the plan's delay)
at least 0
delaySecondsinteger
the same as delay_seconds (the binding's name)
at least 0
dedup_idstring
the same id within 10 minutes is accepted once

Response

202QueueSentAccepted

sentintegerrequired
idsstring[]
duplicatesinteger
messages whose dedup_id was already seen

Errors

Status	Description
400	Bad request: `bad_message`, `bad_delay`, `message_too_large`, `queue_full`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/queues/emails/messages" \
  -H "Authorization: Bearer $KEY" \
  -d '{"body":null}'

POST/v1/queues/{name}/messages/batch

Send up to 100 messages#

At most 256 KB in all.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

messagesQueueMessageIn[]required
1–100 items
- bodyanyrequired
  any JSON value, up to 128 KB
- delay_secondsinteger
  deliver after this long (alias delaySeconds; up to the plan's delay)
  at least 0
- delaySecondsinteger
  the same as delay_seconds (the binding's name)
  at least 0
- dedup_idstring
  the same id within 10 minutes is accepted once

Response

202QueueSentAccepted

sentintegerrequired
idsstring[]
duplicatesinteger
messages whose dedup_id was already seen

Errors

Status	Description
400	Bad request: `bad_message`, `too_many`, `bad_delay`, `message_too_large`, `batch_too_large`, `queue_full`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/queues/emails/messages/batch" \
  -H "Authorization: Bearer $KEY" \
  -d '{"messages":[{"body":null,"delay_seconds":0,"delaySeconds":0,"dedup_id":"…"}]}'

POST/v1/queues/{name}/consumer/rotate-secret

Rotate a URL consumer's signing secret#

A new whsec_ secret, shown once; the old one stops signing.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200object

signing_secretstringrequired

Errors

Status	Description
400	Bad request: `bad_consumer`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/queues/emails/consumer/rotate-secret" \
  -H "Authorization: Bearer $KEY"

POST/v1/queues/{name}/pull

Pull messages#

For a pull consumer: takes up to max_messages ready messages and hides them for the visibility timeout; ack them with POST …/ack.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

max_messagesinteger
1–100 · default 10
visibility_timeout_sinteger
at least 1

Response

200QueuePulled

messagesobject[]required
- idstring
- lease_idstring
  what ack takes
- bodyany
- attemptsinteger
- timestampstring (date-time)

Errors

Status	Description
400	Bad request: `bad_setting`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
409	Conflict: `not_pull` (the queue's consumer is a function or URL)
429	Too many: `ops_limit`
500	`internal`: an unexpected failure
503	Unavailable: `unavailable` (try again)

Example

curl -X POST "https://api.ibel.ai/v1/queues/emails/pull" \
  -H "Authorization: Bearer $KEY" \
  -d '{"max_messages":10,"visibility_timeout_s":1}'

POST/v1/queues/{name}/ack

Acknowledge or retry pulled messages#

A message neither acked nor retried comes back after its visibility timeout.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

acksstring[]
lease ids
retriesobject[]
- lease_idstringrequired
- delay_secondsinteger
  at least 0

Response

200object

ackedinteger
retriedinteger
deadinteger
retries past max_retries, moved to the dead-letter queue

Errors

Status	Description
400	Bad request: `bad_message`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
409	Conflict: `not_pull`
429	Too many: `ops_limit`
500	`internal`: an unexpected failure
503	Unavailable: `unavailable` (try again)

Example

curl -X POST "https://api.ibel.ai/v1/queues/emails/ack" \
  -H "Authorization: Bearer $KEY" \
  -d '{"acks":["…"],"retries":[{"lease_id":"…","delay_seconds":0}]}'

GET/v1/queues/{name}/stats

A queue's numbers now#

Backlog, ready, delayed, in flight, stored bytes, age of the oldest, per-minute rates over the last 5 minutes and the dead letters waiting.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200QueueStats

backloginteger
readyinteger
delayedinteger
in_flightinteger
bytesinteger
oldest_age_sinteger | null
ratesobject
per minute, over the last 5 minutes
- sentnumber
- deliverednumber
- ackednumber
- failednumber
- deadnumber
dead_lettersinteger
messages from this queue waiting in its dead-letter queue

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure
503	Unavailable: `unavailable` (try again)

Example

curl "https://api.ibel.ai/v1/queues/emails/stats" \
  -H "Authorization: Bearer $KEY"

GET/v1/queues/{name}/dead-letters

List a queue's dead letters#

The messages in this queue's dead-letter queue that came from it.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
limitintegerquery
at least 1
afterstringquery
a message id, for the next page

Response

200object

queuestring
dead_letter_queuestring | null
messagesQueueMessage[]
- idstring
- bodyany
- bytesinteger
- attemptsinteger
  deliveries so far
- enqueued_atstring (date-time)
- available_atstring (date-time)
- statestring
  one of ready, delayed, in_flight
- dead_fromstring | null
  in a dead-letter queue: the queue it came from
- dead_reasonstring | null
nextstring | null

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/queues/emails/dead-letters" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/queues/{name}/dead-letters

Delete a queue's dead letters#

Credential: An API key or a dashboard session
Roles: owner, admin, developer
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200object

purgedinteger

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/queues/emails/dead-letters" \
  -H "Authorization: Bearer $KEY"

POST/v1/queues/{name}/dead-letters/retry

Retry dead letters#

Moves dead letters back into this queue, oldest first (or only ids), with their attempts reset.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

limitinteger
1–10000 · default 1000
idsstring[]

Response

200object

retriedinteger

Errors

Status	Description
400	Bad request: `bad_limit`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/queues/emails/dead-letters/retry" \
  -H "Authorization: Bearer $KEY" \
  -d '{"limit":1000,"ids":["…"]}'

POST/v1/queues/{name}/purge

Delete every message#

Credential: An API key or a dashboard session
Roles: owner, admin, developer
Step-up: With a dashboard session, a second factor confirmed in the last 10 minutes; API keys pass.

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Response

200object

namestring
purgedinteger

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/queues/emails/purge" \
  -H "Authorization: Bearer $KEY"

POST/v1/queues/{name}/redrive

Redrive a dead-letter queue#

Moves dead letters back to the queue each came from (or to), with fresh retries.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters

Request body`application/json`

limitinteger
1–10000
tostring

Response

200object

namestring
redriveninteger

Errors

Status	Description
400	Bad request: `bad_limit`, `bad_target`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/queues/emails/redrive" \
  -H "Authorization: Bearer $KEY" \
  -d '{"limit":1,"to":"2026-11-04T06:00:00Z"}'

GET/v1/queues/{name}/observability

Queue metrics#

Messages waiting, age of the oldest, sent, processed, failed deliveries and dead-lettered messages.

Credential: An API key or a dashboard session
Roles: Any role

Parameters

namestringpathrequired
the queue's name
pattern ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$ · up to 63 characters
rangestringquery
one of 1h, 24h, 7d · default "1h"

Response

200Observability

rangestringrequired
stepstringrequired
totalsPercentilesrequired
- requestsinteger
  every request served, static files and code
- function_requestsinteger
  requests that ran the code
- static_requestsinteger
  requests answered with a static file
- errors_4xxinteger
- errors_5xxinteger
- error_ratenumber
- p50number | null
- p95number | null
- p99number | null
seriesPercentiles[]required
- tstring (date-time)
- requestsinteger
- function_requestsinteger
  requests that ran the code
- static_requestsinteger
  requests answered with a static file
- errors_4xxinteger
- errors_5xxinteger
- p50number | null
- p95number | null
- p99number | null
routesPercentiles[]required
- routestring
- requestsinteger
- function_requestsinteger
  requests that ran the code
- static_requestsinteger
  requests answered with a static file
- errors_5xxinteger
- error_ratenumber
- avg_msnumber | null
- p50number | null
- p95number | null
- p99number | null
notestring
copiesFunctionCopies
- limitintegerrequired
  the plan's copies per server (function_copies in GET /v1/limits)
- perstringrequired
  one of server
- totalsCopyFiguresrequired
- seriesobject[]required
  the same steps as the observability series
- serversCopyFigures[]required

Errors

Status	Description
400	Bad request: `bad_range`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/queues/emails/observability" \
  -H "Authorization: Bearer $KEY"

GET/v1/schedules

List schedules#

Credential: An API key or a dashboard session
Roles: Any role

Response

200object

schedulesSchedule[]required
- idstringrequired
- namestring | null
- cronstringrequired
  five fields, e.g. 0 3 * * *
- timezonestringrequired
- targetobjectrequired
- bodyany
  the message each run sends
- pausedbooleanrequired
- last_atstring (date-time) | null
- last_statusstring | null
  one of sent, failed, null
- created_atstring (date-time)
- signing_secretstring
  on create with a URL target only, shown once
limitsobject
- schedulesinteger

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/schedules" \
  -H "Authorization: Bearer $KEY"

POST/v1/schedules

Create a schedule#

Sends body on a cron expression to a queue, a function or a URL. A URL target answers signing_secret once.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Request body`application/json`

namestring
cronstringrequired
timezonestring
default "Asia/Tehran"
targetobject | object | objectrequired
- queuestringrequired
bodyany
pausedboolean

Response

201ScheduleCreated

idstringrequired
namestring | null
cronstringrequired
five fields, e.g. 0 3 * * *
timezonestringrequired
targetobjectrequired
- typestringrequired
  one of queue, function, url
- queuestring
- functionstring
- urlstring
bodyany
the message each run sends
pausedbooleanrequired
last_atstring (date-time) | null
last_statusstring | null
one of sent, failed, null
created_atstring (date-time)
signing_secretstring
on create with a URL target only, shown once

Errors

Status	Description
400	Bad request: `bad_cron`, `bad_target`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `limit`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X POST "https://api.ibel.ai/v1/schedules" \
  -H "Authorization: Bearer $KEY" \
  -d '{"cron":"…","target":{"queue":"…"}}'

GET/v1/schedules/{id}

Get a schedule#

Credential: An API key or a dashboard session
Roles: Any role

Parameters

idstringpathrequired
the schedule's id

Response

200Schedule

idstringrequired
namestring | null
cronstringrequired
five fields, e.g. 0 3 * * *
timezonestringrequired
targetobjectrequired
- typestringrequired
  one of queue, function, url
- queuestring
- functionstring
- urlstring
bodyany
the message each run sends
pausedbooleanrequired
last_atstring (date-time) | null
last_statusstring | null
one of sent, failed, null
created_atstring (date-time)
signing_secretstring
on create with a URL target only, shown once

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl "https://api.ibel.ai/v1/schedules/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY"

DELETE/v1/schedules/{id}

Delete a schedule#

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

idstringpathrequired
the schedule's id

Response

200object

idstring
deletedboolean

Errors

Status	Description
400	Bad request: `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X DELETE "https://api.ibel.ai/v1/schedules/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/schedules/{id}

Change a schedule#

Also pauses and resumes it.

Credential: An API key or a dashboard session
Roles: owner, admin, developer

Parameters

idstringpathrequired
the schedule's id

Request body`application/json`

namestring
cronstring
timezonestring
bodyany
pausedboolean

Response

200Schedule

idstringrequired
namestring | null
cronstringrequired
five fields, e.g. 0 3 * * *
timezonestringrequired
targetobjectrequired
- typestringrequired
  one of queue, function, url
- queuestring
- functionstring
- urlstring
bodyany
the message each run sends
pausedbooleanrequired
last_atstring (date-time) | null
last_statusstring | null
one of sent, failed, null
created_atstring (date-time)
signing_secretstring
on create with a URL target only, shown once

Errors

Status	Description
400	Bad request: `bad_cron`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
404	Not found: `not_found`
500	`internal`: an unexpected failure

Example

curl -X PATCH "https://api.ibel.ai/v1/schedules/88e2fe1d-6d75-4de5-8c8f-27380ec66903" \
  -H "Authorization: Bearer $KEY" \
  -d '{"name":"emails","cron":"…","timezone":"…","body":null,"paused":true}'

List queues#

Response

Errors

Example

Create a queue#

Request bodyapplication/json

Response

Errors

Example

Get a queue#

Parameters

Response

Errors

Example

Delete a queue and its messages#

Parameters

Response

Errors

Example

Change a queue's settings#

Parameters

Request bodyapplication/json

Response

Errors

Example

Set the consumer function#

Parameters

Request bodyapplication/json

Response

Errors

Example

Remove the consumer#

Parameters

Response

Errors

Example

Look at the waiting messages#

Parameters

Response

Errors

Example

Send a message#

Parameters

Request bodyapplication/json

Response

Errors

Example

Send up to 100 messages#

Parameters

Request bodyapplication/json

Response

Errors

Example

Rotate a URL consumer's signing secret#

Parameters

Response

Errors

Example

Pull messages#

Parameters

Request bodyapplication/json

Response

Errors

Example

Acknowledge or retry pulled messages#

Parameters

Request bodyapplication/json

Response

Errors

Example

A queue's numbers now#

Parameters

Response

Errors

Example

List a queue's dead letters#

Parameters

Response

Errors

Example

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`

Request body`application/json`