API reference
Base URL https://ravelin.network/api/v1. JSON in, JSON out, integers as decimal strings. Machine-readable contract: /api/v1/openapi.json (OpenAPI 3.1).
Authentication
- Agents send
Authorization: Bearer rw_test_…. Keys belong to one agent, are shown once and are stored only as a SHA-256 hash. Never put a key in a URL. - People use the console session from wallet sign-in. State changes must come from this site (the
Originheader is checked). With several organizations, choose one with thex-rw-orgheader. - Roles are checked on every request: viewer reads; operator also pauses agents and engages the emergency stop; approver signs approvals; admin manages agents, keys and policies; owner also manages members and lifts the stop.
Errors
Every refusal is { request_id, error: { code, message, retryable } } with a stable reason code. A denied operation is not an error: it returns decision: "DENY" with its reason. When the database or a required input is unavailable the API answers 503 RW_STATE_001 and authorizes nothing. Keys are limited to 120 requests a minute (429 RW_RATE_001).
Operation states
authorized: ALLOW. Usable untilexpires_at(5 minutes); its amount stays reserved for the rolling hour.pending_approval: waiting up to 15 minutes for an approver; thenapproved(a fresh 5-minute authorization),rejectedorexpired.denied,cancelled,authorization_expired: terminal. Nothing in this release moves an operation to executed: that needs receipt reconciliation.
Authorization (agents)
POST/operations
Evaluate a transaction intent and record the decision with its budget reservation.
API key
- request_id
- string, 1-128 of A-Z a-z 0-9 _ . : -; unique per agent
- chain_id
- integer; 46630 (Robinhood Chain Testnet)
- to
- address
- value_wei
- decimal integer string
- data
- 0x hex calldata, at most 65536 bytes; "0x" for a native transfer
- gas_limit
- integer 21000-30000000; fee bound = gas_limit × current gas price
- deadline
- unix seconds, at most one hour ahead
Send Idempotency-Key to make retries return the original decision (header Idempotent-Replayed: true). 201 on a new decision, 200 on an idempotent replay, 409 RW_REPLAY_001 for a reused request_id or a key reused with a different body.
POST/authorizations/evaluate
Dry run: the same evaluation against live state, reserving nothing and consuming no request_id.
API key
- …
- same fields as POST /operations
GET/operations/{id}
One operation. An API key can read only its own agent's operations.
Session or API key · viewer or above
POST/operations/{id}/cancel
With an API key: withdraw a pending approval. In the console: release an unused, unexpired authorization's budget.
Session or API key · operator or above
Console: operations and approvals
GET/operations
List operations, newest first.
Console session · viewer or above
Query: decision, reason_code, agent_id, limit (≤200), before (created_at cursor from next_before).
GET/approvals
Operations waiting for a person (status=pending) or already decided (status=decided). Pending items include the EIP-712 typed data to sign.
Console session · viewer or above
POST/approvals/{id}/approve
Approve with an EIP-712 signature from your signed-in wallet over the exact operation.
Console session · approver or above
- signature
- 0x hex signature of typed_data
POST/approvals/{id}/reject
Reject a pending operation and release its reservation.
Console session · approver or above
- reason
- optional string, ≤280 chars
GET/summary
Counts for the last 24 hours (UTC, hourly buckets) and denials by reason.
Console session · viewer or above
Console: agents and keys
GET/agents
List agents with policy, key count and last operation.
Console session · viewer or above
POST/agents
Register an agent.
Console session · admin or above
- name
- string
- chain_id
- 46630
- account
- smart account address
- policy_id
- optional policy id; must protect the same account
GET/agents/{id}
Agent detail with keys (never secrets) and last-hour usage.
Console session · viewer or above
PATCH/agents/{id}
Rename or rebind the policy.
Console session · admin or above
- name
- optional
- policy_id
- optional; null to unbind
POST/agents/{id}/pause
Deny the agent's new operations with RW_PAUSED_001.
Console session · operator or above
- confirm
- true
POST/agents/{id}/resume
Resume a paused agent.
Console session · admin or above
- confirm
- true
POST/agents/{id}/revoke
Permanently revoke the agent and all its keys.
Console session · admin or above
- confirm
- true
POST/agents/{id}/credentials
Create an API key. The secret is in this response only.
Console session · admin or above
- label
- optional string
POST/credentials/{id}/revoke
Revoke an API key immediately.
Console session · admin or above
Console: policies
GET/policies
List policies with status and active version.
Console session · viewer or above
POST/policies
Create a draft from the strict starter, or from a full document.
Console session · admin or above
- name
- string
- policy_key
- a-z 0-9 _
- chain_id
- 46630
- account
- address
- document
- optional full policy instead
GET/policies/{id}
Draft, its validation errors and hash, the active document and version history.
Console session · viewer or above
PUT/policies/{id}
Save the draft. Drafts may be invalid while you edit.
Console session · admin or above
- document
- policy object
POST/policies/{id}/activate
Activate the saved draft as the next immutable version.
Console session · admin or above
- confirm
- true
- draft_hash
- draft_hash from GET, binding activation to what you reviewed
POST/policies/{id}/disable
Disable: bound agents are denied with RW_POLICY_001.
Console session · admin or above
- confirm
- true
Console: organization and audit
GET/organization
Name, emergency-stop state and counts.
Console session · viewer or above
PATCH/organization
Rename.
Console session · owner or above
- name
- string
POST/organization/emergency-stop
Engage (operator) or lift (owner only) the organization's emergency stop.
Console session · operator or above
- active
- boolean
- confirm
- true
GET/members
Members and roles.
Console session · viewer or above
POST/members
Add a wallet as a member or change its role.
Console session · owner or above
- address
- address
- role
- owner | admin | operator | approver | viewer
DELETE/members/{address}
Remove a member.
Console session · owner or above
GET/audit-events
Append-only audit events, newest first.
Console session · viewer or above
Query: type (exact or prefix, e.g. operation), agent_id, limit (≤200), before (seq cursor from next_before).
Sign-in and health
POST/auth/challenges
Create a SIWE (EIP-4361) challenge for a wallet address.
Public
- address
- address
- chain_id
- integer
POST/auth/verify
Verify the signed challenge and set the session cookie.
Public
- nonce
- string
- signature
- 0x hex
POST/auth/logout
Revoke the session.
Console session
GET/me
Signed-in address and organizations.
Console session
GET/health
Component status. ?shallow=1 does not touch the database.
Public