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

# Introduction

> Get started with the Stardex API

## Base URL

All API requests should be made to:

```bash theme={null}
https://api.stardex.ai
```

For example, to access the `/v1/persons` endpoint, you would make a request to:

```bash theme={null}
https://api.stardex.ai/v1/persons
```

## Authentication

All API endpoints require authentication using Bearer tokens in the Authorization header. Add your API key as follows:

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

You can get your API key from the [Stardex Settings](https://stardex.ai/settings/integrations).

## Response Format

All API endpoints follow a consistent response format:

### Successful Responses

```json theme={null}
{
  "success": true,
  "data": object  // Response data
}
```

For paginated responses:

```json theme={null}
{
  "success": true,
  "data": array,
  "meta": {
    "total": number,
    "offset": number,
    "limit": number
  }
}
```

### Example Successful Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "123",
    "name": "John Doe"
    // ... other fields
  }
}
```

### Error Responses

```json theme={null}
{
  "success": false,
  "error": {
    "code": string,
    "message": string,
  }
}
```

### Example Error Response

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired"
  }
}
```

Common HTTP Status Codes:

* `200`: Operation completed successfully
* `400`: Invalid request or missing fields
* `401`: Missing or invalid API key
* `403`: Forbidden - insufficient permissions
* `404`: Resource not found
* `429`: Rate limit exceeded
* `500`: Unexpected server error

## Rate Limits

API requests are rate-limited using a **sliding window** of **60 requests per minute** per API key. If you exceed the limit, the API will respond with a `429 Too Many Requests` status code.

<Note>
  Rate limits apply per API key. Each key has its own independent counter.
</Note>

### Rate Limit Headers

Every API response includes headers to help you track your current usage:

| Header                  | Description                                             |
| ----------------------- | ------------------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum number of requests allowed per minute           |
| `X-RateLimit-Remaining` | Number of requests remaining in the current window      |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the current window resets |

### Rate Limit Exceeded Response

When the rate limit is exceeded, the API returns a `429` status code with a `Retry-After` header:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 30 seconds.",
    "retry_after_seconds": 30,
    "limit": 60,
    "reset_at": 1717027200
  }
}
```

| Field                 | Description                                     |
| --------------------- | ----------------------------------------------- |
| `retry_after_seconds` | Seconds to wait before making another request   |
| `limit`               | Your rate limit (requests per minute)           |
| `reset_at`            | Unix timestamp (seconds) when the window resets |

### Best Practices

* **Check rate limit headers** on every response to monitor your usage.
* **Implement exponential backoff** when you receive a `429` response — wait for the `retry_after_seconds` value before retrying.
* **Spread requests over time** rather than sending them in bursts to avoid hitting the limit.
* **Cache responses** where possible to reduce the total number of API calls.