OneOS Docs
Genesis 0.1.13 Console

Guides

Queues and topics in Hives

Queues hold work until a consumer takes it. Topics fan one message out to every queue subscribed to them. In this guide you set up both in a new Hives project, wire them together, operate the queue and remove everything again.

You need an API key with hives:read and hives:write.

export GENESIS_API_KEY="sk_..."
export GENESIS_BASE_URL="https://os.one.ml/api"

1. Create a project

Queues and topics belong to a Hives project. Deleted projects keep their name while they finish deleting, so the name carries a timestamp and the guide can run again straight away.

PROJECT_ID=$(curl -sf -X POST "$GENESIS_BASE_URL/v1/hives/projects" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"orders-$(date +%s)\", \"kind\": \"function\"}" | jq -er .id)
echo "$PROJECT_ID"

Operation: hives_create_project.

2. Create a queue

type is standard, fifo or dead_letter. visibilityTimeout (seconds) is how long a received message stays hidden from other consumers, and maxReceiveCount caps how many times a message is received; deadLetterQueueId names a dead_letter queue in the same project.

QUEUE_ID=$(curl -sf -X POST "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/queues" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "orders", "type": "standard", "visibilityTimeout": 30, "maxReceiveCount": 5}' | jq -er .id)
echo "$QUEUE_ID"
Response (abridged)
{
  "id": "bzz_c08b2540e86042c8956db13a8a7c3ef1",
  "name": "orders",
  "type": "standard",
  "status": "active",
  "deliveryAvailable": true,
  "retentionPeriod": 604800,
  "visibilityTimeout": 30,
  "maxMessageSize": 262144,
  "maxReceiveCount": 5,
  "deadLetterQueueId": null,
  "messageCount": 0
}

Unset fields take their defaults: messages are kept for 604800 seconds (seven days) and can be up to 262144 bytes. Operation: hives_create_native_queue.

3. Create a topic and subscribe the queue

A subscription routes a topic to a queue. One topic can feed many queues.

TOPIC_ID=$(curl -sf -X POST "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/topics" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "order-events"}' | jq -er .id)

SUBSCRIPTION_ID=$(curl -sf -X POST "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/topics/$TOPIC_ID/subscriptions" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"queueId\": \"$QUEUE_ID\"}" | jq -er .id)

curl -sf "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/topics/$TOPIC_ID/subscriptions" \
  -H "Authorization: Bearer $GENESIS_API_KEY"
Response
{
  "data": [
    { "id": "sub_01a1584b6d3a73b0a6580eb7aad08daf", "projectId": "prj_dafb0ecd1aee45e78c51e3efa46d279a",
      "topicId": "top_01a1584b6bdc7f639be946144541df7b", "queueId": "bzz_c08b2540e86042c8956db13a8a7c3ef1",
      "createdAt": "2026-10-20T07:51:40.577854Z" }
  ]
}

Operations: hives_create_native_topic, hives_subscribe_native_topic, hives_subscriptions_native_topic.

4. Read the queue's stats and receive

Stats report how many messages are waiting, in flight and delayed. Receiving takes up to maxMessages messages; waitSeconds: 0 answers at once, even when the queue is empty.

curl -sf "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/stats" \
  -H "Authorization: Bearer $GENESIS_API_KEY" | jq '{status, messageCount, messagesProcessing, delayedMessages}'

curl -sf -X POST "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/messages/receive" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"maxMessages": 10, "waitSeconds": 0}'
Response
{ "status": "active", "messageCount": 0, "messagesProcessing": 0, "delayedMessages": 0 }
{ "messages": [] }

Organization API keys can't send messages straight to a queue: Hives answers 401 with code AUTHENTICATION_REQUIRED (tested with a full-scope key on 20 Oct 2026). Send them with a signed-in session (genesis login). Operations: hives_stats_native_queue, hives_receive_native_queue, hives_send_native_queue.

5. Pause, resume and purge

Pausing turns status to paused and deliveryAvailable to false; resuming turns them back. Purging empties the queue and reports how many messages it removed.

curl -sf -X POST "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/pause" \
  -H "Authorization: Bearer $GENESIS_API_KEY" | jq '{status, deliveryAvailable}'

curl -sf -X POST "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/resume" \
  -H "Authorization: Bearer $GENESIS_API_KEY" | jq '{status, deliveryAvailable}'

curl -sf -X POST "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/purge" \
  -H "Authorization: Bearer $GENESIS_API_KEY"
Response
{ "status": "paused", "deliveryAvailable": false }
{ "status": "active", "deliveryAvailable": true }
{ "purged": 0 }

Operations: hives_pause_native_queue, hives_resume_native_queue, hives_purge_native_queue.

6. Clean up

Remove the subscription, the topic and the queue, then the project. The first three answer {"deleted": true}; the project answers {"success": true, "id": "prj_...", ...} and finishes deleting in the background.

curl -sf -X DELETE "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/topics/$TOPIC_ID/subscriptions/$SUBSCRIPTION_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"
curl -sf -X DELETE "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/topics/$TOPIC_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"
curl -sf -X DELETE "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"
curl -sf -X DELETE "$GENESIS_BASE_URL/v1/hives/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Operations: hives_unsubscribe_native_topic, hives_delete_native_topic, hives_delete_native_queue, hives_delete_project.

Next

One Superintelligence, Inc. · Built from Genesis 0.1.13 and the live gateway on 2026-10-20. Support