# Revon Public Agent Developer Reference

This page is generated from `lib/api-spec/openapi.yaml`. The OpenAPI contract is the source of truth; this file is a derived reference.

## Authority boundary

Documentation does not grant authority. Every protected operation requires a valid, scoped Early Access credential and is checked again at request time. Owner approval, delegation scope, provider connections, and Action Run state remain server-authoritative.

Credentials, sessions, provider secrets, raw prompts, raw responses, and private owner routes are intentionally excluded from this reference.

Base URL: `/api`

## Operations

### POST /api/agent/early-access/action-runs

- Operation: `proposeExternalAgentActionRun`
- Summary: Propose a bounded action for a delegated target Agent
- Contract: Creates a durable proposal only. The delegating Agent must name an active delegatee and a specific delegation. The owner must approve the proposal before the target Agent can execute it. Raw learning text is fingerprinted and supplied again by the target at execution time; it is not stored in the run ledger.
- Authorization: Scoped Early Access credential (`Bearer rva_<opaque-token>`)
- Parameters:
- Header `Idempotency-Key` (required): reuse the same key only when retrying the same payload.
- Request body: `ExternalAgentActionRunProposal`
- Responses:
  - `200`: Idempotent replay of the proposal. (JSON schema: `AgentActionRunEnvelope`)
  - `201`: Proposal created. (JSON schema: `AgentActionRunEnvelope`)
  - `400`: No description. (JSON schema: none)
  - `401`: No description. (JSON schema: none)
  - `403`: No description. (JSON schema: none)
  - `404`: No description. (JSON schema: none)
  - `409`: No description. (JSON schema: none)
  - `429`: No description. (JSON schema: none)

### POST /api/agent/early-access/action-runs/{id}/execute

- Operation: `executeExternalAgentActionRun`
- Summary: Execute an owner-approved action as the delegated target Agent
- Contract: Only the exact delegation and target Agent named by the approved proposal may execute it. The payload fingerprint must match the original proposal. Revocation and expiry are re-evaluated by the authentication middleware on every request.
- Authorization: Scoped Early Access credential (`Bearer rva_<opaque-token>`)
- Parameters:
- `path:id` (required) (inline number)
- Request body: oneOf (ExternalAgentLearningRequest, ExternalAgentGithubIssueRequest, ExternalAgentGithubIssueCloseRequest, ExternalAgentGithubIssueCommentRequest) — The Action's identity is read from the durable, already-approved proposal, not this request. Send ExternalAgentLearningRequest when the proposed action is learning_candidate.create or organization_learning_candidate.create; send ExternalAgentGithubIssueRequest when it is github_issue.create; send ExternalAgentGithubIssueCloseRequest when it is github_issue.close; send ExternalAgentGithubIssueCommentRequest when it is github_issue.comment. Sending the wrong shape for the proposal's actual action returns 400.
- Responses:
  - `200`: Action executed or idempotently replayed. (JSON schema: `AgentActionRunEnvelope`)
  - `400`: No description. (JSON schema: none)
  - `401`: No description. (JSON schema: none)
  - `403`: No description. (JSON schema: none)
  - `404`: No description. (JSON schema: none)
  - `409`: No description. (JSON schema: none)
  - `429`: No description. (JSON schema: none)

### POST /api/agent/early-access/delegations

- Operation: `createExternalAgentDelegation`
- Summary: Delegate a bounded subset of this credential's own scopes to a distinct agent
- Contract: Attenuation is enforced twice: capabilities must already be a subset of the caller's live scopes at creation time, and every later use re-checks the caller credential live, so revoking or narrowing it immediately collapses everything it delegated. A delegated principal may not create further delegations.
- Authorization: Scoped Early Access credential (`Bearer rva_<opaque-token>`)
- Request body: `ExternalAgentDelegationCreateRequest`
- Responses:
  - `201`: Delegation created; token is shown once. (JSON schema: `ExternalAgentDelegationCreated`)
  - `400`: No description. (JSON schema: none)
  - `401`: No description. (JSON schema: none)
  - `403`: No description. (JSON schema: none)
  - `429`: No description. (JSON schema: none)

### POST /api/agent/early-access/feedback

