Agentuity Documentation

Publish, consume, and manage messages with worker and pub/sub queues.

Region

https://catalyst-usw.agentuity.cloud

Authentication

All requests require a Bearer token. Pass your SDK key in the Authorization header.

Header	Value
`Authorization`	`Bearer YOUR_SDK_KEY`

You can find your SDK key in the Agentuity Console under your project settings.

Queue Management

Create Queue

Create a queue. If name is omitted, a name is auto-generated.

POST/queue/create

https://catalyst-usw.agentuity.cloud/queue/create

Request Body

Queue creation payload.

Field	Type	Description
`name`	string	Optional queue name (auto-generated if not provided). (optional)
`description`	string	Optional description of the queue's purpose. (optional)
`queue_type`	string	Type of queue to create.
`settings`	object	Optional settings to customize queue behavior (server applies defaults for missing fields). (optional)
`settings.default_ttl_seconds`	number \| null	Default time-to-live for messages in seconds. Null means no expiration. (optional)
`settings.default_visibility_timeout_seconds`	number	Time in seconds a message is invisible after being received. (optional)
`settings.default_max_retries`	number	Maximum number of delivery attempts before moving to DLQ. (optional)
`settings.default_retry_backoff_ms`	number	Initial backoff delay in milliseconds for retries. (optional)
`settings.default_retry_max_backoff_ms`	number	Maximum backoff delay in milliseconds for retries. (optional)
`settings.default_retry_multiplier`	number	Multiplier for exponential backoff. (optional)
`settings.max_in_flight_per_client`	number	Maximum number of messages a single client can process concurrently. (optional)
`settings.retention_seconds`	number	Retention period for acknowledged messages in seconds. (optional)

Response

Queue object including settings, stats, and timestamps.

Status	Description
200	Queue created
401	Unauthorized
402	Payment required

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/queue/create' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "order-processing",
  "queue_type": "worker",
  "description": "Processes customer orders",
  "settings": {
    "default_max_retries": 3,
    "default_visibility_timeout_seconds": 60
  }
}'

Get Queue

Get a queue by name.

GET/queue/get/{name}

https://catalyst-usw.agentuity.cloud/queue/get/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

Response

Queue object.

Status	Description
200	Queue returned
401	Unauthorized
404	Queue not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/get/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Queues

List queues with filtering and pagination.

GET/queue/list

https://catalyst-usw.agentuity.cloud/queue/list

Parameters

query

Name	Type	Required	Description
`limit`	number	No	Maximum queues to return
`offset`	number	No	Offset for pagination
`name`	string	No	Filter by queue name
`queue_type`	string	No	`worker` or `pubsub`
`status`	string	No	`active` or `paused`
`sort`	string	No	Sort field
`direction`	string	No	`asc` or `desc`

Response

Response with queue array and optional total count.

Status	Description
200	Queues returned
401	Unauthorized

Response Fields

Field	Type	Description
`queues`	object[]	Queues in the current page
`queues[].id`	string	Unique identifier for the queue.
`queues[].name`	string	Human-readable queue name (used for API operations).
`queues[].description`	string \| null	Optional description of the queue's purpose. (optional)
`queues[].internal`	boolean	Whether the queue is system-managed. (optional)
`queues[].queue_type`	string	The type of queue (worker or pubsub).
`queues[].default_ttl_seconds`	number \| null	Default time-to-live for messages in seconds. Null means no expiration. (optional)
`queues[].default_visibility_timeout_seconds`	number	Time in seconds a message is invisible after being received. (optional)
`queues[].default_max_retries`	number	Maximum number of delivery attempts before moving to DLQ. (optional)
`queues[].default_retry_backoff_ms`	number	Initial backoff delay in milliseconds for retries. (optional)
`queues[].default_retry_max_backoff_ms`	number	Maximum backoff delay in milliseconds for retries. (optional)
`queues[].default_retry_multiplier`	number	Multiplier for exponential backoff. (optional)
`queues[].max_in_flight_per_client`	number	Maximum number of messages a single client can process concurrently. (optional)
`queues[].next_offset`	number	The next offset that will be assigned to a new message. (optional)
`queues[].message_count`	number	Total number of messages currently in the queue. (optional)
`queues[].dlq_count`	number	Number of messages in the dead letter queue. (optional)
`queues[].created_at`	string	ISO 8601 timestamp when the queue was created.
`queues[].updated_at`	string	ISO 8601 timestamp when the queue was last updated.
`queues[].paused_at`	string \| null	ISO 8601 timestamp when the queue was paused (null if not paused). (optional)
`queues[].retention_seconds`	number	Retention period for acknowledged messages in seconds. (optional)
`total`	number	Optional total queue count (optional)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/list?limit=10&queue_type=worker' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Update Queue

