API Reference

This reference documents the JSON endpoints exposed by the AgentSecrets backend API.

Endpoint Index

Group	Method	Endpoint	Description	Auth Required
System	`GET`	`/api/status/`	Full diagnostic status (Database, Encryption, Cache)	No
	`GET`	`/api/status/health/`	Lightweight health check alias for probes	No
Auth	`POST`	`/api/auth/register/`	Register a new user	No
	`POST`	`/api/auth/login/`	User login (returns access/refresh JWT)	No
	`POST`	`/api/auth/refresh/`	Refresh expired access JWT	No
	`GET`	`/api/users/{email}/public-key/`	Retrieve user public key for asymmetric key wrapping	Yes
Secrets	`GET`	`/api/secrets/{project_id}/`	List encrypted secret keys & metadata	Yes
	`GET`	`/api/secrets/{project_id}/{key}/`	Retrieve specific secret ciphertext blob	Yes
	`POST`	`/api/secrets/`	Bulk upsert client-encrypted secrets	Yes
	`DELETE`	`/api/secrets/{project_id}/{key}/`	Delete a specific secret	Yes
Workspaces	`GET`	`/api/workspaces/`	List workspaces	Yes
	`POST`	`/api/workspaces/`	Create a workspace	Yes
	`GET`	`/api/workspaces/{workspace_id}/members/`	List workspace members	Yes
	`POST`	`/api/workspaces/{workspace_id}/members/`	Invite workspace member(s) with wrapped keys	Yes (Admin)
	`DELETE`	`/api/workspaces/{workspace_id}/members/{user_id}/`	Remove member access	Yes (Admin)
	`GET`	`/api/workspaces/{workspace_id}/allowlist/`	Get domain allowlist	Yes
	`POST`	`/api/workspaces/{workspace_id}/allowlist/`	Add domain(s) to allowlist	Yes (Admin)
	`DELETE`	`/api/workspaces/{workspace_id}/allowlist/{domain}/`	Remove domain from allowlist	Yes (Admin)
Projects	`GET`	`/api/projects/`	List projects in workspace	Yes
	`POST`	`/api/projects/`	Create a project	Yes
Agents	`GET`	`/api/workspaces/{workspace_id}/agents/`	List registered agent identities	Yes
	`POST`	`/api/workspaces/{workspace_id}/agents/`	Register an agent identity	Yes
	`POST`	`/api/workspaces/{workspace_id}/agents/{agent_id}/tokens/`	Issue a cryptographic agent token	Yes
Telemetry	`POST`	`/telemetry/sync/`	Ingest batched 24-hour CLI telemetry snapshots	Optional
	`GET`	`/telemetry/metrics/`	Public platform analytics & adoption metrics	No
	`POST`	`/telemetry/internal/compute-metrics/`	Trigger daily rollup calculation	Bearer (`CRON_SECRET`)

Error Handling

On error, the API returns a structured JSON payload with the appropriate HTTP status code:

{
  "status": "failure",
  "code": "error_code_identifier",
  "message": "Detailed error message explanation"
}

Common Status Codes:

400 Bad Request: Missing parameters, malformed JSON, or validation failure.
401 Unauthorized: Missing, expired, or invalid authorization credentials.
403 Forbidden: Authenticated, but lacking sufficient permissions (e.g. Member trying to perform Admin-only invite).
404 Not Found: The requested resource (workspace, project, user, environment) does not exist.
429 Too Many Requests: Triggered by rate-limiting rules.