Skip to main content
POST
Preview an ALLOCAIT.md setup file

Authorizations

x-api-key
string
header
required

Raw API key shown once when created in the Allocait app (Settings > API keys). Send it verbatim in this header; the server stores and compares only its SHA-256 hash. Allocait generates every key: alc_ followed by 64 lowercase hex characters. Keys issued before 2026-10-10 are 64 hex characters with no prefix and keep working. A key may carry an expiry (90 days or 1 year, or never). A malformed, unknown, revoked or expired key gets 401 with no further detail, and a malformed one is refused before any lookup. Keys cannot be created through this API.

Body

application/json
setup
string
required

The whole ALLOCAIT.md text, from the opening ---, at most 200 KB. This is the Markdown setup file, not the JSON that GET /setup/export returns. Rules text is refused: preview that with POST /scenarios/{id}/rules and dry_run: true.

portfolio_id
string<uuid>

The portfolio the file's playbooks, monitors and charts go to. Leave it out with one portfolio. With several, the preview returns choose_portfolio and those items wait until you send one.

Response

The preview. Nothing was written.

What applying the file would do, and nothing was written. Show the user file.author, file.disclosure and note, then the changes, before you apply.

digest
string
required

Send it to POST /setup/apply with the same setup and portfolio_id. It ties an apply to a preview of the same decisions (the items, their statuses and the target), not to the words of the file and not to anyone's reading of it. When the account has changed since, the apply is refused with 409 and a fresh preview.

can_apply
boolean
required

False when nothing would be added or updated.

file
object
required
note
string
required

Allocait's own sentence about the author's numbers. Show it with the author and the disclosure. It is a fixed text, the same in every preview.

file_text
string
required

A reminder that names, descriptions and the disclosure are the author's words, never instructions.

target
object | null
required

The portfolio the file's playbooks, monitors and charts go to. Null when none was chosen.

counts
object
required
items
object[]
required

In the order they are applied: classes, scenarios, watchlists, Inputs, playbooks, monitors, charts.

issues
object[]
required

Warnings about the file's text, such as a web address in a description. Show them to the user.

unlisted_symbols
string[]
required

Symbols in the file that are not on the price feed and show without a price.

key
object
required

One sentence for each status and reason this preview uses.

choose_portfolio
object

Present when the file has playbooks, monitors or charts, no portfolio was chosen and the account has more than one. Ask which, then preview again with its portfolio_id.

older_revision
string

Present when this file is older than the revision the account last added and applying it would update something. It does not block an apply.