SWARMS API

Our API is organized around REST. It has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. HTTP requests will be forwarded to HTTPS. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side application. All API responses, including errors, will return JSON by default.

Also, check out our python sdk!

Content-Types

The API supports application/json as well as application/hal+json in the accept header. If you call endpoints with the later, the response will include links to related resources and actions that can be performed at that moment.

Authentication

You authenticate by including an API token in the X-Auth-Token header of the requests. You can request and discard the token with your credentials using the endpoints documented in the Auth Token section.

As we are currently in a beta phase, you cannot signup on your own to our platform. If you want to create your account, please send us an email to info@swarms.tech.

Errors

For errors the common HTTP Response Status Codes are used. The body of the response will contain an error code and a message as well as a user friendly description like:

{
    "code": 1000,
    "message": "invalid credentials",
    "description": "The given credentials did not match any user in our database"
}

Each response will contain a X-Request-ID header with an UUID identifying that request. In case you encounter weird behavior, please send us an email and include the request id in your message.

Versioning

Our API is versioned in a major.minor format. You can specify the version to use by setting the X-API-Version header in the requests. If this header is not present, it will default to the latest version. The response will also include the used API version in the X-API-Version header. The current API version is 1.0.

Time Formatting

Timestamps are returned in UTC timezone and formatted according to the ISO-8601 standard, as in 2017-08-02T13:58:24.

Feedback

Our API docs are hosted on GitHub. We appreciate your feedback in issues in the repository or via email at info@swarms.tech.

Auth Token

In order to access and manage your resources via the API, you need to send an API token in the X-Auth-Token header of your requests. You can can requests an auth token with your credentials.

Request an auth token

POST https://api.swarms.com/auth/token/request
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
Body
{
  "email": "me@example.com",
  "password": "password"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxLUlVdVpWSTRKcDFSOVlTTGFOUHBGOVFcL1kwcU95TG10RGt0TE5WaG5GV0hSNDBMTklkZzN4TVAyZ0NrT0N3YzhYQ1Q4cmZsZlprcVhOeE1VQzlaZ3RVRFZnU1dBOXBOVW04MWlhIiwiaXNzIjoia3dpcXByb3ZpZGVyIiwiZXhwIjoxNTA4OTI0NDAwLCJpYXQiOjE1MDYzMzI0MDAsImp0aSI6ImEwMWNmYTBkZjJlYjI2NWYzOTQ1NTkxYmMyOGY3MWEzNTg5ZDE3NjZlYmI4MmRhYTBjYTFhOGIwNzJkNzI1ODk0OWJmOTZkMTUyOTJjNTFmYWNmNGFkZDNkMDZjMDQ2YjExYmRjNmI2Yjc2YTYwNmZkN2JmMTI2MzQ4NWZhZGNhYzU0NjExMTU2NGNhNGNiMjhiZTg5MGNlNDY5MjMyY2QyNmI5ZmIzMTdhZTVhZmQ1NjE0NWQzOGExODg1MzdkZTUxMDMxYWQwYmY4YTY3YjNlNzVjMzkwNTVkZDUxNTQzZDY0ODNkNzc4OGEwOTQwMWY4YWQ0MjEyNTNhYmI3ZDEifQ.AzOxuj3DBELmFyphOJQxAlodA3PzDeBN6x4G5qO1H5s",
  "expiresAt": "2017-10-25T09:40:00",
  "userId": 42
}

Request an auth token
POST/auth/token/request


Discard an auth token

POST https://api.swarms.com/auth/token/discard
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json

Discard an auth token
POST/auth/token/discard


Profile

The Profile object

GET https://api.swarms.com/me
Requestsexample 1
Headers
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "firstName": "Jon",
  "lastName": "Doe",
  "phone": "+123456789",
  "organization": "Swarms Technologies",
  "website": "www.swarms.com",
  "id": 42,
  "customerId": "AB12CD34",
  "balance": {
    "available": "42 USD",
    "frozen": "24 USD"
  },
  "email": "email@swarms.com",
  "logo": "https://logo.swarms.com",
  "commissionRate": 0.2,
  "charity": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "your first name"
    },
    "lastName": {
      "type": "string",
      "description": "your last name"
    },
    "phone": {
      "type": "string",
      "description": "your phone"
    },
    "organization": {
      "type": "string",
      "description": "name of your organization"
    },
    "website": {
      "type": "string",
      "description": "your organization's website"
    },
    "id": {
      "type": "number",
      "description": "your id"
    },
    "customerId": {
      "type": "string",
      "description": "your customer id"
    },
    "balance": {
      "type": "object",
      "properties": {
        "available": {
          "type": "string",
          "description": "money available for new campaigns"
        },
        "frozen": {
          "type": "string",
          "description": "money currently frozen for active campaigns"
        }
      },
      "description": "your current balance"
    },
    "email": {
      "type": "string",
      "description": "your email"
    },
    "logo": {
      "type": "string",
      "description": "URL of your logo"
    },
    "commissionRate": {
      "type": "number",
      "description": "commission rate on worker payments"
    },
    "charity": {
      "type": "boolean",
      "description": "if your account is a charity one"
    }
  }
}

Get your Profile
GET/me


PUT https://api.swarms.com/me
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "firstName": "Jon",
  "lastName": "Doe",
  "phone": "+123456789",
  "organization": "Swarms Technologies",
  "website": "www.swarms.com"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "your first name"
    },
    "lastName": {
      "type": "string",
      "description": "your last name"
    },
    "phone": {
      "type": "string",
      "description": "your phone"
    },
    "organization": {
      "type": "string",
      "description": "name of your organization"
    },
    "website": {
      "type": "string",
      "description": "your organization's website"
    }
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "firstName": "Jon",
  "lastName": "Doe",
  "phone": "+123456789",
  "organization": "Swarms Technologies",
  "website": "www.swarms.com",
  "id": 42,
  "customerId": "AB12CD34",
  "balance": {
    "available": "42 USD",
    "frozen": "24 USD"
  },
  "email": "email@swarms.com",
  "logo": "https://logo.swarms.com",
  "commissionRate": 0.2,
  "charity": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "your first name"
    },
    "lastName": {
      "type": "string",
      "description": "your last name"
    },
    "phone": {
      "type": "string",
      "description": "your phone"
    },
    "organization": {
      "type": "string",
      "description": "name of your organization"
    },
    "website": {
      "type": "string",
      "description": "your organization's website"
    },
    "id": {
      "type": "number",
      "description": "your id"
    },
    "customerId": {
      "type": "string",
      "description": "your customer id"
    },
    "balance": {
      "type": "object",
      "properties": {
        "available": {
          "type": "string",
          "description": "money available for new campaigns"
        },
        "frozen": {
          "type": "string",
          "description": "money currently frozen for active campaigns"
        }
      },
      "description": "your current balance"
    },
    "email": {
      "type": "string",
      "description": "your email"
    },
    "logo": {
      "type": "string",
      "description": "URL of your logo"
    },
    "commissionRate": {
      "type": "number",
      "description": "commission rate on worker payments"
    },
    "charity": {
      "type": "boolean",
      "description": "if your account is a charity one"
    }
  }
}