Partially update queue description/settings.

PATCH/queue/update/{name}

https://catalyst-usw.agentuity.cloud/queue/update/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

Request Body

Partial queue update payload.

Field	Type	Description
`description`	string	New description for the queue. (optional)
`settings`	object	Settings to update (partial update supported, only provided fields are updated). (optional)
`settings.default_ttl_seconds`	number \| null	Default time-to-live for messages in seconds. Null means no expiration. (optional)
`settings.default_visibility_timeout_seconds`	number	Time in seconds a message is invisible after being received. (optional)
`settings.default_max_retries`	number	Maximum number of delivery attempts before moving to DLQ. (optional)
`settings.default_retry_backoff_ms`	number	Initial backoff delay in milliseconds for retries. (optional)
`settings.default_retry_max_backoff_ms`	number	Maximum backoff delay in milliseconds for retries. (optional)
`settings.default_retry_multiplier`	number	Multiplier for exponential backoff. (optional)
`settings.max_in_flight_per_client`	number	Maximum number of messages a single client can process concurrently. (optional)
`settings.retention_seconds`	number	Retention period for acknowledged messages in seconds. (optional)

Response

Updated queue object.

Status	Description
200	Queue updated
401	Unauthorized
404	Queue not found

Example

curl -X PATCH 'https://catalyst-usw.agentuity.cloud/queue/update/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Updated",
  "settings": {
    "default_max_retries": 5
  }
}'

Delete Queue

Delete a queue and associated resources.

DELETE/queue/delete/{name}

https://catalyst-usw.agentuity.cloud/queue/delete/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

Response

Empty response on success.

Status	Description
200	Queue deleted
401	Unauthorized
404	Queue not found

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/queue/delete/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Pause Queue

Pause queue processing.

POST/queue/pause/{name}

https://catalyst-usw.agentuity.cloud/queue/pause/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

Request Body

Empty JSON object is required.

Response

Queue object with paused_at set.

Status	Description
200	Queue paused
401	Unauthorized
404	Queue not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/queue/pause/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

Resume Queue

Resume queue processing.

POST/queue/resume/{name}

https://catalyst-usw.agentuity.cloud/queue/resume/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

Request Body

Empty JSON object is required.

Response

Queue object with paused_at cleared.

Status	Description
200	Queue resumed
401	Unauthorized
404	Queue not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/queue/resume/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'

Message Operations

Publish Message

Publish a single message to a queue.

POST/queue/messages/publish/{name}

https://catalyst-usw.agentuity.cloud/queue/messages/publish/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

query

Name	Type	Required	Description
`sync`	boolean	No	Set `true` for synchronous publish

Request Body

Message payload and optional delivery controls.

Field	Type	Description
`payload`	any	The message payload (JSON object).
`metadata`	object	Optional metadata to attach to the message. (optional)
`idempotency_key`	string	Optional key for deduplication (prevents duplicate messages). (optional)
`partition_key`	string	Optional key for message ordering within a partition. (optional)
`ttl_seconds`	number	Optional time-to-live in seconds. (optional)

Response

Published message object.

Status	Description
200	Message published
401	Unauthorized
404	Queue not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/queue/messages/publish/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "payload": {
    "orderId": 123,
    "action": "process"
  },
  "metadata": {
    "priority": "high"
  }
}'

Batch Publish

Publish up to 1000 messages in one request.

POST/queue/messages/batch/{name}

https://catalyst-usw.agentuity.cloud/queue/messages/batch/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

Request Body

Batch publish payload.

Field	Type	Description
`messages`	object[]	Array of messages to publish (max 1000 per batch).
`messages[].payload`	any	The message payload (JSON object).
`messages[].metadata`	object	Optional metadata to attach to the message. (optional)
`messages[].idempotency_key`	string	Optional key for deduplication (prevents duplicate messages). (optional)
`messages[].partition_key`	string	Optional key for message ordering within a partition. (optional)
`messages[].ttl_seconds`	number	Optional time-to-live in seconds. (optional)

