Get next message to process

Returns the single oldest message that needs processing.

What It Returns

The oldest message that is NOT processed, including:

• New messages (no delivery status yet)
• Delivered messages (acknowledged but not started)
• Processing messages (stuck/crashed - supports crash recovery)
• Failed messages (available for retry)

Returns 204 No Content if there are no messages to process.

Workflow

This is the primary endpoint for agent reasoning loops:

1. GET /messages/next → Get next work item
2. POST /messages/{id}/processing → Required: Mark as processing
3. Process the message (reasoning loop, tool calls, etc.)
4. POST /messages/{id}/processed → Mark as done, OR POST /messages/{id}/failed → Mark as failed with error message
5. Loop back to step 1

Delivery Semantics (at-least-once)

Delivery is at-least-once. The same message can be returned more than once: after a crash or reconnect (processing messages are re-served for recovery), or when multiple clients poll with the same API key. Make your processing idempotent — deduplicate by message id when a repeated run would have side effects.

Crash Recovery

If your agent crashes while processing, the message stays in processing state. When restarted, calling /next will return that same stuck message (oldest first), allowing the agent to reclaim and retry it.

Difference from GET /messages

• GET /messages returns all actionable messages (for batch processing or queue inspection)
• GET /messages/next returns one message (for sequential processing loops)

Both use the same filter logic: everything that is NOT processed.