Responses

All API endpoints listed under Resources, whether successful or not, will be returned in the same type of envelope structure.

The authentication endpoints return a slightly different format that follows the OAuth2 specification.

Response Envelope

The top-level response is an object containing two keys. The first key, data, corresponds to the actual response item requested. This may either be an object itself or a list of objects. The particular data returned is described in each endpoint's documentation. If the request is unsuccessful (results in an error), no data key will be present.

The second key present, meta, corresponds to an object containing additional information about the request. This object will always contain code, a copy of the HTTP status code that has been returned. It will also contain pagination metadata and/or a stream marker when relevant.

Sample Response Envelope

{
  "data": "the data you requested",
  "meta": {
    "more": true,
    "max_id": "2703",
    "min_id": "2702",
    "marker": {
      "id": "2593",
      "last_read_id": "5719",
      "percentage": "0",
      "updated_at": "2017-12-26T15:26:19Z",
      "version": "YM-fTQk8_0nsdlI01kcUCGvyvHN",
      "name": "global"
    },
    "code": 200
  }
}

CORS

CORS is supported for authenticated cross-domain API requests direct from browsers. Be sure to carefully consider how your app will handle access tokens for CORS requests.

X-Pretty-Json Header

The examples in the documentation include the X-Pretty-Json header. This prints the JSON with more readable spacing, for testing. In production there's no reason to include it. If it is set at all, the JSON will be returned that way.

Errors

If the request was unsuccessful, no data key will be returned. code and error_message keys will indicate what error occurred. There may also be a uniquely-identifying error_id present that can be helpful when talking to pnut.io support.

The API will respond with some accuracy for almost all issues. There are two unspecific errors: you may receive code: 400, error_message: Wrong type, which should be straight forward to determine the cause from the client. If you receive code: 500, error_message: Internal Server Error, something internal failed and it should be immediately reported to support.

HTTP status codes

Pnut.io uses the HTTP status code to indicate if an API request was a success or failure. For environments that can't access the raw HTTP response directly, this value is also duplicated in the meta.code value. The following table lists all currently used HTTP status codes. If you get a status code that is not documented below, please open an issue.

Code	Description
200 OK	The request was successful.
204 No Content	Returned when retrieving an incomplete file or when uploading file content to an incomplete file.
302 Found	Redirection to the final destination of a resource. Returned when retrieving user avatar, or a cover image.
400 Bad Request	The API request was malformed in some way. A message should be returned that indicates how this request can be fixed.
401 Unauthorized	A token is required. If you passed a token, a message should indicate why this token is not authorized.
403 Forbidden	The token you are providing doesn't have the right to perform the request. Please check that your token is of the correct type and has the required scope.
404 Not Found	The requested resource was not found.
429 Too Many Requests	The request could not be completed due to a rate limit. Please wait at the number of seconds specified in the Retry-After header before you retry this request.
500 Internal Server Error	An unexpected server error has occurred. Talk to pnut.io support to solve the issue.
507 Insufficient Storage	The request couldn't be completed because the authorized user has hit a quota limit. This could be returned when trying to upload a file. The current token information's data.storage.available key can help an app avoid this error.