Queue an AI extraction of requirements from free-form text (writes no requirement)
const url = 'https://beta-api.plune.ai/v1/projects/example/requirements/import/extractions';const options = { method: 'POST', headers: { cookie: 'plune_session=<plune_session>', 'Content-Type': 'application/json' }, body: '{"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"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”An id from GET /v1/projects
Request Body required
Section titled “Request Body required ”object
The text: at most 100000 characters, at least 20 words.
The language of the titles; the project’s AI language when left out.
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"}Responses
Section titled “ Responses ”Queued, or the earlier extraction of the same text (reused: true)
object
True only on a POST that found the earlier extraction of the same text; false on GET and DELETE.
object
Characters sent, after masking.
Secrets masked before anything left.
The project’s provider when it was queued.
Tokens null = the provider reported none; costUsd null beside tokens = the model’s price is unknown, never 0.
object
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).
What it proposed, each line in the file as sent: only while done and until resultKeptUntil, null otherwise.
object
object
Only when the text states it.
Only the ones the text states.
object
object
finishedAt plus 24 hours when done; then result reads null and the cost stays. Null otherwise.
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
object
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)
object
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)
object
Example generated
{ "error": "example"}text_too_long (more than 100000 characters, with limit) or text_too_empty (fewer than 20 words, with minWords)
object
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)
object
Example generated
{ "error": "example"}No AI platform key on this server (platform_not_configured)
object
Example generated
{ "error": "example"}