Update your Profile
PUT/me


Task

A Task is the unit of work that is displayed in a cohesive view on a mobile device. It consists of several Components which can be interactive (like a TextInput) or non-interactive (like an Image). Interactive components will produce results while the non-interactive ones won’t. For an overview of all available components check out the Components Overview.

The task object

GET https://api.swarms.com/tasks?order=?limit=?search=
Requestsexample 1
Headers
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "_links": {
    "next": {
      "href": "/resources?after=42&..."
    },
    "previous": {
      "href": "/resources?before=42&..."
    }
  },
  "tasks": [
    {
      "name": "My first Task",
      "components": [
        {
          "type": "BinaryChoice",
          "sticky": false,
          "optionalResult": false,
          "landscape": true,
          "properties": {
            "key": "key",
            "value": "value"
          }
        }
      ],
      "properties": {
        "key": "key",
        "value": "value"
      },
      "resourcesSize": "3MB",
      "estimatedUploadSize": "2MB",
      "id": 1,
      "readOnly": false,
      "lastModifiedAt": "2017-08-02T13:58:24",
      "createdAt": "2017-08-02T13:58:24",
      "archived": false
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "properties": {
        "next": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the next page"
            }
          }
        },
        "previous": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the previous page"
            }
          }
        }
      }
    },
    "tasks": {
      "type": "array"
    }
  }
}

List all Tasks
GET/tasks{?order}{?limit}{?search}

URI Parameters
HideShow
order
array[string] (optional) 

Choices: id name lastModifiedAt createdAt

limit
number (optional) 

the number of elements being fetched. Limit can range between 1 and 100 elements. Default is 10.

search
string (optional) 

search for full word matches


GET https://api.swarms.com/tasks/id
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "name": "My first Task",
  "components": [
    {
      "type": "BinaryChoice",
      "sticky": false,
      "optionalResult": false,
      "landscape": true,
      "properties": {
        "key": "key",
        "value": "value"
      }
    }
  ],
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the task"
    },
    "components": {
      "type": "array",
      "description": "components of the task"
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the task including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this task for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Get a single Task
GET/tasks/{id}

URI Parameters
HideShow
id
number (required) 

id of the task


POST https://api.swarms.com/tasks
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "name": "My first Task",
  "components": [
    {
      "type": "BinaryChoice",
      "sticky": false,
      "optionalResult": false,
      "landscape": true,
      "properties": {
        "key": "key",
        "value": "value"
      }
    }
  ],
  "properties": {
    "key": "key",
    "value": "value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the task"
    },
    "components": {
      "type": "array",
      "description": "components of the task"
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Task",
  "components": [
    {
      "type": "BinaryChoice",
      "sticky": false,
      "optionalResult": false,
      "landscape": true,
      "properties": {
        "key": "key",
        "value": "value"
      }
    }
  ],
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the task"
    },
    "components": {
      "type": "array",
      "description": "components of the task"
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the task including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this task for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Create a Task
POST/tasks


PUT https://api.swarms.com/tasks/id
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "name": "My first Task",
  "components": [
    {
      "type": "BinaryChoice",
      "sticky": false,
      "optionalResult": false,
      "landscape": true,
      "properties": {
        "key": "key",
        "value": "value"
      }
    }
  ],
  "properties": {
    "key": "key",
    "value": "value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the task"
    },
    "components": {
      "type": "array",
      "description": "components of the task"
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "name": "My first Task",
  "components": [
    {
      "type": "BinaryChoice",
      "sticky": false,
      "optionalResult": false,
      "landscape": true,
      "properties": {
        "key": "key",
        "value": "value"
      }
    }
  ],
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the task"
    },
    "components": {
      "type": "array",
      "description": "components of the task"
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the task including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this task for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Update a Task
PUT/tasks/{id}

URI Parameters
HideShow
id
number (required) 

id of the task


DELETE https://api.swarms.com/tasks/id
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json

Delete a Task
DELETE/tasks/{id}

URI Parameters
HideShow
id
number (required) 

id of the task


POST https://api.swarms.com/tasks/id/copy
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Task",
  "components": [
    {
      "type": "BinaryChoice",
      "sticky": false,
      "optionalResult": false,
      "landscape": true,
      "properties": {
        "key": "key",
        "value": "value"
      }
    }
  ],
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the task"
    },
    "components": {
      "type": "array",
      "description": "components of the task"
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the task including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this task for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Copy a Task
POST/tasks/{id}/copy

URI Parameters
HideShow
id
number (required) 

id of the task that should be copied


POST https://api.swarms.com/tasks/id/archive
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Task",
  "components": [
    {
      "type": "BinaryChoice",
      "sticky": false,
      "optionalResult": false,
      "landscape": true,
      "properties": {
        "key": "key",
        "value": "value"
      }
    }
  ],
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the task"
    },
    "components": {
      "type": "array",
      "description": "components of the task"
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the task including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this task for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Archive a Task
POST/tasks/{id}/archive

URI Parameters
HideShow
id
number (required) 

id of the task that should be archived


POST https://api.swarms.com/tasks/id/unarchive
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Task",
  "components": [
    {
      "type": "BinaryChoice",
      "sticky": false,
      "optionalResult": false,
      "landscape": true,
      "properties": {
        "key": "key",
        "value": "value"
      }
    }
  ],
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the task"
    },
    "components": {
      "type": "array",
      "description": "components of the task"
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the task including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this task for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Unarchive a Task
POST/tasks/{id}/unarchive

URI Parameters
HideShow
id
number (required) 

id of the task that should be unarchived


Job

A Job is the unit of work a worker gets paid for. It is a sequence of Tasks.

The job object

GET https://api.swarms.com/jobs?order=?limit=?search=
Requestsexample 1
Headers
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "_links": {
    "next": {
      "href": "/resources?after=42&..."
    },
    "previous": {
      "href": "/resources?before=42&..."
    }
  },
  "jobs": [
    {
      "name": "My first Job",
      "description": "this job differs from the others!",
      "properties": {
        "key": "key",
        "value": "value"
      },
      "resourcesSize": "3MB",
      "estimatedUploadSize": "2MB",
      "id": 1,
      "readOnly": false,
      "lastModifiedAt": "2017-08-02T13:58:24",
      "createdAt": "2017-08-02T13:58:24",
      "archived": false
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "properties": {
        "next": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the next page"
            }
          }
        },
        "previous": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the previous page"
            }
          }
        }
      }
    },
    "jobs": {
      "type": "array"
    }
  }
}

List all Jobs
GET/jobs{?order}{?limit}{?search}

URI Parameters
HideShow
order
array[string] (optional) 

Choices: id name lastModifiedAt createdAt

limit
number (optional) 

the number of elements being fetched. Limit can range between 1 and 100 elements. Default is 10.

search
string (optional) 

search for full word matches


