IronMQ REST/HTTP API

IronMQ provides a REST/HTTP API to allow you to interact programmatically with your queues on IronMQ.

Table of Contents

Endpoints

URLHTTP VerbPurpose
/projects/{Project ID}/queues GET List Message Queues
/projects/{Project ID}/queues/{Queue Name} GET Get Info About a Message Queue
/projects/{Project ID}/queues/{Queue Name} POST Update a Message Queue
/projects/{Project ID}/queues/{Queue Name} DELETE Delete a Message Queue
/projects/{Project ID}/queues/{Queue Name}/clear POST Clear All Messages from a Queue
/projects/{Project ID}/queues/{Queue Name}/messages POST Add Messages to a Queue
/projects/{Project ID}/queues/{Queue Name}/messages/webhook POST Add Messages to a Queue via Webhook
/projects/{Project ID}/queues/{Queue Name}/messages GET Get Messages from a Queue
/projects/{Project ID}/queues/{Queue Name}/messages/{Message ID} GET Get Message by ID
/projects/{Project ID}/queues/{Queue Name}/messages/{Message ID} DELETE Delete a Message from a Queue
/projects/{Project ID}/queues/{Queue Name}/messages DELETE Delete Multiple Messages from a Queue
/projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/touch POST Touch a Message on a Queue
/projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/release POST Release a Message on a Queue

Related to Pull Queues

URL HTTP Verb Purpose
/projects/{Project ID}/queues/{Queue Name}/alerts POST Add Alerts to a Queue
/projects/{Project ID}/queues/{Queue Name}/alerts PUT Replace Alerts on a Queue
/projects/{Project ID}/queues/{Queue Name}/alerts DELETE Remove Alerts from a Queue
/projects/{Project ID}/queues/{Queue Name}/alerts/{Alert ID} DELETE Remove Alert from a Queue by ID

Related to Push Queues

URL HTTP Verb Purpose
/projects/{Project ID}/queues/{Queue Name}/subscribers POST Add Subscribers to a Queue
/projects/{Project ID}/queues/{Queue Name}/subscribers DELETE Remove Subscribers from a Queue
/projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/subscribers GET Get Push Status for a Message
/projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/subscribers/{Subscriber ID} DELETE Delete Push Message for a Subscriber

Authentication

IronMQ uses OAuth2 tokens to authenticate API requests. All methods require authentication unless specified otherwise. You can find and create your API tokens in the HUD. To authenticate your request, you should include a token in the Authorization header for your request or in your query parameters. Tokens are universal, and can be used across services.

Note that each request also requires a Project ID to specify which project the action will be performed on. You can find your Project IDs in the HUD. Project IDs are also universal, so they can be used across services as well.

Example Authorization Header: Authorization: OAuth abc4c7c627376858

Example Query with Parameters: GET https://mq-aws-us-east-1.iron.io/1/projects/{Project ID}/queues?oauth=abc4c7c627376858

Notes:

  • Be sure you have the correct case, it's OAuth, not Oauth.
  • In URL parameter form, this will be represented as: ?oauth=abc4c7c627376858

Requests

Requests to the API are simple HTTP requests against the API endpoints.

All request bodies should be in JSON format, with Content-Type of application/json.

Base URL

All endpoints should be prefixed with the following:

https://{Host}.iron.io/{API Version}/

API Version Support : IronMQ API supports version 1

The hosts for the clouds IronMQ supports are as follows:

Cloud Host
AWS US-EAST mq-aws-us-east-1.iron.io
AWS EU-WEST mq-aws-eu-west-1.iron.io
Rackspace ORD mq-rackspace-ord.iron.io
Rackspace LON mq-rackspace-lon.iron.io
Rackspace DFW Pro Plans Only - Contact Us

Alternative domains can be found here in case of dns failures.

Pagination

For endpoints that return lists/arrays of values:

  • page - The page of results to return. Default is 0. Maximum is 100.
  • per_page - The number of results to return. It may be less if there aren't enough results. Default is 30. Maximum is 100.

Responses

All responses are in JSON, with Content-Type of application/json. A response is structured as follows:

{ "msg": "some success or error message" }

Status Codes

The success failure for request is indicated by an HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates an error.

