Skip to content
Browse API reference

API Reference

Reference for the public Castle API. All requests use HTTPS and JSON for request and response bodies.

Introduction

The Castle API is a standard HTTP API for sending security, fraud, and account activity data to Castle and receiving structured JSON results. It uses standard HTTP response codes, authentication, and verbs.

All API requests must use HTTPS. Non-HTTPS calls fail, and the TLS version must be 1.1 or higher. JSON is used for request and response bodies, so requests with a body, such as POST or PUT , must set Content-Type: application/json.

Rate limits

Castle APIs limit the number of requests. Each request returns the following headers:

Header Description
X-RateLimit-Limit The maximum number of requests that you can make in the current time window.
X-RateLimit-Remaining The number of requests remaining in the current time window.
X-RateLimit-Reset The remaining time in seconds until the current time window resets.

The Risk, Filter, and legacy Authenticate APIs also have a per-user-id rate limit of 6 requests per second and 10 requests per 5 seconds.

Authentication

API keys authenticate Castle APIs. You can view and manage API keys in the Castle Dashboard. Castle API keys are secret, so do not share them in publicly accessible areas such as GitHub or client-side code.

All endpoints use HTTP Basic Auth with your API secret as the password and no username. Set the Authorization header to Basic base64(:API_SECRET) . If the header is missing or incorrect, Castle responds with 401.

Security scheme type HTTP
HTTP authorization scheme basic

Risk Assessment

Lists

Events

Privacy

Intelligence