REST API

REST API for Rowvia tables and automations

Use the REST API when you connect Rowvia from your own backend, scheduled job, or internal automation. The ChatGPT connector uses Rowvia OAuth; the REST API uses an rvia_ token in the Authorization header.

Open app Open API console OpenAPI JSON MCP documentation

First automation

Start with a table in the app, then call the REST API

Profile -> Integrations is not a public deep-link route yet. After sign-in, open Profile, go to Integrations, and create a token for a specific table or account.

Create a table in the app and choose a template.
In Profile -> Integrations, create an API token with the needed scopes.
Add a URL or text through the REST API to the existing table.
Start processing explicitly and track row status.
Read the results and check cells against the sources.

Overview

When to use the REST API

The REST API works with the same existing tables as the app. It is for server-side integrations: add a URL, text, or inline file as a row, start processing, track the run, read results, and export data. The default add flow is one primary source as one new row; when reading rows, extended rows can return the primary `document` plus `documents[]` with related attachments. In rare cases, row-add can return 202 with committed=true and reload_required=true; the write succeeded, but the client should reload rows before follow-up processing. For AI agents in ChatGPT or local MCP clients, use the MCP documentation.

Base URL

https://api.rowvia.ai

Authorization: Bearer rvia_...

Auth

Authentication

Create an API token in Rowvia Profile -> Integrations and send it as Authorization: Bearer rvia_.... The token belongs in server-side configuration or a secret manager, not in browser code, prompts, shared chats, or URLs.

tables:read

List tables, table detail, schema, summary, and pending-work metrics.

rows:read

Read rows, results, search, and exports.

row:add

Add new rows from url, text, or file sources.

row:process

Estimate processing, start runs, read status, and cancel runs.

rows:update

Manual cell correction through PATCH; add it only when the integration really needs it.

Token safety

Never paste an rvia_ token into a shared chat, prompt, or document.
Do not put the token in a browser frontend, public JavaScript, or client bundle.
Do not send tokens in URLs, query parameters, or imported links.
Prefer a table-restricted token for repeated workflows.
Start larger processing runs only after confirming the target table and pending-work estimate.
Log request_id or processing_run_id, never the full token.

Quickstart

All examples use the production base URL and real endpoints implemented in /api/v1. For larger batches, estimate first and retry mutations with Idempotency-Key. `POST /rows` creates new rows in the standard one primary source = one row flow; read existing extended rows with `include_document` when you need both the primary document and attachments. If row-add returns 202 committed/reload_required, reuse the same idempotency key or reload rows instead of retrying with a new key.

List tables

bash

curl "https://api.rowvia.ai/api/v1/tables?limit=20" \
  -H "Authorization: Bearer rvia_..."

Add one URL row

bash

curl -X POST "https://api.rowvia.ai/api/v1/tables/sheet_.../rows" \
  -H "Authorization: Bearer rvia_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-001" \
  -d '{
    "documents": [
      {
        "client_id": "invoice-001",
        "source": "url",
        "url": "https://example.com/invoice.pdf"
      }
    ],
    "process_after_add": false
  }'

Add one text row

bash

curl -X POST "https://api.rowvia.ai/api/v1/tables/sheet_.../rows" \
  -H "Authorization: Bearer rvia_..." \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "client_id": "note-001",
        "source": "text",
        "name": "meeting-note.txt",
        "text": "Supplier promised delivery in four weeks."
      }
    ],
    "process_after_add": false
  }'

Add one inline file row

bash

curl -X POST "https://api.rowvia.ai/api/v1/tables/sheet_.../rows" \
  -H "Authorization: Bearer rvia_..." \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "client_id": "file-001",
        "source": "file",
        "name": "invoice.pdf",
        "mime_type": "application/pdf",
        "data_base64": "JVBERi0x..."
      }
    ],
    "process_after_add": false
  }'

Estimate pending work

bash

curl -X POST "https://api.rowvia.ai/api/v1/tables/sheet_.../processing/estimate" \
  -H "Authorization: Bearer rvia_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "all_pending"
  }'

Create an export

bash

curl -X POST "https://api.rowvia.ai/api/v1/tables/sheet_.../exports" \
  -H "Authorization: Bearer rvia_..." \
  -H "Content-Type: application/json" \
  -d '{
    "format": "xlsx",
    "scope": "all"
  }'

Start processing from Node.js

const response = await fetch("https://api.rowvia.ai/api/v1/tables/sheet_.../processing/runs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ROWVIA_API_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "run-001",
  },
  body: JSON.stringify({
    mode: "selected_rows",
    row_ids: ["row_..."],
  }),
});

if (!response.ok) throw new Error(await response.text());
const data = await response.json();

Read results from Python

python

import os
import requests

base_url = "https://api.rowvia.ai"
headers = {"Authorization": f"Bearer {os.environ['ROWVIA_API_TOKEN']}"}

rows = requests.get(
    f"{base_url}/api/v1/tables/sheet_.../rows",
    headers=headers,
    params={"limit": 100, "results_only": "true"},
    timeout=30,
)
rows.raise_for_status()
print(rows.json())

Discovery

Discovery and identity

These endpoints help discover the API contract and check a token. OpenAPI and the console are public; working endpoints under /api/v1 require a Rowvia API token.

