canonical: https://jentic.com/apis/apache.org/qakka

# Apache Qakka

Qakka is the queue system originally developed inside the Apache Usergrid project. The HTTP API exposes queue lifecycle (create, configure, delete), message enqueue and dequeue, single-message lookup, acknowledgement, and a status endpoint. The surface is small (ten operations) and is intended for service-to-service messaging where a lightweight queue is enough and a full broker like Kafka or RabbitMQ would be overkill. The spec does not declare authentication or a base server URL; both are set by the deployment.

## For AI agents

Create and configure queues, send and receive messages, and acknowledge processed messages on a self-hosted Qakka deployment.

## Scope

Does not handle pub-sub topics, stream processing, or persistent log replay - use for queue lifecycle, message enqueue and dequeue, and acknowledgement only.

## Capabilities

- Create a named Qakka queue and update its configuration parameters
- List queues currently registered on the Qakka deployment
- Send a message into a queue and assign it a queueMessageId
- Receive one or more messages from a queue for processing
- Acknowledge a processed message so it is not redelivered
- Probe the Qakka /status endpoint to confirm the service is healthy

## Use cases

### Lightweight job queue for service-to-service work

Use Qakka as a small, self-hosted queue for background jobs that do not justify a Kafka or RabbitMQ deployment. The producer POSTs jobs to `/queues/{queueName}/messages`, workers pull messages from the same path, process them, and acknowledge via `/queues/{queueName}/messages/{queueMessageId}.` Suitable for in-process workflows that just need at-least-once delivery.

Example prompt: POST a job payload to `/queues/email-jobs/messages`, then on a worker poll GET `/queues/email-jobs/messages` and POST acknowledgement once the email is sent

### Queue health monitoring

Run a periodic check that the Qakka deployment is reachable and that critical queues exist. The agent calls /status to confirm the service is up and GET /queues to verify the expected queues are registered, alerting on absence. Useful in operations dashboards for self-hosted Apache Usergrid clusters.

Example prompt: GET /status every 60 seconds and alert if the response is not healthy, plus GET /queues and alert if a required queue name is missing

### Provision a queue from automation

Create and configure a Qakka queue from an infrastructure agent rather than a manual call. The agent POSTs to /queues with the queue name, then PATCHes `/queues/{queueName}/config` with retention and visibility settings, and verifies via GET `/queues/{queueName}` that the queue is registered correctly.

Example prompt: POST {name: 'invoices'} to /queues, then PATCH `/queues/invoices/config` with retention and visibility values and confirm via GET `/queues/invoices`

### AI agent integration via Jentic

An agent that needs to enqueue work into a self-hosted Qakka deployment can search Jentic for 'send a message to a queue' and Jentic returns the schema for `/queues/{queueName}/messages.` The deployment URL is held by Jentic, so the agent only supplies the queue name and the message body.

Example prompt: Search Jentic for 'send a message to a Qakka queue', load the `/queues/{queueName}/messages` schema, and POST the message body for the user-named queue

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/queues` | List queues on the deployment |
| POST | `/queues` | Create a new queue |
| GET | `/queues/{queueName}` | Fetch a single queue |
| POST | `/queues/{queueName}/messages` | Enqueue a message into a queue |
| GET | `/queues/{queueName}/messages` | Receive messages from a queue |
| GET | `/queues/{queueName}/messages/{queueMessageId}` | Fetch a specific queued message by id |
| GET | `/status` | Health probe for the Qakka service |

## Key resources

- **Queues** — Create, list, fetch, configure, and delete queues
- **Messages** — Send messages to a queue, receive them for processing, and acknowledge processed ids
- **Status** — Health and reachability probe for the Qakka deployment

## Why Jentic

- **Setup:** Wiring Qakka by hand means pointing at your own deployment, since the spec declares no security scheme, and mapping the queue lifecycle, enqueue, dequeue, and acknowledge routes yourself. Through Jentic you install once, import Qakka from the API Directory, store any deployment credential once, and your agent calls it.
- **Permission scoping:** Qakka puts the queue name in the URL path (`/queues/{queueName}/messages`), so a rule can pin your agent to one queue: it can enqueue and dequeue for that queue and nothing else. You choose the operations it may call, so queue creation is only included if you add it.
- **Credential handling:** Any deployment-level token or proxy credential for Qakka is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a message to a queue' or 'list queues', and Jentic returns the matching Qakka operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Airflow API (Stable)** — Workflow orchestration that can produce and consume Qakka messages from Airflow tasks.
- **Temporal API** — Durable workflow execution with built-in retries and signals.
- **GitHub API** — Manage the source repo for the consumer code that drains Qakka queues.

## FAQ

### What authentication does the Qakka API use?

The OpenAPI spec does not declare any security schemes, so authentication is whatever the Qakka deployment puts in front of the service (typically a network-level control or a reverse proxy enforcing a bearer token). Through Jentic any deployment-level credential can be stored in the encrypted Jentic One instance.

### Can I send and receive messages with the Qakka API?

Yes. POST to `/queues/{queueName}/messages` enqueues a message and GET on the same path receives messages for a worker to process. After processing, acknowledge the specific message id via `/queues/{queueName}/messages/{queueMessageId}.`

### How do I enqueue a message through Jentic?

Search Jentic for 'send a message to a Qakka queue', load the schema for POST `/queues/{queueName}/messages`, and execute it with the queue name and message body. Jentic resolves the deployment URL and any auth attached to the integration.

### What are the rate limits for the Qakka API?

Qakka itself does not declare rate limits; throughput is bounded by the deployment's hosts and the underlying storage. Limits in practice come from any reverse proxy or load balancer in front of the service.

### Is the Qakka API free to use?

Qakka is part of the Apache Usergrid project and is open source under the Apache 2.0 license, so the API is free. Costs are the infrastructure to run it.

### Does Qakka guarantee message ordering or exactly-once delivery?

The spec defines enqueue, receive, and acknowledgement primitives but does not promise strict ordering or exactly-once semantics; Qakka is at-least-once, like most lightweight queues. Consumers need to be idempotent on the queueMessageId.

### Can I limit what my agent is allowed to do with the Qakka API?

Yes. Because Jentic One is self-hosted, your own rules decide which Qakka operations and credentials the agent may use. Since Qakka puts the queue name in the URL path (`/queues/{queueName}/messages`), a rule can pin the agent to a single queue so it can only enqueue and dequeue messages there. You also choose which operations are exposed, so queue creation and configuration are available to the agent only if you explicitly include them.