GET https://api.swarms.com/jobs/id
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "name": "My first Job",
  "description": "this job differs from the others!",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the job"
    },
    "description": {
      "type": "string",
      "description": "job specific description that will be appended to the campaign description."
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the job including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this job for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Get a single Job
GET/jobs/{id}

URI Parameters
HideShow
id
number (required) 

id of the job


POST https://api.swarms.com/jobs
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "name": "My first Job",
  "description": "this job differs from the others!",
  "properties": {
    "key": "key",
    "value": "value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the job"
    },
    "description": {
      "type": "string",
      "description": "job specific description that will be appended to the campaign description."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Job",
  "description": "this job differs from the others!",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the job"
    },
    "description": {
      "type": "string",
      "description": "job specific description that will be appended to the campaign description."
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the job including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this job for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Create a Job
POST/jobs


PUT https://api.swarms.com/jobs/id
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "name": "My first Job",
  "description": "this job differs from the others!",
  "properties": {
    "key": "key",
    "value": "value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the job"
    },
    "description": {
      "type": "string",
      "description": "job specific description that will be appended to the campaign description."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "name": "My first Job",
  "description": "this job differs from the others!",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the job"
    },
    "description": {
      "type": "string",
      "description": "job specific description that will be appended to the campaign description."
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the job including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this job for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Update a Job
PUT/jobs/{id}

URI Parameters
HideShow
id
number (required) 

id of the job


DELETE https://api.swarms.com/jobs/id
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json

Delete a Job
DELETE/jobs/{id}

URI Parameters
HideShow
id
number (required) 

id of the job


POST https://api.swarms.com/jobs/id/copy?deep=false
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Job",
  "description": "this job differs from the others!",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the job"
    },
    "description": {
      "type": "string",
      "description": "job specific description that will be appended to the campaign description."
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the job including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this job for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Copy a Job
POST/jobs/{id}/copy{?deep}

URI Parameters
HideShow
id
number (required) 

id of the job that should be copied

deep
boolean (required) Example: false

if true, included tasks will also be copied and linked to the job. If false, existing tasks for the orginial job will be linked to the new one.


POST https://api.swarms.com/jobs/id/archive?deep=false
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Job",
  "description": "this job differs from the others!",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the job"
    },
    "description": {
      "type": "string",
      "description": "job specific description that will be appended to the campaign description."
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the job including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this job for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Archive a Job
POST/jobs/{id}/archive{?deep}

URI Parameters
HideShow
id
number (required) 

id of the job that should be archived

deep
boolean (required) Example: false

if true, included tasks will also be archived and linked to the job.


POST https://api.swarms.com/jobs/id/unarchive
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Job",
  "description": "this job differs from the others!",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "resourcesSize": "3MB",
  "estimatedUploadSize": "2MB",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the job"
    },
    "description": {
      "type": "string",
      "description": "job specific description that will be appended to the campaign description."
    },
    "resourcesSize": {
      "type": "string",
      "description": "size of the job including media files"
    },
    "estimatedUploadSize": {
      "type": "string",
      "description": "estimated upload size of the results for this job for the worker"
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Unarchive a Job
POST/jobs/{id}/unarchive

URI Parameters
HideShow
id
number (required) 

id of the job that should be archived. Will also unarchive included tasks.


Tasks of a Job

You can add, update and get the tasks of a job.

GET https://api.swarms.com/jobs/id/tasks
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "_links": {
    "next": {
      "href": "/resources?after=42&..."
    },
    "previous": {
      "href": "/resources?before=42&..."
    }
  },
  "tasks": [
    {
      "name": "My first Task",
      "components": [
        {
          "type": "BinaryChoice",
          "sticky": false,
          "optionalResult": false,
          "landscape": true,
          "properties": {
            "key": "key",
            "value": "value"
          }
        }
      ],
      "properties": {
        "key": "key",
        "value": "value"
      },
      "resourcesSize": "3MB",
      "estimatedUploadSize": "2MB",
      "id": 1,
      "readOnly": false,
      "lastModifiedAt": "2017-08-02T13:58:24",
      "createdAt": "2017-08-02T13:58:24",
      "archived": false
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "properties": {
        "next": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the next page"
            }
          }
        },
        "previous": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the previous page"
            }
          }
        }
      }
    },
    "tasks": {
      "type": "array"
    }
  }
}

List Tasks of a Job
GET/jobs/{id}/tasks

URI Parameters
HideShow
id
number (required) 

id of the job


PUT https://api.swarms.com/jobs/id/tasks
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
[
  1
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Responses200
Headers
Content-Type: application/json

Update Tasks of a Job
PUT/jobs/{id}/tasks

URI Parameters
HideShow
id
number (required) 

id of the job


Campaign

A Campaign is a collection of Jobs. It defines under which conditions its jobs are published to our job market. If you want to make a Job available to the workers, you first need to add it to a campaign first and publish this campaign to our Job Market.

The campaign object

GET https://api.swarms.com/campaigns?order=?limit=?search=
Requestsexample 1
Headers
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "_links": {
    "next": {
      "href": "/resources?after=42&..."
    },
    "previous": {
      "href": "/resources?before=42&..."
    }
  },
  "campaigns": [
    {
      "name": "My first Campaign",
      "title": "Review model images",
      "description": "You will see 20 models images which you should rate on a 1 to 5 scale.",
      "terms": "Don't tell anyone about this.",
      "estDuration": "10 sec",
      "workerPayment": 0.01,
      "results": 3,
      "maxResultsPerWorker": 1,
      "workerGroup": 1,
      "maxWorkTime": "10 min",
      "maxUploadTime": "4 hours",
      "maxReviewTime": "3 hours",
      "training": false,
      "startDate": "2018-01-01T10:00",
      "endDate": "2018-01-01T10:00",
      "properties": {
        "key": "key",
        "value": "value"
      },
      "state": "unpublished",
      "id": 1,
      "readOnly": false,
      "lastModifiedAt": "2017-08-02T13:58:24",
      "createdAt": "2017-08-02T13:58:24",
      "archived": false
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "properties": {
        "next": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the next page"
            }
          }
        },
        "previous": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the previous page"
            }
          }
        }
      }
    },
    "campaigns": {
      "type": "array"
    }
  }
}

List all Campaigns
GET/campaigns{?order}{?limit}{?search}

URI Parameters
HideShow
order
array[string] (optional) 

Choices: id name lastModifiedAt createdAt

limit
number (optional) 

the number of elements being fetched. Limit can range between 1 and 100 elements. Default is 10.

search
string (optional) 

search for full word matches


