REST API

The Castle API is REST-based: it is designed to have predictable urls and uses built-in HTTP features like HTTP Basic Authentication, Response Codes and HTTP Verbs. All requests, including errors, return JSON. The API expects JSON for all POST and PUT requests.

The REST API forms the platform which our libraries are built on. We don't recommend that you build an app using the REST API exclusively – you will probably want to use one of our libraries for that.

However, if you need to reference the way something works on a lower level, or if you're curious about how the libraries interact with the platform itself, this reference has the details.

Authentication

You authenticate to the Castle API by providing your API Secret in the request. The API Secret is random string which gives you full read and write access to your Castle account, so be sure to keep it hidden.

Authentication to the API occurs via HTTP Basic Auth. Provide your API Secret as the basic auth password. You do not need to provide a username.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

Example

curl -s https://api.castle.io/v1 -u ":HCL1SVj3nw4KmL7YpzpivxNyDsUYjbgq"

Note the absence of a basic auth username, and remember the colon!

Errors

Castle uses standard HTTP response codes to indicate whether a request was successful or not. All errors return a JSON object describing the error.

Error object

Field Type Description
type String Type of error
message String Human readable text describing the error that occurred

Example response

{
  "type": "invalid_parameters",
  "message": "One or more parameters are invalid"
}

Summary of response codes

Code Type
400 bad_request
400 missing_headers
400 invalid_header_value
401 unauthorized
403 forbidden
404 not_found
404 route_not_found
422 invalid_parameters
500 server_error
503 service_unavailable