GET /api/v1/openapi.json

OpenAPI contract

Machine-readable description of the implemented REST API.

Scope: public

GET /api/v1/docs

API console

Noindex console that keeps the Bearer token only in browser tab memory.

Scope: public

GET /api/v1/me

Current token identity

Checks which user and restrictions the token resolves to.

Scope: API token

Tables

The public API works with existing Rowvia tables. The table ID is the sheet ID, for example sheet_....

GET /api/v1/tables

List tables

Lists tables available to the token.

Scope: tables:read

GET /api/v1/tables/{table_id}

Get table

Details for one table, including workbook and row counts.

Scope: tables:read

GET /api/v1/tables/{table_id}/schema

Get schema

Columns, prompts, and optional system columns through include_system_columns.

Scope: tables:read

GET /api/v1/tables/{table_id}/summary

Get summary

Table summary for deciding what to process.

Scope: tables:read

GET /api/v1/tables/{table_id}/pending-work

Pending work

Estimate of empty output cells that are ready for processing.

Scope: row:process

Rows

Rows and sources

Rows can be paged, searched, added from sources, and optionally corrected. The source value can be url, text, or file with data_base64. Standard imports create one row per primary source; extended rows can expose `documents[]` for the primary source and related attachments when read.

GET /api/v1/tables/{table_id}/rows

List rows

Cursor pagination through limit and cursor; supports column_ids, include_system_columns, and results_only.

Scope: rows:read

POST /api/v1/tables/{table_id}/rows

Add rows

Adds documents[] from source=url, source=text, or source=file; each item creates a new row with a primary source by default and process_after_add defaults to false. On 202 committed/reload_required, reload the table because row_id values may not be safely available.

Scope: row:add

POST /api/v1/tables/{table_id}/rows/read

Read selected rows

Bulk read of selected row_ids with column projection.

Scope: rows:read

GET /api/v1/tables/{table_id}/rows/search

Search rows

Searches rows through query, statuses, row_filters, and cursor.

Scope: rows:read

GET /api/v1/tables/{table_id}/rows/{row_id}

Get row

Details for one row; include_document adds legacy `document` for the primary source and `documents[]` for the full source set including attachments when available.

Scope: rows:read

GET /api/v1/tables/{table_id}/rows/{row_id}/results

Get row results

Only result cells for one row.

Scope: rows:read

PATCH /api/v1/tables/{table_id}/rows/{row_id}/cells

Update cells

Manual cell correction; requires the explicit rows:update scope.

Scope: rows:update

Processing

Start processing explicitly, especially for larger batches. An empty output cell is processable; a non-empty output cell is normally skipped.

POST /api/v1/tables/{table_id}/processing/estimate

Estimate processing

Estimates rows, cells, and processing units before starting.

Scope: row:process

POST /api/v1/tables/{table_id}/processing/runs

Start processing run

Starts a pending or selected_rows run; supports idempotency keys.

Scope: row:process

GET /api/v1/processing/runs/{processing_run_id}

Get processing run

Status, task counts, PU, and any errors.

Scope: row:process

POST /api/v1/processing/runs/{processing_run_id}/cancel

Cancel processing run

Requests cancellation of a running processing run.

Scope: row:process

Exports

Exports use the rows:read scope and return a short-lived download URL. Public exports are synchronous and limited to 10,000 rows or 10 MiB generated content. Supported formats are xlsx, csv, and jsonl.

POST /api/v1/tables/{table_id}/exports

Create export

Synchronous export for all, selected, search, filtered, or results scope. Larger selections return 413 export_too_large; narrow the selection or page through row reads.

Scope: rows:read

GET /api/v1/exports/{export_id}

Get export

Export metadata, status, and expiration.

Scope: rows:read

GET /api/v1/exports/{export_id}/download

Download export

Downloads the prepared export through a short-lived URL.

Scope: rows:read

Errors

Errors are JSON objects with error.code, error.message, and optional error.request_id. For 429, respect Retry-After.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "request_id": "req_..."
  }
}

401: missing or invalid Bearer token.
403: the token lacks the required scope or table access.
404: the table, row, processing run, or export does not exist for this token.
429: rate_limited; slow down and use Retry-After.
5xx: temporary service error; log request_id without the token.

Limits and pagination

GET list endpoints use cursor pagination; limit defaults to 100 and maxes at 500, with next_cursor for the next page.
Normal read requests are limited to 600/min, rows/processing polling to 300/min, mutations to 180/min, and processing start/estimate to 60/min.
Inline file sources go through backend validation and the current hard cap for the buffered upload path is 25 MB; plan limits can be lower.
Public exports are synchronous, short-lived, and limited to 10,000 rows or 10 MiB generated content; larger selections return 413 export_too_large.
For batch inserts, use Idempotency-Key or idempotency_key so retries do not create duplicate rows.
If a mutation returns committed/reload_required, the write already happened; reload rows or retry only with the same idempotency key.

Security checklist

Never paste tokens into shared chats.
Do not expose rvia tokens in browser code.
Prefer table-restricted tokens for repeated workflows.
Do not send Rowvia tokens to imported URLs.
Start processing explicitly for larger batches.