Skip to main content
The Stairoids REST API gives you programmatic access to every capability of the platform — from ingesting real-time signals to managing audiences, workflows, and webhook subscriptions. All communication happens over HTTPS, and every request and response body uses JSON. This reference covers the foundational conventions you need to know before making your first call, including the base URL, versioning strategy, response envelope schema, and standard HTTP status codes.

​
Base URL

Every API request targets the following base URL: 
https://api.stairoids.com/v1
The version segment (v1) is part of the URL path. When Stairoids introduces a breaking change, a new version prefix (e.g., v2) is released alongside the current one, giving you time to migrate without disrupting live integrations. Non-breaking additions — new optional fields, new endpoints, new enum values — are rolled out to the current version without a version bump.

​
Request Format

All requests must include the Content-Type: application/json header and a JSON body where applicable. Query parameters are used only for filtering and pagination on GET endpoints. 
curl https://api.stairoids.com/v1/signals \
  -X POST \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "type": "page_view", "account_id": "acc_123" }'

​
Response Format

Every Stairoids API response is wrapped in a consistent envelope. Successful responses carry your payload under the data key alongside a meta object containing a unique request identifier and a server-side timestamp — both useful when troubleshooting with Stairoids support. Success response envelope: 
{
  "data": {
    "id": "sig_abc123",
    "type": "page_view",
    "account_id": "acc_123",
    "created_at": "2024-10-15T09:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-10-15T09:30:00Z"
  }
}
Error response envelope: When a request fails, the data key is absent and an error object is returned instead. The code field is a machine-readable string you can use for programmatic error handling, message is a human-readable explanation, and param (when present) identifies the specific field that caused the issue. 
{
  "error": {
    "code": "invalid_signal_type",
    "message": "Signal type must be a non-empty string.",
    "param": "type"
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}
Always log the meta.request_id from error responses. Including it when contacting Stairoids support dramatically speeds up root-cause investigation.

​
HTTP Status Codes

Stairoids uses standard HTTP status codes to communicate the outcome of every request. The table below covers all codes you may encounter across the API.
Status CodeNameWhen you’ll see it
200OKThe request succeeded and a response body is returned.
201CreatedA new resource was created successfully (e.g., a signal or webhook).
400Bad RequestThe request is malformed or missing required parameters.
401UnauthorizedThe API key is missing, expired, or malformed.
403ForbiddenThe API key is valid but lacks the required scope for this endpoint.
404Not FoundThe requested resource does not exist.
422Unprocessable EntityThe request is well-formed but contains semantic validation errors.
429Too Many RequestsYou have exceeded your plan’s rate limit. See the Retry-After header.
500Internal Server ErrorAn unexpected error occurred on Stairoids’ servers.

​
Explore the API

Authentication

Learn how to generate API keys, assign scopes, and attach the Authorization header to every request.

Rate Limits

Understand per-plan rate limits, rate limit headers, and exponential backoff retry strategies.

Send a Signal

Send a real-time intent or behavioral signal into Stairoids for scoring and routing.

Webhooks

Subscribe to platform events and receive real-time HTTP callbacks to your own endpoints.