REST API

REST API für Rowvia-Tabellen und Automatisierungen

Verwenden Sie die REST API, wenn Sie Rowvia aus einem eigenen Backend, geplanten Job oder interner Automatisierung anbinden. Der ChatGPT Connector nutzt Rowvia OAuth; die REST API nutzt ein rvia_ Token im Authorization Header.

App öffnen API-Konsole öffnen OpenAPI JSON MCP-Dokumentation
Erste Automatisierung

Mit einer Tabelle in der App starten, dann die REST API nutzen

Profile -> Integrations ist noch keine öffentliche Deep-Link-Route. Öffnen Sie nach der Anmeldung das Profil, gehen Sie zu Integrations und erstellen Sie ein Token für eine konkrete Tabelle oder das Konto.

  1. Erstellen Sie in der App eine Tabelle und wählen Sie eine Vorlage.
  2. Erstellen Sie in Profile -> Integrations ein API-Token mit den benötigten Scopes.
  3. Fügen Sie URL oder Text per REST API zur bestehenden Tabelle hinzu.
  4. Starten Sie Processing explizit und verfolgen Sie den Zeilenstatus.
  5. Lesen Sie Ergebnisse aus und prüfen Sie Zellen gegen die Quellen.
Overview

Wann die REST API passt

Die REST API arbeitet mit denselben vorhandenen Tabellen wie die App. Sie ist für serverseitige Integrationen gedacht: URL, Text oder Inline-Datei als Zeile hinzufügen, Processing starten, Lauf verfolgen, Ergebnisse lesen und Daten exportieren. Der Standard-Add-Flow ist eine Hauptquelle als eine neue Zeile; beim Lesen können erweiterte Zeilen das primäre `document` und `documents[]` mit zugehörigen Anhängen zurückgeben. In seltenen Fällen kann row-add 202 mit committed=true und reload_required=true zurückgeben; der Schreibvorgang war erfolgreich, aber der Client sollte vor anschließendem Processing die Zeilen neu laden. Für KI-Agenten in ChatGPT oder lokalen MCP-Clients nutzen Sie die MCP-Dokumentation.

Base URL

https://api.rowvia.ai

Authorization: Bearer rvia_...

Auth

Authentication

Erstellen Sie ein API-Token in Rowvia Profil -> Integrationen und senden Sie es als Authorization: Bearer rvia_.... Das Token gehört in serverseitige Konfiguration oder einen Secret Manager, nicht in Browser-Code, Prompts, geteilte Chats oder URLs.

tables:read

Tabellenliste, Tabellendetail, Schema, Summary und Pending-Work-Metriken.

rows:read

Zeilen, Ergebnisse, Suche und Exporte lesen.

row:add

Neue Zeilen aus url-, text- oder file-Quellen hinzufügen.

row:process

Processing schätzen, Läufe starten, Status lesen und Läufe abbrechen.

rows:update

Manuelle Zellkorrektur über PATCH; nur hinzufügen, wenn die Integration es wirklich braucht.

Token-Sicherheit

  • Ein rvia_ Token niemals in geteilte Chats, Prompts oder Dokumente einfügen.
  • Das Token gehört nicht in Browser-Frontends, öffentliches JavaScript oder Client-Bundles.
  • Tokens nicht in URLs, Query-Parametern oder importierten Links senden.
  • Für wiederkehrende Workflows ein auf eine Tabelle beschränktes Token bevorzugen.
  • Größere Processing-Läufe erst nach Bestätigung der Zieltabelle und Pending-Work-Schätzung starten.
  • request_id oder processing_run_id loggen, niemals das vollständige Token.
Quickstart

Quickstart

Alle Beispiele verwenden die Production Base URL und echte Endpunkte aus /api/v1. Bei größeren Batches zuerst Estimate ausführen und Mutationen mit Idempotency-Key wiederholen. `POST /rows` erstellt neue Zeilen im Standardmodell eine Hauptquelle = eine Zeile; vorhandene erweiterte Zeilen mit `include_document` lesen, wenn primäres Dokument und Anhänge gebraucht werden. Wenn row-add 202 committed/reload_required zurückgibt, denselben Idempotency-Key wiederverwenden oder Zeilen neu laden, statt mit neuem Key zu wiederholen.

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

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 und Identität

Diese Endpunkte helfen, den API-Vertrag zu finden und ein Token zu prüfen. OpenAPI und Konsole sind öffentlich; Arbeitsendpunkte unter /api/v1 benötigen ein Rowvia API-Token.

GET /api/v1/openapi.json

OpenAPI contract

Maschinenlesbare Beschreibung der implementierten REST API.

Scope: public
GET /api/v1/docs

API console

Noindex-Konsole, die das Bearer-Token nur im Speicher des Browser-Tabs hält.

Scope: public
GET /api/v1/me

Current token identity

Prüft Benutzer und Einschränkungen, denen das Token zugeordnet ist.

Scope: API token
Tables

Tables

Die öffentliche API arbeitet mit vorhandenen Rowvia-Tabellen. Die Table ID entspricht der Sheet ID, zum Beispiel sheet_....

GET /api/v1/tables

List tables

Listet Tabellen, die für das Token verfügbar sind.

Scope: tables:read
GET /api/v1/tables/{table_id}

Get table

Details einer Tabelle inklusive Workbook und Zeilenzahl.

Scope: tables:read
GET /api/v1/tables/{table_id}/schema

Get schema

Spalten, Prompts und optionale Systemspalten über include_system_columns.

Scope: tables:read
GET /api/v1/tables/{table_id}/summary

Get summary

Tabellenzusammenfassung zur Entscheidung, was verarbeitet werden soll.

