Skip to content

Queue an AI extraction of requirements from free-form text (writes no requirement)

POST
/v1/projects/{id}/requirements/import/extractions
curl --request POST \
--url https://beta-api.plune.ai/v1/projects/example/requirements/import/extractions \
--header 'Content-Type: application/json' \
--cookie plune_session=<plune_session> \
--data '{ "markdown": "# Checkout notes\n\nWe talked about payments with the whole team today and agreed on the first version of the checkout page.\n- The system shall accept a card payment. Priority: High\n- Expired cards must be refused with a clear message.\nWe could maybe support Apple Pay later.\n" }'

Requirements from free-form text with the project’s AI (#1607, epic #1594) as a job (#2292, ADR 0076), so a long text is not bound by the time of a request: a 202 with the extraction queued, and the worker makes the one call to the project’s own AI provider with the file, secrets masked, waiting up to 5 minutes for it. GET …/extractions/{extractionId} reads it back: once done, result holds the proposals for 24 hours after it ended (resultKeptUntil). Nothing writes a requirement: the person keeps what is right and imports it with POST …/import in items mode. The extraction must not invent: a proposal is kept only with a quote the text holds (emphasis, case and line breaks ignored, a link as its text) on word bounds, where a line, a sentence or a clause begins, and of three words at least unless it ends its line; its line is where the quote starts in the file as sent (a masked secret does not move it; a quote with a masked part in it is refused). One without a quote, or with a quote the text does not hold so, is listed in refused with the reason. A priority or an acceptance criterion is kept only when the requirement’s own paragraph or list item says it (with what is nested under it; a table row is only itself), otherwise it is left out. A statement the text does not confirm (an idea, a “maybe”) is a question: shown, never imported. An empty answer ends done with nothing proposed. A person’s session only: a bearer token gets 403. Then, in order: the AI state (503 / 409, a saved key that cannot be read a 409 key_rejected), the text (422); the same text from the same person (the same language too), while that extraction is queued, running, or done with its result still kept and not empty (a requirement, a question or a refusal in it), is a 202 with that extraction and reused: true — nothing is queued and nothing is spent, even once that extraction used up the month; only then the month’s limit (429 ai_budget_spent). The worker asks the month again just before the call: one that finds it used up ends failed / ai_budget_spent, with no call and nothing spent. One that failed or was cancelled, or whose result is gone or empty, is asked again. The tokens and the cost are recorded when the provider answers, whatever it answers, and count in the project’s monthly AI limit; the provider’s failure is the extraction’s failureKind. The fallback provider is not tried.

id
required
string

An id from GET /v1/projects

Media type application/json
object
markdown
required

The text: at most 100000 characters, at least 20 words.

string
language

The language of the titles; the project’s AI language when left out.

string
>= 2 characters <= 35 characters
Example
{
"markdown": "# Checkout notes\n\nWe talked about payments with the whole team today and agreed on the first version of the checkout page.\n- The system shall accept a card payment. Priority: High\n- Expired cards must be refused with a clear message.\nWe could maybe support Apple Pay later.\n"
}

Queued, or the earlier extraction of the same text (reused: true)

Media type application/json
object
id
required
string
state
required
string
Allowed values: queued running done failed cancelled
reused
required

True only on a POST that found the earlier extraction of the same text; false on GET and DELETE.

boolean
createdAt
required
string format: date-time
startedAt
required
string format: date-time
nullable
finishedAt
required
string format: date-time
nullable
fetched
required
object
text
required

Characters sent, after masking.

integer
redactions
required

Secrets masked before anything left.

integer
provider
required

The project’s provider when it was queued.

string
model
required
string
cost
required

Tokens null = the provider reported none; costUsd null beside tokens = the model’s price is unknown, never 0.

object
inputTokens
required
integer
nullable
outputTokens
required
integer
nullable
costUsd
required
number
nullable
failureKind
required

Null unless failed: timeout (no answer within 5 minutes), the provider’s own kind (key_rejected, provider_rate_limited, provider_unavailable, invalid_response, address_rejected), stalled (it did not finish), ai_unavailable (the project’s AI was gone when it ran), or ai_budget_spent (the project’s monthly AI limit ran out while it waited in the queue: the provider was not called, nothing was spent).

string
nullable
result
required

What it proposed, each line in the file as sent: only while done and until resultKeptUntil, null otherwise.

object
requirements
required
Array<object>
object
line
required
integer
>= 1
title
required
string
quote
required
string
priority

Only when the text states it.

string
acceptanceCriteria

Only the ones the text states.

Array<string>
type
string
Allowed values: user_story feature epic
questions
required
Array<object>
object
line
required
integer
>= 1
title
required
string
quote
required
string
refused
required
Array<object>
object
title
required
string
reason
required
string
Allowed values: no_quote quote_not_in_text invalid
resultKeptUntil
required

finishedAt plus 24 hours when done; then result reads null and the cost stays. Null otherwise.

string format: date-time
nullable
Example
{
"id": "7a2c4e10-0000-4000-8000-0000000000b1",
"state": "queued",
"reused": false,
"createdAt": "2026-11-04T09:00:00.000Z",
"startedAt": null,
"finishedAt": null,
"fetched": {
"text": 268
},
"redactions": 0,
"provider": "anthropic",
"model": "claude-haiku-4-5",
"cost": {
"inputTokens": null,
"outputTokens": null,
"costUsd": null
},
"failureKind": null,
"result": null,
"resultKeptUntil": null
}

Invalid JSON or body

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

No / invalid token or session

A bearer token, or you are in the project as a reader

No such project among yours (or a token of another project)

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

No AI provider connected (ai_not_connected), AI turned off (ai_disabled), or a saved key this server cannot read (key_rejected, the extraction only)

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

text_too_long (more than 100000 characters, with limit) or text_too_empty (fewer than 20 words, with minWords)

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

The route’s ceiling, ten an hour (Retry-After), or the month’s AI limit used up (ai_budget_spent, Retry-After until the 1st)

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}

No AI platform key on this server (platform_not_configured)

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}