REST API

Every MCP tool and every REST endpoint calls the same function, so they can't give different answers. The tool reference maps each tool to its endpoint.

The OpenAPI document is authoritative for paths, parameters and response shapes. Generate a client from it rather than copying shapes from this page.

First callCopy Anchor Link

export RIVOMI=https://rivomi.com
curl "$RIVOMI/api/v1/workspace" -H "Authorization: Bearer $RIVOMI_KEY"

PagingCopy Anchor Link

Every list endpoint takes limit (default 25, maximum 200) and offset, and returns:

{ "total": 412, "count": 25, "offset": 0, "has_more": true, "next_offset": 25, "items": [] }

Loop until has_more is false, passing next_offset as the next offset.

IdempotencyCopy Anchor Link

POST /v1/agents/{id}/run, POST /v1/lists/{id}/process and POST /v1/imports accept an Idempotency-Key header. A repeat with the same key within 24 hours replays the first response instead of spending again. Send one on every call you might retry:

curl -X POST "$RIVOMI/api/v1/agents/$AGENT_ID/run" \
  -H "Authorization: Bearer $RIVOMI_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

ErrorsCopy Anchor Link

Errors are JSON with a sentence written for the caller and a stable code:

{ "error": "This key needs the write scope. Create one under Settings › API.", "code": "insufficient_scope" }

Status codes and codes are listed in Errors and limits.