GET https://api.swarms.com/campaigns/id
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "name": "My first Campaign",
  "title": "Review model images",
  "description": "You will see 20 models images which you should rate on a 1 to 5 scale.",
  "terms": "Don't tell anyone about this.",
  "estDuration": "10 sec",
  "workerPayment": 0.01,
  "results": 3,
  "maxResultsPerWorker": 1,
  "workerGroup": 1,
  "maxWorkTime": "10 min",
  "maxUploadTime": "4 hours",
  "maxReviewTime": "3 hours",
  "training": false,
  "startDate": "2018-01-01T10:00",
  "endDate": "2018-01-01T10:00",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "state": "unpublished",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the campaign"
    },
    "title": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "description": {
      "type": "string",
      "description": "description for jobs in this campaign on the job market"
    },
    "terms": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "estDuration": {
      "type": "string",
      "description": "estimated duration for jobs in this campaign"
    },
    "workerPayment": {
      "type": "number",
      "description": "payment (in USD) for workers who work on jobs in this campaign."
    },
    "results": {
      "type": "number",
      "description": "number of results that should be generated for each job of the campaign"
    },
    "maxResultsPerWorker": {
      "type": "number",
      "description": "number of times a single worker can work on each job of the campaign (optional)"
    },
    "workerGroup": {
      "type": "number",
      "description": "id of a workergroup to specify the workers that can work on jobs in this campaign (optional)"
    },
    "maxWorkTime": {
      "type": "string",
      "description": "time a worker has to work on a job of this campaign (optional)"
    },
    "maxUploadTime": {
      "type": "string",
      "description": "time a worker has to upload the results after finishing his work (optional)"
    },
    "maxReviewTime": {
      "type": "string",
      "description": "(string, optional) - timeframe in which results can be (soft-) rejected before they get auto approved (optional)"
    },
    "training": {
      "type": "boolean",
      "description": "if this campaign is a training for future jobs (optional)"
    },
    "startDate": {
      "type": "string",
      "description": "publish this campaign automatically at a specific date (optional)"
    },
    "endDate": {
      "type": "string",
      "description": "finish this campaign automatically at a specific date (optional)"
    },
    "state": {
      "type": "string",
      "enum": [
        "unpublished",
        "active",
        "paused",
        "cancelled",
        "finished"
      ]
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Get a single Campaign
GET/campaigns/{id}

URI Parameters
HideShow
id
number (required) 

id of the campaign


POST https://api.swarms.com/campaigns
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "name": "My first Campaign",
  "title": "Review model images",
  "description": "You will see 20 models images which you should rate on a 1 to 5 scale.",
  "terms": "Don't tell anyone about this.",
  "estDuration": "10 sec",
  "workerPayment": 0.01,
  "results": 3,
  "maxResultsPerWorker": 1,
  "workerGroup": 1,
  "maxWorkTime": "10 min",
  "maxUploadTime": "4 hours",
  "maxReviewTime": "3 hours",
  "training": false,
  "startDate": "2018-01-01T10:00",
  "endDate": "2018-01-01T10:00",
  "properties": {
    "key": "key",
    "value": "value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the campaign"
    },
    "title": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "description": {
      "type": "string",
      "description": "description for jobs in this campaign on the job market"
    },
    "terms": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "estDuration": {
      "type": "string",
      "description": "estimated duration for jobs in this campaign"
    },
    "workerPayment": {
      "type": "number",
      "description": "payment (in USD) for workers who work on jobs in this campaign."
    },
    "results": {
      "type": "number",
      "description": "number of results that should be generated for each job of the campaign"
    },
    "maxResultsPerWorker": {
      "type": "number",
      "description": "number of times a single worker can work on each job of the campaign (optional)"
    },
    "workerGroup": {
      "type": "number",
      "description": "id of a workergroup to specify the workers that can work on jobs in this campaign (optional)"
    },
    "maxWorkTime": {
      "type": "string",
      "description": "time a worker has to work on a job of this campaign (optional)"
    },
    "maxUploadTime": {
      "type": "string",
      "description": "time a worker has to upload the results after finishing his work (optional)"
    },
    "maxReviewTime": {
      "type": "string",
      "description": "(string, optional) - timeframe in which results can be (soft-) rejected before they get auto approved (optional)"
    },
    "training": {
      "type": "boolean",
      "description": "if this campaign is a training for future jobs (optional)"
    },
    "startDate": {
      "type": "string",
      "description": "publish this campaign automatically at a specific date (optional)"
    },
    "endDate": {
      "type": "string",
      "description": "finish this campaign automatically at a specific date (optional)"
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)"
    }
  }
}
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Campaign",
  "title": "Review model images",
  "description": "You will see 20 models images which you should rate on a 1 to 5 scale.",
  "terms": "Don't tell anyone about this.",
  "estDuration": "10 sec",
  "workerPayment": 0.01,
  "results": 3,
  "maxResultsPerWorker": 1,
  "workerGroup": 1,
  "maxWorkTime": "10 min",
  "maxUploadTime": "4 hours",
  "maxReviewTime": "3 hours",
  "training": false,
  "startDate": "2018-01-01T10:00",
  "endDate": "2018-01-01T10:00",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "state": "unpublished",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the campaign"
    },
    "title": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "description": {
      "type": "string",
      "description": "description for jobs in this campaign on the job market"
    },
    "terms": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "estDuration": {
      "type": "string",
      "description": "estimated duration for jobs in this campaign"
    },
    "workerPayment": {
      "type": "number",
      "description": "payment (in USD) for workers who work on jobs in this campaign."
    },
    "results": {
      "type": "number",
      "description": "number of results that should be generated for each job of the campaign"
    },
    "maxResultsPerWorker": {
      "type": "number",
      "description": "number of times a single worker can work on each job of the campaign (optional)"
    },
    "workerGroup": {
      "type": "number",
      "description": "id of a workergroup to specify the workers that can work on jobs in this campaign (optional)"
    },
    "maxWorkTime": {
      "type": "string",
      "description": "time a worker has to work on a job of this campaign (optional)"
    },
    "maxUploadTime": {
      "type": "string",
      "description": "time a worker has to upload the results after finishing his work (optional)"
    },
    "maxReviewTime": {
      "type": "string",
      "description": "(string, optional) - timeframe in which results can be (soft-) rejected before they get auto approved (optional)"
    },
    "training": {
      "type": "boolean",
      "description": "if this campaign is a training for future jobs (optional)"
    },
    "startDate": {
      "type": "string",
      "description": "publish this campaign automatically at a specific date (optional)"
    },
    "endDate": {
      "type": "string",
      "description": "finish this campaign automatically at a specific date (optional)"
    },
    "state": {
      "type": "string",
      "enum": [
        "unpublished",
        "active",
        "paused",
        "cancelled",
        "finished"
      ]
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Create a Campaign
POST/campaigns


PUT https://api.swarms.com/campaigns/id
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "name": "My first Campaign",
  "title": "Review model images",
  "description": "You will see 20 models images which you should rate on a 1 to 5 scale.",
  "terms": "Don't tell anyone about this.",
  "estDuration": "10 sec",
  "workerPayment": 0.01,
  "results": 3,
  "maxResultsPerWorker": 1,
  "workerGroup": 1,
  "maxWorkTime": "10 min",
  "maxUploadTime": "4 hours",
  "maxReviewTime": "3 hours",
  "training": false,
  "startDate": "2018-01-01T10:00",
  "endDate": "2018-01-01T10:00",
  "properties": {
    "key": "key",
    "value": "value"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the campaign"
    },
    "title": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "description": {
      "type": "string",
      "description": "description for jobs in this campaign on the job market"
    },
    "terms": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "estDuration": {
      "type": "string",
      "description": "estimated duration for jobs in this campaign"
    },
    "workerPayment": {
      "type": "number",
      "description": "payment (in USD) for workers who work on jobs in this campaign."
    },
    "results": {
      "type": "number",
      "description": "number of results that should be generated for each job of the campaign"
    },
    "maxResultsPerWorker": {
      "type": "number",
      "description": "number of times a single worker can work on each job of the campaign (optional)"
    },
    "workerGroup": {
      "type": "number",
      "description": "id of a workergroup to specify the workers that can work on jobs in this campaign (optional)"
    },
    "maxWorkTime": {
      "type": "string",
      "description": "time a worker has to work on a job of this campaign (optional)"
    },
    "maxUploadTime": {
      "type": "string",
      "description": "time a worker has to upload the results after finishing his work (optional)"
    },
    "maxReviewTime": {
      "type": "string",
      "description": "(string, optional) - timeframe in which results can be (soft-) rejected before they get auto approved (optional)"
    },
    "training": {
      "type": "boolean",
      "description": "if this campaign is a training for future jobs (optional)"
    },
    "startDate": {
      "type": "string",
      "description": "publish this campaign automatically at a specific date (optional)"
    },
    "endDate": {
      "type": "string",
      "description": "finish this campaign automatically at a specific date (optional)"
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)"
    }
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "name": "My first Campaign",
  "title": "Review model images",
  "description": "You will see 20 models images which you should rate on a 1 to 5 scale.",
  "terms": "Don't tell anyone about this.",
  "estDuration": "10 sec",
  "workerPayment": 0.01,
  "results": 3,
  "maxResultsPerWorker": 1,
  "workerGroup": 1,
  "maxWorkTime": "10 min",
  "maxUploadTime": "4 hours",
  "maxReviewTime": "3 hours",
  "training": false,
  "startDate": "2018-01-01T10:00",
  "endDate": "2018-01-01T10:00",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "state": "unpublished",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the campaign"
    },
    "title": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "description": {
      "type": "string",
      "description": "description for jobs in this campaign on the job market"
    },
    "terms": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "estDuration": {
      "type": "string",
      "description": "estimated duration for jobs in this campaign"
    },
    "workerPayment": {
      "type": "number",
      "description": "payment (in USD) for workers who work on jobs in this campaign."
    },
    "results": {
      "type": "number",
      "description": "number of results that should be generated for each job of the campaign"
    },
    "maxResultsPerWorker": {
      "type": "number",
      "description": "number of times a single worker can work on each job of the campaign (optional)"
    },
    "workerGroup": {
      "type": "number",
      "description": "id of a workergroup to specify the workers that can work on jobs in this campaign (optional)"
    },
    "maxWorkTime": {
      "type": "string",
      "description": "time a worker has to work on a job of this campaign (optional)"
    },
    "maxUploadTime": {
      "type": "string",
      "description": "time a worker has to upload the results after finishing his work (optional)"
    },
    "maxReviewTime": {
      "type": "string",
      "description": "(string, optional) - timeframe in which results can be (soft-) rejected before they get auto approved (optional)"
    },
    "training": {
      "type": "boolean",
      "description": "if this campaign is a training for future jobs (optional)"
    },
    "startDate": {
      "type": "string",
      "description": "publish this campaign automatically at a specific date (optional)"
    },
    "endDate": {
      "type": "string",
      "description": "finish this campaign automatically at a specific date (optional)"
    },
    "state": {
      "type": "string",
      "enum": [
        "unpublished",
        "active",
        "paused",
        "cancelled",
        "finished"
      ]
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Update a Campaign
PUT/campaigns/{id}

URI Parameters
HideShow
id
number (required) 

id of the campaign


DELETE https://api.swarms.com/campaigns/id
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json

Delete a Campaign
DELETE/campaigns/{id}

URI Parameters
HideShow
id
number (required) 

id of the campaign


POST https://api.swarms.com/campaigns/id/copy?deep=false
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Campaign",
  "title": "Review model images",
  "description": "You will see 20 models images which you should rate on a 1 to 5 scale.",
  "terms": "Don't tell anyone about this.",
  "estDuration": "10 sec",
  "workerPayment": 0.01,
  "results": 3,
  "maxResultsPerWorker": 1,
  "workerGroup": 1,
  "maxWorkTime": "10 min",
  "maxUploadTime": "4 hours",
  "maxReviewTime": "3 hours",
  "training": false,
  "startDate": "2018-01-01T10:00",
  "endDate": "2018-01-01T10:00",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "state": "unpublished",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the campaign"
    },
    "title": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "description": {
      "type": "string",
      "description": "description for jobs in this campaign on the job market"
    },
    "terms": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "estDuration": {
      "type": "string",
      "description": "estimated duration for jobs in this campaign"
    },
    "workerPayment": {
      "type": "number",
      "description": "payment (in USD) for workers who work on jobs in this campaign."
    },
    "results": {
      "type": "number",
      "description": "number of results that should be generated for each job of the campaign"
    },
    "maxResultsPerWorker": {
      "type": "number",
      "description": "number of times a single worker can work on each job of the campaign (optional)"
    },
    "workerGroup": {
      "type": "number",
      "description": "id of a workergroup to specify the workers that can work on jobs in this campaign (optional)"
    },
    "maxWorkTime": {
      "type": "string",
      "description": "time a worker has to work on a job of this campaign (optional)"
    },
    "maxUploadTime": {
      "type": "string",
      "description": "time a worker has to upload the results after finishing his work (optional)"
    },
    "maxReviewTime": {
      "type": "string",
      "description": "(string, optional) - timeframe in which results can be (soft-) rejected before they get auto approved (optional)"
    },
    "training": {
      "type": "boolean",
      "description": "if this campaign is a training for future jobs (optional)"
    },
    "startDate": {
      "type": "string",
      "description": "publish this campaign automatically at a specific date (optional)"
    },
    "endDate": {
      "type": "string",
      "description": "finish this campaign automatically at a specific date (optional)"
    },
    "state": {
      "type": "string",
      "enum": [
        "unpublished",
        "active",
        "paused",
        "cancelled",
        "finished"
      ]
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Copy a Campaign
POST/campaigns/{id}/copy{?deep}

URI Parameters
HideShow
id
number (required) 

id of the campaign that should be copied

deep
boolean (required) Example: false

if true, included jobs and tasks will also be copied and linked to the campaign. If false, existing jobs and tasks for the orginial campaign will be linked to the new one.


POST https://api.swarms.com/campaigns/id/archive?deep=false
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Campaign",
  "title": "Review model images",
  "description": "You will see 20 models images which you should rate on a 1 to 5 scale.",
  "terms": "Don't tell anyone about this.",
  "estDuration": "10 sec",
  "workerPayment": 0.01,
  "results": 3,
  "maxResultsPerWorker": 1,
  "workerGroup": 1,
  "maxWorkTime": "10 min",
  "maxUploadTime": "4 hours",
  "maxReviewTime": "3 hours",
  "training": false,
  "startDate": "2018-01-01T10:00",
  "endDate": "2018-01-01T10:00",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "state": "unpublished",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the campaign"
    },
    "title": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "description": {
      "type": "string",
      "description": "description for jobs in this campaign on the job market"
    },
    "terms": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "estDuration": {
      "type": "string",
      "description": "estimated duration for jobs in this campaign"
    },
    "workerPayment": {
      "type": "number",
      "description": "payment (in USD) for workers who work on jobs in this campaign."
    },
    "results": {
      "type": "number",
      "description": "number of results that should be generated for each job of the campaign"
    },
    "maxResultsPerWorker": {
      "type": "number",
      "description": "number of times a single worker can work on each job of the campaign (optional)"
    },
    "workerGroup": {
      "type": "number",
      "description": "id of a workergroup to specify the workers that can work on jobs in this campaign (optional)"
    },
    "maxWorkTime": {
      "type": "string",
      "description": "time a worker has to work on a job of this campaign (optional)"
    },
    "maxUploadTime": {
      "type": "string",
      "description": "time a worker has to upload the results after finishing his work (optional)"
    },
    "maxReviewTime": {
      "type": "string",
      "description": "(string, optional) - timeframe in which results can be (soft-) rejected before they get auto approved (optional)"
    },
    "training": {
      "type": "boolean",
      "description": "if this campaign is a training for future jobs (optional)"
    },
    "startDate": {
      "type": "string",
      "description": "publish this campaign automatically at a specific date (optional)"
    },
    "endDate": {
      "type": "string",
      "description": "finish this campaign automatically at a specific date (optional)"
    },
    "state": {
      "type": "string",
      "enum": [
        "unpublished",
        "active",
        "paused",
        "cancelled",
        "finished"
      ]
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Archive a Campaign
POST/campaigns/{id}/archive{?deep}

URI Parameters
HideShow
id
number (required) 

id of the campaign that should be archived

deep
boolean (required) Example: false

if true, included jobs and tasks will also be archived and linked to the campaign.


POST https://api.swarms.com/campaigns/id/unarchive
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses201
Headers
Content-Type: application/json
Body
{
  "name": "My first Campaign",
  "title": "Review model images",
  "description": "You will see 20 models images which you should rate on a 1 to 5 scale.",
  "terms": "Don't tell anyone about this.",
  "estDuration": "10 sec",
  "workerPayment": 0.01,
  "results": 3,
  "maxResultsPerWorker": 1,
  "workerGroup": 1,
  "maxWorkTime": "10 min",
  "maxUploadTime": "4 hours",
  "maxReviewTime": "3 hours",
  "training": false,
  "startDate": "2018-01-01T10:00",
  "endDate": "2018-01-01T10:00",
  "properties": {
    "key": "key",
    "value": "value"
  },
  "state": "unpublished",
  "id": 1,
  "readOnly": false,
  "lastModifiedAt": "2017-08-02T13:58:24",
  "createdAt": "2017-08-02T13:58:24",
  "archived": false
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "name of the campaign"
    },
    "title": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "description": {
      "type": "string",
      "description": "description for jobs in this campaign on the job market"
    },
    "terms": {
      "type": "string",
      "description": "title for jobs in this campaign on the job market"
    },
    "estDuration": {
      "type": "string",
      "description": "estimated duration for jobs in this campaign"
    },
    "workerPayment": {
      "type": "number",
      "description": "payment (in USD) for workers who work on jobs in this campaign."
    },
    "results": {
      "type": "number",
      "description": "number of results that should be generated for each job of the campaign"
    },
    "maxResultsPerWorker": {
      "type": "number",
      "description": "number of times a single worker can work on each job of the campaign (optional)"
    },
    "workerGroup": {
      "type": "number",
      "description": "id of a workergroup to specify the workers that can work on jobs in this campaign (optional)"
    },
    "maxWorkTime": {
      "type": "string",
      "description": "time a worker has to work on a job of this campaign (optional)"
    },
    "maxUploadTime": {
      "type": "string",
      "description": "time a worker has to upload the results after finishing his work (optional)"
    },
    "maxReviewTime": {
      "type": "string",
      "description": "(string, optional) - timeframe in which results can be (soft-) rejected before they get auto approved (optional)"
    },
    "training": {
      "type": "boolean",
      "description": "if this campaign is a training for future jobs (optional)"
    },
    "startDate": {
      "type": "string",
      "description": "publish this campaign automatically at a specific date (optional)"
    },
    "endDate": {
      "type": "string",
      "description": "finish this campaign automatically at a specific date (optional)"
    },
    "state": {
      "type": "string",
      "enum": [
        "unpublished",
        "active",
        "paused",
        "cancelled",
        "finished"
      ]
    },
    "id": {
      "type": "number",
      "description": "id of the resource"
    },
    "readOnly": {
      "type": "boolean",
      "description": "indicates whether the resource can be modified"
    },
    "lastModifiedAt": {
      "type": "string",
      "description": "the datetime of the last modification of the resource."
    },
    "createdAt": {
      "type": "string",
      "description": "the datetime of the creation of the resource."
    },
    "archived": {
      "type": "boolean",
      "description": "if the resource is archived."
    },
    "properties": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "a custom key"
        },
        "value": {
          "type": "string",
          "description": "a custom value"
        }
      },
      "description": "a json object containing a set of custom key/value pairs (optional)."
    }
  }
}

