API v2 Introduction
The Prefinery API is implemented as JSON over HTTPS. Every resource, like Project or User has their own URL and are manipulated in isolation. We've tried to make the API follow the REST principles as much as possible.
All API calls will be made over HTTPS at:
The Prefinery API has two categories of actions for reading: Show and Index. Show returns a single record and index returns a collection. Both of these actions are done through GET and can be easily examined through your Web browser. Curl is also a great utility for exploring the API.
Creating, updating, and deleting resources through the API is almost as easy as reading, but you can't explore it as easily through a Web browser. Curl is a great utility and will become your best friend.
All create and update requests must send a proper Content-Type header of
application/json. Otherwise, Prefinery won't interpret your request correctly and you'll
500 error back.
Creating resources is done through the POST verb. The response to a successful creation is the status code "201 Created" along with the complete JSON for the created resource.
Updating resources is done through the PUT verb and against the URL of the resource you want to update. The response to a successful update is "200 OK" along with the complete JSON of the updated resource.
Finally, you can delete resources using the DELETE verb. The response to a successful delete is "200 OK".
All timestamps use UTC and are strings in the ISO 8601 combined date and time representation
Requests that return multiple items will be paginated. You can specify further pages with the ?page parameter. Pagination information will be returned in the X-Pagination header, for example:
Possible X-Pagination values are:
|The previous page. null if there is no previous page.
|The next page. null if there is no next page.
|The current page.
|The maximum number of records returned per page.
|The number of records returned on this page.
|The total number of pages.
|The total number of records across all pages.
If your API requests trigger our rate limiting, you will receive a HTTP Error 503: Service Unavailable error.
In addition to endpoint-specific rate limiting, there is limit of 256 simultaneous connections per IP address.
HTTP Status Codes
The Prefinery API attempts to return appropriate HTTP status codes for every request.
|Object was successfully created.
|Your request was queued (in the background) for processing.
|The request could not be understood due to malformed syntax. Please modify your request and try again.
|Authentication credentials were missing or incorrect.
|The account's plan does not have API access enabled.
|The API key does not have permissions to perform this action.
|The URI requested is invalid or the resource requested, such as a tester, does not exists.
|Returned when fields are either absent or invalid.
|Internal Server Error
|Something is broken. Check your request and contact support if you are unable to resolve the issue.
|The rate limit has been reached.
When the Prefinery API returns error messages, it does so in your requested format. We will set the HTTP Status Code to one of the above and return to you a list of errors. Where possible, we will try to return both a unique error code (this is not the same as the HTTP Status Codes list above) and a helpful message. While a code won't always be included, a message will.
An error from a JSON method might look like this:
"message": "Email is required."