Introduction
Welcome to the OpenGuilds API documentation! Our API is REST based. That means predictable resource-oriented URLs, which return HTTP response codes to indicate API errors.
OpenGuilds API returns responses, including errors, and accepts requests in JSON format only. Our supported API libraries convert responses to appropriate language-specific objects.
Requests can be made to the live or test server endpoints. Test servers are separate from your main account and will not incur costs, including on third party services such as Amazon Mechanical Turk (it will use the workersandbox).
Test Endpoint: https://testing.openguilds.com/api
Live Endpoint: https://dashboard.openguilds.com/api
Authentication
Authorize a client using your Personal Access Key:
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
# With shell, you can just pass the correct header with each request
curl https://dashboard.openguilds.com/api/batches
-u "8641fb38-294a-41d9-9591-3449dfd99910"
# If you need to authenticate via bearer auth
# (e.g., for a cross-origin request), use:
-H "Authorization: Bearer 8641fb38-294a-41d9-9591-3449dfd99910"
# instead of -u 8641fb38-294a-41d9-9591-3449dfd99910.
Make sure to replace
8641fb38-294a-41d9-9591-3449dfd99910with your token.
OpenGuilds uses OAuth 2.0 to authenticate users. You can authenticate with the following OAuth flows:
You can also choose to use a personal access token, which you can manage from your account page. Personal access tokens allow access to all functions of your account and should be kept secret. Do not put keys on publicly accessible Github repositories or in client-side code.
If authentication is performed via HTTP Basic Auth provide your token as the basic auth username value. You do not need to provide a password.
All API requests will be made over HTTPS. Calls over plain HTTP will fail. API requests without authentication will also fail.
Authorization Code Flow
require 'open-guilds'
token = OpenGuilds::OAuth::AuthorizationCode.request_token(
client_id: 'YOUR_CLIENT_ID',
client_secret: 'YOUR_CLIENT_SECRET',
code: 'RETURNED_CODE',
redirect_uri: 'urn:ietf:wg:oauth:2.0:oob'
)
# You can then override the default token with the one received:
OpenGuilds::Batches.list(api_key: token)
# We can use the code granted in the previous step like so:
curl https://dashboard.openguilds.com/api/oauth/token
-d client_id="YOUR_CLIENT_ID"
-d client_secret="YOUR_CLIENT_SECRET"
-d code="RETURNED_CODE"
-d grant_type="authorization_code"
-d redirect_uri="urn:ietf:wg:oauth:2.0:oob"
Which should return your token:
{
"access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}
The authorization code flow is for exchanging an authorization code for an access token. It should be used to have users provide you with access to their accounts and your application is a web based app that can be redirected back to.
Getting an Authorization Code
To request this code through the web app you can go to: https://dashboard.openguilds.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code
The weird looking urn:ietf:wg:oauth:2.0:oob is there to tell the server
that you want to be redirected directly to the code page, and not back to your application.
If you have put in something else for your redirect path when registering your application,
make sure it matches with what you put in the above link.
Exchanging the Code for a Token
Once you have acquired the authorization code from above or from a client who has signed in through OAuth on your application, you can exchange it for an access token.
You can view all of your access tokens from your account page.
Access Token Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string | The access token which can be used as your API key in requests. |
| token_type | string | A description of the type of token. |
| expires_in | integer | The number of seconds from its creation until the token expires. |
| refresh_token | string | A code that can be used to refresh the token to extend its expiration date. |
Client Credentials Flow
require 'open-guilds'
token = OpenGuilds::OAuth::ClientCredentials.request_token(
client_id: 'YOUR_CLIENT_ID',
client_secret: 'YOUR_CLIENT_SECRET'
)
# You can then override the default token with the one received:
OpenGuilds::Batches.list(api_key: token)
# We can use the code granted in the previous step like so:
curl https://dashboard.openguilds.com/api/oauth/token
-d client_id="YOUR_CLIENT_ID"
-d client_secret="YOUR_CLIENT_SECRET"
-d grant_type="client_credentials"
Which should return your token:
{
"access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}
The client credentials flow is used for machine to machine authentication. It should be used when you want to authenticate your server to do something on your behalf.
Requesting an Access Token
Credentials can be requested by passing in your client ID as well as your client secret. These are both generated when you create an OAuth application and can be found on your account page.
Access Token Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string | The access token which can be used as your API key in requests. |
| token_type | string | A description of the type of token. |
| expires_in | integer | The number of seconds from its creation until the token expires. |
| refresh_token | string | A code that can be used to refresh the token to extend its expiration date. |
Password Flow
require 'open-guilds'
token = OpenGuilds::OAuth::Password.request_token(
client_id: 'YOUR_CLIENT_ID',
client_secret: 'YOUR_CLIENT_SECRET',
username: 'YOUR_USERNAME',
password: 'YOUR_PASSWORD'
)
# You can then override the default token with the one received:
OpenGuilds::Batches.list(api_key: token)
# We can use the code granted in the previous step like so:
curl https://dashboard.openguilds.com/api/oauth/token
-d client_id="YOUR_CLIENT_ID"
-d client_secret="YOUR_CLIENT_SECRET"
-d username="YOUR_USERNAME"
-d password="YOUR_PASSWORD"
-d grant_type="password"
Which should return your token:
{
"access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1"
}
The password flow is used when your application is not web based, but the owner of the application is also not the owner of the resource you want to access. In this case you can provide a username and password of the user who owns the resource.
Requesting an Access Token
Credentials can be requested by passing in your client ID, client secret as well as a username and password of the user who owns the resources. Your client ID and secret are both generated when you create an OAuth application and can be found on your account page.
Access Token Parameters
| Parameter | Type | Description |
|---|---|---|
| access_token | string | The access token which can be used as your API key in requests. |
| token_type | string | A description of the type of token. |
| expires_in | integer | The number of seconds from its creation until the token expires. |
| refresh_token | string | A code that can be used to refresh the token to extend its expiration date. |
Personal Access Tokens
Simply set your API key default to your personal access key:
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
# With shell, you can just pass the correct header with each request
curl https://dashboard.openguilds.com/api/batches
-u "8641fb38-294a-41d9-9591-3449dfd99910"
# If you need to authenticate via bearer auth
# (e.g., for a cross-origin request), use:
-H "Authorization: Bearer 8641fb38-294a-41d9-9591-3449dfd99910"
# instead of -u 8641fb38-294a-41d9-9591-3449dfd99910.
Make sure to replace
8641fb38-294a-41d9-9591-3449dfd99910with your token.
Personal Access tokens are created by you and act as more permanent API keys. They should be used in scripts or applications where you will only be using resources from your own account, and do not need to go through creating an OAuth application.
Creating a Personal Access Token
You can easily create a personal access token by visiting your account page.
Errors
The OpenGuilds API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- The resource requested is hidden for administrators only. |
| 404 | Not Found -- The specified resource could not be found. |
| 405 | Method Not Allowed -- You tried to access a resource with an invalid method. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 410 | Gone -- The resource requested has been removed from our servers. |
| 429 | Too Many Requests -- You're requesting too many resources! Slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Pagination
The List Object
The list object looks like this:
{
"object": "List",
"url": "/api/batches",
"has_more": false,
"page": 1,
"data": "[ ... ]"
}
All top-level API resources have support for bulk fetches via "list" API methods.
For instance, you can list guilds, list members, and list tasks.
Lists help you manage requests that exceed the 100 return limit on objects. By requesting 100 objects pages at a time until "has_more" returns false, you can crawl through thousands of objects in an ordered way.
| Attribute | Type | Description |
|---|---|---|
| object | string | A string for the objects type. |
| url | string | the url for a successive request. |
| has_more | boolean | A true or false value based on if there is another page. |
| page | integer | The current page number. |
| data | array[objects] | An array of requested objects. |
Options
An example of a call using a list limit:
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Guild.list(limit: 10)
curl https://dashboard.openguilds.com/api/guilds/<ID>?limit=10
-u "8641fb38-294a-41d9-9591-3449dfd99910"
-G
List requests takes 2 additional parameters:
| Parameter | Description |
|---|---|
| limit | A limit on the number of objects to be returned, between 1 and 100. |
| page | The page number, each page represents 100 records or your requested limit. |
Guilds
The Guild Object
The Guild object looks like this:
{
"object": "Guild",
"id": "1",
"name": "Audio Transcription",
"description": "This guild takes an audio file and returns a text transcription",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
Guilds are online organizations with a community of members.
Guilds are made up of many tasks where members process data by modifying it through workspaces.
The object has the following attributes:
| Attribute | Description |
|---|---|
| object | A string representing the object type. |
| id | The ID of the batch being returned. |
| name | The name of the guild. |
| description | A description of the guild. |
List all Guilds
Will return all guilds which an authorized user owns.
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Guild.list
curl https://dashboard.openguilds.com/api/guilds
-u "8641fb38-294a-41d9-9591-3449dfd99910"
The above command returns JSON structured like this:
{
"object": "List",
"url": "api/guilds",
"has_more": false,
"page": 1,
"data": [
{
"object": "Guild",
"id": "1",
"name": "Audio Transcription",
"description": "This guild takes an audio file and returns a text transcription",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
]
}
HTTP Request
GET https://dashboard.openguilds.com/api/guilds
Get a Guild
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Guild.get(1)
curl https://dashboard.openguilds.com/api/guilds/<ID>
-u "8641fb38-294a-41d9-9591-3449dfd99910"
The above command returns JSON structured like this:
{
"object": "Guild",
"id": "1",
"name": "Audio Transcription",
"description": "This guild takes an audio file and returns a text transcription",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
HTTP Request
GET https://dashboard.openguilds.com/api/guilds/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the guild to retrieve |
Members
The Member Object
The Member object looks like this:
{
"object": "Member",
"id": "1",
"email": "email@example.com",
"quality_score": 0.86,
"credit": "$5.00",
"credit_cents": 500,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
Members are individuals in a guilds community. Members can get qualifications, subscribe to tasks and perform work for a guild.
Members are rewarded for their correct work with guild credits. Members can request a payout from a guild which is then authorized by the guild owner.
Members are assigned a quality score which is measured by their answers given to specific questions according to a golden set of answers.
The object has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| object | string | The object being described by the incoming data, in this case a Guild. |
| id | string | The ID of the batch being returned. |
| string | The email of the Member. | |
| quality_score | float | A score between 0.00 and 1.00 which determines the members test accuracy. |
| credit | string | The total available credit a user has to request a payout. |
| credit_cents | integer | The total available credit a user has to request a payout expressed in the number of cents. |
List all Members
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
#The ID for the guild is passed in as the first argument.
OpenGuilds::Member.list(1)
curl https://dashboard.openguilds.com/api/guilds/<GUILD_ID>/members
-u "8641fb38-294a-41d9-9591-3449dfd99910"
The above command returns JSON structured like this:
{
"object": "List",
"url": "api/guilds/1/members",
"has_more": false,
"page": 1,
"data": [
{
"object": "Member",
"id": "1",
"email": "email@example.com",
"quality_score": 0.86,
"credit": "$5.00",
"credit_cents": 500,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
]
}
HTTP Request
GET https://dashboard.openguilds.com/api/guild/<GUILD_ID>/members
URL Parameters
| Parameter | Description |
|---|---|
| GUILD_ID | The ID of the guild you want to view the membership of |
Get a Member
Members can be found by either sending a GET request to the guild members URL, or by finding them by their email attribute.
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Member.find(guild: 1, email: 'email@example.com')
curl https://dashboard.openguilds.com/api/guilds/<GUILD_ID>/members/find
-u "8641fb38-294a-41d9-9591-3449dfd99910"
-d email='email@example.com'
The above command returns JSON structured like this:
{
"object": "Member",
"id": "1",
"email": "email@example.com",
"quality_score": 0.86,
"credit": "$5.00",
"credit_cents": 500,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
HTTP Request
GET https://dashboard.openguilds.com/api/guild/<GUILD_ID>/members/find
OR
GET https://dashboard.openguilds.com/api/guild/<GUILD_ID>/members/<ID>
POST Parameters
| Parameter | Description |
|---|---|
| The email of the member you wish to find |
URL Parameters
| Parameter | Description |
|---|---|
| GUILD_ID | The ID of the guild the membership is for. |
| ID | The ID of the member you are looking for. |
Invite a new Member
Inviting a member will send them an invitation via email with a link they can click to accept.
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Member.invite(guild: 1, email: 'email@example.com')
curl https://dashboard.openguilds.com/api/guilds/<GUILD_ID>/invites
-u "8641fb38-294a-41d9-9591-3449dfd99910"
-d email="email@example.com"
The above command returns JSON structured like this:
{
"object": "Invite",
"id": "1",
"email": "email@example.com",
"status": "sending",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
HTTP Request
GET https://dashboard.openguilds.com/api/guild/<GUILD_ID>/invites
Request Parameters
| Parameter | Description |
|---|---|
| The email of the new member |
URL Parameters
| Parameter | Description |
|---|---|
| GUILD_ID | The ID of the guild the invite is for |
Remove a Member
Removing a member will destroy their active membership to the guild, but maintain all their records of work.
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Member.remove(1)
curl https://dashboard.openguilds.com/api/guilds/<GUILD_ID>/members/<ID>
-u "8641fb38-294a-41d9-9591-3449dfd99910"
-X DELETE
The above command returns JSON structured like this:
{
"object": "Member",
"id": "1",
"deleted": true
}
HTTP Request
GET https://dashboard.openguilds.com/api/guild/<GUILD_ID>/members/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| GUILD_ID | The ID of the guild the invite is for |
| ID | The ID of the member you want to remove |
Tasks
The Task Object
The Task object looks like this:
{
"object": "Task",
"id": "1",
"minimum_amount": "$5.00",
"minimum_amount_cents": 500,
"workspace": {
"name": "Audio Transcription Interface",
"link": "api/workspaces/1",
"preview": "https://preview.interface.com",
"permissions": "open"
},
"connections": {
"object": "List",
"url": "/api/task/1/connections",
"has_more": false,
"page": 1,
"data": [
{
"object": "Connection",
"source_id": "1",
"target_id": "2"
}
]
},
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
Guilds have a series of tasks they perform on each piece of data.
Members subscribe to tasks to receive the tasks work.
To subscribe to a task, members must have all the required qualifications, which can be created by going to the task page.
Members perform work on data by transforming it through a workspace.
Tasks are bound together through connections which are created on your guild page.
The object has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| object | string | The object being described by the incoming data, in this case a Task |
| id | string | The ID of the task being returned. |
| minimum_amount | string | The minimum cost of a datum being processed through this task. |
| minimum_amount_cents | integer | The minimum cost of a datum being processed through this task in cents. |
| workspace | object | The connected workspace object for this task. |
| connections | object | A list of associated connection objects. |
The Connection object has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| object | string | The object being described by the incoming data, in this case a Connection |
| source | string | The ID of the task used as the source of the data transfer. |
| target | string | The ID of the task used as the destination of the data transfer. |
An inbound connection has the task object ID match the target ID, and an outbound connection has the task ID match the source ID.
List all Tasks
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
#The guild ID is passed in as the first argument
OpenGuilds::Tasks.list(1)
curl https://dashboard.openguilds.com/api/guilds/<GUILD_ID>/tasks
-u "8641fb38-294a-41d9-9591-3449dfd99910"
The above command returns JSON structured like this:
{
"object": "List",
"url": "/api/guilds/<GUILD_ID>/tasks",
"has_more": false,
"page": 1,
"data": [
{
"object": "Task",
"id": "1",
"minimum_amount": "$5.00",
"minimum_amount_cents": 500,
"workspace": {
"name": "Audio Transcription Interface",
"link": "api/workspaces/1",
"preview": "https://preview.interface.com",
"permissions": "open"
},
"connections": {
"object": "List",
"url": "/api/task/1/connections",
"has_more": false,
"page": 1,
"data": [
{
"object": "Connection",
"source_id": "1",
"target_id": "2"
}
]
},
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
]
}
HTTP Request
GET https://dashboard.openguilds.com/api/guilds/<GUILD_ID>/tasks
URL Parameters
| Parameter | Description |
|---|---|
| GUILD_ID | The ID of the guild you want to view the tasks of |
Get a Task
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Task.get(1)
curl https://dashboard.openguilds.com/api/tasks/<ID>
-u "8641fb38-294a-41d9-9591-3449dfd99910"
The above command returns JSON structured like this:
{
"object": "Task",
"id": "1",
"minimum_amount": "$5.00",
"minimum_amount_cents": 500,
"workspace": {
"name": "Audio Transcription Interface",
"link": "api/workspaces/1",
"preview": "https://preview.interface.com",
"permissions": "open"
},
"connections": {
"object": "List",
"url": "/api/task/1/connections",
"has_more": false,
"page": 1,
"data": [
{
"object": "Connection",
"source_id": "1",
"target_id": "2"
}
]
},
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
HTTP Request
GET https://dashboard.openguilds.com/api/tasks/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the task |
Workspaces
The Workspace Object
The Workspae object looks like this:
{
"object": "Workspace",
"id": "1",
"name": "Audio Transcription Interface",
"preview": "https://preview.interface.com",
"permissions": "open",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
Workspaces are any statically hosted website that can take parameters in through the URL, allow workers to perform transformations on them, and then send their data back through a form to a given destination.
| Attribute | Type | Description |
|---|---|---|
| object | string | A string representing the object type. |
| id | string | The ID of the workspace. |
| name | string | The workspace name. |
| preview | string | A valid https link to preview the workspace at. |
| permissions | string | The permissions level of the interface. |
Permissions can be one of two states:
| Attribute | Description |
|---|---|
| open | The workspace is open for others to use in their own guilds. |
| closed | The workspace is private to its creator. |
Acceptable Workspaces
Workspaces are any web server which follows some specific rules:
- It must pass through some URL parameters into its form as listed below.
- It must provide the user a submit button which returns information to the submitTo parameter value.
- It must use HTTPs protocol.
- It must be accessible to the guild members.
The attributes it must pass are:
| Attribute | Meaning |
|---|---|
| workerId | The ID of the worker who is completing the assignment |
| assignmentId | The ID of the assignment the work is submitted to |
| submitTo | The URL that the form should be submitted to. |
Make sure your form submits to the submitTo value with the assignmentId as a hidden field.
Batches
The Batch Object
The Batch object looks like this:
{
"object": "Batch",
"id": "1",
"data_completed_count": "0",
"data_count": "1",
"data": {
"object": "List",
"url": "api/batch/1/data",
"has_more": false,
"page": 1,
"data": [
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "2",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio2.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "3",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio3.wav",
"transcription": "There once was a man from peru..."
}
}
]
},
"webhooks": {
"object": "List",
"url": "api/batch/1/webhooks",
"has_more": false,
"page": 1,
"data": {
"object": "Webhook",
"id": "1",
"destination": "https://your.service.com"
}
},
"dataset_destinations": {
"object": "List",
"url": "api/batch/1/datasets",
"has_more": false,
"page": 1,
"data": {
"object": "Dataset",
"id": "1",
"name": "My Audio Transcription Dataset",
"description": "This dataset contains audio transcriptions",
"data": {
"object": "List",
"url": "api/dataset/1/data",
"has_more": false,
"page": 1,
"data": [
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "2",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio2.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "3",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio3.wav",
"transcription": "There once was a man from peru..."
}
}
]
},
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
},
"completed": "false",
"status": "processing",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
Batches are created when you send data to a guild.
Batches can have many webhooks. Webhooks will send the data from a batch to its endpoint when the batch status changes to completed.
Batches can also send their completed data to a given dataset. Datasets hold certain data which can be downloaded or explored as a group.
Batches are funded by the guild before they are given to guild members to work on.
Batches are accounted for by a guild's bank
The object has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| object | string | The object's type. Objects of the same type have the same structure. |
| id | string | The ID of the batch being returned. |
| data_completed_count | integer | A count of all completed data in the batch. |
| data_count | integer | A count of all data in the batch. |
| data | object | The data objects associated with a given batch. |
| webhooks | array[webhooks] | An array of webhook objects. |
| dataset_destinations | array[datasets] | an array of dataset objects. |
| status | string | A status describing the current state of the batch. |
The status of a batch object can be one of the following:
| Status | Description |
|---|---|
| processing | Not all data in the batch has been completed. |
| completed | All data in the batch has been processed and marked as complete. |
| archived | The data has been archived and removed from normal listing. |
The Datum Object
The datum object looks like this:
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
}
The singular word for data is called a datum.
A datum is given to each task and held until workers perform the required work.
When a worker submits their work, new parameters the worker has created are added to a datum and it is opened to the next task through a connection.
The data object has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| object | string | The object's type. Objects of the same type have the same structure. |
| id | string | The ID of the datum being returned. |
| status | string | A status describing the current state of the datum. |
| parameters | object | A hash structure of the given parameters and those added by workers. |
The status of a datum object can be one of the following:
| Status | Description |
|---|---|
| processing | The data has not been processed by all required tasks. |
| completed | The data has been processed by all required tasks. |
The Webhook Object
The webhook object looks like this:
{
"object": "Webhook",
"id": "1",
"destination": "https://your.service.com"
}
A webhook is triggered when a batch object is completed.
It will send a JSON call to its destination with a secret key you create to verify its origin.
The data object has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| destination | string | A valid http url. |
| secret | object | A secret you keep to verify its origin. |
Create a Batch
Creating a batch is as simple as specifying the data you want to use for the initial task as well as the destinations for the data when it is completed.
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
file = File.read('path/to/data.json')
OpenGuilds::Batch.create(
guild: 1,
params: JSON.parse(file)
)
curl https://dashboard.openguilds.com/api/guild/<GUILD_ID>/batch
-u "8641fb38-294a-41d9-9591-3449dfd99910"
-H "Content-Type: application/json"
-d "@data.json"
If we have a guild with only one input parameter with a key value of "image_url".
Then your data.json file should look like:
{
"batch": {
"data": [
{ "image_url": "www.images.com/image1.png", },
{ "image_url": "www.images.com/image2.png", },
{ "image_url": "www.images.com/image3.png", },
],
"webhooks": [
{
"destination": "https://your.service.com",
"secret": "secret123",
},
],
"dataset_destinations" [
{
"dataset_id": "1"
},
]
}
}
Each key value within the "data" array should match the required input parameters for the Guild.
Which should return your batch:
{
"object": "Batch",
"id": "1",
"data_completed_count": "0",
"data_count": "1",
"data": {
"object": "List",
"url": "api/batch/1/data",
"has_more": false,
"page": 1,
"data": [
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "2",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio2.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "3",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio3.wav",
"transcription": "There once was a man from peru..."
}
}
]
},
"webhooks": {
"object": "List",
"url": "api/batch/1/webhooks",
"has_more": false,
"page": 1,
"data": {
"object": "Webhook",
"id": "1",
"destination": "https://your.service.com"
}
},
"dataset_destinations": {
"object": "List",
"url": "api/batch/1/datasets",
"has_more": false,
"page": 1,
"data": {
"object": "Dataset",
"id": "1",
"name": "My Audio Transcription Dataset",
"description": "This dataset contains audio transcriptions",
"data": {
"object": "List",
"url": "api/dataset/1/data",
"has_more": false,
"page": 1,
"data": [
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "2",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio2.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "3",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio3.wav",
"transcription": "There once was a man from peru..."
}
}
]
},
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
},
"completed": "false",
"status": "processing",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
HTTP Request
POST http://dashboard.openguilds.com/api/guilds/<GUILD_ID>/batches
Batch Parameters
| Parameter | Type | Description |
|---|---|---|
| batch | object | The root key for the object, should contain "data" and "webhooks". |
| data | array | An array of objects matching the guilds API. |
| webhooks | array | An array of webhook objects with endpoints and secrets. |
| dataset_destinations | array | An array of dataset destination objects with an ID of the dataset. |
URL Parameters
| Parameter | Description |
|---|---|
| GUILD_ID | The ID of the guild the batch should be for. |
List all Batches
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Batch.list()
curl https://dashboard.openguilds.com/api/guilds
-u "8641fb38-294a-41d9-9591-3449dfd99910"
The above command returns JSON structured like this:
{
"object": "List",
"url": "api/batches",
"has_more": false,
"page": 1,
"data": [
{
"object": "Batch",
"id": "1",
"data_completed_count": "0",
"data_count": "1",
"data": {
"object": "List",
"url": "api/batch/1/data",
"has_more": false,
"page": 1,
"data": [
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "2",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio2.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "3",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio3.wav",
"transcription": "There once was a man from peru..."
}
}
]
},
"webhooks": {
"object": "List",
"url": "api/batch/1/webhooks",
"has_more": false,
"page": 1,
"data": {
"object": "Webhook",
"id": "1",
"destination": "https://your.service.com"
}
},
"dataset_destinations": {
"object": "List",
"url": "api/batch/1/datasets",
"has_more": false,
"page": 1,
"data": {
"object": "Dataset",
"id": "1",
"name": "My Audio Transcription Dataset",
"description": "This dataset contains audio transcriptions",
"data": {
"object": "List",
"url": "api/dataset/1/data",
"has_more": false,
"page": 1,
"data": [
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "2",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio2.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "3",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio3.wav",
"transcription": "There once was a man from peru..."
}
}
]
},
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
},
"completed": "false",
"status": "processing",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
]
}
This will retrieve all batches for the authorized user.
HTTP Request
GET http://dashboard.openguilds.com/api/batches
Get a Specific Batch
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Batch.get(1)
curl https://dashboard.openguilds.com/api/batches/<ID>
-u "8641fb38-294a-41d9-9591-3449dfd99910"
The above command returns JSON structured like this:
{
"object": "Batch",
"id": "1",
"data_completed_count": "0",
"data_count": "1",
"data": {
"object": "List",
"url": "api/batch/1/data",
"has_more": false,
"page": 1,
"data": [
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "2",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio2.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "3",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio3.wav",
"transcription": "There once was a man from peru..."
}
}
]
},
"webhooks": {
"object": "List",
"url": "api/batch/1/webhooks",
"has_more": false,
"page": 1,
"data": {
"object": "Webhook",
"id": "1",
"destination": "https://your.service.com"
}
},
"dataset_destinations": {
"object": "List",
"url": "api/batch/1/datasets",
"has_more": false,
"page": 1,
"data": {
"object": "Dataset",
"id": "1",
"name": "My Audio Transcription Dataset",
"description": "This dataset contains audio transcriptions",
"data": {
"object": "List",
"url": "api/dataset/1/data",
"has_more": false,
"page": 1,
"data": [
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "2",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio2.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "3",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio3.wav",
"transcription": "There once was a man from peru..."
}
}
]
},
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
},
"completed": "false",
"status": "processing",
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
HTTP Request
GET https://dashboard.openguilds.com/api/batches/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the batch to retrieve |
Cancel a Specific Batch
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Batch.cancel(1)
curl https://dashboard.openguilds.com/api/batches/<ID>
-u "8641fb38-294a-41d9-9591-3449dfd99910"
-X DELETE
The above command returns JSON structured like this:
{
"object": "Batch",
"id": "1",
"canceled": true
}
Canceling a batch is made with a delete request. We delete the contents of the batch but keep a record of it being canceled.
HTTP Request
DELETE https://dashboard.openguilds.com/api/batches/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the batch to cancel |
Datasets
The Dataset Object
The dataset object looks like this:
{
"object": "Dataset",
"id": "1",
"name": "My Audio Transcription Dataset",
"description": "This dataset contains audio transcriptions",
"data": {
"object": "List",
"url": "api/dataset/1/data",
"has_more": false,
"page": 1,
"data": [
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "2",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio2.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "3",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio3.wav",
"transcription": "There once was a man from peru..."
}
}
]
},
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
Datasets are created for a specific guild.
Batches can choose to store its finished data within a specific dataset.
Datasets can be accessed for viewing through your guild.
The object has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| object | string | The object's type. Objects of the same type have the same structure. |
| id | string | The ID of the dataset being returned. |
| data | object | The data objects associated with a given dataset. |
List all Datasets
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Dataset.list()
curl https://dashboard.openguilds.com/api/datasets
-u "8641fb38-294a-41d9-9591-3449dfd99910"
The above command returns JSON structured like this:
{
"object": "List",
"url": "api/datasets",
"has_more": false,
"page": 1,
"data": [
{
"object": "Dataset",
"id": "1",
"name": "My Audio Transcription Dataset",
"description": "This dataset contains audio transcriptions",
"data": {
"object": "List",
"url": "api/dataset/1/data",
"has_more": false,
"page": 1,
"data": [
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "2",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio2.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "3",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio3.wav",
"transcription": "There once was a man from peru..."
}
}
]
},
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
]
}
This will retrieve all private datasets for the authorized user.
HTTP Request
GET http://dashboard.openguilds.com/api/datasets
Get a Specific Dataset
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Dataset.get(1)
curl https://dashboard.openguilds.com/api/datasets/<ID>
-u "8641fb38-294a-41d9-9591-3449dfd99910"
The above command returns JSON structured like this:
{
"object": "Dataset",
"id": "1",
"name": "My Audio Transcription Dataset",
"description": "This dataset contains audio transcriptions",
"data": {
"object": "List",
"url": "api/dataset/1/data",
"has_more": false,
"page": 1,
"data": [
{
"object": "Datum",
"id": "1",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio1.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "2",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio2.wav",
"transcription": "There once was a man from peru..."
}
},
{
"object": "Datum",
"id": "3",
"status": "completed",
"parameters": {
"audio_url": "www.audio.com/audio3.wav",
"transcription": "There once was a man from peru..."
}
}
]
},
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
HTTP Request
GET https://dashboard.openguilds.com/api/datasets/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the dataset to retrieve |
Wallet
The Wallet Object
The Wallet object looks like this:
{
"object": "Wallet",
"id": "2",
"transactions": {
"object": "List",
"url": "api/wallet/2/transactions",
"has_more": false,
"page": 1,
"data": [
{
"object": "Transaction",
"id": "1",
"type": "Guild Credit",
"amount": "$5.00",
"amount_cents": 500,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
},
{
"object": "Time Transaction",
"id": "1",
"type": "Guild Time Credit",
"amount": "$5.00",
"amount_cents": 500,
"rate": "$12.00",
"rate_cents": "1200",
"minimum_seconds": 60,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
]
},
"balance": "$20.00",
"balance_cents": 2000,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
Each guild you join has its own individual wallet.
Wallets store a history of transactions, which can be different types.
Wallets are backed by a bank which the owner is responsible for for fulfilling.
Wallet credits can be exchanged by workers by requesting a payout.
A Wallet has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| object | string | A string representing the object type. |
| id | string | The ID of the Wallet being returned. |
| transactions | array[transactions] | A time ordered history of Transactions, with the newest first. |
| balance | string | The total amount of Credits from adding all Credits minus Debits. |
| balance_cents | integer | The balance represented in cents. |
The Bank Object
A bank is has a wallet that is owned by the guild called the vault.
The bank records all transactions made in and out of associated wallets.
Users can place requests for a payout of their credits, which are accepted by the guild owner.
The Transaction Object
The transaction object looks like this:
{
"object": "Transaction",
"id": "1",
"type": "Guild Credit",
"amount": "$5.00",
"amount_cents": 500,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
A variation, called a time transaction object looks like this:
{
"object": "Time Transaction",
"id": "1",
"type": "Guild Time Credit",
"amount": "$5.00",
"amount_cents": 500,
"rate": "$12.00",
"rate_cents": "1200",
"minimum_seconds": 60,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
Transactions are created when paying for something, or exchanging credits.
Time transactions are extensions of transactions which record the time worked which is then converted to the real amount. It can be useful for following fiscal rules such as paying workers hourly.
A Transaction has the following attributes:
| Attribute | Type | Description |
|---|---|---|
| object | string | A string representing the object type. |
| id | string | The ID of the Wallet being returned. |
| type | string | The type of the transaction, can be one of the valid transaction types. |
| amount | string | The amount either credited or debited during the transaction. |
| amount_cents | integer | The amount credited or debited during the transaction in cents. |
A transaction can have the following types:
| Type | Description |
|---|---|
| Guild Credit | A positive transfer of guild currency. |
| Guild Debit | A negative transfer of guild currency. |
| Guild Time Credit | A positive transfer of guild time. |
| Guild Time Debit | A negative transfer of guild time. |
| Amazon Credit | A positive transfer of Amazon credits. |
| Amazon Debit | A negative transfer of Amazon credits. |
| Fiat Credit | A positive transfer of fiat money. |
| Fiat Debit | A negative transfer of fiat money. |
List all Wallets
Will return all wallets belonging to the user.
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Wallet.list()
curl https://dashboard.openguilds.com/api/wallets
-u "8641fb38-294a-41d9-9591-3449dfd99910"
The above command returns JSON structured like this:
{
"object": "List",
"url": "api/wallets/2/transactions",
"has_more": false,
"page": 1,
"data": [
{
"object": "Wallet",
"id": "2",
"transactions": {
"object": "List",
"url": "api/wallet/2/transactions",
"has_more": false,
"page": 1,
"data": [
{
"object": "Transaction",
"id": "1",
"type": "Guild Credit",
"amount": "$5.00",
"amount_cents": 500,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
},
{
"object": "Time Transaction",
"id": "1",
"type": "Guild Time Credit",
"amount": "$5.00",
"amount_cents": 500,
"rate": "$12.00",
"rate_cents": "1200",
"minimum_seconds": 60,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
]
},
"balance": "$20.00",
"balance_cents": 2000,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
]
}
HTTP Request
GET https://dashboard.openguilds.com/api/wallets
Get a Wallet
Will return a wallet object belonging to the authenticated user.
require 'open-guilds'
OpenGuilds.api_key = '8641fb38-294a-41d9-9591-3449dfd99910'
OpenGuilds::Wallet.get(1)
curl https://dashboard.openguilds.com/api/wallet/<ID>
-u "8641fb38-294a-41d9-9591-3449dfd99910"
Which should return your Wallet:
{
"object": "Wallet",
"id": "2",
"transactions": {
"object": "List",
"url": "api/wallet/2/transactions",
"has_more": false,
"page": 1,
"data": [
{
"object": "Transaction",
"id": "1",
"type": "Guild Credit",
"amount": "$5.00",
"amount_cents": 500,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
},
{
"object": "Time Transaction",
"id": "1",
"type": "Guild Time Credit",
"amount": "$5.00",
"amount_cents": 500,
"rate": "$12.00",
"rate_cents": "1200",
"minimum_seconds": 60,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
]
},
"balance": "$20.00",
"balance_cents": 2000,
"created": "2015-05-22T14:56:29.000Z",
"updated": "2015-05-22T14:56:28.000Z"
}
HTTP Request
GET https://dashboard.openguilds.com/api/wallet/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the Wallet to retrieve |