Introduction
Welcome to the Surge API! You can use the API to programmatically create projects and run tasks. All you need is your API key and funds in your account.
Example
Let’s walk through an example using Surge to categorize companies. If you’re currently signed in, we’ve already included your own API key in all the examples so you can run them yourself.
First, let’s create a “categorize website” project. Note: it’s also possible to create the project in the web UI, and add tasks to it through the API.
require 'httparty'
# Create the project.
response = HTTParty.post("https://app.surgehq.ai/api/projects",
basic_auth: { username: "{{YOUR_API_KEY}}" },
body: {
name: "Categorize this website",
questions: [
{
"text": "What is the name of the company at this website?"
},
{
"text": "What category does this company belong to?",
"options": ["Tech", "Sports", "Gaming"]
}
]
}
)
# Extract the project ID.
project_id = JSON.parse(response.body)["id"]
import requests
response = requests.post("https://app.surgehq.ai/api/projects",
auth = ("{{YOUR_API_KEY}}", ""),
json = {
"name": "Categorize this website",
"questions": [
{
"text": "What is the name of the company at this website?"
},
{
"text": "What category does this company belong to?",
"options": ["Tech", "Sports", "Gaming"]
}
]
}
)
# Extract the project ID.
project_id = response.json()["id"]
# See the Python and Ruby tabs instead.
Next, let’s add some tasks to the project. Once a task is added, it gets immediately sent to workers.
Here, we’re creating a task where workers will categorize “google.com”.
Note: by default, workers will see all task fields. If you’d like to customize the layout of the fields (e.g., to create images or urls), then you can pass in a
fields_template
when creating the project; see the Create a project endpoint.
# Add a task to the project.
HTTParty.post("https://app.surgehq.ai/api/projects/#{project_id}/tasks",
basic_auth: { username: "{{YOUR_API_KEY}}" },
body: {
"fields": {
"website": "google.com"
}
}
)
# Add a task to the project.
requests.post("https://app.surgehq.ai/api/projects/%s/tasks" % project_id,
auth = ("{{YOUR_API_KEY}}", ""),
json = {
"fields": {
"website": "google.com"
}
}
)
Finally, we can retrieve the results once completed. You can also download the results as a CSV or spreadsheet in the UI.
# Retrieve all the tasks in the project and their responses.
response = HTTParty.get("https://app.surgehq.ai/api/projects/#{project_id}/tasks",
basic_auth: { username: "{{YOUR_API_KEY}}" }
)
JSON.parse(response.body).each do |task|
puts task["responses"][0]["data"]
end
# Retrieve all the tasks in the project and their responses.
response = requests.get("https://app.surgehq.ai/api/projects/%s/tasks" % project_id,
auth = ("{{YOUR_API_KEY}}", "")
)
for task in response.json():
print task["responses"][0]["data"]
Authentication
To authorize, use this code.
require 'httparty'
# For POST requests
HTTParty.post("{{API_ENDPOINT}}",
basic_auth: { username: "{{YOUR_API_KEY}}" },
body: {
... # Parameters in the POST request
}
)
# For GET requests
HTTParty.get("{{API_ENDPOINT}}",
basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests
# For POST requests
requests.post("{{API_ENDPOINT}}",
auth = ("{{YOUR_API_KEY}}", ""),
json = {
... # Parameters in the POST request
}
)
# For GET requests
requests.get("{{API_ENDPOINT}}",
auth = ("{{YOUR_API_KEY}}", "")
)
# Note that the colon follows the API key and is not part of it.
curl {{API_ENDPOINT}} \
-u {{YOUR_API_KEY}}:
Surge uses API keys to allow access to the API. You can find your API key in your profile.
Authentication is performed via HTTP Basic Auth. Your API key is your basic auth username, and you do not need to provide a password.
If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: {{YOUR_API_KEY}}:"
instead of -u {{YOUR_API_KEY}}:
.
Projects
The project object
Example Response
{
"id": "17e323f1-f7e4-427c-a2d5-456743aba8",
"callback_url": "https://www.mywebsite.com/callback",
"fields_template": "<a href='{{website_url}}'>Company website</a>",
"instructions": "Visit the website and categorize the company.",
"name": "Categorize this website",
"num_tasks": 1000,
"num_tasks_completed": 239,
"num_workers_per_task": 1,
"questions": [
{
"text": "What is the name of the company at this website?"
}
],
"status": "unlaunched"
}
Parameter | Type | Description |
---|---|---|
id | string | |
callback_url | string | Once a task is completed, it is POSTed to this url. |
created_at | string | |
fields_template | string | A template describing how fields are shown to workers working on the task. For example, if fields_template is “{{company_name}}”, then workers will be shown a link to the company. |
instructions | string | Instructions shown to workers describing how they should complete the task. |
name | string | Name of the project. |
num_tasks | integer | Number of tasks in the project. |
num_tasks_completed | integer | Number of completed tasks. |
num_workers_per_task | integer | How many workers work on each task (i.e., how many responses per task). |
payment_per_response | float | How much a worker is paid (in US dollars) for an individual response. |
questions | array | An array of question objects describing the questions to be answered. Each question object contains a text field (the text of the question), an optional options array (for multiple choice and checkbox questions, listing the answer options), a type field (one of free_response , multiple_choice , bounding_box , or checkbox ), and a required boolean field (describing whether or not workers must answer the question) |
status | string | One of in_progress , completed , canceled , or paused . |
Create a project
Definition
POST https://app.surgehq.ai/api/projects
Example Request
curl https://app.surgehq.ai/api/projects \
-u {{YOUR_API_KEY}}: \
-d name="Categorize this company" \
-d payment_per_response=0.1 \
-d questions=... (can't do this in curl)
require 'httparty'
HTTParty.post("https://app.surgehq.ai/api/projects",
basic_auth: { username: "{{YOUR_API_KEY}}" },
body: {
name: "Categorize this company",
payment_per_response: 0.1,
instructions: "You will be asked to categorize a company.",
questions: [
{
"text": "What is the name of the company at this website?"
},
{
"text": "What category does this company belong to?",
"options": ["Tech", "Sports", "Gaming"]
},
{
"type": "checkbox",
"text": "Check all the social media accounts this company has",
"options": ["Facebook", "Twitter", "Pinterest", "Google+"]
}
]
}
)
import requests
requests.post("https://app.surgehq.ai/api/projects",
auth = ("{{YOUR_API_KEY}}", ""),
json = {
"name": "Categorize this website",
"payment_per_response": 0.1,
"instructions": "You will be asked to categorize a company.",
"questions": [
{
"text": "What is the name of the company at this website?"
},
{
"text": "What category does this company belong to?",
"options": ["Tech", "Sports", "Gaming"]
},
{
"type": "checkbox",
"text": "Check all the social media accounts this company has",
"options": ["Facebook", "Twitter", "Pinterest", "Google+"]
}
]
}
)
Example Response
{
"id": "17e323f1-f7e4-427c-a2d5-456743aba8",
"callback_url": "https://www.mywebsite.com/callback",
"instructions": "You will be asked to categorize a company.",
"name": "Categorize this website",
"num_tasks": 0,
"num_tasks_completed": 0,
"num_workers_per_task": 1,
"payment_per_response": 0.1,
"questions": [
{
"text": "What is the name of the company at this website?"
},
{
"text": "What category does this company belong to?",
"options": ["Tech", "Sports", "Gaming"]
},
{
"type": "checkbox",
"text": "Check all the social media accounts this company has",
"options": ["Facebook", "Twitter", "Pinterest", "Google+"]
}
],
"status": "unlaunched"
}
Creates a project. It is also possible to create a project through the web UI (instead of the API), and you will still be able to use the API to post tasks to the project.
Parameters
Parameter | Type | Description |
---|---|---|
name | string | Name to give your project. (required) |
payment_per_response | float | Amount in dollars to pay workers for each response. |
questions | array | An array of JSON objects that define the questions that are shown to workers. Each question object takes a text field (the question that gets shown to workers), an optional options array (for multiple_choice and checkbox , which define the answer options that workers see), an optional type field (one of free_response , multiple_choice , bounding_box , or checkbox ; by default, if the field is not provided, then question objects without options are assumed to be free_response , and question objects with options are assumed to be multiple_choice ), and an optional required field (a boolean that defines whether or not the question must be answered; default true). (required) |
callback_url | string | URL where completed tasks will be POSTed. (optional, default null) |
fields_template | string | An HTML mustache template that defines how task fields are presented to workers. For example, if the task contains a “first_name” and a “last_name”, then the mustache template might be “Name: {{first_name}} {{last_name}}”, and workers would see something like “Name: John Smith”. (optional, defaults to a named list of the fields passed into the task) |
num_workers_per_task | integer | Number of workers who work on each task. (optional, default 1) |
List all projects
Definition
GET https://app.surgehq.ai/api/projects
GET https://app.surgehq.ai/api/projects?page=n
Example Request
require 'httparty'
HTTParty.get("https://app.surgehq.ai/api/projects?page=2",
basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests
requests.get("https://app.surgehq.ai/api/projects",
auth = ("{{YOUR_API_KEY}}", "")
)
curl https://app.surgehq.ai/api/projects \
-u {{YOUR_API_KEY}}:
Example Response
[
{
"id": "17e323f1-f7e4-427c-a2d5-456743aba8",
"callback_url": "https://www.mywebsite.com/callback",
"instructions": "You will be asked to categorize a company.",
"name": "Categorize this website",
"num_tasks": 500,
"num_tasks_completed": 239,
"num_workers_per_task": 1,
"payment_per_response": 0.1,
"questions": [
{
"text": "What is the name of the company at this website?"
},
{
"text": "What category does this company belong to?",
"options": ["Tech", "Sports", "Gaming"]
},
{
"type": "checkbox",
"text": "Check all the social media accounts this company has",
"options": ["Facebook", "Twitter", "Pinterest", "Google+"]
}
],
"status": "in_progress"
}
]
Lists all projects you have created.
Parameters
Parameter | Type | Description |
---|---|---|
page | integer | Projects are returned in descending created_at order. Each page contains a maximum of 25 projects. Pages start at 1. (optional, default 1) |
Retrieve a project
Definition
GET https://app.surgehq.ai/api/projects/{{PROJECT_ID}}
Example Request
require 'httparty'
HTTParty.get("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8",
basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests
requests.get("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8",
auth = ("{{YOUR_API_KEY}}", "")
)
curl https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8 \
-u {{YOUR_API_KEY}}:
Example Response
{
"id": "17e323f1-f7e4-427c-a2d5-456743aba8",
"callback_url": "https://www.mywebsite.com/callback",
"instructions": "You will be asked to categorize a company.",
"name": "Categorize this website",
"num_tasks": 500,
"num_tasks_completed": 239,
"num_workers_per_task": 1,
"payment_per_response": 0.1,
"questions": [
{
"text": "What is the name of the company at this website?"
},
{
"text": "What category does this company belong to?",
"options": ["Tech", "Sports", "Gaming"]
},
{
"type": "checkbox",
"text": "Check all the social media accounts this company has",
"options": ["Facebook", "Twitter", "Pinterest", "Google+"]
}
],
"status": "in_progress"
}
Retrieves a specific project you have created.
Pause a project
Definition
PUT https://app.surgehq.ai/api/projects/{{PROJECT_ID}}/pause
Example Request
require 'httparty'
HTTParty.put("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/pause",
basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests
requests.put("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/pause",
auth = ("{{YOUR_API_KEY}}", "")
)
curl https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/pause \
-u {{YOUR_API_KEY}}: \
-X PUT
Example Response
{
"id": "17e323f1-f7e4-427c-a2d5-456743aba8",
"callback_url": "https://www.mywebsite.com/callback",
"instructions": "You will be asked to categorize a company.",
"name": "Categorize this website",
"num_tasks": 500,
"num_tasks_completed": 239,
"num_workers_per_task": 1,
"payment_per_response": 0.1,
"questions": [
{
"text": "What is the name of the company at this website?"
},
{
"text": "What category does this company belong to?",
"options": ["Tech", "Sports", "Gaming"]
},
{
"type": "checkbox",
"text": "Check all the social media accounts this company has",
"options": ["Facebook", "Twitter", "Pinterest", "Google+"]
}
],
"status": "paused"
}
Pauses a project. Tasks added to the project will not be worked on until you resume the project.
Resume a project
Definition
PUT https://app.surgehq.ai/api/projects/{{PROJECT_ID}}/resume
Example Request
require 'httparty'
HTTParty.put("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/resume",
basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests
requests.put("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/resume",
auth = ("{{YOUR_API_KEY}}", "")
)
curl https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/resume \
-u {{YOUR_API_KEY}}: \
-X PUT
Example Response
{
"id": "17e323f1-f7e4-427c-a2d5-456743aba8",
"callback_url": "https://www.mywebsite.com/callback",
"instructions": "You will be asked to categorize a company.",
"name": "Categorize this website",
"num_tasks": 500,
"num_tasks_completed": 239,
"num_workers_per_task": 1,
"payment_per_response": 0.1,
"questions": [
{
"text": "What is the name of the company at this website?"
},
{
"text": "What category does this company belong to?",
"options": ["Tech", "Sports", "Gaming"]
},
{
"type": "checkbox",
"text": "Check all the social media accounts this company has",
"options": ["Facebook", "Twitter", "Pinterest", "Google+"]
}
],
"status": "in_progress"
}
Resumes a paused project.
Cancel a project
Definition
PUT https://app.surgehq.ai/api/projects/{{PROJECT_ID}}/cancel
Example Request
require 'httparty'
HTTParty.put("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/cancel",
basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests
requests.put("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/cancel",
auth = ("{{YOUR_API_KEY}}", "")
)
curl https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/cancel \
-u {{YOUR_API_KEY}}: \
-X PUT
Example Response
{
"id": "17e323f1-f7e4-427c-a2d5-456743aba8",
"callback_url": "https://www.mywebsite.com/callback",
"instructions": "You will be asked to categorize a company.",
"name": "Categorize this website",
"num_tasks": 500,
"num_tasks_completed": 239,
"num_workers_per_task": 1,
"payment_per_response": 0.1,
"questions": [
{
"text": "What is the name of the company at this website?"
},
{
"text": "What category does this company belong to?",
"options": ["Tech", "Sports", "Gaming"]
},
{
"type": "checkbox",
"text": "Check all the social media accounts this company has",
"options": ["Facebook", "Twitter", "Pinterest", "Google+"]
}
],
"status": "canceled"
}
Cancels a project.
Tasks
The task object
Example Response
{
"id": "38da6bc5-a644-41b9-a964-4678bc7375c6",
"project_id": "b31ede78-afdf-4938-b775-8813453c7fc5",
"created_at": "2016-11-01T18:56:56.000Z",
"is_complete": true,
"fields": {
"company": "Surge",
"city": "San Francisco",
"state": "CA"
},
"responses": [
{
"created_at": "2016-11-01T23:29:17.971Z",
"id": "1befb37b-8e4f-42b6-8a61-2c946ad4b5ce",
"data": {
"website": "https://www.surgehq.ai",
"category": "Technology"
}
}
]
}
Parameter | Type | Description |
---|---|---|
id | string | |
created_at | string | |
project_id | string | ID of the project that this task belongs to. |
is_complete | boolean | Whether or not this task has received the desired number of responses (equal to the project’s num_workers_per_task field). |
fields | dictionary | A dictionary of named fields that get shown (according to the project template) to workers when working on the task. |
responses | array | An array of responses to the task. Each response contains an id , a created_at field, and a data dictionary that maps questions to their answers. |
Create a task
Definition
POST https://app.surgehq.ai/api/projects/{{PROJECT_ID}}/tasks
Example Request
require 'httparty'
HTTParty.post("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/tasks",
basic_auth: { username: "{{YOUR_API_KEY}}" },
body: {
"fields": {
"company": "Surge",
"city": "San Francisco",
"state": "CA"
}
}
)
import requests
requests.post("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/tasks",
auth = ("{{YOUR_API_KEY}}", ""),
json = {
"fields": {
"company": "Surge",
"city": "San Francisco",
"state": "CA"
}
}
)
curl https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/tasks \
-u {{YOUR_API_KEY}}: \
-d data=... (can't do this in curl)
Example Response
{
"id": "38da6bc5-a644-41b9-a964-4678bc7375c6",
"project_id": "b31ede78-afdf-4938-b775-8813453c7fc5",
"created_at": "2016-11-01T18:56:56.000Z",
"is_complete": false,
"fields": {
"company": "Surge",
"city": "San Francisco",
"state": "CA"
},
"responses": []
}
Creates a task.
Parameters
Parameter | Type | Description |
---|---|---|
fields | dictionary | A dictionary of named fields that get shown (according to the project template) to workers when working on the task. (required) |
List all tasks
Definition
GET https://app.surgehq.ai/api/projects/{{PROJECT_ID}}/tasks
GET https://app.surgehq.ai/api/projects/{{PROJECT_ID}}/tasks?page=n
Example Request
require 'httparty'
HTTParty.get("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/tasks",
basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests
requests.get("https://app.surgehq.ai/api/projects/17e323f1-f7e4-427c-a2d5-456743aba8/tasks",
auth = ("{{YOUR_API_KEY}}", "")
)
curl https://app.surgehq.ai/api/projects/b31ede78-afdf-4938-b775-8813453c7fc5/tasks \
-u {{YOUR_API_KEY}}: \
...
Example Response
[
{
"id": "38da6bc5-a644-41b9-a964-4678bc7375c6",
"project_id": "b31ede78-afdf-4938-b775-8813453c7fc5",
"created_at": "2016-11-01T18:56:56.000Z",
"is_complete": true,
"fields": {
"company": "Surge",
"city": "San Francisco",
"state": "CA"
},
"responses": [
{
"created_at": "2016-11-01T23:29:17.971Z",
"id": "1befb37b-8e4f-42b6-8a61-2c946ad4b5ce",
"data": {
"website": "https://www.surgehq.ai",
"category": "Technology"
}
}
]
},
{
"id": "dd66e80a-88b3-4c4f-9efc-2aca8eed73db",
"project_id": "b31ede78-afdf-4938-b775-8813453c7fc5",
"created_at": "2016-11-01T23:23:26.016Z",
"is_complete": true,
"fields": {
"company": "Google",
"city": "Mountain View",
"state": "CA"
},
"responses": [
{
"created_at": "2016-11-01T23:22:19.124Z",
"id": "cc9f4263-1d0f-4730-a97e-199851b6ade5",
"data": {
"website": "https://www.google.com",
"category": "Technology"
}
}
]
}
]
Lists all tasks belonging to a project.
Query Parameters
Parameters
Parameter | Type | Description |
---|---|---|
page | integer | Tasks are returned in ascending created_at order. Each page contains a maximum of 25 tasks. Pages start at 1. (optional, default 1) |
Retrieve a task
Definition
GET https://app.surgehq.ai/api/tasks/{{TASK_ID}}
Example Request
require 'httparty'
HTTParty.get("https://app.surgehq.ai/api/tasks/38da6bc5-a644-41b9-a964-4678bc7375c6",
basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests
requests.get("https://app.surgehq.ai/api/tasks/38da6bc5-a644-41b9-a964-4678bc7375c6",
auth = ("{{YOUR_API_KEY}}", "")
)
curl https://app.surgehq.ai/api/tasks/38da6bc5-a644-41b9-a964-4678bc7375c6 \
-u {{YOUR_API_KEY}}:
Example Response
{
"id": "38da6bc5-a644-41b9-a964-4678bc7375c6",
"project_id": "b31ede78-afdf-4938-b775-8813453c7fc5",
"created_at": "2016-11-01T18:56:56.000Z",
"is_complete": true,
"fields": {
"company": "Surge",
"city": "San Francisco",
"state": "CA"
},
"responses": [
{
"created_at": "2016-11-01T23:29:17.971Z",
"id": "1befb37b-8e4f-42b6-8a61-2c946ad4b5ce",
"data": {
"website": "https://www.surgehq.ai",
"category": "Technology"
}
}
]
}
Retrieves a specific task you have created.
Complete a task
Definition
POST https://app.surgehq.ai/api/projects/{{PROJECT_ID}}/tasks/complete
Example Request
require 'httparty'
HTTParty.post("https://app.surgehq.ai/api/projects/38da6bc5-a644-41b9-a964-4678bc7375c6/tasks/complete?worker_id=QKHQDWHQXH2D",
basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests
requests.post("https://app.surgehq.ai/api/projects/38da6bc5-a644-41b9-a964-4678bc7375c6/tasks/complete?worker_id=QKHQDWHQXH2D",
auth = ("{{YOUR_API_KEY}}", "")
)
curl https://app.surgehq.ai/api/projects/38da6bc5-a644-41b9-a964-4678bc7375c6/tasks/complete?worker_id=QKHQDWHQXH2D \
-u {{YOUR_API_KEY}}:
Example Response
{
"id": "38da6bc5-a644-41b9-a964-4678bc7375c6",
"worker_id": "QKHQDWHQXH2D",
"data": {},
"completed_at": "2018-01-15T14:03:01.354Z",
"time_spent_in_secs": 0,
}
Completes a specific task or random task.
Parameter | Type | Description |
---|---|---|
worker_id | string | The id of the worker completing the task. (required) |
task_id | string | The id of the task being completed. If not provided, a random workable task will be used instead. (optional) |