DashboardSign inStart your trial
In this guide · OperateClose guide

API & MCP

Read your workspace's tables, forms, workflows, approvals, decision records, agents, integrations, and files over a scoped REST API or MCP.

Use the Rills API to read the operational data already in your workspace: tables, forms, workflows, runs, approvals, decision records, agents, connected integrations, and files. Build internal reports, feed another system, or chart pipeline and approval health in Grafana without giving that tool direct database access.

Access is bound to one workspace and limited by scopes. Metadata and payload values are separate permissions, so a dashboard can monitor run health without reading lead data, approval context, or workflow inputs.

API reads don’t use action credits. If you start a workflow through the API, that run’s actions are billed exactly as if it had started any other way. See what costs credits.

#What you can do

  • Read resources: list and fetch workspace resources with cursor pagination and allowlisted filters.
  • Query aggregates: POST /query returns counts, sums, averages, and percentiles grouped by field and time bucket. It’s built for dashboards. See Query workspace data.
  • Take two actions: start a workflow run, or submit a proposal to the approval queue. Both require an idempotency key.
  • Follow the review queue: GET /review-queue/events streams server-sent events as approvals and optimization suggestions arrive or are decided. Reconnect with Last-Event-ID to resume where you left off. GET /review-queue/count returns how many items are waiting, which is all a badge needs.
  • Connect an AI agent: the MCP server exposes the same data and actions as tools, under the same scopes.

#Base URL and reference

Every REST endpoint lives under one base path:

https://rills.ai/api/v1

The complete, generated endpoint reference is an OpenAPI 3.1 document. It lists every endpoint, its parameters, response schemas, error responses, and the scopes it requires (in the x-rills-scopes extension), plus example bodies for every query dataset:

https://rills.ai/api/v1/openapi.json

Import it into Postman, Insomnia, or a client generator instead of copying endpoints by hand.

#Quick start

Create an API key in Settings → API & MCP access (see Authentication), store it in an environment variable, then list your workflows:

curl --fail-with-body \
  --header "Authorization: Bearer $RILLS_API_KEY" \
  "https://rills.ai/api/v1/workflows?limit=25"

Run an aggregate query from a JSON file:

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $RILLS_API_KEY" \
  --header "Content-Type: application/json" \
  --data @query.json \
  "https://rills.ai/api/v1/query"

Keep keys in environment variables or a secret manager. Never paste a real key into a command you’ll save in shell history, a repository, or a screenshot.

#Conventions

  • JSON in and out, UTF-8, camelCase field names.
  • Timestamps are ISO 8601 strings in UTC.
  • IDs are opaque strings. Don’t parse meaning out of them.
  • A detail response is { "data": { ... } }. A list response adds "page": { "nextCursor": ... }. A query response adds "meta": { "dataset": ..., "generatedAt": ... }.
  • Every response carries an X-Request-Id header. Include it when you contact support.
  • Browser calls are not supported (CORS is off). Call the API from a server, a script, or a tool’s backend.

#Versioning

v1 only receives backward-compatible additions, such as new endpoints, new optional parameters, and new response fields. Your client should ignore fields it doesn’t recognize. A breaking change ships as a new version or follows an announced deprecation window.

#In this section