> ## 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 Bearer authentication — a Monid API key or an OAuth/JWT access 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

When you authenticate with a Monid API key, the workspace is bound to the key — no `x-workspace-id` header is needed. The header only applies when authenticating with an OAuth/JWT access token that does not carry an organization context; in that case pass it explicitly. Get the list of workspaces the caller can access with [`GET /v1/auth/workspaces`](/docs/api/auth/workspaces).

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

## Endpoints

### Auth

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

### Endpoints

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

### Runs

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

### Wallet

| Method | Path                                              | Description              |
| ------ | ------------------------------------------------- | ------------------------ |
| `GET`  | [`/v1/wallet/balance`](/docs/api/wallet/balance)       | Get current balance      |
| `GET`  | [`/v1/wallet/activities`](/docs/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 | varies  | Maximum items to return (default and max vary 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                                                                                                    |
| ----- | ---------------------------------------------------------------------------------------------------------- |
| `202` | Accepted — the operation runs asynchronously (async runs, stop requests)                                   |
| `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, or the resource belongs to another workspace |
| `404` | Not found — resource doesn't exist                                                                         |
| `408` | Request timeout — a synchronous run timed out (`TIMED_OUT`)                                                |
| `409` | Conflict — e.g. stopping a run that is terminal or not stoppable                                           |
| `500` | Internal server error                                                                                      |
| `502` | Bad gateway — the upstream provider rejected the call (e.g. provider-side payment error)                   |
| `503` | Service unavailable — e.g. the wallet is not active                                                        |

## Request Tracing

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