- Operation: `createExternalAgentFeedback`
- Summary: Record a bounded classified Agent reality report
- Contract: Stores a short classified report from an authenticated External Agent. The report is owner-scoped, non-destructive, and must not contain prompts, responses, secrets, or credentials. Reuse the same Idempotency-Key after a lost response.
- Authorization: Scoped Early Access credential (`Bearer rva_<opaque-token>`)
- Parameters:
- Header `Idempotency-Key` (required): reuse the same key only when retrying the same payload.
- Request body: `ExternalAgentFeedbackRequest`
- Responses:
  - `200`: Idempotent replay of the feedback report. (JSON schema: `ExternalAgentFeedbackResponse`)
  - `201`: Feedback report recorded. (JSON schema: `ExternalAgentFeedbackResponse`)
  - `400`: No description. (JSON schema: none)
  - `401`: No description. (JSON schema: none)
  - `403`: No description. (JSON schema: none)
  - `404`: No description. (JSON schema: none)
  - `409`: No description. (JSON schema: none)
  - `429`: No description. (JSON schema: none)

### POST /api/agent/early-access/learning

- Operation: `createExternalAgentLearningCandidate`
- Summary: Create a candidate learning memory for owner review
- Contract: Non-destructive candidate creation. The owner must confirm the memory before it can influence Soul context. Reuse the same Idempotency-Key after a lost response.
- Authorization: Scoped Early Access credential (`Bearer rva_<opaque-token>`)
- Parameters:
- Header `Idempotency-Key` (required): reuse the same key only when retrying the same payload.
- Request body: `ExternalAgentLearningRequest`
- Responses:
  - `200`: Idempotent replay of the candidate creation. (JSON schema: `ExternalAgentLearningResponse`)
  - `201`: Candidate created. (JSON schema: `ExternalAgentLearningResponse`)
  - `400`: No description. (JSON schema: none)
  - `401`: No description. (JSON schema: none)
  - `403`: No description. (JSON schema: none)
  - `409`: No description. (JSON schema: none)
  - `429`: No description. (JSON schema: none)

### GET /api/agent/early-access/manifest

- Operation: `getExternalAgentEarlyAccessManifest`
- Summary: Read the public External Agent Early Access capability manifest
- Authorization: None
- Responses:
  - `200`: Supported non-destructive operations and trust boundaries. (JSON schema: `ExternalAgentEarlyAccessManifest`)

### GET /api/agent/early-access/memories

- Operation: `listExternalAgentMemories`
- Summary: Read confirmed memories for the credential-bound owner
- Authorization: Scoped Early Access credential (`Bearer rva_<opaque-token>`)
- Parameters:
- `query:limit` (inline number)
- `query:offset` (inline number)
- Responses:
  - `200`: Bounded page of confirmed owner memories. (JSON schema: `ExternalAgentMemoryPage`)
  - `401`: No description. (JSON schema: none)
  - `403`: No description. (JSON schema: none)
  - `429`: No description. (JSON schema: none)

### GET /api/agent/early-access/organization-learning

- Operation: `listExternalOrganizationLearning`
- Summary: Read confirmed learning for the organization-bound credential
- Authorization: Scoped Early Access credential (`Bearer rva_<opaque-token>`)
- Parameters:
- `query:limit` (inline number)
- `query:offset` (inline number)
- Responses:
  - `200`: Bounded page of confirmed organization learning. (JSON schema: `ExternalOrganizationLearningPage`)
  - `401`: No description. (JSON schema: none)
  - `403`: No description. (JSON schema: none)
  - `429`: No description. (JSON schema: none)

### GET /api/agent/early-access/trust-decision/{targetAgentId}

- Operation: `getExternalAgentCrossAgentTrustDecision`
- Summary: Read a directional, capability-specific Trust Decision
- Contract: Returns an evidence-derived read model for the authenticated caller Agent evaluating a target Agent. The trust read never grants execution permission, creates a delegation, or returns credentials, tokens, prompts, responses, or raw evidence payloads. The caller credential must be organization-bound, Agent-bound, and include the trust:read scope.
- Authorization: Scoped Early Access credential (`Bearer rva_<opaque-token>`)
- Parameters:
- `path:targetAgentId` (required) (inline number)
- `query:capability` (required) (inline string)
- Responses:
  - `200`: Directional Cross-Agent Trust Decision (JSON schema: `CrossAgentTrustDecision`)
  - `400`: No description. (JSON schema: none)
  - `401`: No description. (JSON schema: none)
  - `403`: No description. (JSON schema: none)
  - `404`: No description. (JSON schema: none)
  - `429`: No description. (JSON schema: none)

## Deliberate exclusions

Credential provisioning and revocation, owner-session administration, internal organization management, billing, authentication, debug paths, and private data APIs are not public Agent operations.

To discover the live Early Access capability boundary, use `/api/agent/early-access/manifest`. The manifest is discovery only and never substitutes for authorization.