CodeStatus
200OK: Successful GET
201Created: Successful POST
400Bad Request: Invalid JSON (can't be parsed or has wrong types).
401Unauthorized: The OAuth token is either not provided or invalid.
403Project suspected, resource limits.
404Not Found: The resource, project, or endpoint being requested doesn’t exist.
405Invalid HTTP method: A GET, POST, DELETE, or PUT was sent to an endpoint that doesn’t support that particular verb.
406Not Acceptable: Required fields are missing.
503Service Unavailable. Clients should implement exponential backoff to retry the request.

Specific endpoints may provide other errors in other situations.

When there's an error, the response body contains a JSON object something like:

{ "msg": "reason for error" }

Exponential Backoff

When a 503 error code is returned, it signifies that the server is currently unavailable. This means there was a problem processing the request on the server-side; it makes no comment on the validity of the request. Libraries and clients should use exponential backoff when confronted with a 503 error, retrying their request with increasing delays until it succeeds or a maximum number of retries (configured by the client) has been reached.

List Message Queues

Get a list of all queues in a project. By default, 30 queues are listed at a time. To see more, use the page parameter or the per_page parameter. Up to 100 queues may be listed on a single page.

Endpoint

GET /projects/{Project ID}/queues

URL Parameters

  • Project ID: Project these queues belong to

Optional URL Parameters

  • page: The 0-based page to view. The default is 0.
  • per_page: The number of queues to return per page. The default is 30, the maximum is 100.

Response

[
  {
    "id": "1234567890abcdef12345678",
    "project_id": "1234567890abcdef12345678",
    "name": "queue name"
  }
]

Get Info About a Message Queue

This call gets general information about the queue.

Endpoint

GET /projects/{Project ID}/queues/{Queue Name}

URL Parameters

  • Project ID: Project the queue belongs to
  • Queue Name: Name of the queue

Response

{
  "size": "queue size"
}

Delete a Message Queue

This call deletes a message queue and all its messages.

Endpoint

DELETE /projects/{Project ID}/queues/{Queue Name}

URL Parameters

  • Project ID: Project the queue belongs to
  • Queue Name: Name of the queue

Response

{
  "msg": "Deleted."
}

Update a Message Queue

This allows you to change the properties of a queue including setting subscribers and the push type if you want it to be a push queue.

Endpoint

POST /projects/{Project ID}/queues/{Queue Name}

URL Parameters

  • Project ID: Project the queue belongs to
  • Queue Name: Name of the queue. If the queue does not exist, it will be created for you.
WARNING: Do not use the following RFC 3986 Reserved Characters within your in the naming of your queues.

! * ' ( ) ; : @ & = + $ , / ? # [ ]

Body Parameters

Optional

The following parameters are all related to Push Queues.

  • subscribers: An array of subscriber hashes containing a required "url" field and an optional "headers" map for custom headers. This set of subscribers will replace the existing subscribers. See Push Queues to learn more about types of subscribers. To add or remove subscribers, see the add subscribers endpoint or the remove subscribers endpoint. The maximum is 64kb for JSON array of subscribers' hashes. See below for example JSON.
  • push_type: Either multicast to push to all subscribers or unicast to push to one and only one subscriber. Default is multicast. To revert push queue to reqular pull queue set pull.
  • retries: How many times to retry on failure. Default is 3. Maximum is 100.
  • retries_delay: Delay between each retry in seconds. Default is 60.
  • error_queue: The name of another queue where information about messages that can't be delivered after retrying retries number of times will be placed. Pass in an empty string to disable error queues. Default is disabled. See Push Queues to learn more.

Request

{
  "push_type":"multicast",
   "subscribers": [
     {"url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_1"},
     {
        "url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_2",
        "headers": {"Content-Type": "application/json"}
     }
   ]
}

Response

{
  "id":"50eb546d3264140e8638a7e5",
  "name":"pushq-demo-1",
  "size":7,
  "total_messages":7,
  "project_id":"4fd2729368a0197d1102056b",
  "retries":3,
  "push_type":"multicast",
  "retries_delay":60,
  "subscribers":[
    {"url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_1"},
    {"url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_2", "headers": {"Content-Type": "application/json"}}
  ]
}

Add Alerts to a Queue

Add alerts to a queue. This is for Pull Queue only.

POST /projects/{Project ID}/queues/{Queue Name}/alerts/
Optional
  • alerts: An array of alert hashes containing required "type", "queue", "trigger", and optional "direction", "snooze" fields. Maximum number of alerts is 5. See Queue Alerts to learn more.

Request

{
   "alerts": [
     {
       "type": "fixed",
       "direction": "asc",
       "trigger": 1000,
       "queue": "my_queue_for_alerts"
     }
   ]
}

Response

{
  "msg": "Alerts were added."
}

Replace Alerts on a Queue

Replace current queue alerts with a given list of alerts. This is for Pull Queue only.

PUT /projects/{Project ID}/queues/{Queue Name}/alerts/

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of queue.

Body Parameters

Optional
  • alerts: An array of alerts hashes containing required "type", "queue", "trigger", and optional "direction", "snooze" fields. Maximum number of alerts is 5. See Queue Alerts to learn more.

Request

{
   "alerts": [
     {
       "type": "progressive",
       "direction": "desc",
       "trigger": 1000,
       "queue": "my_queue_for_alerts"
     }
   ]
}

Note: to clear all alerts on a queue send an empty alerts array like so:

{
  "alerts": []
}

Response

{
  "msg": "Alerts were replaced."
}

Remove Alerts from a Queue

Remove alerts from a queue. This is for Pull Queue only.

DELETE /projects/{Project ID}/queues/{Queue Name}/alerts/

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of queue.

Body Parameters

Optional
  • alerts: An array of alerts hashes containing "id" field. See Queue Alerts to learn more.

Request

{
   "alerts": [
     {"id": "5eee546df4a4140e8638a7e5"}
   ]
}

Response

{
  "msg": "Alerts were deleted."
}

Remove Alert from a Queue by ID

Remove alert from a queue by its ID. This is for Pull Queue only.

DELETE /projects/{Project ID}/queues/{Queue Name}/alerts/{Alert ID}

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of queue.
  • Alert ID: The id of the alert to delete.

Response

{
  "msg": "Alerts were deleted."
}

Add Subscribers to a Queue

Add subscribers (HTTP endpoints) to a queue. This is for Push Queues only.

Endpoint

POST /projects/{Project ID}/queues/{Queue Name}/subscribers

URL Parameters

  • Project ID: Project the queue belongs to
  • Queue Name: Name of the queue. If the queue does not exist, it will be created for you.

Body Parameters

Optional

The following parameters are all related to Push Queues.

  • subscribers: An array of subscriber hashes containing a required "url" field and an optional "headers" map for custom headers. See below for example. See Push Queues to learn more about types of subscribers.

Request

{
   "subscribers": [
     {
        "url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_2",
        "headers": {"Content-Type": "application/json"}
     }
   ]
}

Response

{
  "id":"50eb546d3264140e8638a7e5",
  "name":"pushq-demo-1",
  "size":7,
  "total_messages":7,
  "project_id":"4fd2729368a0197d1102056b",
  "retries":3,
  "push_type":"multicast",
  "retries_delay":60,
  "subscribers":[
    {"url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_1"},
    {"url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_2", "headers": {"Content-Type": "application/json"}}
  ]
}

Remove Subscribers from a Queue

Remove subscriber from a queue. This is for Push Queues only.

Endpoint

DELETE /projects/{Project ID}/queues/{Queue Name}/subscribers

URL Parameters

  • Project ID: Project the queue belongs to
  • Queue Name: Name of the queue. If the queue does not exist, it will be created for you.

Body Parameters

Optional

The following parameters are all related to Push Queues.

  • subscribers: An array of subscriber hashes containing a "url" field. See below for example.

Request

{
   "subscribers": [
     {"url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_2"}
   ]
}

Response

{
  "id":"50eb546d3264140e8638a7e5",
  "name":"pushq-demo-1",
  "size":7,
  "total_messages":7,
  "project_id":"4fd2729368a0197d1102056b",
  "retries":3,
  "push_type":"multicast",
  "retries_delay":60,
  "subscribers":[
    {"url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_1"}
  ]
}

Clear All Messages from a Queue

This call deletes all messages on a queue, whether they are reserved or not.

Endpoint

POST /projects/{Project ID}/queues/{Queue Name}/clear

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of the queue.

Response

{
  "msg": "Cleared"
}

Add Messages to a Queue

This call adds or pushes messages onto the queue.

Endpoint

POST /projects/{Project ID}/queues/{Queue Name}/messages

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of the queue. If the queue does not exist, it will be created for you.

Message Object

Multiple messages may be added in a single request, provided that the messages should all be added to the same queue. Each message object should contain the following keys:

Required
  • body: The message data
Optional
  • timeout: After timeout (in seconds), item will be placed back onto queue. You must delete the message from the queue to ensure it does not go back onto the queue. Default is 60 seconds. Minimum is 30 seconds, and maximum is 86,400 seconds (24 hours).
  • delay: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days).
  • expires_in: How long in seconds to keep the item on the queue before it is deleted. Default is 604,800 seconds (7 days). Maximum is 2,592,000 seconds (30 days).

