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

# API Overview

> Base URL, versioning, and general API conventions

# API Overview

<Note>
  **API Version:** v1 (Private Beta) · **Status:** Accepting waitlist applications · **Base URL:** `https://api.stablegenius.co/v1`
</Note>

The Stable Genius API is a REST API that uses JSON for request and response bodies, standard HTTP status codes, and bearer token authentication.

## Base URL

```
https://api.stablegenius.co/v1
```

All API requests must be made over HTTPS.

## Authentication

Include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer sk_test_abc123
```

See [Authentication](/api-reference/authentication) for details on API key types and management.

## Request Format

* All POST/PUT requests must include `Content-Type: application/json`
* Request bodies are JSON objects
* Query parameters are used for filtering on GET requests

## Response Format

All responses follow a consistent structure:

```json theme={null}
{
  "id": "pi_xyz789",
  "object": "payment_intent",
  "status": "awaiting_payment",
  "amount": 4.50,
  // ... additional fields
}
```

List endpoints return paginated results:

```json theme={null}
{
  "object": "list",
  "data": [ /* array of objects */ ],
  "has_more": true,
  "total_count": 142
}
```

## Pagination

List endpoints support cursor-based pagination:

| Parameter        | Type      | Description                                                                         |
| ---------------- | --------- | ----------------------------------------------------------------------------------- |
| `limit`          | `integer` | Number of results per page. Default: 25. Max: 100.                                  |
| `starting_after` | `string`  | Cursor for forward pagination. Pass the `id` of the last item in the previous page. |
| `ending_before`  | `string`  | Cursor for backward pagination.                                                     |

## Errors

Errors return standard HTTP status codes with a JSON body:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "Amount must be greater than 0",
    "param": "amount",
    "code": "amount_too_small"
  }
}
```

| Status Code | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| `200`       | Success                                                     |
| `201`       | Created                                                     |
| `400`       | Bad request — invalid parameters                            |
| `401`       | Unauthorized — invalid or missing API key                   |
| `403`       | Forbidden — valid key but insufficient permissions          |
| `404`       | Not found                                                   |
| `409`       | Conflict — duplicate resource (e.g., idempotency key match) |
| `422`       | Unprocessable — request understood but cannot be processed  |
| `429`       | Rate limited — too many requests                            |
| `500`       | Internal server error                                       |

## Rate Limits

| Environment              | Limit                 |
| ------------------------ | --------------------- |
| Sandbox (`sk_test_*`)    | 100 requests/minute   |
| Production (`sk_live_*`) | 1,000 requests/minute |

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1711929600
```

## Versioning

The API is versioned via the URL path (`/v1/`). Breaking changes will only be introduced in new major versions. Non-breaking additions (new fields, new endpoints) may be added to the current version at any time.

Set the `X-API-Version` header to pin your integration to a specific API version:

```bash theme={null}
X-API-Version: 2026-04-01
```

## Idempotency

POST endpoints support idempotency via the `idempotency_key` field in the request body. Resubmitting a request with the same key within 24 hours returns the original response instead of creating a duplicate.