Unarchive a Campaign
POST/campaigns/{id}/unarchive

URI Parameters
HideShow
id
number (required) 

id of the campaign that should be archived. Will also unarchive included jobs and tasks.


Jobs of a Campaign

You can add, update and get the jobs of a campaign.

GET https://api.swarms.com/campaigns/id/jobs
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "_links": {
    "next": {
      "href": "/resources?after=42&..."
    },
    "previous": {
      "href": "/resources?before=42&..."
    }
  },
  "jobs": [
    {
      "name": "My first Job",
      "description": "this job differs from the others!",
      "properties": {
        "key": "key",
        "value": "value"
      },
      "resourcesSize": "3MB",
      "estimatedUploadSize": "2MB",
      "id": 1,
      "readOnly": false,
      "lastModifiedAt": "2017-08-02T13:58:24",
      "createdAt": "2017-08-02T13:58:24",
      "archived": false
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "properties": {
        "next": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the next page"
            }
          }
        },
        "previous": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the previous page"
            }
          }
        }
      }
    },
    "jobs": {
      "type": "array"
    }
  }
}

List Jobs of a Campaign
GET/campaigns/{id}/jobs

URI Parameters
HideShow
id
number (required) 

id of the campaign


POST https://api.swarms.com/campaigns/id/jobs
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
[
  1
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Responses200
Headers
Content-Type: application/json

Add Jobs to a Campaign
POST/campaigns/{id}/jobs

URI Parameters
HideShow
id
number (required) 

id of the campaign


PUT https://api.swarms.com/campaigns/id/jobs
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
[
  1
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Responses200
Headers
Content-Type: application/json

Update Jobs of a Campaign
PUT/campaigns/{id}/jobs

URI Parameters
HideShow
id
number (required) 

id of the campaign


Campaign Lifecycle

The Campaigns state manages the availability of it’s jobs on our Job Market.

Initially, a Campaign is unpublished. After you added Jobs to it, you can publish it to our Job Market which will set its state to active. When the Campaign is active, it’s Jobs are available on our Job Market and workers can work on them. You can pause an active Campaign and continue it afterwards. When all results for a Campaign have been generated, the Campaign’s state is set to finished.

It is also possible to cancel a campaign after it has been published.

This lifecycle is also shown in the below drawing.

test

POST https://api.swarms.com/campaigns/id/publish
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json

Publish a Campaign
POST/campaigns/{id}/publish

URI Parameters
HideShow
id
number (required) 

id of the campaign


POST https://api.swarms.com/campaigns/id/pause
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json

Pause an active Campaign
POST/campaigns/{id}/pause

URI Parameters
HideShow
id
number (required) 

id of the campaign


POST https://api.swarms.com/campaigns/id/continue
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json

Continue a paused Campaign
POST/campaigns/{id}/continue

URI Parameters
HideShow
id
number (required) 

id of the campaign


POST https://api.swarms.com/campaigns/id/cancel
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json

Cancel a published Campaign
POST/campaigns/{id}/cancel

URI Parameters
HideShow
id
number (required) 

id of the campaign


Result

You can get the Results for Campaigns that have been published to our Job Market. In the moment the Worker uploads the Results to our servers, your time to review the Results begins. This time can be set by the maxReviewTime attribute of the Campaign.

You can approve, reject or soft-reject a Result during the review time. If you reject a Result, the worker won’t get paid and his reputation gets damaged. With a soft-reject, you can ask a Worker to redo the Job. In contrast to a normal reject this will have no effect on the Worker’s reputation.

When the review time expires without any action, it will get auto-approved.

The Worker will only get paid at the moment his Results get approved.

The result object

GET https://api.swarms.com/campaigns/id/results?limit=?state=?since=
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "_links": {
    "next": {
      "href": "/resources?after=42&..."
    },
    "previous": {
      "href": "/resources?before=42&..."
    }
  },
  "results": [
    {
      "worker": 42,
      "job": 24,
      "startedAt": "2017-08-02T13:58:24",
      "completedAt": "2017-08-02T13:58:24",
      "state": "InReview",
      "taskResults": [
        {
          "task": {
            "id": 42,
            "name": "My first Task"
          },
          "startedAt": "2017-08-02T13:58:24",
          "completedAt": "2017-08-02T13:58:24",
          "components": [
            {
              "data": {
                "type": "BinaryChoice",
                "landscape": true,
                "properties": {
                  "key": "key",
                  "value": "value"
                },
                "sticky": false
              },
              "result": {
                "url": "Hello, world!"
              }
            }
          ]
        }
      ],
      "id": 12,
      "assignmentId": 6
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "properties": {
        "next": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the next page"
            }
          }
        },
        "previous": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the previous page"
            }
          }
        }
      }
    },
    "results": {
      "type": "array"
    }
  }
}

