IronWorker REST HTTP API

IronWorker provides a RESTful HTTP API to allow you to interact programmatically with our service and your workers.

Endpoints

Code Packages

URL HTTP Verb Purpose
/projects/{Project ID}/codes GET List Code Packages
/projects/{Project ID}/codes POST Upload or Update a Code Package
/projects/{Project ID}/codes/{Code ID} GET Get Info About A Code Package
/projects/{Project ID}/codes/{Code ID} DELETE Delete a Code Package
/projects/{Project ID}/codes/{Code ID}/download GET Download a Code Package
/projects/{Project ID}/codes/{Code ID}/revisions GET List Code Package Revisions

Tasks

URLHTTP VerbPurpose
/projects/{Project ID}/tasks GET List Tasks
/projects/{Project ID}/tasks POST Queue a Task
/projects/{Project ID}/tasks/webhook POST Queue a Task from a Webhook
/projects/{Project ID}/tasks/{Task ID} GET Get Info About a Task
/projects/{Project ID}/tasks/{Task ID}/log GET Get a Task's Log
/projects/{Project ID}/tasks/{Task ID}/cancel POST Cancel a Task
/projects/{Project ID}/tasks/{Task ID}/progress POST Set a Task's Progress
/projects/{Project ID}/tasks/{Task ID}/retry POST Retry a Task

Scheduled Tasks

URLHTTP VerbPurpose
/projects/{Project ID}/schedules GET List Scheduled Tasks
/projects/{Project ID}/schedules POST Schedule a Task
/projects/{Project ID}/schedules/{Schedule ID} GET Get Info About a Scheduled Task
/projects/{Project ID}/schedules/{Schedule ID}/cancel POST Cancel a Scheduled Task

Stacks

URLHTTP VerbPurpose
/stacks GET List of available stacks

Authentication

IronWorker uses OAuth2 tokens to authenticate API requests. 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

Note: Be sure you have the correct case: it's OAuth, not Oauth.

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

Requests

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

All request bodies should be in JSON format.

Unless otherwise noted, all requests should use the following headers (in addition to their authentication): - Accept : application/json - Accept-Encoding : gzip/deflate - Content-Type : application/json

Base URL

All endpoints should be prefixed with the following:

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

API Version Support : IronWorker API supports version 2

The domains for the clouds Iron Worker supports are as follows:

Cloud{Host}
AWSworker-aws-us-east-1

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 a Content-Type of application/json. Your requests should all contain an Accept: application/json header to accommodate the responses.

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
200Success
401Invalid authentication: The OAuth token is either not provided or invalid.
403Project suspected, resource limits.
404Invalid endpoint: 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.
406Invalid request: Required fields are missing.

Errors

In the event of an error, the appropriate status code will be returned with a body containing more information. An error response is structured as follows:

