---
search:
  tags:
    - proposals
    - POST
seo:
  description: >-
    Create an agent proposal without mutating business data (scope
    proposals:write). Reference for the POST /api/v1/proposals endpoint in the
    Basenet Public API.
sidebar:
  label: >-
    Create an agent proposal without mutating business data (scope
    proposals:write)
  badge: POST
title: >-
  Create an agent proposal without mutating business data (scope
  proposals:write)
type: openapi-operation
---
Endpoint: `POST /api/v1/proposals`

Authentication: `bearerAuth` (Scoped API token (bnx\_…). Required scopes are noted per operation.)

Request body (`application/json`):
- `capabilityId` (string, required)
- `input` (object, required)
- `rationale` (string, optional)
- `evidence` (array of string, optional)
- `riskFlags` (array of string, optional)
- `expiresAt` (string, optional)

Responses:
- `201`: Proposal created
- `400`: Invalid request
- `401`: Unauthenticated
- `403`: Forbidden (missing scope or permission)
- `429`: Rate limited

Response 201 body (`application/json`):
- `proposal` (object, required)
- `proposal.id` (string, required)
- `proposal.capabilityId` (string, required)
- `proposal.status` (one of `"open"`, `"accepted"`, `"committed"`, `"cancelled"`, `"expired"`, required)
- `proposal.version` (integer, required)
- `proposal.input` (object, required)
- `proposal.rationale` (string or null, required)
- `proposal.evidence` (any, optional)
- `proposal.metadata` (object, required)
- `proposal.metadata.duplicateMatches` (array of object, optional)
- `proposal.metadata.confirmDuplicates` (one of `true`, optional)
- `proposal.riskFlags` (array of string or null, required)
- `proposal.expiresAt` (string or null, required)
- `proposal.createdAt` (string, required)
- `proposal.updatedAt` (string, required)