NAV
ruby python shell

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)
ruby python shell