Getting started

Overview

The Loam API lets you query your data, manage Namespaces and permissions, and integrate AI tools programmatically. Use the regional data-plane URL returned for your workspace, such as https://rw-us-east1.api.loamdata.com. Query and management endpoints include the workspace public ID in their path and require a short-lived Bearer JWT. API-key exchange uses that same workspace path; anonymous public endpoints are the exception.

Quick start

1. Create an API key

In the Loam web app, go to Settings > API keys and click Create key. Give it a name, choose the resource UUIDs and Viewer, Editor, or Admin access it needs, and copy the key secret. You will not be able to see it again.

API keys are api_key authenticators bound to one human or Agent principal. They are managed through the workspace's regional /v1/workspaces/{workspacePublicId}/credentials surface. Optional node rules and capability ceilings can only narrow that principal's live authority. The key secret and exchanged JWT contain no grant state, and the human who creates an Agent-bound key is retained as audit provenance rather than added to the Agent's access.

2. Exchange the key secret for a JWT

API key secrets cannot be used directly against query endpoints. Exchange your secret for a short-lived JWT (15 minutes):

curl -X POST https://rw-us-east1.api.loamdata.com/v1/workspaces/rw-us-east1-ws-0195a3c47d3e7ab18c4f123456789abc/token/exchange \
  -H "Content-Type: application/json" \
  -d '{"token": "loam_your_api_key_secret_here"}'

Response:

{
  "jwt": "eyJhbGciOiJSUzI1NiIs...",
  "workspaceId": "rw-us-east1-ws-0195a3c47d3e7ab18c4f123456789abc",
  "dataPlaneUrl": "https://rw-us-east1.api.loamdata.com",
  "expiresAt": "2026-03-16T12:15:00Z"
}

3. Make your first query

Use the returned dataPlaneUrl as the base URL and the JWT as a Bearer token. SQL relation paths are absolute from the workspace root and can contain any supported number of Namespace components.

curl -X POST https://rw-us-east1.api.loamdata.com/v1/workspaces/rw-us-east1-ws-0195a3c47d3e7ab18c4f123456789abc/query \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM commerce.sales.production.charges LIMIT 10", "format": "json"}'

Try it live

{
  "sql": "SELECT 1 AS hello",
  "format": "json"
}

[
  { "hello": 1 }
]

Next steps

• Authentication: JWT lifecycle, auto-refresh, and TypeScript examples
• Query API: SQL dialect, response formats, and error handling
• Namespaces & Tables: recursively list and inspect your data
• Grants & Permissions: control who can access what