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

# API Reference

> DataRaven REST API

The DataRaven API lets you programmatically manage teams, locations, tasks, executions, and vault
connections.

## Base URL

```
https://api.dataraven.io
```

## Authentication

All API requests require a Bearer token in the `Authorization` header:

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
curl https://api.dataraven.io/v1/teams \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Rate Limits

The API enforces rate limits per IP address. If you receive a `429` response, respect the `Retry-After` header and retry with exponential backoff.

### Global Rate Limit

All endpoints are subject to a global rate limit:

* **120 requests per minute** per IP address

### Rate Limit Headers

When you make a request, the API returns rate limit information in response headers:

| Header                  | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| `X-RateLimit-Limit`     | The rate limit for the endpoint (requests per minute)         |
| `X-RateLimit-Remaining` | The number of requests remaining in the current window        |
| `X-RateLimit-Reset`     | Unix timestamp (seconds) when the rate limit window resets    |
| `Retry-After`           | Seconds to wait before retrying (included in `429` responses) |

### Handling 429 Responses

When rate limited, the API responds with `429 Too Many Requests`:

```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
  "error": "Rate limit exceeded",
  "message": "..."
}
```

### Best Practices

1. **Check the `Retry-After` header** before retrying a rate-limited request
2. **Implement exponential backoff** for retries
3. **Batch requests** when possible to reduce API calls
4. **Monitor rate limit headers** in responses to adjust request frequency proactively

Validation errors (`422`) include a `detail` array with specific field-level error information.

## OpenAPI Spec

The full OpenAPI 3.1 specification is available at:

```
https://api.dataraven.io/openapi.json
```

Interactive API documentation is available at:

```
https://api.dataraven.io/scalar
```