API Overview
The CrowdFlower API gives developers the ability to build applications that interact with and use all the features of CrowdFlower in an automated fashion. Tasks can be generated, work can be ordered, and your application can be notified as data is processed and judged by the CrowdFlower platform. The methods and practices described in this documentation are subject to change as the CrowdFlower API matures.
CrowdFlower uses a RESTful API. It accepts data as URL-encoded key value pairs. Authentication is currently key-based. Responses are currently restricted to the JSON format.
URLs
All URLs begin with the following pattern:
https://api.crowdflower.com/v1/...Authentication
CrowdFlower uses key-based authentication. You can obtain or change your key in the account pane. To maintain security keep the key secret and use it only over SSL. Each request to the API must contain a key parameter with your account key.
https://api.crowdflower.com/v1/jobs?key=1a2b3c4d5e6f7g8h9i0jFormats
The API currently supports JSON only. You must set the Accept header to “application/json” or append “.json” to the URL of the request. For example:
https://api.crowdflower.com/v1/jobs.json?key=1a2b3c4d5e6f7g8h9i0jMessaging
If the status code of a response is something other than 200, you will find a JSON message in the body of the response. Messages are used to give you the status of a given operation, to report an error. CrowdFlower can return three types of messages:
{success: {message: "Job created successfully."}}
{notice: {message: "Your job is being completed."}}
{error: {message: "Job could not be canceled."}}Webhooks
Webhooks allow your system to receive notifications when interesting events happen to the jobs you create on CrowdFlower. Select the Webhooks link at right to learn more.
REST
The API supports the four standard HTTP methods, each altering the behavior of a given URL. These are referred to as VERBs in the rest of the documentation.
- GET
- Used to request information. This method is non-destructive.
- POST
- Used to create new records.
- PUT
- Used to update or alter existing information.
- DELETE
- Used to remove records.
Status Codes
- 200 Success
- The request was successful.
- 202 Accepted
- We have accepted your request, and it has been queued for processing. The body of this response indicates when to try the request again.
- 302 Redirect
- We are redirecting you to a resource. The body of this response often contains a message.
- 400 Bad Request
- You failed to pass one or more required parameters.
- 401 Unauthenticated
- Authorization failed, check your key.
- 402 Payment Required
- The operation you are trying to complete requires payment.
- 404 Not Found
- The resource you are referencing does not exist, or you don’t own it.
- 405 Method Not Allowed
- The method you are using (GET, POST, PUT, DELETE) is not available from this URL.
- 406 Not Acceptable
- The format you requested is not available.
- 500 Internal Server Error
- An error occurred on the server. When this happens, a full stack trace is sent to the CrowdFlower developers.
Reference Implementations
We currently maintain a Ruby gem that implements the functionality described in this documentation. You can view and contribute to the code at http://github.com/dolores/ruby-crowdflower.
Questions?
We are actively working on our API and would love to hear from you! Drop us a line at support@crowdflower.com.