List all Results for a Campaign
GET/campaigns/{id}/results{?limit}{?state}{?since}

URI Parameters
HideShow
id
number (required) 

id of the result

limit
number (optional) 

the number of elements being fetched. Default is 10.

state
string (optional) 

filter results by state. One of InReview, Approved, Rejected.

since
string (optional) 

only fetch results that were submitted after a specific date. Format as in 2018-03-14T03:14.


GET https://api.swarms.com/campaigns/id/workers?limit=?InReview=
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "_links": {
    "next": {
      "href": "/resources?after=42&..."
    },
    "previous": {
      "href": "/resources?before=42&..."
    }
  },
  "workers": [
    {
      "id": 42,
      "reputation": {
        "me": 100,
        "global": 99.99
      },
      "experience": {
        "me": 24,
        "global": 42
      },
      "results": {
        "inReview": 24,
        "approved": 42,
        "rejected": 24
      }
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "properties": {
        "next": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the next page"
            }
          }
        },
        "previous": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the previous page"
            }
          }
        }
      }
    },
    "workers": {
      "type": "array"
    }
  }
}

List all Workers that participated in a Campaign
GET/campaigns/{id}/workers{?limit}{?InReview}

URI Parameters
HideShow
id
number (required) 

id of the result

limit
number (optional) 

