The LightHouse API

The LightHouse API is the HTTP interface to everything LightHouse shows: agents, runs, usage and cost, evidence, knowledge bases, approvals, limits, access and keys. The portal uses it too: what you see in LightHouse is what the API returns.

The tenant host and base path

Every request goes to your tenant’s own host:

https://<tenant id>.atlanticagenticlabs.com/api/v1/...

The tenant comes from the hostname and nothing else. Every request is authenticated (see Authentication) and every query runs under your tenant’s row-level security scope.

A first request

curl

curl -s "https://$AAL_TENANT.atlanticagenticlabs.com/api/v1/runs?limit=5" \
  -H "Authorization: Bearer $AAL_KEY" \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

Python

import os

import httpx

client = httpx.Client(
    base_url=f"https://{os.environ['AAL_TENANT']}.atlanticagenticlabs.com/api/v1",
    headers={
        "Authorization": f"Bearer {os.environ['AAL_KEY']}",
        "CF-Access-Client-Id": os.environ["CF_ACCESS_CLIENT_ID"],
        "CF-Access-Client-Secret": os.environ["CF_ACCESS_CLIENT_SECRET"],
    },
)
r = client.get("/runs", params={"limit": 5})
r.raise_for_status()
for run in r.json()["runs"]:
    print(run["started_at"], f"{run['pack']}:{run['card']}", run["status"])

TypeScript

const base = `https://${process.env.AAL_TENANT}.atlanticagenticlabs.com/api/v1`;
const headers = {
  Authorization: `Bearer ${process.env.AAL_KEY}`,
  "CF-Access-Client-Id": process.env.CF_ACCESS_CLIENT_ID!,
  "CF-Access-Client-Secret": process.env.CF_ACCESS_CLIENT_SECRET!,
};
const res = await fetch(`${base}/runs?limit=5`, { headers });
if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).error}`);
const { runs } = await res.json();
for (const run of runs) console.log(run.started_at, `${run.pack}:${run.card}`, run.status);

The answer is {"runs": [...], "next": "<cursor or null>"}. See Pagination.

Conventions

• JSON in and out. A write’s body is a JSON object.
• Timestamps are RFC 3339, in UTC. Query parameters such as since and until take the same.
• Money is in the provider’s own currency, with a *_usd figure beside it. Reads of money also give *_money figures in the caller’s display currency, set under Settings → Preferences.
• Identifiers: an agent is <pack>:<card>; a run is its run_id_hash. See Agents and Runs.
• Counts, never content. Apart from the content routes, which read in place from your deployment and need content_viewer, no answer carries prompt, answer or document text.
• Refusals are {"error": "<code>", "message": "..."} with a fixed code, and Cache-Control: no-store. See Errors.
• People-only routes: anything that approves, decides, pays, changes a limit or changes access refuses a machine key (403 person_required or role_required). See Authentication.

The reference

The API reference is generated from LightHouse’s own OpenAPI document, so it cannot drift from the service. Download it: openapi.json. The same reads are available as MCP tools.