> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stairoids.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stairoids API Overview: Base URL, Formats, and Status Codes

> Explore the Stairoids REST API: base URL, versioning, JSON request and response formats, status codes, and links to core reference topics.

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:

```text theme={null}
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.

```bash theme={null}
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:**

```json theme={null}
{
  "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.

```json theme={null}
{
  "error": {
    "code": "invalid_signal_type",
    "message": "Signal type must be a non-empty string.",
    "param": "type"
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}
```

<Note>
  Always log the `meta.request_id` from error responses. Including it when contacting Stairoids support dramatically speeds up root-cause investigation.
</Note>

## 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 Code | Name                  | When you'll see it                                                      |
| ----------- | --------------------- | ----------------------------------------------------------------------- |
| `200`       | OK                    | The request succeeded and a response body is returned.                  |
| `201`       | Created               | A new resource was created successfully (e.g., a signal or webhook).    |
| `400`       | Bad Request           | The request is malformed or missing required parameters.                |
| `401`       | Unauthorized          | The API key is missing, expired, or malformed.                          |
| `403`       | Forbidden             | The API key is valid but lacks the required scope for this endpoint.    |
| `404`       | Not Found             | The requested resource does not exist.                                  |
| `422`       | Unprocessable Entity  | The request is well-formed but contains semantic validation errors.     |
| `429`       | Too Many Requests     | You have exceeded your plan's rate limit. See the `Retry-After` header. |
| `500`       | Internal Server Error | An unexpected error occurred on Stairoids' servers.                     |

## Explore the API

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn how to generate API keys, assign scopes, and attach the `Authorization` header to every request.
  </Card>

  <Card title="Rate Limits" icon="gauge-high" href="/api-reference/rate-limits">
    Understand per-plan rate limits, rate limit headers, and exponential backoff retry strategies.
  </Card>

  <Card title="Send a Signal" icon="bolt" href="/api-reference/signals/send-signal">
    Send a real-time intent or behavioral signal into Stairoids for scoring and routing.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/overview">
    Subscribe to platform events and receive real-time HTTP callbacks to your own endpoints.
  </Card>
</CardGroup>