IronMQ REST/HTTP API

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

Endpoints

Related to Push Queues

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://{Domain}.iron.io/1

The domains for the clouds IronMQ supports are as follows:

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.

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

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

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

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

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. This set of subscribers will replace the existing subscribers. To add or remove subscribers, see the add subscribers endpoint or the remove subscribers endpoint. The maximum is 64kb for JSONify 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.

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"}
   ]
}

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"}
  ]
}

Add Subscribers to a Queue

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

Endpoint

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"},
    {"url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_2"}
  ]
}

Remove Subscribers from a Queue

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

Endpoint

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

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

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

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

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.
• 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).

Sample Request

Response

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

Peek Messages on a Queue

Peeking at a queue returns the next messages on the queue, but it does not reserve them.

Endpoint

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 peek. Default is 1. Maximum is 100.

Sample Request

Response

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

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

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

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

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"
}

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.

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

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"
}