API Overview

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

Base URL

https://api.monid.ai

Authentication

All /v1/* endpoints require Bearer authentication — a Monid API key or an OAuth/JWT access token:

Authorization: Bearer monid_live_...

Create an API key at 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.

x-workspace-id: org_abc123

Endpoints

Auth

Method	Path	Description
`GET`	`/v1/auth/whoami`	Return the identity behind the current credentials
`GET`	`/v1/auth/workspaces`	List workspaces the caller can access

Endpoints

Method	Path	Description
`POST`	`/v1/discover`	Search for data endpoints
`POST`	`/v1/inspect`	Get full endpoint details
`POST`	`/v1/run`	Execute a data endpoint

Runs

Method	Path	Description
`GET`	`/v1/runs`	List runs
`GET`	`/v1/runs/:runId`	Get run status and results
`POST`	`/v1/runs/:runId/stop`	Stop a queued or running run

Wallet

Method	Path	Description
`GET`	`/v1/wallet/balance`	Get current balance
`GET`	`/v1/wallet/activities`	List wallet transactions

Request Format

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

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:

{
  "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:

{
  "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.

​Base URL

​Authentication

​Workspace Header

​Endpoints

​Auth

​Endpoints

​Runs

​Wallet

​Request Format

​Response Format

​Pagination

​Error Codes

​Request Tracing

Base URL

Authentication

Workspace Header

Endpoints

Auth

Endpoints

Runs

Wallet

Request Format

Response Format

Pagination

Error Codes

Request Tracing