Docs
⌘K

HTTP API: queues

Create message queues, send and read messages with a visibility timeout, archive, delete, purge, metrics and dead letters.

Updated Oct 26, 2026

Durable message queues (pgmq-style) over HTTP: create queues, send messages, read them with a visibility timeout, archive or delete them, and look at metrics. Guide: Queues.

Base URLhttps://<project-ref>.sovarias.in — your project URL from Connect.
KeysSend the project's key as apikey. Calls made for a signed-in user also send Authorization: Bearer <access token>.
ErrorsA status code and {"detail": …} — a sentence, or {code, message} for errors your code may branch on (HTTP API).

#Queues

GET/api/v1/queues

The queues of the project's environment, with length and oldest message age, plus the plan's limits and usage.

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Responses

  • 200Success.
  • 401No valid session or key.
curl -s "$URL/api/v1/queues" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
  "project_id": "f0c3e9a2-1b4d-4e7f-8a6c-2d9b5e3f1a07",
  "queues": [
    {
      "queue_id": "3c9d1e7f2a4b4c6d8e0f1a2b3c4d5e6f",
      "org_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "project_id": "f0c3e9a2-1b4d-4e7f-8a6c-2d9b5e3f1a07",
      "env_id": "",
      "name": "emails",
      "description": "Outgoing mail",
      "visibility_timeout_sec": 60,
      "max_reads": 5,
      "dead_letter_queue": "emails-dead",
      "retention_days": null,
      "app_send": false,
      "consumer": {
        "function_name": "send-email",
        "enabled": true,
        "batch_size": 10,
        "concurrency": 2,
        "visibility_timeout_sec": null,
        "ack": "archive",
        "last_error": ""
      },
      "queue_length": 12,
      "stored_bytes": 3480,
      "sent_total": 940,
      "dead_total": 2,
      "created_by": "8b2c…",
      "created_at": 1791800000.0,
      "updated_at": 1791800000.0,
      "metrics": {
        "oldest_msg_age_sec": 42.5
      }
    }
  ],
  "limits": {
    "max_queues": 25,
    "messages_month": 2000000,
    "max_message_bytes": 262144,
    "storage_bytes": 2147483648,
    "retention_days": 7
  },
  "usage": {
    "queues": 2,
    "stored_bytes": 3480
  }
}

POST/api/v1/queues

Create a queue.

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Body

descriptionstring | nulloptional
A note.
0–500 characters
visibility_timeout_secinteger | nulloptional
Seconds a read hides a message (default 30, ≤ 43,200).
0.0–43200.0
max_readsinteger | nulloptional
Reads after which a message that comes back is dead-lettered (null = never).
1.0–1000.0
dead_letter_queuestring | nulloptional
An existing queue that receives dead letters (else they are archived as dead).
0–48 characters
retention_daysinteger | nulloptional
Days archived messages are kept (≤ plan queues.retention_days).
1.0–365.0
app_sendboolean | nulloptional
Let app users and the anon key send (never read).
consumerobject | nulloptional
{function_name, enabled, batch_size, concurrency, visibility_timeout_sec, ack}: a function that gets batches of messages; ack archive or delete.
6 fields
function_namestring | nulloptional
The function's name.
0–128 characters
enabledboolean | nulloptional
batch_sizeinteger | nulloptional
1.0–100.0
concurrencyinteger | nulloptional
1.0–10.0
visibility_timeout_secinteger | nulloptional
10.0–43200.0
ackstring | nulloptional
One of archive, delete
namestringrequired
1–48 characters: lowercase letters, digits, _ or -, starting with a letter; unique per environment.
pattern `^[a-z][a-z0-9_-]{0,47}$`

Responses

  • 201Created.
  • 400Bad name or settings; the dead-letter queue has its own dead-letter queue.
  • 403The plan's queue limit (queues.max_queues) or retention.
  • 404The dead-letter queue doesn't exist.
  • 409A queue with that name exists.
  • 401No valid session or key.
  • 422The body is missing a required field or has a field of the wrong type.
