API reference: the /v1 control plane

The control plane at https://api.provely.sh exposes ten endpoints under /v1. It is the only place verification happens. Every other surface is a thin client of this API.

Method and path	Purpose	Metered
`POST /v1/operations`	Create an operation against a contract. Returns the idempotency key and the correlation keys.	no
`POST /v1/operations/{id}/action-result`	Submit the provider acknowledgement (E1).	no
`POST /v1/operations/{id}/verify`	Observe once and evaluate the contract.	yes, one verified action
`GET /v1/operations/{id}`	Read the operation state and the last verdict.	no
`GET /v1/operations/{id}/receipt`	Read the signed receipt.	no
`POST /v1/events/{provider}/{workspace}`	Receive a provider webhook. The signature is validated and the event is deduplicated.	no
`GET /v1/contracts/{id}`	Read a contract by id.	no
`GET /v1/skills/{service}`	Read the skill manifest of a service.	no
`POST /v1/connections`	Store a read-only provider credential, encrypted.	no
`GET /v1/usage`	Read the plan bucket, the bought bucket, and the verified actions this period.	no

How does authentication work?

Send Authorization: Bearer pv_... with an API key, or an OAuth access token from the pinned issuer.
The control plane hashes an API key at rest. A key carries scopes, expires, and rotates with a grace time.
The credential decides the account. There is no account id in the request body.
Every response carries a request id in x-request-id.

What happens when the agent session ends?

The agent reports the operation id. A later session, the CLI, or the dashboard resumes it by id and fetches the receipt. An agent is ephemeral. An operation is not.

How does a metered call behave?

Rate limit, then request size, then parse, then preflight.
Idempotency: a reused Idempotency-Key with the same body returns the stored result. A different body returns 422.
Reserve one credit, run, then settle. A failed run refunds the credit.
With no credit left, the response is 402 with the plans and the packs in payment.

Create and verify an operation with curl

curl -X POST https://api.provely.sh/v1/operations \
  -H "Authorization: Bearer $PROVELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contract":"stripe.refund.succeeded","input":{"charge_id":"ch_3QxT5s2eZvKYlo2C","amount_cents":14200}}'

curl -X POST https://api.provely.sh/v1/operations/op_01J.../verify \
  -H "Authorization: Bearer $PROVELY_API_KEY" \
  -H "Idempotency-Key: verify-op_01J...-1"

Is there an OpenAPI document?

Yes. The control plane serves /v1/openapi.json. The SDK clients are generated from it.

Which events does the billing webhook accept?

The six Stripe events for checkout, invoices, refunds, and disputes, plus checkout.session.async_payment_succeeded. The control plane grants credits only from a signed webhook.