Response

Batch publish response with created messages and optional failed indexes.

Status	Description
200	Batch publish completed
401	Unauthorized
404	Queue not found

Response Fields

Field	Type	Description
`messages`	object[]	Published messages
`messages[].id`	string	Unique identifier for the message (prefixed with qmsg_).
`messages[].queue_id`	string	ID of the queue this message belongs to.
`messages[].offset`	number	Sequential offset within the queue.
`messages[].payload`	any	The message payload (JSON object).
`messages[].size`	number	Size of the message payload in bytes. (optional)
`messages[].metadata`	object \| null	Optional metadata attached to the message. (optional)
`messages[].state`	string	Current state of the message. (optional)
`messages[].idempotency_key`	string \| null	Optional key for message deduplication. (optional)
`messages[].partition_key`	string \| null	Optional key for message ordering. (optional)
`messages[].ttl_seconds`	number \| null	Time-to-live in seconds (null means no expiration). (optional)
`messages[].delivery_attempts`	number	Number of times delivery has been attempted. (optional)
`messages[].max_retries`	number	Maximum number of delivery attempts allowed. (optional)
`messages[].published_at`	string	ISO 8601 timestamp when the message was published. (optional)
`messages[].expires_at`	string \| null	ISO 8601 timestamp when the message will expire (if TTL set). (optional)
`messages[].delivered_at`	string \| null	ISO 8601 timestamp when the message was delivered. (optional)
`messages[].acknowledged_at`	string \| null	ISO 8601 timestamp when the message was acknowledged. (optional)
`messages[].created_at`	string	ISO 8601 timestamp when the message was created. (optional)
`messages[].updated_at`	string	ISO 8601 timestamp when the message was last updated. (optional)
`messages[].source_id`	string \| null	ID of the source that ingested this message (null if published directly). (optional)
`messages[].source_name`	string \| null	Name of the source that ingested this message. (optional)
`failed`	number[]	Indexes that failed (optional)

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/queue/messages/batch/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "messages": [
    {
      "payload": {
        "orderId": 1
      }
    },
    {
      "payload": {
        "orderId": 2
      }
    }
  ]
}'

Get Message

Get a message by message ID (msg_...).

GET/queue/messages/get/{name}/{messageId}

https://catalyst-usw.agentuity.cloud/queue/messages/get/{name}/{messageId}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name
`messageId`	string	Yes	Message ID (`msg_...`)

Response

Message object.

Status	Description
200	Message returned
401	Unauthorized
404	Message or queue not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/messages/get/order-processing/msg_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Message by Offset

Get a message by numeric offset.

GET/queue/messages/offset/{name}/{offset}

https://catalyst-usw.agentuity.cloud/queue/messages/offset/{name}/{offset}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name
`offset`	number	Yes	Message offset

Response

Message object.

Status	Description
200	Message returned
401	Unauthorized
404	Message or queue not found

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/messages/offset/order-processing/42' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Messages

List messages with pagination and optional state filter.

GET/queue/messages/list/{name}

https://catalyst-usw.agentuity.cloud/queue/messages/list/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

query

Name	Type	Required	Description
`limit`	number	No	Maximum messages to return
`offset`	number	No	Offset for pagination
`state`	string	No	`pending`, `processing`, `completed`, `failed`, or `dead`

Response

Response with message list and optional total count.

Status	Description
200	Messages returned
401	Unauthorized
404	Queue not found

Response Fields

