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

# API Overview

> Discover, inspect, and run data endpoints programmatically.

The Monid HTTP API lets you discover, inspect, and run data endpoints programmatically.

## Base URL

```text theme={null}
https://api.monid.ai
```

## Authentication

All `/v1/*` endpoints require an API key passed as a Bearer token:

```text theme={null}
Authorization: Bearer monid_live_...
```

Create an API key at [https://app.monid.ai/access/api-keys](https://app.monid.ai/access/api-keys).

## Workspace Header

Every request should include `x-workspace-id` so Monid knows which workspace to operate against. Get the list of workspaces the caller can access with [`GET /v1/auth/workspaces`](/api/auth/workspaces).

```text theme={null}
x-workspace-id: ws_abc123
```

## Endpoints

### Auth

| Method | Path                                          | Description                                        |
| ------ | --------------------------------------------- | -------------------------------------------------- |
| `GET`  | [`/v1/auth/whoami`](/api/auth/whoami)         | Return the identity behind the current credentials |
| `GET`  | [`/v1/auth/workspaces`](/api/auth/workspaces) | List workspaces the caller can access              |

### Endpoints

| Method | Path                            | Description               |
| ------ | ------------------------------- | ------------------------- |
| `POST` | [`/v1/discover`](/api/discover) | Search for data endpoints |
| `POST` | [`/v1/inspect`](/api/inspect)   | Get full endpoint details |
| `POST` | [`/v1/run`](/api/run)           | Execute a data endpoint   |

### Runs

| Method | Path                                     | Description                  |
| ------ | ---------------------------------------- | ---------------------------- |
| `GET`  | [`/v1/runs`](/api/runs/list)             | List runs                    |
| `GET`  | [`/v1/runs/:runId`](/api/runs/get)       | Get run status and results   |
| `POST` | [`/v1/runs/:runId/stop`](/api/runs/stop) | Stop a queued or running run |

### Wallet

| Method | Path                                              | Description              |
| ------ | ------------------------------------------------- | ------------------------ |
| `GET`  | [`/v1/wallet/balance`](/api/wallet/balance)       | Get current balance      |
| `GET`  | [`/v1/wallet/activities`](/api/wallet/activities) | List wallet transactions |

## Request Format

All request bodies must be JSON with `Content-Type: application/json`.

```bash theme={null}
curl -X POST https://api.monid.ai/v1/discover \
  -H "Authorization: Bearer monid_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "twitter posts"}'
```

## Response Format

All responses return JSON. Successful responses return the resource directly. Error responses return:

```json theme={null}
{
  "code": 400,
  "message": "Descriptive error message"
}
```

## Pagination

All list endpoints use cursor-based pagination:

**Request:**

| Parameter | Type   | Default | Description                                      |
| --------- | ------ | ------- | ------------------------------------------------ |
| `limit`   | number | 10      | Maximum items to return (max varies by endpoint) |
| `cursor`  | string | —       | Opaque cursor from a previous response           |

**Response:**

```json theme={null}
{
  "items": [],
  "cursor": "eyJsYXN0..."
}
```

If `cursor` is `null` or absent, you've reached the last page.

## Error Codes

| Code  | Meaning                                                          |
| ----- | ---------------------------------------------------------------- |
| `400` | Bad request — invalid input, malformed JSON, or validation error |
| `401` | Unauthorized — missing or invalid API key                        |
| `402` | Payment required — insufficient wallet balance                   |
| `403` | Forbidden — key is valid but not associated with a workspace     |
| `404` | Not found — resource doesn't exist                               |
| `408` | Request timeout — execution timed out                            |
| `500` | Internal server error                                            |

## Request Tracing

Every request is assigned a unique request ID via the `x-request-id` header. Include this ID when reporting issues.