EN
Coming soon

API: getting started

The REST API lets an app or script call SRVO actions. The Cloud base URL is https://api.srvo.app/api/v1. For self-hosted SRVO, use your server’s origin followed by /api/v1.

Create an API key

  1. In SRVO, open Settings → API, MCP & webhooks.
  2. Under API keys, choose Personal or Workspace. Workspace keys can be managed by workspace owners and admins.
  3. Select Create key, enter a Name, and choose a Scope:
    • Read only lets the key read data.
    • Read and write also lets it make supported changes.
  4. Choose which actions the key may use. Your own role and permissions still apply.
  5. Choose an expiry and select Create key.
  6. Copy the key and store it safely. SRVO shows it only once. Select I’ve stored it.

Use the smallest scope and action set that works for your task. Revoke a key in Settings when you no longer need it.

Make your first request

Set the key in an environment variable. Do not put it directly in a command or commit it to source control.

export SRVO_API_KEY='your-key'
curl --fail-with-body \
  -H "Authorization: Bearer $SRVO_API_KEY" \
  https://api.srvo.app/api/v1/me

GET /api/v1/me returns your workspace, member, role, and accessible modules. The API returns JSON. Send the bearer token with each request.

Read a list

List operations use cursor pagination when their schema supports it. The default page size is 50 and the maximum is 200. Follow nextCursor until it is null.

For example, GET /tables/{tableId}/records takes cursor and limit as query parameters. Some reads take nested filters or other structured input, so they use POST. Examples include POST /search/query, taxonomy history, and Sergio list operations. For those routes, pass pagination and filters in the JSON body when the reference lists them there. Check each operation in the API reference.

Make writes safe to retry

Some writes accept an Idempotency-Key header; others define an idempotencyKey input field. Use the exact field shown for that operation. Generate a unique key for one intended write, then reuse that same key if you retry after a timeout. Do not reuse it for a different write. The API reference shows which operations accept a key.

Handle errors and limits

Errors use JSON with an error.code, such as VALIDATION, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, STALE_PREVIEW, or RATE_LIMITED. HTTP status codes include 400 for invalid input, 401 for missing sign-in, 403 for forbidden or disabled modules, 404 for missing or hidden items, 409 for conflicts, and 429 for rate limits.

The default outer limit is 600 requests per minute for each verified session or API key. Anonymous requests use a per-IP limit of 600 per minute. When a response includes Retry-After, wait that many seconds before retrying. Limits can vary by route and server configuration.

Preview destructive actions

Some destructive actions need two calls. First call the action without its confirmation value to get a preview. Review the summary and warnings. Then call it again with the confirmation value from that preview. The field or header depends on the action. If the preview is stale, request a new one. The reference documents each action’s confirmation contract.

Generated developer reference.