api_endpoint_contract · supabase_json
Bezel API api_endpoint_contract
api_endpoint_contract artifact · for Bezel API · status draft
Agent Handoff
Start Here
api_endpoint_contract artifact · for Bezel API · status draft
Completion Evidence
No explicit evidence field yet. Require tests, screenshots, linked PRs, or reviewed outputs before marking complete.
Artifact Shape
- auth: api_keys: object, human_session: object
- roles: 4 items
- agents: 5 items
- product: Bezel API
- version: 0.1
- principle: Expose coordination primitives, not Hedera internals. Human auth and agent runtime auth are separate. Agents normally call claim-next; they do not choose tasks before claiming.
- workflows: 8 items
- invariants: 6 items
- workspaces: 3 items
- ledger usage: 6 items
- product modes: lite: object, verified: object
- queues and tasks: 8 items
Structured Payload
Machine-readable source fields
auth
api keys
| body | path | method | purpose | returns |
|---|---|---|---|---|
| - name: string - scopes: 4 items - environment: development|production | /workspaces/:workspaceId/api-keys | POST | Create a workspace-scoped API key | - scopes: string[] - api key id: key_* - plaintext key: shown once |
| /workspaces/:workspaceId/api-keys | GET | List API key metadata without plaintext secrets | ||
| /workspaces/:workspaceId/api-keys/:apiKeyId | DELETE | Revoke an API key |
human session
| body | path | method | purpose | returns |
|---|---|---|---|---|
| - name: string - email: string - password: string optional when OAuth is used - oauth provider: string optional | /auth/accounts | POST | Create a human account | - email: string - session: optional session object - user id: usr_* |
| - email: string - password: string | /auth/login | POST | Create a human session | - user id: usr_* - session id: sess_* - active workspace id: wk_* optional |
| /auth/logout | POST | Revoke the current human session | - status: ok | |
| - email: string | /auth/password/reset | POST | Start password reset flow | - status: ok |
| /auth/session | GET | Read current human session | - user id: usr_* - expires at: ISO timestamp - active workspace id: wk_* optional |
roles
| body | path | method | purpose | returns |
|---|---|---|---|---|
| - name: string - description: string optional - default lease seconds: number - required capabilities: string[] | /workspaces/:workspaceId/roles | POST | Create a role and provision the workspace-role HCS topic | - role id: role_* - hcs topic id: internal/admin only in v1 - topic status: pending|ready|failed |
| /workspaces/:workspaceId/roles | GET | List roles | ||
| /roles/:roleId/agents/:agentId | POST | Assign an agent to a role | ||
| /roles/:roleId/agents/:agentId | DELETE | Remove role assignment |
agents
| body | path | method | purpose | returns | auth |
|---|---|---|---|---|---|
| - agent card: object optional - agent card url: string optional - development mode: boolean optional | /workspaces/:workspaceId/agents/register-card | POST | Register an agent by A2A Agent Card URL or inline Agent Card JSON | - agent id: agt_* - verification status: unverified|reachable|verified|failed | |
| /workspaces/:workspaceId/agents | GET | List workspace agents | |||
| /agents/:agentId | GET | Read one agent after workspace ownership check | |||
| /agents/:agentId/heartbeat | POST | Agent runtime heartbeat | agent:runtime API key | ||
| /agents/:agentId/deactivate | POST | Deactivate an agent |
product
Bezel API
version
0.1
principle
Expose coordination primitives, not Hedera internals. Human auth and agent runtime auth are separate. Agents normally call claim-next; they do not choose tasks before claiming.
workflows
| path | method | purpose |
|---|---|---|
| /workflow-definitions/validate | POST | Validate plan.json before saving or starting a workflow |
| /workflows/intake | POST | Turn natural-language build request/spec into draft plan.json requiring approval before dispatch |
| /workflows | POST | Start workflow from approved plan.json |
| /workflows/:workflowId/state | GET | Read materialized workflow state |
| /workflows/:workflowId/events | GET | Read workflow event timeline |
| /workflows/:workflowId/pause | POST | Pause workflow opening of new tasks |
| /workflows/:workflowId/resume | POST | Resume workflow |
| /workflows/:workflowId/cancel | POST | Cancel workflow |
invariants
- Every path containing object IDs must prove the object belongs to the authenticated workspace.
- Agent runtime keys cannot administer workspace billing or create broad-scope API keys.
- Raw HCS topic IDs are internal/admin-only in v1 UI and API responses unless receipt detail requires them.
- Reads are not metered in v1. HCS-backed writes consume event credits.
- The normal agent loop is POST /queues/:queueId/claim-next -> claimed/no_tasks/rejected. Agents do not first list tasks and pick one unless using advanced/debug APIs.
- Lite mode HCS writes must not include task title, task input, plan_json, brief text/ref that reveals task details, artifact details, or completion summaries. HCS is used only for minimal claim arbitration/proof.
workspaces
| path | method | purpose | body | returns |
|---|---|---|---|---|
| /workspaces | GET | List workspaces visible to the human user | ||
| /workspaces | POST | Create tenant boundary | - name: string - company name: string optional - intended use: openclaw|typescript_sdk|manual_api|other | - workspace id: wk_* - owner user id: usr_* - free verified events remaining: 1000 |
| /workspaces/:workspaceId | GET | Read workspace details |
ledger usage
| path | method | purpose |
|---|---|---|
| /events/:eventId | GET | Read public event projection |
| /events/:eventId/receipt | GET | Read verified receipt |
| /tasks/:taskId/events | GET | Read task event timeline |
| /claims/:claimId/events | GET | Read claim event timeline |
| /agents/:agentId/events | GET | Read agent event timeline scoped to workspace |
| /workspaces/:workspaceId/usage | GET | Read verified event usage and credits |
product modes
lite
value
Lowest-friction hosted coordination: verified claim races without publishing customer task data to HCS.
principle
Use HCS only for claim arbitration/proof. Do not store task briefs, task details, plan details, lifecycle summaries, or artifact details in HCS.
db content
- workspace
- roles
- agents
- queues
- workflow_definitions.plan_json
- workflow_runs
- tasks
- claims read model
- artifacts
- usage
hcs content
- claim_attempted minimal commitment
- claim_won/claim_result proof metadata or minimal claim decision
- optional receipt anchor
verified
value
Full verified ledger replay for higher-trust/enterprise workflows.
principle
Use Agent Wire v1.1 for broader lifecycle/task/artifact reference events on HCS.
hcs content
- task.created/available refs
- claim lifecycle
- artifact.ready refs
- task.complete/fail summaries and verification refs
- workflow/reducer events
queues and tasks
| body | path | method | purpose | returns | mode behavior |
|---|---|---|---|---|---|
| - name: string - default priority: low|normal|high|critical - eligible role ids: string[] - default retry policy: object - default lease seconds: number | /workspaces/:workspaceId/queues | POST | Create a queue | - queue id: queue_* | |
| /workspaces/:workspaceId/queues | GET | List queues | |||
| - input: object - title: string - idempotency key: string optional - required role id: role_* - required capabilities: string[] optional | /queues/:queueId/tasks | POST | Publish a simple role task | - task id: task_* - event id: evt_* - receipt status: pending|verified | - lite: Stores task in DB only; does not emit task.created/task.available details to HCS. Marks DB task available for claim-next arbitration. - verified: May emit Agent Wire task.created/task.available refs according to Agent Wire v1.1 profile. |
| /claims/:claimId/heartbeat | POST | Extend or confirm active claim lease | |||
| - output: object optional but not large raw model logs - summary: string - artifact refs: array optional | /claims/:claimId/complete | POST | Complete claimed task | - status: completed - task id: task_* - event id: evt_* | |
| - reason: string - retryable: boolean | /claims/:claimId/fail | POST | Fail claimed task | - status: failed - task id: task_* - event id: evt_* | |
| - agent id: agt_* - role ids: role_*[] optional; defaults to assigned roles - lease seconds: number optional - idempotency key: string required | /queues/:queueId/claim-next | POST | Primary agent runtime endpoint: find the next eligible available task for an agent and attempt the claim on its behalf | - missed: array of internal race misses optionally included for observability - status: claimed|no_tasks|rejected - task id: task_* when claimed - claim id: clm_* when claimed - brief ref: string when claimed - lease expires at: ISO timestamp when claimed - next poll after ms: number when no_tasks | - lite: Uses HCS only for minimal claim race/arbitration. Response returns DB task details after claim is won. - verified: Uses Agent Wire v1.1 claim events and receipts. |
| - agent id: agt_* - lease seconds: number optional - idempotency key: string required | /tasks/:taskId/claim | POST | Secondary/debug/specific-assignment endpoint: attempt to claim a known task id. Not the normal agent polling loop. | - status: claimed|missed|rejected - task id: task_* - claim id: clm_* optional - event id: evt_* |