ProvelyThis page lists 25 public routes of the control plane at https://api.provely.sh, from its OpenAPI document, version 0.1.0.
Which routes are public?
| Route | What it does | Body members |
|---|---|---|
POST /v1/operations | Begin an operation. Create an operation for one contract. The answer carries the idempotency key and the correlation keys that the agent must use for the action. The call is metered: one operation is one verified action. Send an Idempotency-Key header to make the call safe to retry. | contract (required), input, intent, versions, skill, project, retry_of, idempotency_key, decision_id |
POST /v1/operations/{id}/action-result | Report the action result. Report what the provider answered when the agent did the action. An acknowledgement is never terminal success. The runtime schedules the first verification attempt. | status (required), evidence_level (required), result, error, envelope, transport, idempotency_key, provider_api_version, started_at, completed_at, redaction |
POST /v1/operations/{id}/verify | Run one verification attempt. Run one attempt now, when the timing policy permits it, and return the verdict. PENDING is a normal answer. The worker continues while the operation is open. | action_result, ignore_schedule |
GET /v1/operations/{id} | Read an operation. Return the operation record and its status. The call runs no attempt. | - |
GET /v1/operations/{id}/receipt | Read the signed receipt. Return the Ed25519-signed receipt. A terminal operation returns its stored receipt. An open operation returns an interim receipt that states the last verdict. | - |
POST /v1/intents | Compile a task into a proposed contract. Compile one task in natural language into a proposed completion contract. The answer states what the contract checks, and it states every part of the task that the contract does not check. A proposal decides nothing. Confirm it before it verifies anything. | statement (required), context, tools (required) |
GET /v1/intents/{id} | Read a compiled proposal. Return the proposal, the review page that a person reads, and the confirmation when a person already confirmed it. | - |
POST /v1/intents/{id}/confirm | Confirm a proposal. | proposal_hash (required), confirmed_by (required), acknowledged_unchecked (required), note |
GET /v1/intents/confirmations/{id}/policy | Read the guard policy of a confirmed compilation. Return the tool guard policy that one confirmed compilation states. Each rule binds one tool of the task to the contract of one step. A mapping that the compilation does not state binds nothing, and it reaches the answer as one REQUIRES_REVIEW part. A tool that no step names gets no rule, and the guard runs it unchanged. | - |
POST /v1/events/{provider}/{workspace} | Receive a provider webhook. Receive one provider event. The connection that owns the workspace states the signature scheme and the payload version source. A duplicate delivery answers 200 without a second write. A late delivery is stored under its provider timestamp. | - |
GET /v1/contracts/{id} | Read a completion contract. Return the contract with this identity. The version query takes a selector. Without it the newest version answers. A global contract from a skill wins over a private one. | - |
GET /v1/skills/{service} | Read a service verification skill. A global skill wins over a private skill of the caller. | - |
POST /v1/connections | Create a connection. Store the read-only verifier credentials and the webhook settings of one provider account. The answer never repeats a secret. The webhook URL in the answer is the endpoint to register at the provider. | provider (required), name, workspace, provider_api_version, credentials, webhook |
GET /v1/usage | - | - |
POST /v1/operations/{id}/fix | Ask a host to run the fix of one operation. Sign one fix directive for a registered host. The frozen retry table decides: only retry_step and retry_action reach a host, and every other verdict is refused with the correction. A second click while the first directive is open answers 409. | host (required), tool (required) |
POST /v1/hosts | Register a host. Register a process of the customer that runs a fix directive. A push host takes a delivery at its URL. A pull host asks for its directives. The record holds no credential. | name (required), delivery (required), url, tools (required) |
GET /v1/hosts | List the hosts of the account. | - |
GET /v1/hosts/{id}/directives | Read the open directives of a host. Answer the signed directives that this host has not taken yet, and mark them taken. The host verifies each signature against its trusted key map before it runs anything. | - |
POST /v1/directives/{id}/result | Report what a host did with a directive. Record the answer of the host: accepted with the operation that it opened, or refused with a reason code. The report is an audit line. The state of the row comes from the operation, never from this report. | status (required), reason_code, operation_id |
POST /v1/reviews | Open a review from a scan document. Open one review from the scan document of one repository. One item is one group of call sites that share a provider, an effect, a callee, and an argument shape. An item that a confirmed authority of the organization covers is covered. An item that no signed contract proves is requires_review. Every other item is needs_statement: a person writes the promise, because a scan finding has no words. The call is metered. | schema_version (required), repository (required), base_sha (required), head_sha (required), scanned_at (required), groups (required), surfaces |
GET /v1/reviews/{id} | Read one review with its items. | - |
GET /v1/reviews/{id}/status | Read the status of one review. Return whether every item is decided, and the items that still wait for a person. A CI gate reads complete. It is true only when no item is needs_statement, requires_review, or needs_confirmation. | - |
POST /v1/reviews/{id}/items/{key}/statement | Write the statement of one item, and compile it. Record the promise that one person states for one item, and compile it into a proposal. The statement is the words of the person. The callee and its argument names are the tool of the agent. The snippets are untrusted context. The item moves to needs_confirmation, and the answer states every part of the statement that the proposal does not check. The call is metered as a compilation. | statement (required) |
POST /v1/reviews/{id}/items/{key}/confirm | Confirm one item. | confirmed_by (required), allow_open_review, reason, note, proposal_hash |
POST /v1/reviews/{id}/compile-all | Draft and compile every item that waits for words. | - |
Where this page comes from
A generator writes this page from the files below. A test fails when the page differs from them.
| File | Commit | Committed |
|---|---|---|
apps/api/openapi/openapi.json | 704c2b5e | 2026-10-16 |