{
    "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.

Dates and Times

All dates, times, and timestamps will use the ISO 8601 / RFC 3339 format.

Code Packages

Your workers are run against code packages that can be updated and deleted over time. The code packages define the functionality a worker has through the code they contain. Put simply, code packages are simply the code that will run when your worker runs.

List Code Packages

Endpoint

GET /projects/{Project ID}/codes

URL Parameters

  • Project ID: The ID of the project whose code packages you want to get a list of.

Optional Query Parameters

  • page: The page of code packages you want to retrieve, starting from 0. Default is 0, maximum is 100.
  • per_page: The number of code packages to return per page. Note this is a maximum value, so there may be fewer packages returned if there aren’t enough results. Default is 30, maximum is 100.

Response

The response will be a JSON object. The "codes" property will contain a JSON array of objects, each representing a code package.

Sample:

{
    "codes": [
        {
            "id": "4ea9c05dcddb131f1a000002",
            "project_id": "4ea9c05dcddb131f1a000001",
            "name": "MyWorker",
            "runtime": "ruby",
            "latest_checksum": "b4781a30fc3bd54e16b55d283588055a",
            "rev": 1,
            "latest_history_id": "4f32ecb4f840063758022153",
            "latest_change": 1328737460598000000
        }
    ]
}

Upload or Update a Code Package

You will almost always want to use our Command Line Interface to make uploading easier.

Building a Code Package

If your client doesn't support uploading code packages and you don't want to use the CLI, you're going to need to build the code package yourself before uploading it.

Code should be submitted as a zip file containing all of the files your project needs. That includes dependencies, libraries, data files... everything.

Endpoint

POST /projects/{Project ID}/codes

URL Parameters

  • Project ID: The ID of the project that you are uploading the code to.

Request

The request should be JSON-encoded and contain the following information:

  • name: A unique name for your worker. This will be used to assign tasks to the worker as well as to update the code. If a worker with this name already exists, the code you are uploading will be added as a new revision.

When uploading code, the following are required (not required if just updating code options below):

  • file: A multipart-encoded string containing the zip file you are uploading.
  • file_name: The name of the file within the zip that will be executed when a task is run.
  • runtime: The language to execute your worker with. The following values are valid:
    • sh
    • ruby
    • python
    • php

The request also accepts the following optional parameters:

  • config: An arbitrary string (usually YAML or JSON) that, if provided, will be available in a file that your worker can access. The config file location will be passed in via the -config argument to your worker. The config cannot be larger than 64KB in size.
  • stack: A string that, if provided, will set the specific language environment. If blank the language version will be set to default language version defined in runtime. See More Information on Stack settings.
  • max_concurrency: The maximum number of workers that should be run in parallel. This is useful for keeping your workers from hitting API quotas or overloading databases that are not prepared to handle the highly-concurrent worker environment. If omitted, there will be no limit on the number of concurrent workers.
  • retries: The maximum number of times failed tasks should be retried, in the event that there's an error while running them. If omitted, tasks will not be retried. Tasks cannot be retried more than ten times.
  • retries_delay: The number of seconds to wait before retries. If omitted, tasks will be immediately retried.

Your request also needs the following headers, in addition to the headers required by all API calls:

  • Content-Length: The number of bytes in your JSON-encoded request body
  • Content-Type: Should be set to "multipart/form-data ; boundary={Insert Value Here}" with boundary set to an appropriate value.

Note: This request is not limited to 64 KB, unlike other requests.

Sample Headers: Content-Length: 3119 Content-Type: multipart/form-data; boundary=39f5903459794ad483153244cc6486ec

Sample Body: --39f5903459794ad483153244cc6486ec Content-Disposition: form-data; name="data" Content-Type: text/plain; charset=utf-8

{
    "file_name": "MyWorker.rb",
    "name": "MyWorker",
    "runtime": "ruby",
    "max_concurrency": 12
}

--39f5903459794ad483153244cc6486ec Content-Disposition: form-data; name="file"; filename="MyWorker.zip" Content-Type: application/zip

{ Form-encoded zip data goes here }

--39f5903459794ad483153244cc6486ec--

Response

The response will be a JSON object containing a "msg" property that contains a description of the response.

Sample:

{
    "msg": "Upload successful."
}

Get Info About a Code Package

Endpoint

GET /projects/{Project ID}/codes/{Code ID}

URL Parameters

  • Project ID: The ID of the project that the code package belongs to.
  • Code ID: The ID of the code package you want details on.

Response

The response will be a JSON object containing the details of the code package.

Sample:

{
    "id": "4eb1b241cddb13606500000b",
    "project_id": "4eb1b240cddb13606500000a",
    "name": "MyWorker",
    "runtime": "ruby",
    "latest_checksum": "a0702e9e9a84b758850d19ddd997cf4a",
    "rev": 1,
    "latest_history_id": "4eb1b241cddb13606500000c",
    "latest_change": 1328737460598000000
}

Delete a Code Package

Endpoint

DELETE /projects/{Project ID}/codes/{Code ID}

URL Parameters

  • Project ID: The ID of the project that the code package belongs to.
  • Code ID: The ID of the code package you want to delete.

Response

The response will be a JSON object containing a message property explaining whether the request was successful or not.

Sample:

{
    "msg":"Deleted"
}

Download a Code Package

Endpoint

GET /projects/{Project ID}/codes/{Code ID}/download

URL Parameters

  • Project ID: The ID of the project that the task belongs to.
  • Code Package ID: The ID of the task you want details on.

Optional Query Parameters

  • revision: The revision of the code package you want to download. If not specified, the latest revision will be downloaded.

Response

The response will be a zip file containing your code package. The response header will include a Content-Disposition header containing "filename=yourworker_rev.zip", where yourworker is the code package’s name and rev is the numeric revision. The response’s Content-Type will be "application/zip".

List Code Package Revisions

Endpoint

GET /projects/{Project ID}/codes/{Code ID}/revisions

URL Parameters

  • Project ID: The ID of the project that the task belongs to.
  • Code Package ID: The ID of the code package whose revisions you’re retrieving.

Optional Query Parameters

  • page: The page of revisions you want to retrieve, starting from 0. Default is 0, maximum is 100.
  • per_page: The number of revisions to return per page. Note this is a maximum value, so there may be less revisions returned if there aren’t enough results. Default is 30, maximum is 100.

Response

The response will be a JSON object with a revisions property, containing a list of JSON objects, each representing a revision to the code package.

Sample:

{
    "revisions": [
        {
            "id": "4f32d9c81cf75447be020ea6",
            "code_id": "4f32d9c81cf75447be020ea5",
            "project_id": "4f32d521519cb67829000390",
            "rev": 1,
            "runtime": "ruby",
            "name": "MyWorker",
            "file_name": "worker.rb",
        },
        {
            "id": "4f32da021cf75447be020ea8",
            "code_id": "4f32d9c81cf75447be020ea5",
            "project_id": "4f32d521519cb67829000390",
            "rev": 2,
            "runtime": "ruby",
            "name": "MyWorker",
            "file_name": "worker.rb",
        }
    ]
}

Tasks

Tasks are specific instance of your workers being run. They encompass a single execution of a code package. Tasks consist of the code package to be run and the data to pass to the code package.

Task Properties

Task State

Tasks will be in different states during the course of operation. Here are the states that tasks can be in in the system:

Task StateStatus
queuedin the queue, waiting to run
runningrunning
completefinished running
errorerror during processing
cancelledcancelled by user
killedkilled by system
timeoutexceeded processing time threshold

Priority

Task priority determines how much time a task may sit in queue. Higher values means tasks spend less time in the queue once they come off the schedule. Access to priorities depends on your selected IronWorker plan see plans. You must have access to higher priority levels in your chosen plan or your priority will automatically default back to 0. The standard/default priority is 0.

Priority
0Default
1Medium
2High (less time in queue)

Timeout

Tasks have timeouts associated with them that specify the amount of time (in seconds) the process may run. The maximum timeout is 3600 seconds (60 minutes). It’s also the default timeout but it can be set on a task-by-task basis to be anytime less than 3600 seconds.

Timeout (in seconds)
3600Maximum time a task can run (also default)

Runtime

Languages
ruby
python
php

List Tasks

Endpoint

GET /projects/{Project ID}/tasks?code_name={CODE NAME}

URL Parameters

  • Project ID: The ID of the project whose tasks you want to get a list of.

Required Query Parameters

  • code_name: The name of your worker (code package).

Optional Query Parameters

  • page: The page of tasks you want to retrieve, starting from 0. Default is 0, maximum is 100.
  • per_page: The number of tasks to return per page. Note this is a maximum value, so there may be less tasks returned if there aren’t enough results. Default is 30, maximum is 100.
  • Filter by Status: the parameters queued, running, complete, error, cancelled, killed, and timeout will all filter by their respective status when given a value of 1. These parameters can be mixed and matched to return tasks that fall into any of the status filters. If no filters are provided, tasks will be displayed across all statuses.
  • from_time: Limit the retrieved tasks to only those that were created after the time specified in the value. Time should be formatted as the number of seconds since the Unix epoch.
  • to_time: Limit the retrieved tasks to only those that were created before the time specified in the value. Time should be formatted as the number of seconds since the Unix epoch.

Response

The response will be a JSON object. The "tasks" property will contain a JSON array of objects, each representing a task.

Sample:

{
    "tasks": [
        {
            "id": "4f3595381cf75447be029da5",
            "created_at": "2012-02-10T22:07:52.712Z",
            "updated_at": "2012-02-10T22:11:55Z",
            "project_id": "4f32d521519cb67829000390",
            "code_id": "4f32d9c81cf75447be020ea5",
            "status": "complete",
            "msg": "SetProgress output",
            "code_name": "MyWorker",
            "start_time": "2012-02-10T22:07:54Z",
            "end_time": "2012-02-10T22:11:55Z",
            "duration": 241441,
            "run_times": 1,
            "timeout": 3600,
            "percent": 100
        }
    ]
}

Queue a Task

Endpoint

POST /projects/{Project ID}/tasks

URL Parameters

  • Project ID: The ID of the project that you are creating the task in.

Request

The request should be JSON-encoded and consist of an object with a single property, "tasks", which contains an array of objects. Each object in the array should consist of:

  • code_name: The name of the code package to execute for this task.
  • payload: A string of data to be passed to the worker (usually JSON) so the worker knows exactly what worker it should perform. This is the equivalent to a message in a typical message queue. The payload will be available in a file that your worker can access. File location will be passed in via the -payload argument. The payload cannot be larger than 64KB in size.

Optionally, each object in the array can also contain the following:

  • priority: The priority queue to run the task in. Valid values are 0, 1, and 2. Task priority determines how much time a task may sit in queue. Higher values means tasks spend less time in the queue once they come off the schedule. Access to priorities depends on your selected IronWorker plan see plans. You must have access to higher priority levels in your chosen plan or your priority will automatically default back to 0. The standard/default priority is 0.
  • cluster: cluster name ex: "high-mem" or "dedicated". This is a premium feature for customers to have access to more powerful or custom built worker solutions. Dedicated worker clusters exist for users who want to reserve a set number of workers just for their queued tasks. If not set default is set to "default" which is the public IronWorker cluster.
  • timeout: The maximum runtime of your task in seconds. No task can exceed 3600 seconds (60 minutes). The default is 3600 but can be set to a shorter duration.
  • delay: The number of seconds to delay before actually queuing the task. Default is 0.

The request also needs to be sent with a "Content-Type: application/json" header, or it will respond with a 406 status code and a "msg" property explaining the missing header.

Sample:

{
    "tasks": [
        {
            "code_name": "MyWorker",
            "payload": "{\"x\": \"abc\", \"y\": \"def\"}"
        }
    ]
}

Response

The response will be a JSON object containing a "msg" property that contains a description of the response and a "tasks" property that contains an array of objects, each with an "id" property that contains the created task’s ID.

Sample:

{
    "msg": "Queued up",
    "tasks": [
        {
            "id": "4eb1b471cddb136065000010"
        }
    ]
}

Queue a Task From a Webhook

Endpoint

POST /projects/{Project ID}/tasks/webhook?code_name={Code Name}

URL Parameters

  • Project ID: The ID of the project that you are uploading the code to.
  • Code Name: The name of the code package you want to execute the task.

Request

The request body is free-form: anything at all can be sent. Whatever the request body is will be passed along as the payload for the task, and therefore needs to be under 64KB in size.

Response

The response will be a JSON object containing a "msg" property that contains a description of the response.

Sample:

{
    "id": "4f3595381cf75447be029da5",
    "msg":"Queued up."
}

Get Info About a Task

Endpoint

GET /projects/{Project ID}/tasks/{Task ID}

URL Parameters

  • Project ID: The ID of the project that the task belongs to.
  • Task ID: The ID of the task you want details on.

Response

The response will be a JSON object containing the details of the task.

Sample:

{
    "id": "4eb1b471cddb136065000010",
    "project_id": "4eb1b46fcddb13606500000d",
    "code_id": "4eb1b46fcddb13606500000e",
    "code_history_id": "4eb1b46fcddb13606500000f",
    "status": "complete",
    "code_name": "MyWorker",
    "code_rev": "1",
    "start_time": 1320268924000000000,
    "end_time": 1320268924000000000,
    "duration": 43,
    "timeout": 3600,
    "payload": "{\"foo\":\"bar\"}",
    "updated_at": "2012-11-10T18:31:08.064Z",
    "created_at": "2012-11-10T18:30:43.089Z"
}

Get a Task’s Log

Endpoint

GET /projects/{Project ID}/tasks/{Task ID}/log

URL Parameters

  • Project ID: The ID of the project that the task belongs to.
  • Task ID: The ID of the task whose log you are retrieving.

Response

Unlike the other API methods, this method will return a Content-Type of "text/plain". The response will only include the task’s log.

Sample: Hello World!

Cancel a Task

Endpoint

POST /projects/{Project ID}/tasks/{Task ID}/cancel

URL Parameters

  • Project ID: The ID of the project that the task belongs to.
  • Task ID: The ID of the task you want to cancel.

Response

The response will be a JSON object containing a message explaining whether the request was successful or not.

Sample:

{
    "msg": "Cancelled"
}

Set a Task’s Progress

Endpoint

POST /projects/{Project ID}/tasks/{Task ID}/progress

URL Parameters

  • Project ID: The ID of the project that contains the task.
  • Task ID: The ID of the task whose progress you are updating.

Request

The request should be JSON-encoded and can contain the following information:

  • percent: An integer, between 0 and 100 inclusive, that describes the completion of the task.
  • msg: Any message or data describing the completion of the task. Must be a string value, and the 64KB request limit applies.

The request also needs to be sent with a "Content-Type: application/json" header, or it will respond with a 406 status code and a "msg" property explaining the missing header.

Sample:

{
    "percent": 25,
    "msg": "Any message goes here."
}

Response

The response will be a JSON object containing a message explaining whether the request was successful or not.

Sample:

{
    "msg": "Progress set"
}

Retry a Task

Endpoint

POST /projects/{Project ID}/tasks/{Task ID}/retry

URL Parameters

  • Project ID: The ID of the project that the task belongs to.
  • Task ID: The ID of the task you want to cancel.

Request

The request must be JSON-encoded and can contain the following information:

  • delay: The number of seconds the task should be delayed before it runs again.

The request also needs to be sent with a "Content-Type: application/json" header, or it will respond with a 406 status code and a "msg" property explaining the missing header.

Response

The response will be a JSON object containing a message explaining whether the request was successful or not.

Sample:

{
    "msg": "Queued up",
    "tasks": [
        {
            "id": "4eb1b471cddb136065000010"
        }
    ]
}

Scheduled Tasks

Scheduled tasks are just tasks that run on a schedule. While the concept is simple, it enables a powerful class of functionality: tasks can be used as cron workers, running at specific intervals a set (or unlimited) number of times.

List Scheduled Tasks

Endpoint

GET /projects/{Project ID}/schedules

URL Parameters

  • Project ID: The ID of the project whose scheduled tasks you want to get a list of.

Optional Query Parameters

  • page: The page of scheduled tasks you want to retrieve, starting from 0. Default is 0, maximum is 100.
  • per_page: The number of scheduled tasks to return per page. Note this is a maximum value, so there may be less tasks returned if there aren’t enough results. Default is 30, maximum is 100.

Response

The response will be a JSON object. The "schedules" property will contain a JSON array of objects, each representing a schedule.

Sample:

{
    "schedules": [
        {
            "id": "4eb1b490cddb136065000011",
            "created_at": "2012-02-14T03:06:41Z",
            "updated_at": "2012-02-14T03:06:41Z",
            "project_id": "4eb1b46fcddb13606500000d",
            "msg": "Ran max times.",
            "status": "complete",
            "code_name": "MyWorker",
            "start_at": "2011-11-02T21:22:34Z",
            "end_at": "2262-04-11T23:47:16Z",
            "next_start": "2011-11-02T21:22:34Z",
            "last_run_time": "2011-11-02T21:22:51Z",
            "run_times": 1,
            "run_count": 1,
            "cluster": "high-memory"
        }
    ]
}

Schedule a Task

Endpoint

POST /projects/{Project ID}/schedules

URL Parameters

  • Project ID: The ID of the project that you want to schedule the task in.

Request

The request should be a JSON object with a "schedules" property containing an array of objects with the following properties:

  • code_name: The name of the code package to execute.
  • payload: A string of data to pass to the code package on execution.

Optionally, each object in the array can specify the following properties:

  • start_at: The time the scheduled task should first be run.
  • run_every: The amount of time, in seconds, between runs. By default, the task will only run once. run_every will return a 400 error if it is set to less than 60.
  • end_at: The time tasks will stop being queued. Should be a time or datetime.
  • run_times: The number of times a task will run.
  • priority: The priority queue to run the task in. Valid values are 0, 1, and 2. Task priority determines how much time a task may sit in queue. Higher values means tasks spend less time in the queue once they come off the schedule. Access to priorities depends on your selected IronWorker plan see plans. You must have access to higher priority levels in your chosen plan or your priority will automatically default back to 0. The standard/default priority is 0.
  • cluster: cluster name ex: "high-mem" or "dedicated". This is a premium feature for customers for customers to have access to more powerful or custom built worker solutions. Dedicated worker clusters exist for users who want to reserve a set number of workers just for their queued tasks. If not set default is set to "default" which is the public IronWorker cluster.

The request also needs to be sent with a "Content-Type: application/json" header, or it will respond with a 406 status code and a "msg" property explaining the missing header.

Sample:

{
  schedules: [
    {
      payload : "{\"x\": \"abc\", \"y\": \"def\"}",
      name: "MyScheduledTask",
      code_name: "MyWorker"
      run_every: 3600
    }
  ]
}

Response

The response will be a JSON object containing a "msg" property that contains a description of the response and a "schedules" property that contains an array of objects, each with an "id" property that contains the scheduled task’s ID.

Sample:

{
    "msg": "Scheduled",
    "schedules": [
        {
            "id": "4eb1b490cddb136065000011"
        }
    ]
}

Get Info About a Scheduled Task

Endpoint

GET /projects/{Project ID}/schedules/{Schedule ID}

URL Parameters

  • Project ID: The ID of the project that the scheduled task belongs to.
  • Schedule ID: The ID of the scheduled task you want details on.

Response

The response will be a JSON object containing the details of the scheduled task.

Sample:

{
    "id": "4eb1b490cddb136065000011",
    "created_at": "2011-11-02T21:22:51Z",
    "updated_at": "2011-11-02T21:22:51Z",
    "project_id": "4eb1b46fcddb13606500000d",
    "msg": "Ran max times.",
    "status": "complete",
    "code_name": "MyWorker",
    "delay": 10,
    "start_at": "2011-11-02T21:22:34Z",
    "end_at": "2262-04-11T23:47:16Z",
    "next_start": "2011-11-02T21:22:34Z",
    "last_run_time": "2011-11-02T21:22:51Z",
    "run_times": 1,
    "run_count": 1
}

Cancel a Scheduled Task

Endpoint

POST /projects/{Project ID}/schedules/{Schedule ID}/cancel

URL Parameters

  • Project ID: The ID of the project that the scheduled task belongs to.
  • Schedule ID: The ID of the scheduled task you want to cancel.

Response

The response will be a JSON object containing a message explaining whether the request was successful or not.

Sample:

{
    "msg": "Cancelled"
}

Stacks

List of available stacks

List of stacks

Endpoint

GET /stacks

Response

The response will be a JSON object.

Sample:

{
  ["scala-2.9","ruby-2.1","ruby-1.9","python-3.2","python-2.7","php-5.4","node-0.10","java-1.7","mono-3.0","mono-2.10"]
}