Skip to main content

Bulk Allocate Cost Entries with AI

POST 

/api/cost-entries/ai-allocation/bulk

Runs AI allocation across several cost entries at once.

Required scope: purchase-orders:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Body:

  • action (string, required) — propose starts an AI allocation batch for every entry that has source lines (entries without any are skipped); confirm_high confirms only the high-confidence (85 and up) ready proposals of each entry's latest completed, non-stale batch. Neither action confirms anything below high confidence.
  • cost_entry_ids (array of integers, required, 1–500, distinct, existing cost entries).
  • preview (boolean, optional) — true saves nothing and returns the counts the action would cover.

Preview response (200): data is {action, entries, lines, total, currency_code, totals_by_currency, skipped} — the entries and lines the action covers, the amount (total, 0 for propose) and how many selected entries are skipped. availability is {available, message, code} for the calling user.

propose response: 202 Accepted with data {tracked_job_log_id, batch_ids, skipped}, a top-level tracked_job_log_id and message. When none of the entries has source lines it returns 200 with batch_ids: [] and tracked_job_log_id: null.

confirm_high response: 202 Accepted with data.tracked_job_log_id, a top-level tracked_job_log_id and message. Entries without a confirmable batch are skipped by the job.

Poll GET /api/tracked-job-logs/{trackedJobLog} for progress.

Errors:

  • When AI cannot run the request is refused and nothing is queued. The body carries message and a machine code:
  • ai_disabled (422) — AI is switched off for the workspace or no API key is set for the active provider.
  • ai_not_permitted (403) — the user's role lacks the ai.use permission.
  • ai_scope_blocked (422) — the workspace has switched off a data type this feature sends to the AI provider. Allocating by hand through the Cost Allocations endpoints stays available in every case.
  • 422 validation errors (unknown action, empty or oversized selection, unknown cost entry ID, confirm_high without the preview's batches or with a batch missing its proposals).

Required permission: cost_entries.ai_allocate (Allocate with AI).

Authentication: Requires Bearer token (scope purchase-orders:write).

batches (required for confirm_high without preview): send back the batches object from the preview response; without it the request is refused with 422. Each batch needs batch_id, input_hash, currency_code and a non-empty proposals (proposal id => revision). Only those proposals are confirmed; an entry whose proposal changed since the preview, or that the preview did not count, is skipped with a reason. The preview response (preview: true) returns data.batches: per counted cost entry id, the batch_id and input_hash the count was made from.

Revisions: each entry in the preview's data.batches also carries proposals (proposal id => revision) and currency_code. Send batches back unchanged: when any previewed proposal changed since (re-pointed, left unallocated or confirmed by someone else), or a new high-confidence proposal appeared, nothing is queued and the response is 409 with code: proposal_changed and proposal_ids; preview again. If a proposal, the entry's currency or its exchange rate changes after the job is queued, the job skips that entry with a reason instead of confirming it.

Currencies: each cost entry is allocated in its own currency, so amounts are never added across currencies. The preview returns totals_by_currency ([{currency_code, total, entries, lines}]); total and currency_code are set only when every counted entry shares one currency (otherwise total is null). The job's results carry amounts_by_currency (currency => amount); amount_allocated is null for a mixed-currency run.

Request​

Responses​

OK

Response Headers
    Content-Type