dna api¶
Expose the live DNA (definitions + memory) over a REST read-API.
Generated from the command definitions
This page is introspected from the dna Click command tree by
scripts/gen_cli_docs.py, so it stays in lockstep with
dna api --help.
dna api serve¶
Run the DNA REST read-API (the WEB face — a request/response HTTP API).
LOCAL (no auth): $ dna api serve --port 8080 --auth none $ curl -s localhost:8080/v1/agents
ENDPOINTS (read-focused; tenant-aware via a tenant query param):
GET /health -> {ok:true}
GET /v1/agents?scope=&tenant= -> {scope, agents:[...]}
GET /v1/agents/{name}/prompt?scope=&tenant= -> {scope, agent, prompt, ...}
GET /v1/tools?scope=&tenant= -> {scope, tools:[...]}
GET /v1/memories?scope=&tenant= -> {memories:[...]}
GET /v1/memories/search?q=&scope=&tenant=&k=5 -> {query, hits:[...]}
DELETE /v1/memories/{name}?scope=&tenant= -> delete from the tenant's OWN overlay
GET /v1/sources?scope=&tenant= -> {sources:[...]}
GET /v1/insights?scope=&tenant=&state=&source= -> {insights:[...]}
GET /v1/orgs?tenant= -> {orgs:[...]}
GET /v1/projects?tenant= -> {projects:[...]}
GET /v1/projects/{slug}?tenant= -> {project, repos:[...]}
GET /v1/projects/{slug}/members?tenant=&viewer= -> {members:[...], viewer}
POST /v1/projects/{slug}/members?tenant= -> invite/set-role {user, role, actor} (RBAC)
DELETE /v1/projects/{slug}/members/{user}?tenant=&actor= -> remove (RBAC)
GET /v1/repos?tenant= -> {repos:[...]}
GET /v1/board?scope=&tenant= -> {counts, totals, recent}
PUT /v1/account-plan -> billing->runtime AccountPlan write {account_id, tier_id, ...}
POST /v1/tenants/{tid}/provision-owner -> first-login Owner bootstrap {user} (idempotent)
POST /v1/workspaces/{id}/provision-owner -> Model B first-login owner bootstrap {claims} (idempotent, id==tid)
POST /v1/workspaces/{id}/invites -> invite by email {email, role, actor} (Owner/Admin)
GET /v1/workspaces/{id}/members -> list members (Owner/Admin)
POST /v1/workspaces/{id}/members/revoke -> remove a member {target_email|target_oid, actor} (last-owner protected)
POST /v1/workspaces/accept -> accept pending invites {claims} (verified sign-in)
Every endpoint reads/writes through the SAME live kernel dna commands +
dna mcp serve use — this is a second HTTP face over one core, not a copy.
Options
| Option | Description |
|---|---|
--auth |
Auth mode. none = local dev (no bearer). token = require Authorization: Bearer <DNA_API_TOKEN> on every route (the MVP shared token). config = the Model B verified-identity path — a bearer JWT verified by the N-provider layer (dna.config.yaml auth.providers[]), then the effective workspace BOUND from the identity's WorkspaceMembership (the tenant param is overwritten from membership, never trusted from the caller). (default: none) |
--base-dir |
Source directory override (else DNA_SOURCE_URL / DNA_BASE_DIR / ./.dna). |
--cors-origin |
Allowed browser origin for CORS (repeatable; else DNA_API_CORS_ORIGINS, else http://localhost:3000). |
--help |
Show this message and exit. |
--host |
Bind host. (default: 127.0.0.1) |
--port |
Bind port. (default: 8080) |
--scope |
Default scope for endpoints that omit one (else the sole/first scope). |
--token |
Expected bearer token for --auth token (else the DNA_API_TOKEN env var). |
--token-scope |
A scope this credential may read when the request resolves NO workspace (repeatable; else the DNA_TOKEN_SCOPES env var, comma-separated). Absent, such a caller is bound to the ONE scope this server was booted on — absence of a workspace is not a right to every scope. Pass * to consciously opt out. |