REST API

REST API pro Rowvia tabulky a automatizace

Použijte REST API, když chcete Rowvia napojit z vlastního backendu, plánovaného jobu nebo interní automatizace. ChatGPT connector používá Rowvia OAuth; REST API používá rvia_ token v hlavičce Authorization.

Otevřít aplikaci Otevřít API konzoli OpenAPI JSON MCP dokumentace
První automatizace

Začněte tabulkou v aplikaci, potom volejte REST API

Přímý deep-link do Profile -> Integrations zatím není veřejná route. Po přihlášení otevřete profil, přejděte na Integrations a vytvořte token až pro konkrétní tabulku nebo účet.

  1. V aplikaci vytvořte tabulku a vyberte šablonu.
  2. V Profile -> Integrations vytvořte API token s potřebnými scopes.
  3. Přidejte URL nebo text přes REST API do existující tabulky.
  4. Spusťte processing výslovně a sledujte stav řádků.
  5. Přečtěte výsledky a zkontrolujte buňky proti zdrojům.
Overview

Kdy použít REST API

REST API pracuje se stejnými existujícími tabulkami jako aplikace. Hodí se pro server-side integrace: přidat URL, text nebo inline soubor jako řádek, spustit processing, sledovat běh, přečíst výsledky a exportovat data. Výchozí add flow je jeden hlavní zdroj jako jeden nový řádek; při čtení mohou rozšířené řádky vracet primary `document` i `documents[]` se souvisejícími přílohami. Row-add může ve výjimečné situaci vrátit 202 s committed=true a reload_required=true; zápis proběhl, ale klient má před navazujícím processingem znovu načíst řádky. Pro AI agenty v ChatGPT nebo lokálních MCP klientech použijte MCP dokumentaci.

Base URL

https://api.rowvia.ai

Authorization: Bearer rvia_...

Auth

Authentication

Vytvořte API token v Rowvia Profil -> Integrace a posílejte ho jako Authorization: Bearer rvia_.... Token patří do server-side konfigurace nebo secret manageru, ne do browser kódu, promptu, sdíleného chatu ani URL.

tables:read

Vypsání tabulek, detail tabulky, schema, summary a metriky pending work.

rows:read

Čtení řádků, výsledků, search a exportů.

row:add

Přidání nových řádků ze zdrojů url, text nebo file.

row:process

Odhad processingu, spuštění běhu, status a cancel.

rows:update

Ruční korekce buněk přes PATCH; přidávejte jen pokud ji integrace opravdu potřebuje.

Bezpečnost tokenů

  • Nikdy nevkládejte rvia_ token do sdíleného chatu, promptu ani dokumentu.
  • Token nepatří do browser frontendu, veřejného JavaScriptu ani klientského balíčku.
  • Token neposílejte v URL, query parametrech ani importovaných odkazech.
  • Pro opakované workflow preferujte token omezený na konkrétní tabulku.
  • Větší processing spouštějte až po potvrzení cílové tabulky a odhadu pending práce.
  • Do logů ukládejte request_id nebo processing_run_id, nikdy celý token.
Quickstart

Quickstart

Všechny příklady používají produkční base URL a skutečné endpointy implementované v /api/v1. Před větší dávkou nejdřív spusťte estimate a mutace opakujte s Idempotency-Key. `POST /rows` vytváří nové řádky standardně 1 hlavní zdroj = 1 řádek; existující rozšířené řádky čtěte s `include_document`, pokud potřebujete primary dokument i přílohy. Pokud row-add vrátí 202 committed/reload_required, použijte stejný idempotency key nebo znovu načtěte řádky místo opakování s novým klíčem.

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 a identita

Tyto endpointy pomáhají najít kontrakt API a ověřit token. OpenAPI a konzole jsou veřejné, pracovní endpointy pod /api/v1 vyžadují Rowvia API token.

GET /api/v1/openapi.json

OpenAPI contract

Strojově čitelný popis implementovaného REST API.

Scope: public
GET /api/v1/docs

API console

Noindex konzole, která drží Bearer token jen v paměti browser tabu.

Scope: public
GET /api/v1/me

Current token identity

Ověření, ke kterému uživateli a omezení se token vztahuje.

Scope: API token
Tables

Tables

Veřejné API pracuje s existujícími Rowvia tabulkami. Table ID odpovídá sheet ID, například sheet_....