curl -s -X POST "$URL/api/v1/queues" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name": "emails", "visibility_timeout_sec": 60, "max_reads": 5, "dead_letter_queue": "emails-dead", "consumer": {"function_name": "send-email", "batch_size": 10}}'
Response
{
  "queue_id": "3c9d1e7f2a4b4c6d8e0f1a2b3c4d5e6f",
  "org_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "project_id": "f0c3e9a2-1b4d-4e7f-8a6c-2d9b5e3f1a07",
  "env_id": "",
  "name": "emails",
  "description": "Outgoing mail",
  "visibility_timeout_sec": 60,
  "max_reads": 5,
  "dead_letter_queue": "emails-dead",
  "retention_days": null,
  "app_send": false,
  "consumer": {
    "function_name": "send-email",
    "enabled": true,
    "batch_size": 10,
    "concurrency": 2,
    "visibility_timeout_sec": null,
    "ack": "archive",
    "last_error": ""
  },
  "queue_length": 12,
  "stored_bytes": 3480,
  "sent_total": 940,
  "dead_total": 2,
  "created_by": "8b2c…",
  "created_at": 1791800000.0,
  "updated_at": 1791800000.0
}

GET/api/v1/queues/{name}

One queue with its settings, consumer and metrics.

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Responses

  • 200Success.
  • 404No such queue in this environment.
  • 401No valid session or key.
curl -s "$URL/api/v1/queues/welcome" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
  "queue_id": "3c9d1e7f2a4b4c6d8e0f1a2b3c4d5e6f",
  "org_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "project_id": "f0c3e9a2-1b4d-4e7f-8a6c-2d9b5e3f1a07",
  "env_id": "",
  "name": "emails",
  "description": "Outgoing mail",
  "visibility_timeout_sec": 60,
  "max_reads": 5,
  "dead_letter_queue": "emails-dead",
  "retention_days": null,
  "app_send": false,
  "consumer": {
    "function_name": "send-email",
    "enabled": true,
    "batch_size": 10,
    "concurrency": 2,
    "visibility_timeout_sec": null,
    "ack": "archive",
    "last_error": ""
  },
  "queue_length": 12,
  "stored_bytes": 3480,
  "sent_total": 940,
  "dead_total": 2,
  "created_by": "8b2c…",
  "created_at": 1791800000.0,
  "updated_at": 1791800000.0,
  "metrics": {
    "queue_name": "emails",
    "queue_length": 12,
    "visible": 9,
    "in_flight": 3,
    "delayed": 0,
    "oldest_msg_age_sec": 42.5,
    "newest_msg_age_sec": 1.2,
    "total_messages": 940,
    "archived": 915,
    "dead_lettered": 2,
    "stored_bytes": 3480,
    "scrape_time": 1792206000.0
  }
}

PATCH/api/v1/queues/{name}

Change a queue's settings or consumer (send only what changes).

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Body

descriptionstring | nulloptional
A note.
0–500 characters
visibility_timeout_secinteger | nulloptional
Seconds a read hides a message (default 30, ≤ 43,200).
0.0–43200.0
max_readsinteger | nulloptional
Reads after which a message that comes back is dead-lettered (null = never).
1.0–1000.0
dead_letter_queuestring | nulloptional
An existing queue that receives dead letters (else they are archived as dead).
0–48 characters
retention_daysinteger | nulloptional
Days archived messages are kept (≤ plan queues.retention_days).
1.0–365.0
app_sendboolean | nulloptional
Let app users and the anon key send (never read).
consumerobject | nulloptional
{function_name, enabled, batch_size, concurrency, visibility_timeout_sec, ack}: a function that gets batches of messages; ack archive or delete.
6 fields
function_namestring | nulloptional
The function's name.
0–128 characters
enabledboolean | nulloptional
batch_sizeinteger | nulloptional
1.0–100.0
concurrencyinteger | nulloptional
1.0–10.0
visibility_timeout_secinteger | nulloptional
10.0–43200.0
ackstring | nulloptional
One of archive, delete

Responses

  • 200Success.
  • 401No valid session or key.
  • 422The body is missing a required field or has a field of the wrong type.
