API & Platform

REST API, SDKs & integration surfaces

Every capability the platform offers is reachable three ways: the /v1 REST API, the lace-app-sdk (Python), and the event/hook surfaces the platform operates.

The REST API — `/v1`

Base URL: https://api.laceplatform.com (or http://localhost:8000 in dev). Auth: Authorization: Bearer <api_key> (API key scoped to a tenant; see authentication). All routes are tenant-scoped — the tenant is derived from the principal, not from a request parameter you can spoof.

terminalbash

curl https://api.laceplatform.com/v1/enterprise-search \
  -H "Authorization: Bearer $LACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Q3 warranty reserves","limit":10,"rerank":true}' | jq

Group	Example routes	What it owns
Auth	`POST /v1/auth/login`, `GET /v1/auth/whoami`	Session + principal
Apps	`POST /v1/apps`, `GET /v1/apps/{id}`, `GET /v1/apps/{id}/git-credential`	Lifecycle, releases, sidecar
App data	`GET /v1/apps/{id}/collections/{coll}/records`	Typed collections + blobs
Datasets	`POST /v1/datasets`, `POST /v1/datasets/{id}/sync`	Connectors, sync, permissions snapshots
Search	`POST /v1/enterprise-search`, `POST /v1/search`	Enterprise search & RAG retrieval
Knowledge graph	`POST /v1/kg/query`, `POST /v1/kg/assertions`	Entities, assertions, evidence
Pipelines	`POST /v1/pipelines/{id}/runs`	Workflow execution
Agents	`POST /v1/agents/{id}/sessions`	Sessions, tasks, control plane
Builder	`POST /v1/builder/sessions`	App Builder architect sessions

Conventions: JSON everywhere, paginated lists with limit/offset (or cursor where noted), stable error shape {"detail": "...", "code": "..."}, and OpenAPI at /openapi.json in dev. Read src/lace/api/routes/ (159 files, ~713 paths) for the full inventory.

SDKs we ship

SDK	Package	For	Import / install
lace-app-sdk (Python)	`lace-app-sdk` on PyPI	App authors — the only supported surface for apps	`pip install lace-app-sdk` → `from lace_app_sdk.data import AppDataService`
lace-runtime (Python)	internal (`src/lace_runtime`)	Sidecar server — you don't install this, the platform runs it	`from lace_runtime.tool_host import ...` (inside sidecar only)
lace CLI	entry point `lace-app` in the SDK wheel	Local dev, CI, operator tasks	`lace-app --help` — see CLI reference
Frontend SDK	JS/TS in `frontend/`	Internal app shell + generated runtime UI	Module Federation remote — apps expose `./RuntimeView`
OpenAPI client	generated from `/openapi.json`	Any language	`npx openapi-generator-cli ...` against dev spec

pythonAppData query via SDK vs raw REST

from lace_app_sdk.data import AppDataService, AppDataQueryRequest

svc = AppDataService(app_state=state)
page = svc.list_records("acme.field_intake", "tickets",
                         AppDataQueryRequest(search="warranty", limit=20))

Other integration surfaces

Surface	What it is
Webhooks	Outbound HTTP on dataset sync, pipeline run, agent task, and release events. HMAC-signed.
Event bus (NATS)	Internal pub/sub for ingest and KG events — not a public contract today; webhooks are the stable outbound surface.
MCP	Builder and assistant expose Model Context Protocol tools for workspace and platform operations.
Sidecar HTTP	Your app's own routes at `/apps/<app_id>/api/*` + `/ui/manifest.json` — see routes & UI.

Versioning & pagination

API is versioned by path prefix (/v1). Breaking changes bump the prefix; additive changes don't.
SDK is semver — breaking a published lace_app_sdk symbol is a major bump with a deprecation window.
Lists paginate with limit (default 20) + offset or cursor; responses include total where stable.

Errors

Errors are JSON: {"detail": "human message", "code": "app_data_unique_constraint_failed"}. Constraint violations (unique, foreign) surface as HTTP 409; permission failures as 403 — not 404 — so callers can distinguish "not found" from "not allowed."

Next: authentication & tenancy or CLI reference.