# mqlite for AI agents

You have access to a message queue (an mqlite broker).

Base URL:  <MQLITE_ENDPOINT>              the broker's origin, including the port.
           Direct:  http://127.0.0.1:6754   (mqlite serves JSON-over-HTTP on TCP 6754
                                             and terminates no TLS of its own)
           Proxied: https://mq.example.com  (HTTPS :443 at a reverse proxy, which
                                             forwards to the broker's internal :6754)
           Endpoint paths below are relative to this origin.
Auth:      every call needs the header    Authorization: Bearer <MQLITE_TOKEN>
Protocol:  every operation is ONE HTTP POST with a JSON body to
           /mqlite.v1.QueueService/<Method>, /mqlite.v1.AdminService/<Method>,
           or /mqlite.v1.AuthService/<Method> (v0.3.1 and later).
           GET / (no auth) returns a discovery card listing every endpoint.

Rules:
- Key rights: send produces/schedules/cancels; listen receives/settles/renews/peeks
  and reads queue stats; manage includes both and administration/key issuance.
  Rights apply across the broker. Do not retry 401 or 403; obtain a valid key
  with the required permission from an administrator.
- On v0.3.2+, AdminService/Observe {} reads broker measurements using a configured
  monitor credential or manage key. Check collection/availability fields; missing
  measurements are not zero. Monitor credentials cannot read message bodies.
- Message bodies are BASE64 strings in JSON. Encode before sending,
  decode after receiving.
- Queues never auto-create. Create first:
    AdminService/CreateQueue  {"name":"jobs","config":{}}
- Consume with Peek-Lock:
    QueueService/Receive  {"queue":"jobs","max_messages":1,"wait_time_ms":5000}
  Each returned message has seq_number + lock_token. You MUST settle every
  message you receive, using its lock_token:
    QueueService/Complete {"queue":"jobs","seq_number":N,"lock_token":"..."}  done
    QueueService/Abandon  {...,"delay_ms":60000}   retry later (optional backoff)
    QueueService/Reject   {...}                    give up -> dead-letter queue
  If you settle nothing, the lock expires (default 30s). Recovery returns the
  message to active, or sends it to the DLQ at its delivery limit.
  New settlements and Renew require locked_until_ms > now: the exact deadline
  is already expired, even before the reaper runs. An unexpired receipt only lets
  the exact request replay a previously committed settlement after expiry.
- Receive-and-Delete grants no lease: lock_token is empty and locked_until_ms
  is zero (omitted in JSON), including receive-attempt replays. Do not settle it.
- Default Peek-Lock delivery is AT-LEAST-ONCE: you may see a message twice.
  Make your handling idempotent (set message_id on send; check your own state
  before acting).
- Long-running work: call QueueService/Renew with the lock_token to extend the
  lock before it expires.
- Pub/sub: AdminService/Subscribe {"topic":"events","name":"my-sub",
  "filter":{"expr":"subject == \"order\""}} — then Send to "events" fans out;
  Receive from "my-sub". Filter may be omitted (match all).
- Ordered work: send with "group_id" — messages sharing a group_id are
  delivered strictly in order, one in flight per group. Abandon with delay_ms > 0
  parks the message in scheduled and keeps blocking its ordered group until due
  (strict_fifo: the whole queue). Cancel only removes never-delivered scheduled
  messages, with delivery_count = 0.
- Errors are JSON {"code","message"}: 400 invalid_argument · 401 unauthenticated ·
  403 permission_denied · 404 not_found ·
  409 name_conflict / already_exists / lock_lost / key_conflict ·
  413 message_too_large. On 409 lock_lost, re-Receive instead of retrying
  the settle.

Cheat sheet (request bodies abbreviated):
  AdminService/CreateQueue   {"name","config":{}}
  AdminService/ListQueues    {}
  AdminService/Subscribe     {"topic","name","filter?"}
  QueueService/Send          {"queue","messages":[{"body":"<base64>",
                              "message_id?","group_id?"}]}
  QueueService/Receive       {"queue","max_messages","wait_time_ms"}
  QueueService/Complete      {"queue","seq_number","lock_token"}
  QueueService/Abandon       {"queue","seq_number","lock_token","delay_ms?"}
  QueueService/Reject        {"queue","seq_number","lock_token"}
  QueueService/Renew         {"queue","seq_number","lock_token"}
  QueueService/Stats         {"queue"}
  AuthService/CreateKey      {"id","name","permissions":["send"],"expires_at_ms?"}
  AuthService/ListKeys       {"after_id?","limit?","sort?"}
  AuthService/RevokeKey      {"id"}
  For CreateKey: retain a unique 32-lowercase-hex id BEFORE the call. Token is
  returned once. On an uncertain result, list/revoke that id before replacing;
  a repeated id returns key_conflict and never returns the secret again.
  For ListKeys: sort defaults to id_asc. Use created_desc for newest first,
  keep the same sort on every page, and pass next_after_id back as after_id.
Full reference: https://github.com/mqlitehq/mqlite/blob/main/docs/api-reference.md