curl -s -X PATCH "$URL/api/v1/queues/welcome" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"consumer": {"enabled": false}}'
Response
{
  "queue_id": "3c9d1e7f2a4b4c6d8e0f1a2b3c4d5e6f",
  "org_id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "project_id": "f0c3e9a2-1b4d-4e7f-8a6c-2d9b5e3f1a07",
  "env_id": "",
  "name": "emails",
  "description": "Outgoing mail",
  "visibility_timeout_sec": 60,
  "max_reads": 5,
  "dead_letter_queue": "emails-dead",
  "retention_days": null,
  "app_send": false,
  "consumer": {
    "function_name": "send-email",
    "enabled": false,
    "batch_size": 10,
    "concurrency": 2,
    "visibility_timeout_sec": null,
    "ack": "archive",
    "last_error": ""
  },
  "queue_length": 12,
  "stored_bytes": 3480,
  "sent_total": 940,
  "dead_total": 2,
  "created_by": "8b2c…",
  "created_at": 1791800000.0,
  "updated_at": 1791800000.0,
  "metrics": {
    "queue_name": "emails",
    "queue_length": 12,
    "visible": 9,
    "in_flight": 3,
    "delayed": 0,
    "oldest_msg_age_sec": 42.5,
    "newest_msg_age_sec": 1.2,
    "total_messages": 940,
    "archived": 915,
    "dead_lettered": 2,
    "stored_bytes": 3480,
    "scrape_time": 1792206000.0
  }
}

DELETE/api/v1/queues/{name}

Delete a queue and all its messages.

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Responses

  • 200Success.
  • 409Another queue uses it as its dead-letter queue.
  • 401No valid session or key.
curl -s -X DELETE "$URL/api/v1/queues/welcome" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
  "deleted": true,
  "name": "emails",
  "messages_deleted": 12
}

GET/api/v1/queues/{name}/metrics

Length, visible / in flight / delayed counts (up to 100,000), oldest and newest message age, totals.

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Responses

  • 200Success.
  • 401No valid session or key.
curl -s "$URL/api/v1/queues/welcome/metrics" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
  "queue_name": "emails",
  "queue_length": 12,
  "visible": 9,
  "in_flight": 3,
  "delayed": 0,
  "oldest_msg_age_sec": 42.5,
  "newest_msg_age_sec": 1.2,
  "total_messages": 940,
  "archived": 915,
  "dead_lettered": 2,
  "stored_bytes": 3480,
  "scrape_time": 1792206000.0
}

#Messages

POST/api/v1/queues/{name}/send

Send one message.

App users and the anon key may call this only for a queue with app_send on. Counts against queues.messages_month.

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Body

messageanyoptional
Any JSON value (≤ plan queues.max_message_bytes).
delaynumberoptionaldefault 0
Seconds before it can be read (≤ 7 days).
0.0–…
headersobject | nulloptional
An object kept with the message (≤ 4 KB).

Responses

  • 201Created.
  • 403Monthly messages or queues.storage_bytes used up.
  • 404No such queue (or app sends are off).
  • 413Message over the plan's size.
  • 401No valid session or key.
  • 422The body is missing a required field or has a field of the wrong type.
curl -s -X POST "$URL/api/v1/queues/welcome/send" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"message": {"to": "ada@example.com", "template": "welcome"}, "delay": 0}'
Response
{
  "msg_id": 41
}

POST/api/v1/queues/{name}/send_batch

Send up to 100 messages at once.

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Body

messagesarray<any>required
A list of JSON values.
1–100 items
delaynumberoptionaldefault 0
Seconds before they can be read.
0.0–…
headersobject | nulloptional
Kept with every message.

Responses

  • 201Created.
  • 401No valid session or key.
  • 422The body is missing a required field or has a field of the wrong type.
curl -s -X POST "$URL/api/v1/queues/welcome/send_batch" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"messages": [{"to": "a@example.com"}, {"to": "b@example.com"}]}'
Response
{
  "msg_ids": [
    42,
    43
  ]
}

POST/api/v1/queues/{name}/read

Read up to qty visible messages and hide them for vt seconds.

Archive or delete each message when done, or it becomes visible again. A message read max_reads times that comes back is moved to the dead-letter queue instead.

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Body

qtyintegeroptionaldefault 1
1–100 (default 1).
1.0–100.0
vtnumber | nulloptional
Seconds to hide them (default: the queue's).
0.0–43200.0

Responses

  • 200Success.
  • 401No valid session or key.
  • 422The body is missing a required field or has a field of the wrong type.
curl -s -X POST "$URL/api/v1/queues/welcome/read" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"qty": 10, "vt": 120}'
Response
{
  "messages": [
    {
      "msg_id": 41,
      "read_ct": 1,
      "enqueued_at": 1792205990.0,
      "vt": 1792206060.0,
      "message": {
        "to": "ada@example.com",
        "template": "welcome"
      },
      "headers": null
    }
  ]
}

