Automations, secrets and keys API
Scheduled automations, write-only org secrets, and session-only API keys.
Scheduling and the credential surfaces. All routes are org-session scoped; secret writes require an org admin, and API-key routes are session-only. See Automations and Secrets.
Automations
The router is mounted at both /api/automations (primary) and /api/schedules
(a backward-compatible alias); the paths are identical under either prefix. A new
automation is always created disabled, so nothing auto-fires until it is
explicitly enabled.
| Method | Path | Description | Notes |
|---|---|---|---|
| GET | /api/automations |
List the org’s automations, newest first. | Returns {automations, schedules} (the same array under both keys for resumed clients). |
| POST | /api/automations |
Create an automation (created disabled). | JSON body validated by the service. 201 created object; 400 on invalid JSON. |
| PATCH | /api/automations/:id |
Update an automation (enable/disable or edit). | Partial JSON body. 200 updated object. |
| POST | /api/automations/:id/run-now |
Fire immediately: create a real run and record a manual firing. | 201 {run_id}. 404 schedule not found. |
| GET | /api/automations/:id/history |
Firing history, newest first. | {firings}. 404 schedule not found. |
| DELETE | /api/automations/:id |
Delete an automation and its firing rows. | 204. Runs from past firings remain in the durable run log. |
Secrets
Encrypted named secrets injected as env vars into the per-thread sandbox at boot. Values are write-only: they can be set and removed but are never returned. Writes require an org admin.
| Method | Path | Description | Notes |
|---|---|---|---|
| GET | /api/secrets |
List secret names and timestamps (never values). | {secrets}, metadata only. |
| PUT | /api/secrets/:name |
Upsert a secret value (encrypted at rest). | Org-admin. Body: value (required), kind (default env). Name must match ^[A-Z][A-Z0-9_]*$ and not be reserved (400 otherwise). Response echoes metadata only. |
| DELETE | /api/secrets/:name |
Delete a secret. | Org-admin. {deleted: true, name}. 404 secret not found. |
API keys
Long-lived bearer credentials for local-to-cloud run dispatch. Session auth
only: a bearer key can never mint, list, or revoke keys (403 session_required). The plaintext secret is shown once at creation; only its hash
is stored. Keys are scoped to the signing-in member.
| Method | Path | Description | Notes |
|---|---|---|---|
| POST | /api/api-keys |
Mint a key for the org, owned by the signed-in user. | Session-only. Body: name (required, at most 100 chars). 201 including the plaintext secret one time only. |
| GET | /api/api-keys |
List the member’s keys (metadata only). | Session-only. {keys}, no plaintext secrets. |
| DELETE | /api/api-keys/:id |
Revoke one of the member’s keys (soft delete). | Session-only. {revoked: true, id}. Another member’s id returns 404, not 403. |