Request

{
  "messages": [
    {
      "body": "This is my message 1."
    },
    {
      "body": "This is my message 2.",
      "timeout": 30,
      "delay": 2,
      "expires_in": 86400
    }
  ]
}

Response

{
  "ids": ["message 1 ID", "message 2 ID"],
  "msg": "Messages put on queue."
}

Add Messages to a Queue via Webhook

By adding the queue URL below to a third party service that supports webhooks, every webhook event that the third party posts will be added to your queue. The request body as is will be used as the "body" parameter in normal POST to queue above.

Endpoint

POST /projects/{Project ID}/queues/{Queue Name}/messages/webhook

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of the queue. If the queue does not exist, it will be created for you.

Get Messages from a Queue

This call gets/reserves messages from the queue. The messages will not be deleted, but will be reserved until the timeout expires. If the timeout expires before the messages are deleted, the messages will be placed back onto the queue. As a result, be sure to delete the messages after you're done with them.

Endpoint

GET /projects/{Project ID}/queues/{Queue Name}/messages

URL Parameters

  • Project ID: The Project these messages belong to.
  • Queue Name: The name of queue.

Optional Parameters

  • n: The maximum number of messages to get. Default is 1. Maximum is 100. Note: You may not receive all n messages on every request, the more sparse the queue, the less likely you are to receive all n messages.
  • timeout: After timeout (in seconds), item will be placed back onto queue. You must delete the message from the queue to ensure it does not go back onto the queue. If not set, value from POST is used. Default is 60 seconds, minimum is 30 seconds, and maximum is 86,400 seconds (24 hours).
  • wait: Time in seconds to wait for a message to become available. This enables long polling. Default is 0 (does not wait), maximum is 30.
  • delete: true/false. This will delete the message on get. Be careful though, only use this if you are ok with losing a message if something goes wrong after you get it. Default is false.