GET /api/v1/tables

List tables

Vypsání dostupných tabulek pro token.

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

Get table

Detail jedné tabulky, včetně workbooku a počtů řádků.

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

Get schema

Sloupce, prompty a volitelné system columns přes include_system_columns.

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

Get summary

Souhrn tabulky pro rychlé rozhodnutí, co zpracovávat.

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

Pending work

Odhad prázdných output buněk vhodných pro další processing.

Scope: row:process
Rows

Rows a sources

Řádky lze číst po stránkách, hledat, přidávat ze zdrojů a volitelně korigovat buňky. Zdroj source může být url, text nebo file s data_base64. Standardní import vytváří jeden řádek na každý hlavní zdroj; rozšířené řádky mohou při čtení obsahovat `documents[]` pro primary zdroj i související přílohy.

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

List rows

Cursor pagination přes limit a cursor; podporuje column_ids, include_system_columns a results_only.

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

Add rows

Přidání documents[] ze source=url, source=text nebo source=file; každá položka standardně vytvoří nový řádek s hlavním zdrojem a process_after_add je defaultně false. Při 202 committed/reload_required znovu načtěte tabulku, protože row_id nemusí být bezpečně dostupné.

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

Read selected rows

Bulk čtení vybraných row_ids s projekcí sloupců.

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

Search rows

Vyhledání v řádcích přes query, statuses, row_filters a cursor.

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

Get row

Detail jednoho řádku; include_document přidá legacy `document` pro primary zdroj a `documents[]` pro celý source set včetně příloh, pokud jsou dostupné.

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

Get row results

Pouze výsledkové buňky pro jeden řádek.

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

Update cells

Ruční korekce buněk; vyžaduje explicitní rows:update scope.

Scope: rows:update
Processing

Processing

Processing spouštějte výslovně, zvlášť pro větší dávky. Prázdná output buňka je processable, neprázdná output buňka se běžně přeskakuje.

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

Estimate processing

Odhad řádků, buněk a processing units před spuštěním.

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

Start processing run

Spuštění pending nebo selected_rows běhu; podporuje idempotency key.

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

Get processing run

Status, počty tasků, PU a případné errors.

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

Cancel processing run

Požádá o zrušení běžícího processing runu.

Scope: row:process
Exports

Exports

Exporty používají rows:read scope a vrací krátkodobý download URL. Veřejné exporty jsou synchronní a mají limit 10,000 řádků nebo 10 MiB výsledku. Podporované formáty jsou xlsx, csv a jsonl.

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

Create export

Synchronní export all, selected, search, filtered nebo results scope. Větší výběry vrátí 413 export_too_large; použijte užší výběr nebo stránkované čtení řádků.

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

Get export

Metadata exportu, status a expirace.

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

Download export

Stažení připraveného exportu přes krátkodobou URL.

Scope: rows:read

Errors

Chyby jsou JSON objekt s error.code, error.message a volitelným error.request_id. Pro 429 respektujte Retry-After.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "request_id": "req_..."
  }
}
  • 401: chybí nebo je neplatný Bearer token.
  • 403: token nemá potřebný scope nebo přístup k tabulce.
  • 404: tabulka, řádek, processing run nebo export neexistuje pro daný token.
  • 429: rate_limited; zpomalte a použijte Retry-After.
  • 5xx: dočasná chyba služby; logujte request_id bez tokenu.

Limits a pagination

  • GET list endpointy používají cursor pagination; limit má default 100 a maximum 500, další stránka je v next_cursor.
  • Běžné read requesty mají limit 600/min, polling rows/processing 300/min, mutace 180/min a processing start/estimate 60/min.
  • Inline file source pro REST API prochází backend validací a aktuální hard cap bufferované upload cesty je 25 MB; plánové limity mohou být nižší.
  • Veřejné exporty jsou synchronní, krátkodobé a omezené na 10,000 řádků nebo 10 MiB výsledku; větší výběr vrací 413 export_too_large.
  • Pro dávkové přidávání používejte Idempotency-Key nebo idempotency_key, aby opakování requestu nevytvořilo duplicitní řádky.
  • Pokud mutace vrátí committed/reload_required, zápis už proběhl; znovu načtěte řádky nebo opakujte jen se stejným 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.