OKMQ - Getting Started Guide

Free Tier Includes

• 100 MB storage
• 100,000 messages
• 1 channel (queue or stream)
• 1 concurrent consumer

1. Get Your API Key

Sign up for an account, then create an API key in the dashboard under API Keys — it is shown once at creation, so copy it immediately. Use this key in the Authorization header for all requests.

Authorization: your-api-key

2. Quick Start (No Setup Required)

Try OKMQ right now with simple HTTP requests. No SDK installation needed.


# Set your API key
export TOKEN="your-api-key"

# Create a queue
curl -X POST https://api.okmq.net/queues \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-queue", "auto_ack": true}'

# Send a message
curl -X POST https://api.okmq.net/queues/my-queue/messages \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id": "msg-1", "body": "Hello, OKMQ!"}]'

# Receive messages
curl https://api.okmq.net/queues/my-queue/messages \
  -H "Authorization: $TOKEN"

That's it! You've just created a queue, sent a message, and received it.

3. Generate a Type-Safe Client (Optional)

For production use, we recommend generating a type-safe client from our OpenAPI specification. This gives you autocomplete, type checking, and a better developer experience.

Download OpenAPI Spec

Download the OpenAPI specification

For TypeScript/JavaScript:


# Generate the TypeScript client (no installation needed)
npx @hey-api/openapi-ts \
  -i openapi.yaml \
  -o ./client \
  -c @hey-api/client-fetch


// Now use the generated client
import { postQueues } from './client'
import { client } from './client/client.gen'

// Configure authentication
client.setConfig({
  headers: {
    authorization: process.env.OKMQ_API_KEY || ''
  }
})

// Create a queue (async/await - no callbacks!)
await postQueues({
  body: {
    name: 'my-queue',
    auto_ack: true,
    ttl: 300
  }
})

console.log('Queue created successfully')

For Other Languages:

For Python, Go, Java, Rust, and other languages, use your preferred OpenAPI client generator:


# Python
pip install openapi-python-client
openapi-python-client generate --path openapi.yaml

# Go
go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
oapi-codegen -package okmq openapi.yaml > okmq.go

# Java, Ruby, Rust, etc. (50+ languages supported)
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -i openapi.yaml -g  -o ./client

Benefits of Generated Clients

Full type safety and autocomplete in your IDE
Automatic request/response validation
No manual URL construction or header management
Catch API misuse at compile time, not runtime

4. Create a Queue

Let's create a queue for processing email notifications. This example shows how to set up a queue with automatic acknowledgment and a 5-minute TTL.


import { postQueues } from './client'
import { client } from './client/client.gen'

// Configure authentication
client.setConfig({
  headers: {
    authorization: process.env.OKMQ_API_KEY || ''
  }
})

// Create email notifications queue
await postQueues({
  body: {
    name: 'email-notifications',
    auto_ack: true,
    ttl: 300 // 5 minutes
  }
})

console.log('Queue created successfully')

5. Send a Message

Now let's send an email notification message to the queue. Messages are sent as JSON arrays, allowing you to send multiple messages in a single request.


import { postQueuesByQueueMessages } from './client'

const sendEmailNotification = async (userEmail, subject, body) => {
  await postQueuesByQueueMessages({
    path: { queue: 'email-notifications' },
    body: [{
      id: `email-${Date.now()}`,
      body: JSON.stringify({
        to: userEmail,
        subject: subject,
        body: body,
        priority: 'normal'
      })
    }]
  })

  console.log('Email notification queued')
}

// Send a welcome email notification
await sendEmailNotification(
  'user@example.com',
  'Welcome to our service!',
  'Thank you for signing up...'
)

6. Process Messages

Create a worker process to continuously poll for new messages and process them. This example shows how to process email notifications.


import { getQueuesByQueueMessages } from './client'

const processEmailNotifications = async () => {
  while (true) {
    try {
      const response = await getQueuesByQueueMessages({
        path: { queue: 'email-notifications' }
      })

      const data = response.data

      if (Array.isArray(data) && data.length > 0) {
        // Process messages only if data is an array with items
        for (const message of data) {
          console.log('Processing email:', message.id)

          // Process the email notification
          const emailData = JSON.parse(message.body)
          await sendEmail(emailData.to, emailData.subject, emailData.body)

          console.log(`Email sent to ${emailData.to}`)
        }
      }

    } catch (error) {
      console.error('Error processing messages:', error)
    }
  }
}