Sample Request

GET /projects/{Project ID}/queues/{Queue Name}/messages?n=10&timeout=120

Response

{
  "messages": [
    {
       "id": 1,
       "body": "first message body",
       "timeout": 600,
       "reserved_count": 1,
       "push_status": {"retries_remaining": 1}
    },
    {
       "id": 2,
       "body": "second message body",
       "timeout": 600,
       "reserved_count": 1,
       "push_status": {"retries_remaining": 1}
    }
  ]
}

Get Message by ID

Get a message by ID.

Endpoint

GET /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}

URL Parameters

  • Project ID: The Project these messages belong to.
  • Queue Name: The name of queue.
  • Message ID: The id of the message to release.

Sample Request

GET /projects/4ccf55250948510894024119/queues/test_queue/messages/5981787539458424851

Response

{
  "id": "5924625841136130921",
  "body": "hello 265",
  "timeout": 60,
  "status":"deleted",
  "reserved_count": 1
}

Release a Message on a Queue

Releasing a reserved message unreserves the message and puts it back on the queue as if the message had timed out.

Endpoint

POST /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/release

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of queue.
  • Message ID: The id of the message to release.

Body Parameters

  • delay: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days).

Request Body

{
  "delay": 60
}

A JSON document body is required even if all parameters are omitted.

{}

Response

{
  "msg": "Released"
}

Touch a Message on a Queue

Touching a reserved message extends its timeout to the duration specified when the message was created. Default is 60 seconds.

Endpoint

POST /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/touch

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of queue.
  • Message ID: The id of the message to touch.

Request

Any empty JSON body.

{}

Response

{
  "msg": "Touched"
}

Delete a Message from a Queue

This call will delete the message. Be sure you call this after you're done with a message or it will be placed back on the queue.

Endpoint

DELETE /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of queue.
  • Message ID: The id of the message to delete.

Response

{
  "msg": "Deleted"
}

Delete Multiple Messages from a Queue

This call will delete multiple messages in one call.

Endpoint

DELETE /projects/{Project ID}/queues/{Queue Name}/messages

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of queue.

Body Parameters

  • ids: An array of message ids as string.

Request Body

{
  "ids": [
    "MESSAGE_ID_1",
    "MESSAGE_ID_2"
  ]
}

Response

{
  "msg": "Deleted"
}

Get Push Status for a Message

You can retrieve the push status for a particular message which will let you know which subscribers have received the message, which have failed, how many times it's tried to be delivered and the status code returned from the endpoint.

GET /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/subscribers

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of queue.
  • Message ID: The id of the message to retrieve status for.

Response

{
  "subscribers":[
    {
      "retries_delay":60,
      "retries_remaining":2,
      "status_code":200,
      "status":"deleted",
      "url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_2",
      "id":"5831237764476661217"
    },
    {
      "retries_delay":60,
      "retries_remaining":2,
      "status_code":200,
      "status":"deleted",
      "url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_1",
      "id":"5831237764476661218"
    }
  ]
}

Acknowledge / Delete Push Message for a Subscriber

This is only for use with long running processes that have previously returned a 202. Read Push Queues page for more information on Long Running Processes

DELETE /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/subscribers/{Subscriber ID}

URL Parameters

  • Project ID: The project these messages belong to.
  • Queue Name: The name of queue.
  • Message ID: The id of the message.
  • Subscriber ID: The id of the subscriber to delete.

Response

{
  "msg": "Deleted"
}