the number of elements being fetched. Default is 10.

InReview
boolean (optional) 

if true, only workers that currently have results in review will be fetched.


GET https://api.swarms.com/campaigns/campaignId/workers/workerId/results?limit=?state=?since=
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Responses200
Headers
Content-Type: application/json
Body
{
  "_links": {
    "next": {
      "href": "/resources?after=42&..."
    },
    "previous": {
      "href": "/resources?before=42&..."
    }
  },
  "results": [
    {
      "worker": 42,
      "job": 24,
      "startedAt": "2017-08-02T13:58:24",
      "completedAt": "2017-08-02T13:58:24",
      "state": "InReview",
      "taskResults": [
        {
          "task": {
            "id": 42,
            "name": "My first Task"
          },
          "startedAt": "2017-08-02T13:58:24",
          "completedAt": "2017-08-02T13:58:24",
          "components": [
            {
              "data": {
                "type": "BinaryChoice",
                "landscape": true,
                "properties": {
                  "key": "key",
                  "value": "value"
                },
                "sticky": false
              },
              "result": {
                "url": "Hello, world!"
              }
            }
          ]
        }
      ],
      "id": 12,
      "assignmentId": 6
    }
  ],
  "worker": {
    "id": 42,
    "reputation": {
      "me": 100,
      "global": 99.99
    },
    "experience": {
      "me": 24,
      "global": 42
    },
    "results": {
      "inReview": 24,
      "approved": 42,
      "rejected": 24
    }
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "_links": {
      "type": "object",
      "properties": {
        "next": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the next page"
            }
          }
        },
        "previous": {
          "type": "object",
          "properties": {
            "href": {
              "type": "string",
              "description": "url of the previous page"
            }
          }
        }
      }
    },
    "results": {
      "type": "array"
    },
    "worker": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number",
          "description": "workers id"
        },
        "reputation": {
          "type": "object",
          "properties": {
            "me": {
              "type": "number",
              "description": "workers reputation on jobs from you"
            },
            "global": {
              "type": "number",
              "description": "workers global reputation on the platform"
            }
          },
          "description": "workers reputation"
        },
        "experience": {
          "type": "object",
          "properties": {
            "me": {
              "type": "number",
              "description": "workers experience on jobs from you"
            },
            "global": {
              "type": "number",
              "description": "workers global experience on the platform"
            }
          },
          "description": "workers experience"
        },
        "results": {
          "type": "object",
          "properties": {
            "inReview": {
              "type": "number",
              "description": "number of results in review in the campaign"
            },
            "approved": {
              "type": "number",
              "description": "number of approved results in the campaign"
            },
            "rejected": {
              "type": "number",
              "description": "number of rejected results in the campaign"
            }
          },
          "description": "workers results counts for the campaign"
        }
      }
    }
  }
}

List all Results for a Campaign for a specific Worker
GET/campaigns/{campaignId}/workers/{workerId}/results{?limit}{?state}{?since}

URI Parameters
HideShow
campaignId
number (required) 

id of the campaign

workerId
number (required) 

id of the worker

limit
number (optional) 

the number of elements being fetched. Default is 10.

state
string (optional) 

filter results by state. One of InReview, Approved, Rejected.

since
string (optional) 

only fetch results that were submitted after a specific date. Format as in 2018-03-14T03:14.


