API documentation

Documentation

Docs navigation
API navigation

This site will help you get started with the Curator.io API. You'll be up and running in a jiffy!

Overview

The Curator.io API is a RESTfull HTTP API that allows developer to interact with the Curator platform.

Only HTTPS is supported for API requests (for privacy and to securely allow transport of API Keys).

All requests to the should be to the API server:

https://api.curator.io/v1

Content-Type

All requests must be set to Content-Type: application/json

Content-Type: application/json

Authentication

Each API request requires an API key either as a HTTP Header or included as a query string.

You can find your API key in the Curator Dashboard.

Your API key has many privileges, be sure to keep it secret! Do not share the key in publicly accessible areas such GitHub, client-side code, and so forth.

Query string

Include the API key as part of the request path in the format ?api_key=API_KEY.

GET https://api.curator.io/v1/feeds?api_key=ABCD-1234

HTTP Header / Basic Auth

Following the Authorization Basic HTTP Spec (eg https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side). Provide your API key as the basic auth username value. You do not need to provide a password.

The Authorization field is constructed as follows:

  1. The username (api_key) and password (leave blank) are combined with a single colon. (:)
  2. The resulting string is encoded into an octet sequence.
  3. The resulting string is encoded using a variant of Base64.
  4. The authorization method and a space is then prepended to the encoded string, separated with a space (e.g. "Basic ").
GET https://api.curator.io/v1/feeds
Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Response codes

The common HTTP Response Status Codes are used.

Successful Response

Successful API queries will return a 200 HTTP Response code

Error Responses

As much as possible, Curator attempts to use appropriate HTTP status codes to indicate the general class of problem, and this status code is repeated in the code section of the meta response.

400 (Bad Request)
Any case where a parameter is invalid, or a required parameter is missing. This includes the case where no OAuth token is provided and the case where a resource ID is specified incorrectly in a path.

403 (Forbidden)
The requested information cannot be viewed by the acting user, for example, because they are not friends with the user whose data they are trying to read.

404 (Not Found)
Endpoint does not exist.

405 (Method Not Allowed)
Attempting to use POST with a GET-only endpoint, or vice-versa.

422 (Unprocessable Entity)
The request could not be completed as it is. Use the information included in the response to modify the request and retry.

500 (Internal Server Error)
Curator's servers are unhappy. The request is probably valid but needs to be retried later. If the problem persist please contact support@curator.io

Error responses will return JSON a message in the following format.

{
  "success": false,
  "message": "Please provide a feed_id"
}