---
title: "Draft a structured app proposal from a plain-language description (persists nothing)"
method: POST
path: "/v1/apps/proposals"
tags: ["Apps"]
---

# Draft a structured app proposal from a plain-language description (persists nothing)

`POST /v1/apps/proposals`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/apps/proposals`
- Auth: HTTP bearer

## Request body

- object
  - `description` string, required

## Response `201`

The structured proposal: name, slug, mode, IF/THEN policy sentences grounded only in the description (missing specifics become open_questions), the data the app will need granted, and the v1 approve/hold output contract. The client creates the real app via POST /v1/apps + PUT /v1/apps/{id}/logic once accepted.

- object
  - `proposal` AppProposal
    - `display_name` string
    - `slug` string
    - `mode` 'rules' | 'assisted' | 'external'
    - `summary` string
    - `policy_sentences` string[]: Flat sentence mirror of the rules sentences.
    - `rules` object[]
      - `sentence` string
      - `applies_to` string, nullable: One of doc_types
      - `params` object, nullable
        - `threshold` number: Stated similarity tolerance in (0,1].
        - `exact` boolean
    - `doc_types` string[]
    - `rollup` object, nullable
      - `description` string
      - `substantive_hint` integer[]
    - `external` object, nullable
      - `decisionSlaSeconds` integer
      - `leaseSeconds` integer
    - `fallback` 'rules' | 'hold' | 'none'
    - `output_contract` object: Always the v1 approve/hold template.
    - `triggers` object
      - `manual` boolean
      - `api` boolean
    - `inputs_needed` string[]
    - `open_questions` string[]
  - `model` string: The model id that produced the draft.

## Other responses

- `401`: Missing or invalid API key.
- `422`: Description outside 20-2000 characters.
- `429`: Daily rate limit exceeded.
- `502`: The drafting model is unavailable; retryable.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)