Agent Approval Protocol

Creates a new instance of the agent the provisioner token belongs to and returns it together with its agent credential. Use this from a fleet or platform that starts agent replicas itself, so each replica gets a credential of its own. The bearer token must be a provisioner token (whp_); an agent credential is rejected. Requires an Idempotency-Key header scoped to the provisioner: repeating the same submission with the same key within seven days answers 200 with the original instance and credential, without creating another instance, renewing the credential or verifying the receiver again. Reusing a key with different input answers 409 with code idempotency_conflict, a key whose attempt is still running answers 409 with code idempotency_in_progress, and replaying a key whose instance was deleted answers 409 with code instance_deleted. Pass delivery to use the Agent Approval Protocol's asynchronous mode: before the instance is created, withHuman sends a signed webhook.verification message to the receiver, which must answer 200 with the same challenge within ten seconds, or the call fails with 422 and code webhook_verification_failed and no instance is created (the same key may be retried). A malformed or non-public receiver URL answers 400 with code invalid_webhook_url. Afterwards, every request of the instance that becomes approved, denied, expired or cancelled sends one signed request.resolved notification to the receiver, retried with backoff for up to seven days until it answers 2xx; notifications wait while the instance is disabled. The notification carries only IDs; read the decision with GET /api/aap/v1/requests/{id}. Both messages are signed with the Standard Webhooks scheme (webhook-id, webhook-timestamp and webhook-signature headers). Requires the deployment's secrets key; without it, delivery is refused with 501.

Returns an instance of the provisioner token's agent with its receiver, if any. The signing secret and credentials are never returned. A deleted instance, or one of another agent, answers 404.

Renames an instance of the provisioner token's agent, replaces its receiver, or removes it. A delivery object replaces the whole configuration, signing secret included, and is verified first exactly as at creation: the old configuration and name stay in place until verification succeeds, and a failure answers 422 with code webhook_verification_failed. Queued notifications then go to the new receiver with the new secret, with unchanged IDs and bodies. delivery: null removes the receiver and ends outstanding deliveries and retries. Requires an Idempotency-Key header scoped to the provisioner and the instance: repeating the same submission answers the original response without applying it again. A deleted instance answers 404.

Retires an instance of the provisioner token's agent: its credentials are revoked, its receiver is removed with every outstanding delivery, and each of its pending requests is cancelled without a notification. Requests that already reached an outcome are unchanged. The instance stays listed in the product, disabled, and cannot be enabled again. Deleting it again answers 204.

Asks for approval to run a tool call. The organization's approval pipeline evaluates the request first and may approve or deny it on the spot, in which case the response already carries the decision. Otherwise the request goes to reviewers and comes back as pending; retrieve it with a wait to learn the outcome. A request nobody decides before its timeout becomes expired: the adapter does not run the call and tells the agent the approval timed out. An adapter that stops waiting should cancel the request so reviewers stop seeing it. Requires an Idempotency-Key header scoped to this operation and the authenticated instance. Reusing it with changed input returns 409.

Returns the request and, once it has been decided, its decision. Pass wait to hold the response until the request is decided or the wait runs out, whichever comes first. Only the instance that created the request may retrieve it. A request stops changing once it is approved, denied, expired, or cancelled.

Withdraws a pending request. Use it when the runtime that asked stops waiting for the answer: it was interrupted, timed out locally, or is shutting down. Reviewers stop seeing the request, notifications stop, and anyone holding it is released. Only the instance that created the request may cancel it; another instance of the same agent gets a 403. A cancelled request is final and answers cancelled with a protocol decision, so a long poll in flight returns at once. Cancelling again returns the same cancelled request. A request that was already approved, denied, or expired is unchanged and answers 409 with code already_terminal. This is an optional capability of the Agent Approval Protocol: adapters must treat a 404 or 405 from a provider that does not offer it as nothing to do.

Marks an approved request as used, right before the adapter runs the call. Each approval runs one call: only one consume succeeds, so a second attempt to run the same call is refused. Call it after checking decision.expires_at, and do not start the call until it succeeds. Only the instance that created the request may consume it; another instance gets a 403. Requires an Idempotency-Key header that identifies this execution attempt: repeating the key returns the request as it is now, even after expires_at. The request takes no body; an empty body or {} is accepted. Answers 409 with code already_consumed when another key already consumed it, not_approved when the request is not approved, and approval_expired once expires_at has passed.

Records whether the approved call succeeded, after the adapter consumed the approval and ran it. The outcome is for the record only: it never changes the request's status or decision. Report it once. Repeating the same body returns the same request; a different outcome answers 409 with code outcome_conflict. A request that was not consumed answers 409 with code not_consumed. Only the instance that created the request may report its outcome; another instance gets a 403.