API reference

Oruoma is API-first. The dashboard, SDK, and custom integrations should all consume the same workspace API surface instead of bypassing the service layer.

This page is a practical endpoint map for builders. Exact response payloads may evolve, but these resource groups and safety rules are the stable contract.

URL structure

Workspace routes are scoped by workspace id:

/api/ws/{workspace_id}/...

Platform/control routes are intentionally separate:

/api/platform/...
/api/workspaces
/api/me

If an integration is operating on tenant data, prefer the workspace route. Avoid control-account routes for automation unless you are building platform administration features.

Authentication

Use a workspace account API key for workspace routes:

Authorization: Bearer <workspace-account-api-key>

Recommended key policy:

Create one key per integration or machine. Never share one owner key across every tool like it is a communal toothbrush.

Common response conventions

List endpoints generally return either:

{ "items": [] }

or a resource-specific collection:

{ "models": [] }

Errors return a JSON object with a human-readable message:

{ "error": "This account does not have permission to perform that action" }

Treat non-2xx responses as actionable failures and surface the error field to administrators or integration owners.

Workspaces and current user

Workspace accounts and API keys

Account roles:

Jobs and tasks

Task status lifecycle:

Teams and delegation graphs

Use delegation graph edges to make authority explicit. If agent A can delegate to agent B, that should be visible in the graph rather than hidden in a prompt.

Workflows

Deliverable actions

Use deliverable actions to replace vague “done” with explicit output shapes: approval decisions, URLs, reports, files, review forms, QA results, and similar artifacts.

Triggers

Triggers should use workspace secrets for credentials and fail closed when a required secret is absent.

Workspace secrets

Secret values are never returned after write. Reference them in configs with:

${secret.NAME}
${secrets.NAME}

Visibility policy

Visibility policy controls which users can see accounts, teams, workflows, and other workspace resources. It should narrow views by default and expand access intentionally.

SDK example coverage

The private examples repository maps every user-facing SDK-exposed feature to a working path. Use these links when turning endpoint groups into runnable automation:

If a route is added to this API page, add or update an example link at the same time. Ghost APIs are how platforms become archaeological sites.

API design rules for builders

• Workspace features must exist at the API layer first; UI and tooling are consumers.
• Do not implement dashboard-only behavior that cannot be automated.
• Return actionable errors with enough context to fix the request.
• Keep tenant data behind /api/ws/{workspace_id} boundaries.
• Use immutable notes/audit events for work history.
• Prefer disabling risky resources before deleting them when administrators need recovery time.
• Use encrypted workspace secrets for credentials.
• Keep generated docs and dashboard docs sourced from repo markdown, not separate hand-written website copies.