# Agent Proposals

Agent action proposals submitted by AI agents for human review and approval. Agents submit proposals when they identify an action that should be taken but requires a human decision. Proposals surface in the Agent Hub at /auto/agent-hub?tab=proposals.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### GET /agent-proposals

List agent proposals. Defaults to pending. Use status=all to see the full history.

**Scopes:** `agent-ops:read` — [full detail](./agent-proposals/get-agent-proposals.md)

### GET /agent-proposals/:id

Get a single agent proposal by ID.

**Scopes:** `agent-ops:read` — [full detail](./agent-proposals/get-agent-proposals-id.md)

### POST /agent-proposals

Create an agent proposal. Submitted by AI agents when they identify an action that requires human approval. The proposal is surfaced in the Agent Hub for review.

**Scopes:** `agent-ops:write` — [full detail](./agent-proposals/post-agent-proposals.md)

### POST /agent-proposals/:id/approve

Approve a pending proposal and execute its proposed action immediately. The action is resolved via a tool-to-API mapping and executed server-side. The result is stored on the proposal record (status becomes "executed" on success, "failed" on error).

**Scopes:** `agent-ops:write` — [full detail](./agent-proposals/post-agent-proposals-id-approve.md)

### POST /agent-proposals/:id/reject

Reject a pending proposal. The proposed action is NOT executed. The rejection reason is stored and visible to the agent.

**Scopes:** `agent-ops:write` — [full detail](./agent-proposals/post-agent-proposals-id-reject.md)