curl -sS "https://api.orgs.sh/v1/entities/$ENTITY_ID/proposals" \
  -H "authorization: Bearer $ORGS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "spend",
    "title": "Pay registered agent invoice",
    "description": "Annual registered-agent renewal",
    "amount_usd": 125,
    "recipient": "registered-agent"
  }'

{
  "id": "9c41cb41-1351-4230-9a02-a3f48196dd06",
  "title": "Pay registered agent invoice",
  "proposal_type": "Spend",
  "state": "Draft",
  "escalation": null
}
POST
/
v1
/
entities
/
{id}
/
proposals
curl -sS "https://api.orgs.sh/v1/entities/$ENTITY_ID/proposals" \
  -H "authorization: Bearer $ORGS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "spend",
    "title": "Pay registered agent invoice",
    "description": "Annual registered-agent renewal",
    "amount_usd": 125,
    "recipient": "registered-agent"
  }'

{
  "id": "9c41cb41-1351-4230-9a02-a3f48196dd06",
  "title": "Pay registered agent invoice",
  "proposal_type": "Spend",
  "state": "Draft",
  "escalation": null
}

​
Path parameters

​
id
string
required
Entity UUID.

​
Request body

​
kind
string
required
Supported values: spend, hire_agent, dissolution.
​
title
string
required
Short proposal title.
​
description
string
required
Human-readable reason and context.
​
amount_usd
number
Required for spend proposals.
​
recipient
string
Required for spend proposals.

​
Response fields

​
id
string
required
Proposal UUID.
​
proposal_type
string
required
Server-side proposal type.
​
state
string
required
Current proposal state.
​
escalation
string | null
Reason the constitution requires escalation or approval.
Use kind: "spend" for treasury movement. Include amount_usd and recipient.
Agents should create proposals instead of executing directly when risk is unclear or when the constitution requires approval.

Authorizations

​
Authorization
string
header
required

Use Authorization: Bearer <token>. The token can be a legacy Orgs API key or a platform-minted JWT.

Path Parameters

​
id
string<uuid>
required

Entity UUID.

Body

application/json
​
kind
enum<string>
required
Available options:
spend,
hire_agent,
dissolution
​
title
string
required
​
description
string
required
​
amount_usd
number<double>
​
recipient
string

Response

Proposal created.

​
id
string<uuid>
required
​
title
string
required
​
proposal_type
string
required
​
state
string
required
​
escalation
string | null