Bulk Allocate Cost Entries with AI
POST/api/cost-entries/ai-allocation/bulk
Runs AI allocation across several cost entries at once.
purchase-orders:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body:
action(string, required) —proposestarts an AI allocation batch for every entry that has source lines (entries without any are skipped);confirm_highconfirms 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
messageand a machinecode: 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 theai.usepermission.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_highwithout the preview'sbatchesor with a batch missing itsproposals).
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
- 200
- 202
- 401
- 403
- 409
- 422
- 429
OK
Response Headers
Accepted
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Conflict
Response Headers
Unprocessable Content
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.