Field	Type	Description
`messages`	object[]	Messages in current page
`messages[].id`	string	Unique identifier for the message (prefixed with qmsg_).
`messages[].queue_id`	string	ID of the queue this message belongs to.
`messages[].offset`	number	Sequential offset within the queue.
`messages[].payload`	any	The message payload (JSON object).
`messages[].size`	number	Size of the message payload in bytes. (optional)
`messages[].metadata`	object \| null	Optional metadata attached to the message. (optional)
`messages[].state`	string	Current state of the message. (optional)
`messages[].idempotency_key`	string \| null	Optional key for message deduplication. (optional)
`messages[].partition_key`	string \| null	Optional key for message ordering. (optional)
`messages[].ttl_seconds`	number \| null	Time-to-live in seconds (null means no expiration). (optional)
`messages[].delivery_attempts`	number	Number of times delivery has been attempted. (optional)
`messages[].max_retries`	number	Maximum number of delivery attempts allowed. (optional)
`messages[].published_at`	string	ISO 8601 timestamp when the message was published. (optional)
`messages[].expires_at`	string \| null	ISO 8601 timestamp when the message will expire (if TTL set). (optional)
`messages[].delivered_at`	string \| null	ISO 8601 timestamp when the message was delivered. (optional)
`messages[].acknowledged_at`	string \| null	ISO 8601 timestamp when the message was acknowledged. (optional)
`messages[].created_at`	string	ISO 8601 timestamp when the message was created. (optional)
`messages[].updated_at`	string	ISO 8601 timestamp when the message was last updated. (optional)
`messages[].source_id`	string \| null	ID of the source that ingested this message (null if published directly). (optional)
`messages[].source_name`	string \| null	Name of the source that ingested this message. (optional)
`total`	number	Optional total message count (optional)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/messages/list/order-processing?limit=20&state=pending' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Message

Delete a message by ID.

DELETE/queue/messages/delete/{name}/{messageId}

https://catalyst-usw.agentuity.cloud/queue/messages/delete/{name}/{messageId}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name
`messageId`	string	Yes	Message ID

Response

Empty response on success.

Status	Description
200	Message deleted
401	Unauthorized
404	Message or queue not found

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/queue/messages/delete/order-processing/msg_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Replay Message

Replay a message back into the queue flow.

POST/queue/messages/replay/{name}/{messageId}

https://catalyst-usw.agentuity.cloud/queue/messages/replay/{name}/{messageId}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name
`messageId`	string	Yes	Message ID

Response

Replayed message object.

Status	Description
200	Message replayed
401	Unauthorized
404	Message or queue not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/queue/messages/replay/order-processing/msg_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Consume Messages

Log-style consumption starting from offset. Does not mark messages as processing.

GET/queue/consume/{name}

https://catalyst-usw.agentuity.cloud/queue/consume/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

query

Name	Type	Required	Description
`offset`	number	Yes	Starting offset
`limit`	number	No	Maximum messages to return

Response

Response containing consumed messages.

Status	Description
200	Messages consumed
401	Unauthorized
404	Queue not found

Response Fields

Field	Type	Description
`messages`	object[]	Consumed messages
`messages[].id`	string	Unique identifier for the message (prefixed with qmsg_).
`messages[].queue_id`	string	ID of the queue this message belongs to.
`messages[].offset`	number	Sequential offset within the queue.
`messages[].payload`	any	The message payload (JSON object).
`messages[].size`	number	Size of the message payload in bytes. (optional)
`messages[].metadata`	object \| null	Optional metadata attached to the message. (optional)
`messages[].state`	string	Current state of the message. (optional)
`messages[].idempotency_key`	string \| null	Optional key for message deduplication. (optional)
`messages[].partition_key`	string \| null	Optional key for message ordering. (optional)
`messages[].ttl_seconds`	number \| null	Time-to-live in seconds (null means no expiration). (optional)
`messages[].delivery_attempts`	number	Number of times delivery has been attempted. (optional)
`messages[].max_retries`	number	Maximum number of delivery attempts allowed. (optional)
`messages[].published_at`	string	ISO 8601 timestamp when the message was published. (optional)
`messages[].expires_at`	string \| null	ISO 8601 timestamp when the message will expire (if TTL set). (optional)
`messages[].delivered_at`	string \| null	ISO 8601 timestamp when the message was delivered. (optional)
`messages[].acknowledged_at`	string \| null	ISO 8601 timestamp when the message was acknowledged. (optional)
`messages[].created_at`	string	ISO 8601 timestamp when the message was created. (optional)
`messages[].updated_at`	string	ISO 8601 timestamp when the message was last updated. (optional)
`messages[].source_id`	string \| null	ID of the source that ingested this message (null if published directly). (optional)
`messages[].source_name`	string \| null	Name of the source that ingested this message. (optional)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/consume/order-processing?offset=0&limit=10' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Receive Message

