API Reference
REST API endpoints, request parameters, and response shapes
Public HTTP API for WyrdOS. Authenticate with a Bearer API key.
Use these pages when you need scriptable access to WyrdOS state. The API is useful for internal tools, CI jobs, data import/export, and agent integrations that need stable JSON contracts.
Base URL
Use the base URL for your deployment, then append the documented /api/v1/... path.
| Deployment | Base URL |
|---|---|
| Hosted API proxy | https://<your-wyrdos-api-host> |
| Direct Convex HTTP endpoint | https://<your-deployment>.convex.site |
| Local proxy | http://localhost:3001 |
Authentication
Create API keys in Settings > API Keys. Keys are scoped to a workspace and carry explicit read, write, and delete permissions. Treat them like passwords.
Authorization: Bearer <API_KEY>Smoke test a key before using resource endpoints:
curl -H "Authorization: Bearer <API_KEY>" \
"https://<your-wyrdos-api-host>/api/v1/organisations"Response contract
Successful list, get, create, and update calls return 200 OK with a data wrapper. Delete calls return 204 No Content.
{
"data": []
}Common errors:
| Status | Meaning |
|---|---|
| 400 | Request body or query is invalid. |
| 401 | API key is missing or invalid. |
| 403 | API key is valid but lacks permission for the resource. |
| 404 | Resource does not exist or is not visible to the key. |
| 500 | Server error. Retry only after checking request shape and service status. |
Resources
- Organisations
- Engines
- Containers
- Zones
- Actions
- Pages
- Stacks
- Rolodex
- Funding
- Ontology
- Evidence
- Evidence Proposals
Evidence workflow
External agents should usually create evidence proposals, not accepted evidence. See Evidence workflow for review-context, proposal, approval, and rejection patterns.
Example workflow
For a copy-ready sequence that creates a small traceable operating graph, see Create a traceable workflow.
All rights reserved.