---
title: "Create Proposal Route"
method: POST
path: "/api/v1/nova/proposals"
tags: ["nova"]
---

# Create Proposal Route

`POST /api/v1/nova/proposals`

## Request

- Base URL: `https://cp.xenovia.io` (the document declares no server; this is the origin it was published from)
- URL: `https://cp.xenovia.io/api/v1/nova/proposals`
- Auth: none declared

Dry-run validated by the direct route; supersedes the open proposal of
the same kind for the same target.

## Headers

- `Authorization` string, nullable
- `X-Request-ID` string, nullable

## Request body

- ProposalCreate
  - `kind` string, required
  - `target_id` string, uuid, nullable
  - `ops` object
  - `title` string, required
  - `summary` string

## Response `201`

Successful Response

- ProposalRead
  - `id` string, uuid, required
  - `kind` string, required
  - `status` 'proposed' | 'applied' | 'discarded' | 'expired' | 'superseded' | 'failed', required
  - `title` string, required
  - `summary` string, required
  - `target` Ref, required
    - `type` string, nullable
    - `id` string, uuid, nullable, required
    - `name` string, nullable, required
  - `before` object, required
  - `after` object, required
  - `stale` boolean, required
  - `preview_available` boolean
  - `requested_by` Ref, required
    - `type` string, nullable
    - `id` string, uuid, nullable, required
    - `name` string, nullable, required
  - `decided_by` Ref, required
    - `type` string, nullable
    - `id` string, uuid, nullable, required
    - `name` string, nullable, required
  - `decided_at` string, date-time, nullable, required
  - `applied_at` string, date-time, nullable, required
  - `session_id` string, uuid, nullable, required
  - `created_at` string, date-time, required
  - `expires_at` string, date-time, required
  - `can_apply` boolean, required
  - `error` string, nullable, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-26** `3e25bef24f8f`: 1 info
  - added the optional property `preview_available` to the response with the `201` status
- **2026-10-04** `b475b750a0b7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/xenovia/apis/controlplane/changes/api/v1/nova/proposals/post.md)

---

[API](https://skmtc.dev/xenovia/apis/controlplane.md) - [All operations](https://skmtc.dev/xenovia/apis/controlplane/llms.txt) - [OpenAPI document](https://skmtc.dev/xenovia/apis/controlplane/revisions/3e25bef24f8f?raw)