// Simulated email sending function
const sendEmail = async (to, subject, body) => {
  // Your email sending logic here
  console.log(`Sending email to ${to}: ${subject}`)
}

// Start processing
processEmailNotifications()

Complete Example

Here's a complete working example that demonstrates creating a queue, sending messages, and processing them:


import { postQueues, getQueuesByQueueMessages, postQueuesByQueueMessages } from './client'
import { client } from './client/client.gen'

// Configure authentication
client.setConfig({
  headers: {
    authorization: process.env.OKMQ_API_KEY || ''
  }
})

const main = async () => {
  // Create the queue
  await postQueues({
    body: {
      name: 'email-notifications',
      auto_ack: true,
      ttl: 300
    }
  })

  // Start processing messages in the background
  const processMessages = async () => {
    while (true) {
      try {
        const response = await getQueuesByQueueMessages({
          path: { queue: 'email-notifications' }
        })

        const data = response.data
        if (Array.isArray(data) && data.length > 0) {
          for (const message of data) {
            const emailData = JSON.parse(message.body)
            console.log('Processing:', emailData.subject)
            // Process your email here
          }
        }

      } catch (error) {
        console.error('Error processing:', error)
      }
    }
  }
  processMessages()

  // Send test messages every 5 seconds
  setInterval(async () => {
    try {
      await postQueuesByQueueMessages({
        path: { queue: 'email-notifications' },
        body: [{
          id: `email-${Date.now()}`,
          body: JSON.stringify({
            to: 'user@example.com',
            subject: `Test email ${Date.now()}`,
            body: 'Test message'
          })
        }]
      })
    } catch (error) {
      console.error('Error sending:', error)
    }
  }, 5000)
}

main()

Error Handling

OKMQ returns standard HTTP status codes. Here are the most common responses you'll encounter:

Status	Meaning	Example Response
`200`	Success	Request completed successfully
`201`	Created	Queue or stream created successfully
`401`	Unauthorized	`{"type": "https://okmq.net/problems/unauthorized", "title": "Unauthorized", "status": 401, "detail": "invalid authorization token", "instance": "/queues"}`
`404`	Not Found	`{"type": "https://okmq.net/problems/queue-not-found", "title": "Queue Not Found", "status": 404, "detail": "queue not found", "instance": "/queues"}`
`409`	Conflict	`{"type": "https://okmq.net/problems/queue-exists", "title": "Queue Already Exists", "status": 409, "detail": "queue already exists", "instance": "/queues"}`
`413`	Quota Exceeded	`{"type": "https://okmq.net/problems/messages-quota-exceeded", "title": "Message Quota Exceeded", "status": 413, "detail": "account messages quota exceeded", "instance": "/queues"}`


// Example: Handle common errors
const createQueue = async (name) => {
  const response = await fetch('https://api.okmq.net/queues', {
    method: 'POST',
    headers: {
      authorization: process.env.OKMQ_API_KEY,
      'content-type': 'application/json'
    },
    body: JSON.stringify({ name, auto_ack: true })
  })

  if (response.status === 409) {
    const problem = await response.json()
    if (problem.type === 'https://okmq.net/problems/queue-exists') {
      console.log('Queue already exists, continuing...')
      return
    }
    throw new Error(`Conflict: ${problem.detail}`)
  }

  if (response.status === 413) {
    const problem = await response.json()
    throw new Error(`Quota exceeded: ${problem.detail}`)
  }

  if (!response.ok) {
    const problem = await response.json()
    throw new Error(`Failed to create queue: ${problem.detail}`)
  }

  console.log('Queue created successfully')
}

List Your Queues and Streams

View all your queues and streams to monitor your messaging infrastructure.


# List all queues
curl https://api.okmq.net/queues -H "Authorization: $TOKEN"

# List all streams
curl https://api.okmq.net/streams -H "Authorization: $TOKEN"

# Get account info and usage
curl https://api.okmq.net/account -H "Authorization: $TOKEN"

Getting Started Guide