POST https://api.swarms.com/results/id/approve
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "message": "Well done!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "an optional message for the worker"
    }
  }
}
Responses200
Headers
Content-Type: application/json

Approve a Result
POST/results/{id}/approve

URI Parameters
HideShow
id
number (required) 

id of the result


POST https://api.swarms.com/campaigns/campaignId/workers/workerId/approve-all
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "message": "Well done!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "an optional message for the worker"
    }
  }
}
Responses200
Headers
Content-Type: application/json

Approve all in review Results of a Worker
POST/campaigns/{campaignId}/workers/{workerId}/approve-all

URI Parameters
HideShow
campaignId
number (required) 

id of the campaign

workerId
number (required) 

id of the worker


POST https://api.swarms.com/campaigns/campaignId/results/approve-all
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "message": "Well done!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "an optional message for the worker"
    }
  }
}
Responses200
Headers
Content-Type: application/json

Approve all in review Results of a Campaign
POST/campaigns/{campaignId}/results/approve-all

URI Parameters
HideShow
campaignId
number (required) 

id of the campaign


POST https://api.swarms.com/results/id/reject
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "reason": "Cheating detected!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "reason": {
      "type": "string",
      "description": "a reason for the rejection that is displayed to the worker"
    }
  },
  "required": [
    "reason"
  ]
}
Responses200
Headers
Content-Type: application/json

Reject a Result
POST/results/{id}/reject

URI Parameters
HideShow
id
number (required) 

id of the result


POST https://api.swarms.com/results/id/soft-reject
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
  "reason": "Be more precise, please",
  "until": "2017-08-02T13:58:24"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "reason": {
      "type": "string",
      "description": "a reason for the rejection that is displayed to the worker provided in Markdown"
    },
    "until": {
      "type": "string",
      "description": "timestamp until when the worker can redo the job"
    }
  },
  "required": [
    "reason",
    "until"
  ]
}
Responses200
Headers
Content-Type: application/json

Soft-reject a Result
POST/results/{id}/soft-reject

URI Parameters
HideShow
id
number (required) 

id of the result


POST https://api.swarms.com/preview/markdown
Requestsexample 1
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: token
Body
{
    "text": "# Markdown Feedback
    Get a HTML preview of the message you include as feedback to the worker in the results actions.
    Find a Markdown cheat sheet at: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet.
    You can include videos ans audio data the same way as images, i.e. `![alt text](https://example.com/video.mp4 "Sample video")`.
    It is also possible to include youtube videos: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#youtube-videos."
}
Responses200
Headers
Content-Type: application/json

HTML Markdown message Preview
POST/preview/markdown


Components Overview

Here you can see the all currently supported components that you can use to build your Tasks. The components will be displayed below each other in the Task.

Interactive Components

  • AudioRecording

  • BinaryChoice

  • BinaryImageChoice

  • ImageMarker

  • Rating

  • TextInput

  • Toggle

  • VideoRecording

Non-Interactive Components

  • Audio

  • Image

  • Text

  • Video

Interactive Components

Interactive Components require the Worker’s input. These components will generate the Results that can be fetched afterwards.

AudioRecording

The AudioRecording let’s the worker to record audio. The worker can record, play and rerecord the audio.

Example

AudioRecording

Attributes

name type description
minDurationInSeconds number minimum duration of the recording in seconds
maxDurationInSeconds number maximum duration of the recording in seconds

Result

name type description
url string url of the audio (with .aac extension)

BinaryChoice

A BinaryChoice will display two labelled buttons to the worker. The worker can only select one of them.

Example

BinaryChoice

Attributes

name type description
option1 string 1st option label
option2 string 2nd option label

Result

name type description
selectedOption string selected option label

BinaryImageChoice

A BinaryImageChoice will display two labelled images to the worker. The worker can only select one of them.

Example

BinaryImageChoice

Attributes

name type description
option1 Option Object 1st Option Object
option2 Option Object 2nd Option Object
Option Object
name type description
id string option id
url string option image url
label string option label

Result

name type description
selectedOption string selected option id

ImageMarker

The ImageMarker let’s the worker draw on an image using his finger. He can adjust the size, color and opacity of the drawing. Also erase the drawing, undo and redo his changes, zoom, and draw in landscape or portrait mode. The image is rendered without pixel smoothing, so that the worker can be very precise with his drawings.

Example

ImageMarker

This example uses the following input image and would generate the following result:

input

a

result

ImageMarkerResult

Attributes

name type description
url string url of the image

Result

name type description
url string url of the drawing (with .png extension)

Rating

A Rating component displays a simple Rating bar to the user. The worker must select at least one star. You can define the number of stars and if the worker can also select half stars.

Example

Rating

Attributes

name type description
steps number number of stars
halfSteps boolean whether the worker can select half stars

Result

name type description
rating number rating

Stepper

A Stepper component requires the worker to select a number from a specified number range by tapping up and down arrows. You can define the minimum and maximum values of the range, a start value, and an value change step.

Example

Stepper

Attributes

name type description
min number minimum value of the range
max number maximum value of the range
step number value change step
start number number of stars

Result

name type description
result number selected number

TextInput

A TextInput will ask a worker for a short text input via keyboard. You can set a hint that is displayed in the input field before the worker starts typing.

Example

TextInput

Attributes

name type description
hint string text of the input field before typing

Result

name type description
text string the worker’s input

Toggle

A Toggle can be used to ask for a simple true/false on a label. It can be set to be toggled by default.

Example

Toggle

Attributes

name type description
label string label of the Toggle
checkedByDefault boolean the initial state of the Toggle
explanation string an explanation for the worker. Shown as a Popup.

Result

name type description
checked boolean whether worker checked the Toggle

VideoRecording

Example

VideoRecording

Attributes

name type description
orientation string video orientation: “any”, “portrait”, “landscape”
minDurationInSeconds number minimum video duration
maxDurationInSeconds number maximum video duration

Result

name type description
url string url of the recorded video

Non-interactive Components

Audio

An audio file which is playable in a simple audio player in the Task. You can set whether it should start or repeat automatically and whether the worker has to listen it fully at least once. The worker can pause and replay the audio.

Example

Audio

Attributes

name type description
url string url of the audio
autoplay boolean whether the audio should start playing automatically
repeat boolean whether the audio should repeat automatically
mustListen boolean whether the worker must listen the audio at least once

Image

A simple image that is displayed in the Task.

Example

Image

Attributes

name type description
url string url of the image

Text

A text that is displayed in the Task in a style of your choice

Example

Text

Attributes

name type description
text string the text to display
style string the style of the text

The attribute style can be one of: "Question", "Instruction", "H1", "H2", "PlainText", "Html", "Quote"

Video

A video which is playable in a simple video player in the Task. You can set it to play or repeat automatically, mute the sound, and define whether the worker has to watch it fully at least once. The worker can pause and replay the video.

Example

Video

Attributes

name type description
url string url of the video
autoplay boolean whether the video should start playing automatically
repeat boolean whether the video should repeat automatically
mustWatch boolean whether the worker must watch the video at least once
playAudio boolean whether the audio should be played

Generated by aglio on 06 Jun 2018