Atomically receive and lock the next pending message. Must ack/nack when done.

GET/queue/receive/{name}

https://catalyst-usw.agentuity.cloud/queue/receive/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

query

Name	Type	Required	Description
`timeout`	number	No	Long-poll timeout in seconds (0–30)

Response

Response containing a message or null when none available.

Status	Description
200	Receive operation completed
401	Unauthorized
404	Queue not found

Response Fields

Field	Type	Description
`message`	object \| null	Received message if available

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/receive/order-processing?timeout=10' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Acknowledge Message

Mark message as successfully processed (completed).

POST/queue/ack/{name}/{messageId}

https://catalyst-usw.agentuity.cloud/queue/ack/{name}/{messageId}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name
`messageId`	string	Yes	Message ID

Response

Empty response on success.

Status	Description
200	Message acknowledged
401	Unauthorized
404	Message or queue not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/queue/ack/order-processing/msg_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Negative Acknowledge

Return message for retry. After max retries, moves to DLQ.

POST/queue/nack/{name}/{messageId}

https://catalyst-usw.agentuity.cloud/queue/nack/{name}/{messageId}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name
`messageId`	string	Yes	Message ID

Response

Empty response on success.

Status	Description
200	Message negatively acknowledged
401	Unauthorized
404	Message or queue not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/queue/nack/order-processing/msg_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Queue Head

Get offset of the oldest message.

GET/queue/head/{name}

https://catalyst-usw.agentuity.cloud/queue/head/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

Response

JSON object containing the head offset.

Status	Description
200	Queue head returned
401	Unauthorized
404	Queue not found

Response Fields

Field	Type	Description
`offset`	number	Oldest message offset

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/head/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Get Queue Tail

Get offset of the newest message.

GET/queue/tail/{name}

https://catalyst-usw.agentuity.cloud/queue/tail/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

Response

JSON object containing the tail offset.

Status	Description
200	Queue tail returned
401	Unauthorized
404	Queue not found

Response Fields

Field	Type	Description
`offset`	number	Newest message offset

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/tail/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Destinations

Create Destination

Create an HTTP destination for queue deliveries.

POST/queue/destinations/create/{name}

https://catalyst-usw.agentuity.cloud/queue/destinations/create/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

Request Body

Destination creation payload.

Field	Type	Description
`name`	string	Human-readable name for the destination.
`description`	string	Optional description of the destination. (optional)
`destination_type`	string	Type of destination to create.
`config`	object	HTTP configuration for the destination.
`config.url`	string	The URL to send messages to.
`config.headers`	object	Optional custom headers to include in requests. (optional)
`config.method`	string	HTTP method to use (default: POST).
`config.timeout_ms`	number	Request timeout in milliseconds (default: 30000).
`config.retry_policy`	object	Optional retry policy for failed deliveries. (optional)
`config.retry_policy.max_attempts`	number	Maximum number of delivery attempts (default: 5).
`config.retry_policy.initial_backoff_ms`	number	Initial backoff delay in milliseconds (default: 1000).
`config.retry_policy.max_backoff_ms`	number	Maximum backoff delay in milliseconds (default: 60000).
`config.retry_policy.backoff_multiplier`	number	Backoff multiplier for exponential backoff (default: 2.0).
`config.signing`	object	Optional request signing configuration. (optional)
`config.signing.enabled`	boolean	Whether signing is enabled (default: false).
`config.signing.secret_key`	string	Secret key for HMAC signing. (optional)
`enabled`	boolean	Whether the destination should be enabled (default: true).

Response

Created destination object.

Status	Description
200	Destination created
401	Unauthorized
404	Queue not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/queue/destinations/create/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "my-webhook",
  "destination_type": "http",
  "config": {
    "url": "https://example.com/webhook"
  },
  "enabled": true
}'

List Destinations

List queue destinations.

GET/queue/destinations/list/{name}

https://catalyst-usw.agentuity.cloud/queue/destinations/list/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

Response

Response containing destination list.

Status	Description
200	Destinations returned
401	Unauthorized
404	Queue not found

Response Fields

