# POST /agent-proposals

**Resource:** [Agent Proposals](./agent-proposals.md)  
**Scopes:** `agent-ops:write`  
**Write operation:** yes

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.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `agent_name` | body | string | yes | Name of the agent submitting the proposal |
| `category` | body | string | yes | Category: enable, fix, config, strategy, diagnose, learn |
| `title` | body | string | yes | Short action-oriented title |
| `proposed_action` | body | object | yes | Action to execute on approval: { "tool": "<tool_name>", "params": { ... } }. Use tool: "custom" for manual actions. |
| `description` | body | string | no | Explanation of why this action is needed |
| `context` | body | object | no | Supporting evidence as key-value pairs (e.g. { "days_stale": 22 }) |
| `priority` | body | string | no | Priority: low, medium (default), high, critical |
| `options` | body | array | no | List of choices for the reviewer. Each item: { "label": "...", "action": { "tool": "...", "params": {...} } } |
| `expires_at` | body | string | no | ISO datetime when this proposal expires (default: 7 days) |

## Request example

```bash
{
  "agent_name": "project-manager",
  "category": "enable",
  "priority": "high",
  "title": "Enable welcome automation",
  "description": "The welcome sequence automation has been disabled for 5 days. 3 new clients received no onboarding email.",
  "context": { "affected_deals": 3, "pipeline": "Fulfillment Kickoff", "days_disabled": 5 },
  "proposed_action": { "tool": "enable_automation", "params": { "id": "auto-uuid" } }
}
```

## Response example

```json
{
  "data": {
    "id": "f1a2b3c4-...",
    "status": "pending",
    "expires_at": "2026-04-20T00:00:00Z"
  },
  "meta": { "url": "https://app.trustpager.com/auto/agent-hub?tab=proposals" }
}
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`