SWARMS API
API Endpoint
https://api.swarms.comOur 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
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0Body
{
"email": "me@example.com",
"password": "password"
}Responses
Headers
Content-Type: application/jsonBody
{
"accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxLUlVdVpWSTRKcDFSOVlTTGFOUHBGOVFcL1kwcU95TG10RGt0TE5WaG5GV0hSNDBMTklkZzN4TVAyZ0NrT0N3YzhYQ1Q4cmZsZlprcVhOeE1VQzlaZ3RVRFZnU1dBOXBOVW04MWlhIiwiaXNzIjoia3dpcXByb3ZpZGVyIiwiZXhwIjoxNTA4OTI0NDAwLCJpYXQiOjE1MDYzMzI0MDAsImp0aSI6ImEwMWNmYTBkZjJlYjI2NWYzOTQ1NTkxYmMyOGY3MWEzNTg5ZDE3NjZlYmI4MmRhYTBjYTFhOGIwNzJkNzI1ODk0OWJmOTZkMTUyOTJjNTFmYWNmNGFkZDNkMDZjMDQ2YjExYmRjNmI2Yjc2YTYwNmZkN2JmMTI2MzQ4NWZhZGNhYzU0NjExMTU2NGNhNGNiMjhiZTg5MGNlNDY5MjMyY2QyNmI5ZmIzMTdhZTVhZmQ1NjE0NWQzOGExODg1MzdkZTUxMDMxYWQwYmY4YTY3YjNlNzVjMzkwNTVkZDUxNTQzZDY0ODNkNzc4OGEwOTQwMWY4YWQ0MjEyNTNhYmI3ZDEifQ.AzOxuj3DBELmFyphOJQxAlodA3PzDeBN6x4G5qO1H5s",
"expiresAt": "2017-10-25T09:40:00",
"userId": 42
}Request an auth tokenPOST/auth/token/request
Discard an auth token ¶
POST https://api.swarms.com/auth/token/discard
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonDiscard an auth tokenPOST/auth/token/discard
Profile ¶
The Profile object ¶
GET https://api.swarms.com/me
Requests
Headers
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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 ProfileGET/me
PUT https://api.swarms.com/me
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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"
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"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 ProfilePUT/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=
Requests
Headers
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"_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 TasksGET/tasks{?order}{?limit}{?search}
URI Parameters
- order
array[string](optional)Choices:
idnamelastModifiedAtcreatedAt- 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
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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)."
}
}
}POST https://api.swarms.com/tasks
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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)."
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"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 TaskPOST/tasks
PUT https://api.swarms.com/tasks/id
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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)."
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"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)."
}
}
}DELETE https://api.swarms.com/tasks/id
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonPOST https://api.swarms.com/tasks/id/copy
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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 TaskPOST/tasks/{id}/copy
URI Parameters
- id
number(required)id of the task that should be copied
POST https://api.swarms.com/tasks/id/archive
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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 TaskPOST/tasks/{id}/archive
URI Parameters
- id
number(required)id of the task that should be archived
POST https://api.swarms.com/tasks/id/unarchive
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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 TaskPOST/tasks/{id}/unarchive
URI Parameters
- 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=
Requests
Headers
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"_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 JobsGET/jobs{?order}{?limit}{?search}
URI Parameters
- order
array[string](optional)Choices:
idnamelastModifiedAtcreatedAt- 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
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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)."
}
}
}POST https://api.swarms.com/jobs
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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)."
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"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 JobPOST/jobs
PUT https://api.swarms.com/jobs/id
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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)."
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"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)."
}
}
}DELETE https://api.swarms.com/jobs/id
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonPOST https://api.swarms.com/jobs/id/copy?deep=false
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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 JobPOST/jobs/{id}/copy{?deep}
URI Parameters
- id
number(required)id of the job that should be copied
- deep
boolean(required) Example: falseif
true, included tasks will also be copied and linked to the job. Iffalse, existing tasks for the orginial job will be linked to the new one.
POST https://api.swarms.com/jobs/id/archive?deep=false
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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 JobPOST/jobs/{id}/archive{?deep}
URI Parameters
- id
number(required)id of the job that should be archived
- deep
boolean(required) Example: falseif
true, included tasks will also be archived and linked to the job.
POST https://api.swarms.com/jobs/id/unarchive
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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 JobPOST/jobs/{id}/unarchive
URI Parameters
- 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
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"_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"
}
}
}PUT https://api.swarms.com/jobs/id/tasks
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
[
1
]Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}Responses
Headers
Content-Type: application/jsonCampaign ¶
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=
Requests
Headers
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"_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 CampaignsGET/campaigns{?order}{?limit}{?search}
URI Parameters
- order
array[string](optional)Choices:
idnamelastModifiedAtcreatedAt- 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
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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)."
}
}
}POST https://api.swarms.com/campaigns
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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)"
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"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 CampaignPOST/campaigns
PUT https://api.swarms.com/campaigns/id
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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)"
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"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)."
}
}
}DELETE https://api.swarms.com/campaigns/id
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonPOST https://api.swarms.com/campaigns/id/copy?deep=false
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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 CampaignPOST/campaigns/{id}/copy{?deep}
URI Parameters
- id
number(required)id of the campaign that should be copied
- deep
boolean(required) Example: falseif
true, included jobs and tasks will also be copied and linked to the campaign. Iffalse, 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
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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 CampaignPOST/campaigns/{id}/archive{?deep}
URI Parameters
- id
number(required)id of the campaign that should be archived
- deep
boolean(required) Example: falseif
true, included jobs and tasks will also be archived and linked to the campaign.
POST https://api.swarms.com/campaigns/id/unarchive
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"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 CampaignPOST/campaigns/{id}/unarchive
URI Parameters
- 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
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"_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"
}
}
}POST https://api.swarms.com/campaigns/id/jobs
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
[
1
]Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}Responses
Headers
Content-Type: application/jsonPUT https://api.swarms.com/campaigns/id/jobs
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
[
1
]Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array"
}Responses
Headers
Content-Type: application/jsonUpdate Jobs of a CampaignPUT/campaigns/{id}/jobs
URI Parameters
- 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.
.svg)
POST https://api.swarms.com/campaigns/id/publish
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonPOST https://api.swarms.com/campaigns/id/pause
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonPause an active CampaignPOST/campaigns/{id}/pause
URI Parameters
- id
number(required)id of the campaign
POST https://api.swarms.com/campaigns/id/continue
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonContinue a paused CampaignPOST/campaigns/{id}/continue
URI Parameters
- id
number(required)id of the campaign
POST https://api.swarms.com/campaigns/id/cancel
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonCancel a published CampaignPOST/campaigns/{id}/cancel
URI Parameters
- 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=
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"_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 CampaignGET/campaigns/{id}/results{?limit}{?state}{?since}
URI Parameters
- 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=
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"_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 CampaignGET/campaigns/{id}/workers{?limit}{?InReview}
URI Parameters
- 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=
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenResponses
Headers
Content-Type: application/jsonBody
{
"_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 WorkerGET/campaigns/{campaignId}/workers/{workerId}/results{?limit}{?state}{?since}
URI Parameters
- 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
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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"
}
}
}Responses
Headers
Content-Type: application/jsonPOST https://api.swarms.com/campaigns/campaignId/workers/workerId/approve-all
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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"
}
}
}Responses
Headers
Content-Type: application/jsonApprove all in review Results of a WorkerPOST/campaigns/{campaignId}/workers/{workerId}/approve-all
URI Parameters
- campaignId
number(required)id of the campaign
- workerId
number(required)id of the worker
POST https://api.swarms.com/campaigns/campaignId/results/approve-all
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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"
}
}
}Responses
Headers
Content-Type: application/jsonApprove all in review Results of a CampaignPOST/campaigns/{campaignId}/results/approve-all
URI Parameters
- campaignId
number(required)id of the campaign
POST https://api.swarms.com/results/id/reject
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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"
]
}Responses
Headers
Content-Type: application/jsonPOST https://api.swarms.com/results/id/soft-reject
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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"
]
}Responses
Headers
Content-Type: application/jsonPOST https://api.swarms.com/preview/markdown
Requests
Headers
Content-Type: application/json
X-API-Version: 1.0
X-Auth-Token: tokenBody
{
"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. ``.
It is also possible to include youtube videos: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#youtube-videos."
}Responses
Headers
Content-Type: application/jsonHTML Markdown message PreviewPOST/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
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
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
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
This example uses the following input image and would generate the following result:
input
result
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
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
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
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
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
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
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
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
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
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