Start an endpoint run

Start an execution of an endpoint. For a sync COMPLETED run the HTTP status FAITHFULLY MIRRORS the provider’s own status (2xx → 2xx, provider 4xx/5xx → 4xx/5xx, request-timeout → 504); the body always carries the full run. A control gate returns a 200 BLOCKED run, and a run that exceeds its time budget returns 408 (TIMED_OUT). Async endpoints return a 202 acceptance ack — poll GET /v1/runs/ for the result. Scopes: runs:create, plus resources:create / resources:update / resources:delete when the endpoint provisions / updates / releases a resource.

POST /v1/run

Start an endpoint run

cURL

curl --request POST \
  --url https://api.monid.ai/v1/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "exa",
  "endpoint": "search",
  "input": {
    "body": {},
    "queryParams": {},
    "pathParams": {}
  }
}
'

200

{
  "runId": "<string>",
  "provider": "<string>",
  "endpoint": "<string>",
  "status": "READY",
  "providerResponse": {
    "httpStatus": 200,
    "error": "<unknown>"
  },
  "price": {
    "type": "<string>",
    "amount": {
      "value": 123,
      "currency": "USD"
    },
    "flatFee": {
      "value": 123,
      "currency": "USD"
    },
    "period": {
      "unit": "MINUTE",
      "count": 123
    },
    "per": {
      "unit": "MINUTE",
      "count": 123
    },
    "unit": "token",
    "default": {
      "type": "PER_CALL",
      "amount": {
        "value": 123,
        "currency": "USD"
      }
    },
    "selectors": [
      {
        "label": "<string>",
        "key": "<string>",
        "in": "body",
        "offset": 1
      }
    ],
    "variants": [
      {
        "when": {},
        "price": {
          "type": "PER_CALL",
          "amount": {
            "value": 123,
            "currency": "USD"
          }
        },
        "label": "<string>"
      }
    ],
    "tiers": [
      {
        "label": "<string>",
        "price": {
          "type": "PER_CALL",
          "amount": {
            "value": 123,
            "currency": "USD"
          }
        },
        "when": {},
        "selector": {
          "label": "<string>",
          "key": "<string>",
          "in": "body",
          "offset": 1
        }
      }
    ],
    "notes": [
      "<string>"
    ]
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "output": "<unknown>",
  "billing": {
    "reportedCost": {
      "currency": "USD",
      "value": 1,
      "unit": "MICRO_DOLLAR"
    }
  },
  "resultCount": 1,
  "billedUnits": 1,
  "resources": [
    {
      "action": "PROVISIONED",
      "resourceId": "<string>",
      "resourceType": "phone_number",
      "identifier": "<string>"
    }
  ],
  "stopRequestedAt": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z",
  "hints": {}
}

Authorizations

Authorization · string · header · required

Monid API key (Authorization: Bearer mk_...) or Clerk-issued JWT. Each operation lists the ONE scope an API key needs. {resource}:* grants every action on that resource; * grants everything; Clerk sessions hold *. Operations with an empty list need no scope. Scope catalog: GET /v1/api-keys/scopes.

Headers

X-Monid-Agent-Model · string

Model driving the calling agent. Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error).

Maximum string length: 256

X-Monid-Agent-Harness · string

Agent harness or client making the call (e.g. a coding agent, an agent framework). Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error).

Maximum string length: 256

X-Monid-Agent-Session-Id · string

Caller-side session identifier, so the calls of one agent session (discover → inspect → run → polling) can be correlated. Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error).

Maximum string length: 256

Body

application/json

provider · string · required

Provider slug.

Minimum string length: 1

Example:

"exa"

endpoint · string · required

Endpoint path within the provider.

Minimum string length: 1

Example:

"search"

input · object

Composite endpoint input — body + URL query + URL path. All sub-fields optional.

Show child attributes

Response

200

application/json

Terminal run — COMPLETED (sync execution, when the provider responded 2xx) or BLOCKED (a workspace control gate rejected the run). A COMPLETED run with a non-2xx provider status is returned with that same HTTP status and this body shape — EXCEPT a provider 402 (the upstream vendor's payment/quota failure, not your wallet), which is returned as 502.

Option 1

Option 2

runId · string · required

provider · string · required

endpoint · string · required

status · enum<string> · required

Run lifecycle status. Always one of the UPPERCASE enum values (e.g. COMPLETED, never completed) — compare case-sensitively. COMPLETED means the provider responded (any HTTP status); FAILED means an infrastructure failure.

Available options: READY, RUNNING, STOPPING, COMPLETED, FAILED, BLOCKED, STOPPED, TIMED_OUT

providerResponse · object · required

Show child attributes

price · object · required

User-facing price (markup applied).

Show child attributes

createdAt · string<date-time> · required

output · any

Provider output data (terminal runs only; may be null). Endpoints that generate FILES (e.g. audio) surface each file INSIDE output as an artifact object under a stable key: { download_link (fresh signed URL, valid until link_expires_at — re-fetch the run for a new one), content_type, link_expires_at, file_expires_at? }. After the file's retention lapses the object becomes { expired: true, file_expired_at, message }.

billing · object

Show child attributes

resultCount · number

Required range: x >= 0

billedUnits · number

Required range: x >= 0

resources · object[]

Show child attributes

stopRequestedAt · string<date-time>

completedAt · string<date-time>

hints · object

Show child attributes