API reference / Projects & API keys
Projects & API keys scope: manage · reads: read
Projects namespace your streams and subscriptions; project API keys are pinned to their project and can never leave it.
Projects are the namespace: stream, subscription, and key names are scoped per project. API keys are created under a project and can never leave it.
GET/v1/projectsList projects with counts
Response · 200
{ "projects": [ { "name": "payments", "description": "Billing pipeline",
"streams": 2, "subscriptions": 3, "created_at": "…" } ] }POST/v1/projectsCreate a project
Request body
{ "name": "payments", "description": "Billing pipeline" }| name | Letters, digits, dot, dash, underscore. "all" and "none" are reserved |
Response · 200
{ "name": "payments", "created": true }Errors
| 400 | invalid or reserved name |
| 409 | a project named {name} already exists |
GET/v1/projects/{project}One project: its streams and subscriptions
Response · 200
{ "name": "payments", "description": "…", "created_at": "…",
"streams": [ { "name": "orders", "messages": 1204, "created_at": "…" } ],
"subscriptions": [ { "name": "billing-worker", "stream": "orders",
"paused": false, "created_at": "…" } ] }Errors
| 404 | no project named {project} |
PATCH/v1/projects/{project}Change the description (null clears it)
Request body
{ "description": "Billing pipeline v2" }Response · 200
{ "name": "payments", "description": "Billing pipeline v2" }Errors
| 400 | nothing to update; pass description |
| 404 | no project named {project} |
DELETE/v1/projects/{project}Delete an empty project
Response · 200
{ "name": "payments", "deleted": true }Errors
| 400 | the default project cannot be deleted |
| 404 | no project named {project} |
| 409 | delete this project's streams first: … |
GET/v1/projects/{project}/keysList this project's API keys (ids only — secrets are never stored)
Response · 200
{ "keys": [ { "key": "vk_b70b33563dd2…", "label": "order-service",
"created_at": "…", "created_by": "dinesh@…",
"last_used_at": "…" } ] }POST/v1/projects/{project}/keysCreate an API key — the secret is in this response and nowhere else
Request body
{ "label": "order-service" }Response · 200
{ "key": "vk_b70b33563dd28527571f4ac2",
"secret": "vs_5d2bf3063439af1a3db4…",
"project": "payments", "label": "order-service" }Errors
| 404 | no project named {project} |
DELETE/v1/projects/{project}/keys/{key}Revoke — clients using it stop working immediately
Response · 200
{ "key": "vk_…", "revoked": true }Errors
| 404 | no such key in this project |