Field	Type	Description
`destinations`	object[]	Configured destinations
`destinations[].id`	string	Unique identifier for the destination (prefixed with qdest_).
`destinations[].name`	string	Human-readable name for the destination.
`destinations[].description`	string \| null	Optional description of the destination. (optional)
`destinations[].queue_id`	string	ID of the queue this destination is attached to.
`destinations[].destination_type`	string	Type of destination (currently only 'http').
`destinations[].config`	object	HTTP configuration for the destination.
`destinations[].config.url`	string	The URL to send messages to.
`destinations[].config.headers`	object	Optional custom headers to include in requests. (optional)
`destinations[].config.method`	string	HTTP method to use (default: POST).
`destinations[].config.timeout_ms`	number	Request timeout in milliseconds (default: 30000).
`destinations[].config.retry_policy`	object	Optional retry policy for failed deliveries. (optional)
`destinations[].config.retry_policy.max_attempts`	number	Maximum number of delivery attempts (default: 5).
`destinations[].config.retry_policy.initial_backoff_ms`	number	Initial backoff delay in milliseconds (default: 1000).
`destinations[].config.retry_policy.max_backoff_ms`	number	Maximum backoff delay in milliseconds (default: 60000).
`destinations[].config.retry_policy.backoff_multiplier`	number	Backoff multiplier for exponential backoff (default: 2.0).
`destinations[].config.signing`	object	Optional request signing configuration. (optional)
`destinations[].config.signing.enabled`	boolean	Whether signing is enabled (default: false).
`destinations[].config.signing.secret_key`	string	Secret key for HMAC signing. (optional)
`destinations[].enabled`	boolean	Whether the destination is enabled for delivery.
`destinations[].stats`	object	Delivery statistics for this destination. (optional)
`destinations[].stats.total_deliveries`	number	Total number of delivery attempts.
`destinations[].stats.successful_deliveries`	number	Number of successful deliveries.
`destinations[].stats.failed_deliveries`	number	Number of failed deliveries.
`destinations[].stats.last_delivery_at`	string \| null	ISO 8601 timestamp of the last delivery attempt. (optional)
`destinations[].stats.last_success_at`	string \| null	ISO 8601 timestamp of the last successful delivery. (optional)
`destinations[].stats.last_failure_at`	string \| null	ISO 8601 timestamp of the last failed delivery. (optional)
`destinations[].success_count`	number	Total successful deliveries. (optional)
`destinations[].failure_count`	number	Total failed deliveries. (optional)
`destinations[].last_success_at`	string \| null	ISO 8601 timestamp of last success. (optional)
`destinations[].last_failure_at`	string \| null	ISO 8601 timestamp of last failure. (optional)
`destinations[].last_failure_error`	string \| null	Error message from last failure. (optional)
`destinations[].created_at`	string	ISO 8601 timestamp when the destination was created.
`destinations[].updated_at`	string	ISO 8601 timestamp when the destination was last updated.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/destinations/list/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Update Destination

Partially update destination fields.

PATCH/queue/destinations/update/{name}/{destinationId}

https://catalyst-usw.agentuity.cloud/queue/destinations/update/{name}/{destinationId}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name
`destinationId`	string	Yes	Destination ID

Request Body

Partial destination update payload.

Response

Updated destination object.

Status	Description
200	Destination updated
401	Unauthorized
404	Queue or destination not found

Example

curl -X PATCH 'https://catalyst-usw.agentuity.cloud/queue/destinations/update/order-processing/dst_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "timeout_seconds": 20
}'

Delete Destination

Delete a queue destination.

DELETE/queue/destinations/delete/{name}/{destinationId}

https://catalyst-usw.agentuity.cloud/queue/destinations/delete/{name}/{destinationId}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name
`destinationId`	string	Yes	Destination ID

Response

Empty response on success.

Status	Description
200	Destination deleted
401	Unauthorized
404	Queue or destination not found

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/queue/destinations/delete/order-processing/dst_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Delivery Logs

List destination delivery logs with optional status filter.

GET/queue/destinations/deliveries/{name}/{destinationId}

https://catalyst-usw.agentuity.cloud/queue/destinations/deliveries/{name}/{destinationId}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name
`destinationId`	string	Yes	Destination ID

query

Name	Type	Required	Description
`limit`	number	No	Maximum logs to return
`offset`	number	No	Offset for pagination
`status`	string	No	Delivery status filter

Response

Response containing delivery log entries.

Status	Description
200	Delivery logs returned
401	Unauthorized
404	Queue or destination not found

