API Overview

Authenticate with scoped API keys and call the Communa REST API from your own dashboards, scripts, and integrations.

Tip: Use the API when you want code you control — a custom dashboard, a script, or another service — to read or write data your agent manages. Generate a key in the agent's Settings → API Keys section.

Overview

The Communa API exposes your agent's resources over a small, REST-standard HTTP interface. It's authenticated with scoped API keys and follows the PostgREST/Supabase query style, so any developer — or AI model — already knows how to call it.

Under the hood the API reuses the exact same permission checks, plan limits, and validation as the agent itself, so an external integration can never do something the agent couldn't.

This page covers everything that applies to every endpoint: the base URL, authentication, scopes, response shape, errors, and key management. Each resource then has its own reference page:

Datasets API — read and write an agent's dataset rows.

More resources (runs, files, and more) will be added here over time.

Base URL

All endpoint paths are relative to the production base URL:

https://communa.io/api/v1

Quickstart

Make your first request in under a minute.

Create an API key — In the agent's Settings → API Keys, create a key with the datasets:read scope. Copy the raw key (shown once).
List your datasets to confirm it works:


curl https://communa.io/api/v1/datasets \
  -H "Authorization: Bearer $COMMUNA_API_KEY"

You should get back a list of datasets:

json
{ "data": [ { "id": "abc123", "name": "Leads", "row_count": 42 } ] }

That's it — every other endpoint follows the same auth header and base URL.

Authentication

Every request sends the key as a Bearer token:

Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxx

Keys are created in the agent's Settings → API Keys section (admin/owner only). The raw key is shown once at creation — store it safely. Each key carries one or more scopes:

Scope	Grants
`datasets:read`	List datasets, query/read rows (GET)
`datasets:write`	Insert, update, delete rows (POST / PATCH / DELETE)

⚠️ Never put the key in browser code

A key in front-end JavaScript (including VITE_-prefixed env vars) is fully visible to anyone. Always call the API from a server-side proxy that holds the key in a server environment variable:

[Browser]  →  [Your dashboard's server proxy]  →  [Communa API]
              (holds the key in env)

Locally (Vite): use server.proxy in vite.config.ts, or a tiny Node route.
On Vercel: a serverless function (e.g. /api/proxy) that forwards requests and injects the Authorization header.

The Communa-side code is identical in both cases.

Response shape

Success responses wrap the payload in data (with optional meta). Row queries return a consistent { rows, total, columns } shape, where total is the number of rows matching your query (filter/search aware):

json
{ "data": { "rows": [ ... ], "total": 42, "columns": ["name","status"] } }

A distinct query instead returns { values, total_unique, ... }.

Errors

Errors use a consistent envelope with a machine-readable code:

json
{ "error": { "message": "This API key lacks the required scope \"datasets:write\".", "code": "insufficient_scope" } }

Code	Status	Cause	Fix
(auth)	`401`	Missing, invalid, revoked, or expired key	Send a valid `Authorization: Bearer` header with an active key
`insufficient_scope`	`403`	Key lacks the required scope, or the resource is locked for that operation	Use a key with the scope the endpoint requires
`not_found`	`404`	The resource doesn't exist or isn't owned by this key's agent	Check the resource ID and that the key belongs to the right agent
`row_not_found`	`404`	The `rowId` doesn't exist in this dataset	Re-fetch row IDs from a GET query
`invalid_query`	`400`	Bad operator, out-of-range `limit`, negative `offset`, or non-integer pagination	Use valid query params (`limit` 1–1000, `offset` ≥ 0)
`invalid_row_id`	`400`	The `rowId` in the path is not a valid UUID	Pass a UUID from a row's `id` field

Managing & revoking keys

In Settings → API Keys you can see each key's prefix, scopes, last-used time, and request count, and revoke a key instantly. A revoked key is rejected on the very next request.

What's Next?

Datasets API — The full endpoint reference for reading and writing dataset rows
Credentials — Secrets your agent uses to log into services

Agent Settings

Datasets API