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

# API Overview

> Base URL, authentication, response format, and pagination for the MeshAI API

## Base URL

All API requests use the following base URL:

```
https://api.meshai.dev/api/v1
```

## Authentication

Include your API key as a Bearer token in the `Authorization` header:

```bash theme={null}
curl https://api.meshai.dev/api/v1/agents \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

API keys start with `msh_`. Create keys in the dashboard at **Settings → API Keys**.

See [Authentication](/api-reference/authentication) for key types, scopes, and signup/login endpoints.

## Response Format

All responses use a consistent envelope:

### Success

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

### Success (Paginated)

```json theme={null}
{
  "success": true,
  "data": [ ... ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20
  }
}
```

### Error

```json theme={null}
{
  "success": false,
  "error": "Human-readable error message",
  "code": "VALIDATION_ERROR"
}
```

## Common Error Codes

| HTTP Status | Code                 | Description                                                   |
| ----------- | -------------------- | ------------------------------------------------------------- |
| 400         | `VALIDATION_ERROR`   | Invalid request body or parameters                            |
| 401         | `UNAUTHORIZED`       | Missing or invalid API key                                    |
| 402         | `PLAN_LIMIT_REACHED` | Agent limit or feature not available on your plan             |
| 403         | `FORBIDDEN`          | Insufficient permissions or policy violation                  |
| 404         | `NOT_FOUND`          | Resource not found                                            |
| 409         | `CONFLICT`           | Resource already exists (e.g., duplicate agent name)          |
| 429         | `RATE_LIMITED`       | Too many requests: retry after the `Retry-After` header value |
| 500         | `INTERNAL_ERROR`     | Server error: contact support                                 |

## Pagination

List endpoints support pagination with `page` and `limit` query parameters:

```bash theme={null}
curl "https://api.meshai.dev/api/v1/agents?page=2&limit=50" \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

| Parameter | Type    | Default | Description                |
| --------- | ------- | ------- | -------------------------- |
| `page`    | integer | 1       | Page number (1-based)      |
| `limit`   | integer | 20      | Results per page (max 100) |

The response `meta` object contains the total count for building pagination UI.

## Rate Limits

| Plan            | Requests/min |
| --------------- | ------------ |
| Starter         | 60           |
| Professional    | 300          |
| Enterprise      | 1,000        |
| Enterprise Plus | Custom       |

Rate-limited responses include a `Retry-After` header (seconds).

## Content Type

All POST/PATCH/PUT requests must include:

```
Content-Type: application/json
```