Skip to Content
APIREST

REST API

Call a capability with POST /api/v1/capabilities/{name}. Authenticate with Authorization: Bearer {api_key} (or X-API-Key: {api_key}) and send the capability’s input object as the JSON body:

curl -s \
  -X POST https://gateway.example.com/api/v1/capabilities/get_customer \
  -H "Authorization: Bearer $ONPREST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":1}'

The body must match the capability’s input schema. Capabilities with file inputs also accept multipart/form-data; see Files.

Success

{
  "request_id": "01J5ABCDEF1234567890ABCDEF01",
  "result": {
    "data": {
      "rows": [{ "id": 1, "name": "Ada Lovelace" }],
      "count": 1
    },
    "files": []
  }
}

request_id identifies the call in the gateway log. result.data has the shape the capability’s output declares: {rows, count} for database queries and CSV, {count} for database mutations, and the JSON value itself for HTTP and Wasm capabilities. It is null when the capability publishes no data. result.files lists returned files; see Files.

A capability with delivery.rest: direct returns its single file as the response body instead of this envelope.

Failure

{
  "request_id": "01J5ABCDEF1234567890ABCDEF01",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "input validation failed",
    "outcome": "not_started"
  }
}

A response has either result or error, never both. code determines the HTTP status, and outcome tells you whether anything happened on the on-prem side. Both are listed in Errors. Messages are safe to show and never contain SQL, paths, credentials, or the values you sent.

Limits

The gateway accepts JSON bodies up to 1 MiB by default (GATEWAY_MAX_REQUEST_BODY_BYTES); larger bodies get HTTP 413. Each capability also has its own input limits and a timeout set by its policy. Integers keep full 64-bit precision, so use a JSON library that preserves large integers if your values can exceed 2^53.

OverviewFiles