Response Fields

Field	Type	Description
`deliveries`	object[]	Delivery log entries
`deliveries[].id`	string	Unique identifier for the delivery attempt.
`deliveries[].destination_id`	string	ID of the destination this delivery was sent to.
`deliveries[].queue_id`	string	ID of the queue.
`deliveries[].message_id`	string	ID of the message that was delivered.
`deliveries[].payload`	any	Payload delivered to the destination. (optional)
`deliveries[].status`	string	Status of the delivery attempt.
`deliveries[].http_status_code`	number \| null	HTTP status code from the destination. (optional)
`deliveries[].error`	string \| null	Error message if delivery failed. (optional)
`deliveries[].duration_ms`	number	Duration of the delivery attempt in milliseconds. (optional)
`deliveries[].attempt_number`	number	Which attempt number this was (1-based). (optional)
`deliveries[].request_headers`	object	Request headers sent to the destination. (optional)
`deliveries[].response_headers`	object	Response headers from the destination. (optional)
`deliveries[].delivered_at`	string	ISO 8601 timestamp when the delivery was attempted.
`deliveries[].created_at`	string	ISO 8601 timestamp when the log entry was created.

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/destinations/deliveries/order-processing/dst_abc123?limit=20' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Dead Letter Queue

List DLQ Messages

List dead-letter queue messages.

GET/queue/dlq/list/{name}

https://catalyst-usw.agentuity.cloud/queue/dlq/list/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

query

Name	Type	Required	Description
`limit`	number	No	Maximum messages to return
`offset`	number	No	Offset for pagination

Response

Response containing DLQ messages and optional total.

Status	Description
200	DLQ messages returned
401	Unauthorized
404	Queue not found

Response Fields

Field	Type	Description
`messages`	object[]	DLQ messages
`messages[].id`	string	Unique identifier for the DLQ entry.
`messages[].queue_id`	string	ID of the queue this message belongs to.
`messages[].original_message_id`	string	ID of the original message that failed (optional until backend includes it). (optional)
`messages[].offset`	number	Offset of the original message in the queue.
`messages[].payload`	any	The message payload (JSON object).
`messages[].metadata`	object \| null	Optional metadata from the original message. (optional)
`messages[].failure_reason`	string \| null	Reason why the message was moved to DLQ. (optional)
`messages[].delivery_attempts`	number	Number of delivery attempts before failure.
`messages[].moved_at`	string	ISO 8601 timestamp when the message was moved to DLQ (optional until backend includes it). (optional)
`messages[].original_published_at`	string	ISO 8601 timestamp when the original message was published (optional, falls back to published_at). (optional)
`messages[].published_at`	string	ISO 8601 timestamp when the message was published (from base message). (optional)
`messages[].created_at`	string	ISO 8601 timestamp when the DLQ entry was created.
`total`	number	Optional total DLQ message count (optional)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/queue/dlq/list/order-processing?limit=20' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Replay DLQ Message

Replay a DLQ message back to the queue.

POST/queue/dlq/replay/{name}/{messageId}

https://catalyst-usw.agentuity.cloud/queue/dlq/replay/{name}/{messageId}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name
`messageId`	string	Yes	DLQ message ID

Response

Replayed message object.

Status	Description
200	DLQ message replayed
401	Unauthorized
404	Queue or message not found

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/queue/dlq/replay/order-processing/msg_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Purge DLQ

Delete all messages in the dead-letter queue.

DELETE/queue/dlq/purge/{name}

https://catalyst-usw.agentuity.cloud/queue/dlq/purge/{name}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name

Response

Empty response on success.

Status	Description
200	DLQ purged
401	Unauthorized
404	Queue not found

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/queue/dlq/purge/order-processing' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete DLQ Message

Delete a specific message from the dead-letter queue.

DELETE/queue/dlq/delete/{name}/{messageId}

https://catalyst-usw.agentuity.cloud/queue/dlq/delete/{name}/{messageId}

Parameters

path

Name	Type	Required	Description
`name`	string	Yes	Queue name
`messageId`	string	Yes	DLQ message ID

Response

Empty response on success.

Status	Description
200	DLQ message deleted
401	Unauthorized
404	Queue or message not found

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/queue/dlq/delete/order-processing/msg_abc123' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'