POST/api/v1/queues/{name}/pop

Read and delete up to qty messages at once (at-most-once).

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Body

qtyintegeroptionaldefault 1
1–100.
1.0–100.0

Responses

  • 200Success.
  • 401No valid session or key.
  • 422The body is missing a required field or has a field of the wrong type.
curl -s -X POST "$URL/api/v1/queues/welcome/pop" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"qty": 1}'
Response
{
  "messages": [
    {
      "msg_id": 41,
      "read_ct": 1,
      "enqueued_at": 1792205990.0,
      "vt": 1792206060.0,
      "message": {
        "to": "ada@example.com",
        "template": "welcome"
      },
      "headers": null
    }
  ]
}

POST/api/v1/queues/{name}/archive

Archive messages (kept for the retention period).

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Body

msg_idsarray<integer>required
Message ids.
1–1000 items

Responses

  • 200Success.
  • 401No valid session or key.
  • 422The body is missing a required field or has a field of the wrong type.
curl -s -X POST "$URL/api/v1/queues/welcome/archive" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"msg_ids": [41]}'
Response
{
  "archived": [
    41
  ]
}

POST/api/v1/queues/{name}/delete

Delete messages.

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Body

msg_idsarray<integer>required
Message ids.
1–1000 items

Responses

  • 200Success.
  • 401No valid session or key.
  • 422The body is missing a required field or has a field of the wrong type.
curl -s -X POST "$URL/api/v1/queues/welcome/delete" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"msg_ids": [42]}'
Response
{
  "deleted": [
    42
  ]
}

DELETE/api/v1/queues/{name}/messages/{msg_id}

Delete one message.

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.
msg_idintegerrequired
The message.

Responses

  • 200Success.
  • 404No such message.
  • 401No valid session or key.
curl -s -X DELETE "$URL/api/v1/queues/welcome/messages/<msg_id>" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
  "deleted": [
    42
  ]
}

POST/api/v1/queues/{name}/set_vt

Hide a message for vt more seconds from now (0 = visible now).

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Body

msg_idintegerrequired
The message.
vtnumberrequired
Seconds.
0.0–43200.0

Responses

  • 200Success.
  • 404The message isn't waiting in this queue.
  • 401No valid session or key.
  • 422The body is missing a required field or has a field of the wrong type.
curl -s -X POST "$URL/api/v1/queues/welcome/set_vt" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"msg_id": 43, "vt": 300}'
Response
{
  "message": {
    "msg_id": 43,
    "read_ct": 1,
    "enqueued_at": 1792205990.0,
    "vt": 1792206060.0,
    "message": {
      "to": "ada@example.com",
      "template": "welcome"
    },
    "headers": null
  }
}

POST/api/v1/queues/{name}/purge

Delete every waiting message (and the archive with include_archived).

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Body

include_archivedbooleanoptionaldefault false
Also delete archived messages.

Responses

  • 200Success.
  • 401No valid session or key.
  • 422The body is missing a required field or has a field of the wrong type.
curl -s -X POST "$URL/api/v1/queues/welcome/purge" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"include_archived": false}'
Response
{
  "purged": 12
}

GET/api/v1/queues/{name}/messages

Look at messages without reading them.

Who
Your team or your backend: a member's session, or a server key (apikey: <service role or custom key>). Never from a browser or app.

Path parameters

namestringrequired
The queue.

Query parameters

statestringoptionaldefault waiting
waiting (incl. in flight), archived or dead.
One of waiting, archived, dead
limitintegeroptionaldefault 50
≤ 200.
1–200
beforeinteger | nulloptional
Page: the last msg_id shown.

Responses

  • 200Success.
  • 401No valid session or key.
curl -s "$URL/api/v1/queues/welcome/messages" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Response
{
  "messages": [
    {
      "msg_id": 41,
      "read_ct": 1,
      "enqueued_at": 1792205990.0,
      "vt": 1792206060.0,
      "message": {
        "to": "ada@example.com",
        "template": "welcome"
      },
      "headers": null,
      "archived_at": null,
      "dead_lettered": false,
      "in_flight": true
    }
  ],
  "next_before": null
}

Related

QueuesCron jobsEvent triggers