Scope: tables:read
GET /api/v1/tables/{table_id}/pending-work

Pending work

Schätzung leerer Output-Zellen, die für Processing bereit sind.

Scope: row:process
Rows

Rows und sources

Zeilen können paginiert, gesucht, aus Quellen hinzugefügt und optional korrigiert werden. source kann url, text oder file mit data_base64 sein. Standardimporte erstellen eine Zeile pro Hauptquelle; erweiterte Zeilen können beim Lesen `documents[]` für Hauptquelle und zugehörige Anhänge enthalten.

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

List rows

Cursor Pagination über limit und cursor; unterstützt column_ids, include_system_columns und results_only.

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

Add rows

Fügt documents[] aus source=url, source=text oder source=file hinzu; jedes Element erstellt standardmäßig eine neue Zeile mit Hauptquelle und process_after_add ist standardmäßig false. Bei 202 committed/reload_required die Tabelle neu laden, weil row_id Werte eventuell noch nicht sicher verfügbar sind.

Scope: row:add
POST /api/v1/tables/{table_id}/rows/read

Read selected rows

Bulk-Lesen ausgewählter row_ids mit Spaltenprojektion.

Scope: rows:read
GET /api/v1/tables/{table_id}/rows/search

Search rows

Durchsucht Zeilen mit query, statuses, row_filters und cursor.

Scope: rows:read
GET /api/v1/tables/{table_id}/rows/{row_id}

Get row

Details einer Zeile; include_document ergänzt legacy `document` für die Primary-Quelle und `documents[]` für das gesamte Source-Set inklusive Anhängen, wenn verfügbar.

Scope: rows:read
GET /api/v1/tables/{table_id}/rows/{row_id}/results

Get row results

Nur Ergebniszellen einer Zeile.

Scope: rows:read
PATCH /api/v1/tables/{table_id}/rows/{row_id}/cells

Update cells

Manuelle Zellkorrektur; erfordert den expliziten Scope rows:update.

Scope: rows:update
Processing

Processing

Processing ausdrücklich starten, besonders bei größeren Batches. Eine leere Output-Zelle ist verarbeitbar; eine nicht leere Output-Zelle wird normalerweise übersprungen.

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

Estimate processing

Schätzt Zeilen, Zellen und Processing Units vor dem Start.

Scope: row:process
POST /api/v1/tables/{table_id}/processing/runs

Start processing run

Startet einen pending- oder selected_rows-Lauf; unterstützt Idempotency Keys.

Scope: row:process
GET /api/v1/processing/runs/{processing_run_id}

Get processing run

Status, Task-Zahlen, PU und mögliche Fehler.

Scope: row:process
POST /api/v1/processing/runs/{processing_run_id}/cancel

Cancel processing run

Fordert Abbruch eines laufenden Processing Runs an.

Scope: row:process
Exports

Exports

Exporte verwenden rows:read und geben eine kurzlebige Download URL zurück. Öffentliche Exporte sind synchron und auf 10,000 Zeilen oder 10 MiB Ergebnisinhalt begrenzt. Unterstützte Formate sind xlsx, csv und jsonl.

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

Create export

Synchroner Export für all, selected, search, filtered oder results scope. Größere Auswahlen geben 413 export_too_large zurück; Auswahl eingrenzen oder Zeilen paginiert lesen.

Scope: rows:read
GET /api/v1/exports/{export_id}

Get export

Export-Metadaten, Status und Ablaufzeit.

Scope: rows:read
GET /api/v1/exports/{export_id}/download

Download export

Lädt den vorbereiteten Export über eine kurzlebige URL.

Scope: rows:read

Errors

Fehler sind JSON-Objekte mit error.code, error.message und optional error.request_id. Bei 429 Retry-After beachten.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "request_id": "req_..."
  }
}
  • 401: Bearer-Token fehlt oder ist ungültig.
  • 403: dem Token fehlt der erforderliche Scope oder Tabellenzugriff.
  • 404: Tabelle, Zeile, Processing Run oder Export existiert für dieses Token nicht.
  • 429: rate_limited; langsamer senden und Retry-After verwenden.
  • 5xx: temporärer Servicefehler; request_id ohne Token loggen.

Limits und pagination

  • GET-Listenendpunkte verwenden Cursor Pagination; limit ist standardmäßig 100 und maximal 500, die nächste Seite steht in next_cursor.
  • Normale Read Requests sind auf 600/min begrenzt, Rows/Processing-Polling auf 300/min, Mutationen auf 180/min und Processing Start/Estimate auf 60/min.
  • Inline file sources laufen durch Backend-Validierung und der aktuelle Hard Cap des gepufferten Upload-Pfads ist 25 MB; Planlimits können niedriger sein.
  • Öffentliche Exporte sind synchron, kurzlebig und auf 10,000 Zeilen oder 10 MiB Ergebnisinhalt begrenzt; größere Auswahlen geben 413 export_too_large zurück.
  • Für Batch-Inserts Idempotency-Key oder idempotency_key verwenden, damit Wiederholungen keine doppelten Zeilen erzeugen.
  • Wenn eine Mutation committed/reload_required zurückgibt, ist der Schreibvorgang bereits passiert; Zeilen neu laden oder nur mit demselben Idempotency-Key wiederholen.

Security checklist

  • Tokens niemals in geteilte Chats einfügen.
  • rvia Tokens nicht in Browser-Code offenlegen.
  • Für wiederkehrende Workflows tabellenbeschränkte Tokens bevorzugen.
  • Rowvia Tokens nicht an importierte URLs senden.
  • Processing für größere Batches ausdrücklich starten.