# Overview

The Minded REST API provides programmatic access to analytics events and knowledge base document management.

## Base URL

```
https://api.minded.com/api/v1
```

## Authentication

All API requests require an **organization API token** passed via the `Authorization` header:

```http
Authorization: Bearer md_yourTokenHere
```

### Token Characteristics

* **Scoped**: Permissions are granted per token
* **Org-bound**: Requests are authorized for the organization tied to the token
* **One-time visible**: The plaintext token is shown only when created and cannot be recovered

### Managing Tokens

In the Minded dashboard, navigate to **Organization Settings → API Tokens** to create, view, or revoke tokens.

### Token Scopes

| Scope                  | Grants Access To                                       |
| ---------------------- | ------------------------------------------------------ |
| `analytics`            | [Analytics API](https://docs.minded.com/api/analytics) |
| `knowledge-management` | [Knowledge API](https://docs.minded.com/api/knowledge) |

## Rate Limiting

Rate limits vary by deployment (default: \~10 requests/minute). Response headers indicate current limits:

| Header                | Description                  |
| --------------------- | ---------------------------- |
| `RateLimit-Limit`     | Maximum requests allowed     |
| `RateLimit-Remaining` | Requests remaining in window |
| `RateLimit-Reset`     | Seconds until limit resets   |

## Response Format

All responses are JSON. Successful responses typically include:

```json
{
  "success": true,
  "data": { ... }
}
```

## Error Codes

| Code | Description                                                                 |
| ---- | --------------------------------------------------------------------------- |
| 400  | Bad request — missing required fields or invalid parameters                 |
| 401  | Unauthorized — invalid or missing token                                     |
| 403  | Forbidden — token missing required scope                                    |
| 404  | Not found — resource does not exist or does not belong to your organization |
| 429  | Too many requests — rate limit exceeded                                     |
| 500  | Internal server error                                                       |

Error responses include details:

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required field: agentId"
  }
}
```