# Allocait

> Allocait checks a portfolio against the owner's own allocation rules. This site documents the REST API agents call and how to connect Claude, ChatGPT and Codex to it.

- [Introduction](https://docs.allocait.app/index.md): Allocait checks your portfolio against the rules you wrote, and never trades for you.
- [Quickstart](https://docs.allocait.app/quickstart.md): Add your holdings, write your rules, and read where you stand.
- [Connect an agent](https://docs.allocait.app/connect-an-agent.md): Pick how to connect Claude, ChatGPT, Codex, Cursor, another MCP client or your own code.
- [Access levels](https://docs.allocait.app/concepts/access-levels.md): What Read only and Read and change let an agent do
- [Docs for agents](https://docs.allocait.app/docs-for-agents.md): Point an agent at these docs as text, one file, a skill or an MCP server.
- [Allocation bands](https://docs.allocait.app/concepts/allocation-bands.md): The rule that checks how much of your portfolio sits in each asset class.
- [Status words](https://docs.allocait.app/concepts/status-words.md): What within range, below the minimum and above the maximum mean on each surface.
- [Size ranges](https://docs.allocait.app/concepts/position-sizes.md): The rule that caps or floors how large one holding can be.
- [Scenarios](https://docs.allocait.app/concepts/scenarios.md): A named set of rules for one portfolio. You can switch a portfolio between them.
- [Targets](https://docs.allocait.app/concepts/targets.md): A target is the point inside a band that a rebalance aims at.
- [Fund filing](https://docs.allocait.app/concepts/fund-filing.md): How Allocait files a fund into an asset class.
- [Shorts](https://docs.allocait.app/concepts/shorts.md): A negative share count is a short, judged by its own size range.
- [Options](https://docs.allocait.app/concepts/options.md): Options are held at the premium you record, and count zero once expired.
- [Moves](https://docs.allocait.app/concepts/moves.md): Your own setting for how far a holding moves per move of its market.
- [Exposure](https://docs.allocait.app/concepts/exposure.md): A reading beside size, as percents of portfolio value, with no verdict.
- [Action log](https://docs.allocait.app/concepts/action-log.md): The record of changes made to your holdings and cash.
- [Prices](https://docs.allocait.app/concepts/prices.md): An agent supplies every price it uses, and the app shows quotes for reference.
- [App prices](https://docs.allocait.app/concepts/app-prices.md): How the app keeps quotes current and fills a partly priced class.
- [Price freshness](https://docs.allocait.app/concepts/price-freshness.md): What each freshness label means and what shows when a price is missing.
- [Check result](https://docs.allocait.app/concepts/check-result.md): Every field a check returns and how to read it.
- [Standing](https://docs.allocait.app/concepts/standing.md): Where you stand against your own bands and size ranges, as percents and labels.
- [Inputs](https://docs.allocait.app/concepts/inputs.md): Record your own values over time against a symbol.
- [Playbooks](https://docs.allocait.app/concepts/playbooks.md): Read your recorded values per date in one sheet.
- [Watchlists and charts](https://docs.allocait.app/concepts/watchlists-and-charts.md): Group symbols to follow and chart the values you record.
- [Monitors](https://docs.allocait.app/concepts/monitors.md): Check a symbol's daily close against a level or range you record.
- [Labels](https://docs.allocait.app/concepts/labels.md): A label is a name you keep research under, such as an index or a macro series, that Allocait never treats as a security
- [Rules text](https://docs.allocait.app/concepts/rules-text.md): A portable, plain-text format for one scenario's rules.
- [Rules text format](https://docs.allocait.app/concepts/rules-text-format.md): The keys, defaults and class names rules text accepts.
- [ALLOCAIT.md](https://docs.allocait.app/concepts/setup-file.md): ALLOCAIT.md, one reviewed file that sets up scenarios, watchlists, Inputs and a portfolio's playbooks, monitors and charts.
- [Overview](https://docs.allocait.app/claude/overview.md): What the Allocait connector and Claude Code plugin do, and what they never do
- [Install plugin](https://docs.allocait.app/claude/install-plugin.md): Add the Allocait plugin to Claude Code from its public repository
- [Connect Claude](https://docs.allocait.app/claude/connect.md): Connect Claude to your Allocait account by signing in through the connector
- [Use an API key](https://docs.allocait.app/claude/connect-with-api-key.md): Connect Claude Code or another MCP client with an API key
- [Read prompts](https://docs.allocait.app/claude/example-prompts.md): Questions about your own rules, and the Allocait tools they use
- [Write prompts](https://docs.allocait.app/claude/write-prompts.md): Requests that record or change something, and the tools they use
- [MCP tools](https://docs.allocait.app/claude/tools.md): Every MCP tool at a glance, with a link to the page for its area.
- [Portfolio tools](https://docs.allocait.app/claude/tools/portfolios.md): List, read and save portfolios.
- [Holding tools](https://docs.allocait.app/claude/tools/holdings.md): Record holdings and cash that already moved.
- [Check tools](https://docs.allocait.app/claude/tools/checks.md): Check a change and size a holding.
- [Rule tools](https://docs.allocait.app/claude/tools/rules.md): Scenarios, asset classes and rules text.
- [Setup file tools](https://docs.allocait.app/claude/tools/setup-file.md): Preview, apply and undo an ALLOCAIT.md.
- [Watchlist tools](https://docs.allocait.app/claude/tools/watchlists.md): List, save and delete watchlists.
- [Input tools](https://docs.allocait.app/claude/tools/inputs.md): Define Inputs and record values.
- [Playbook and chart tools](https://docs.allocait.app/claude/tools/playbooks-charts.md): Save and read playbooks, and save charts.
- [Monitor tools](https://docs.allocait.app/claude/tools/monitors.md): Save and delete monitors.
- [Action and feedback tools](https://docs.allocait.app/claude/tools/actions-feedback.md): Read the action log and send feedback.
- [Resources and prompts](https://docs.allocait.app/claude/tools/resources-prompts.md): The resources and prompts the server offers beside its tools.
- [MCP errors](https://docs.allocait.app/claude/errors.md): Find the error code you got and what to do about it.
- [Record and price errors](https://docs.allocait.app/claude/errors/records-and-prices.md): Errors for missing records, invalid fields and missing prices.
- [Holding and rule errors](https://docs.allocait.app/claude/errors/holdings-and-rules.md): Errors for holdings, cash, rules and files.
- [Access and limit errors](https://docs.allocait.app/claude/errors/access-and-limits.md): Errors for read-only access, account limits, rate limits and sign-in.
- [Failures](https://docs.allocait.app/claude/errors/failures.md): Retired tools and failures on Allocait's side.
- [Connect ChatGPT](https://docs.allocait.app/chatgpt/connect.md): Add Allocait to ChatGPT by signing in.
- [Connect Codex](https://docs.allocait.app/chatgpt/codex.md): Add Allocait to Codex with the same sign-in.
- [Access](https://docs.allocait.app/chatgpt/access.md): What you allow and how to change or remove it.
- [What is sent](https://docs.allocait.app/chatgpt/data.md): What ChatGPT and Codex send, and why prices come from you.
- [ChatGPT errors](https://docs.allocait.app/chatgpt/errors.md): What a connection or tool error means in ChatGPT or Codex.
- [Write your rules](https://docs.allocait.app/guides/write-your-rules.md): Write your rules as text by hand, with an AI, or from an existing statement.
- [Check a change](https://docs.allocait.app/guides/check-before-you-trade.md): Ask which of your rules a change would put outside range, with prices you supply.
- [Plan a rebalance](https://docs.allocait.app/guides/plan-a-rebalance.md): See how far each class is from its band and the amounts that close the gap.
- [Size a position](https://docs.allocait.app/guides/size-a-position.md): Work out a share count that fits a holding's size range.
- [Import holdings](https://docs.allocait.app/guides/import-holdings.md): Bring in holdings from a pasted list or a file.
- [Update holdings](https://docs.allocait.app/guides/update-holdings.md): Keep your holdings and cash in sync in the app.
- [Update with an agent](https://docs.allocait.app/guides/update-with-an-agent.md): Sync holdings and cash through MCP tools or the REST API.
- [Webhooks](https://docs.allocait.app/guides/webhooks.md): Get a signed notification when a portfolio moves outside its ranges or a monitor confirms.
- [Agent feedback](https://docs.allocait.app/guides/agent-feedback.md): How an agent reports a gap in the API, MCP server or docs.
- [Send feedback](https://docs.allocait.app/guides/send-feedback.md): Which of support, early access and agent feedback to use.
- [Scheduled brief](https://docs.allocait.app/guides/scheduled-brief.md): Have an agent report what changed in your book on a schedule.
- [Check from a script](https://docs.allocait.app/recipes/run-a-check-from-a-script.md): Call the check from your own code with prices you supply.
- [Other MCP clients](https://docs.allocait.app/recipes/use-with-any-mcp-client.md): Connect any MCP client with an API key and call check_trades.
- [API overview](https://docs.allocait.app/api/introduction.md): What the REST API does and where to start.
- [Endpoints by task](https://docs.allocait.app/api/endpoints-by-task.md): Which endpoint to call for each job.
- [API quickstart](https://docs.allocait.app/api/quickstart.md): Create a key, read a portfolio, run a check and handle a refusal.
- [Authentication](https://docs.allocait.app/api/authentication.md): API keys, permissions and scope.
- [Conventions](https://docs.allocait.app/api/conventions.md): Ids, field types, Content-Type and body parsing.
- [Rate limits](https://docs.allocait.app/api/rate-limits.md): Request budgets, headers and the 429 response.
- [Idempotency](https://docs.allocait.app/api/idempotency.md): Make a cash movement retry safe.
- [API errors](https://docs.allocait.app/api/errors.md): The error envelope and the HTTP status codes.
- [Error codes](https://docs.allocait.app/api/error-codes.md): Every REST error code and its common causes.
- [Webhook events](https://docs.allocait.app/api/webhook-events.md): The events a webhook sends and the fields in each payload.
- [Verify deliveries](https://docs.allocait.app/api/webhook-verification.md): Check the signature on each webhook delivery.
- [Check compliance with your prices](https://docs.allocait.app/api-reference/checks/check-compliance-with-your-prices.md): Returns compliance violations using the prices you provide: every rule the app checks. `class_violations` lists each asset class outside its allocation band (Cash included, and a class you hold nothing in at 0%), `size_violations` each holding outside its class's position size range, and `violations…
- [Pre-flight check of a proposed allocation plan](https://docs.allocait.app/api-reference/checks/pre-flight-check-of-a-proposed-allocation-plan.md): Given a proposed `{symbol: target_pct}` map, returns whether each asset-class rollup satisfies its allocation band and each proposed holding satisfies its class's position size range. Also reports `sum_ok` (allocations must sum to 100) and `unknown_symbols` (symbols not held and not given a class).
- [Check a proposed change against the rules](https://docs.allocait.app/api-reference/checks/check-a-proposed-change-against-the-rules.md): States which of the user's own rules a proposed change puts outside its range or leaves further outside, using prices you supply. It reads and writes nothing, decides nothing and needs only `read`, so a Core account's key can call it. A result inside every range does not say a change is advisable. A…
- [Preview rebalance amounts with your prices](https://docs.allocait.app/api-reference/checks/preview-rebalance-amounts-with-your-prices.md): Returns pro rata amounts that would move out-of-compliance classes toward their aim: the class rule's own Target % when set, otherwise the midpoint of its allocation band, using the prices you provide. Rows are ordered largest-dollar-value first. This is arithmetic on the user's own rules, not a rec…
- [Get portfolio summary](https://docs.allocait.app/api-reference/portfolios/get-portfolio-summary.md): Returns what the user recorded for a portfolio, unpriced: name, currency, position count, and active scenario. No total value. Allocait never returns a value computed from its own stored quote on this surface (ADR-036). For a priced total, POST /portfolio/snapshot with prices.
- [List portfolios](https://docs.allocait.app/api-reference/portfolios/list-portfolios.md): Convenience alias for `GET /portfolio/summary` without a `portfolio_id`. Returns the `{data, has_more}` list envelope, one summary per portfolio.
- [Create a portfolio with an initial cash position](https://docs.allocait.app/api-reference/portfolios/create-a-portfolio-with-an-initial-cash-position.md): Creates a portfolio and its cash position in one transaction. Most other calls take a `portfolio_id`. A new account already holds a `Main Portfolio`, so read it with `GET /portfolios` first and use this call for an additional portfolio.
- [Delete a portfolio](https://docs.allocait.app/api-reference/portfolios/delete-a-portfolio.md): Cascades to the portfolio's positions, actions, monitors, playbooks, charts and compliance history. Scenarios are user-scoped, not portfolio-scoped, and are never touched. There is no undo.
- [Change a portfolio's name, description, active scenario or Allow shorts](https://docs.allocait.app/api-reference/portfolios/change-a-portfolios-name-description-active-scenario-or-allow-shorts.md): Every field is optional. A field you send replaces the stored value, and a field you leave out keeps its value; send `description: null` to clear the description. `active_scenario_id` switches the scenario the portfolio is checked against, in the app and on this API alike. The same function backs th…
- [Get a portfolio snapshot (unpriced)](https://docs.allocait.app/api-reference/portfolios/get-a-portfolio-snapshot-unpriced.md): This is the discovery call: unpriced. Returns a single denormalized blob with the portfolio, the holdings in shares, the active scenario's rules, the recorded levels, and monitor configuration. `current_price`, `position_value` and `position_pct` on every non-cash position, `total_value`, `exposure`…
- [Get a portfolio snapshot with your prices](https://docs.allocait.app/api-reference/portfolios/get-a-portfolio-snapshot-with-your-prices.md): Same blob as GET /portfolio/snapshot, priced as far as your `prices` map reaches, no further. A position you priced keeps its value; one you did not comes back null. `position_pct`, `total_value`, `exposure`, `compliance` (and `rebalance`, when you ask for it) need every non-cash position covered, b…
- [List positions](https://docs.allocait.app/api-reference/holdings-and-cash/list-positions.md): Returns what the user recorded for every position in a portfolio: symbol, shares, asset class, Moves. Unpriced: no current price, value, or day change; Allocait never returns a value computed from its own stored quote on this surface (ADR-036). Ordered by symbol. For values, POST /portfolio/snapshot…
- [Record one holding's new total shares](https://docs.allocait.app/api-reference/holdings-and-cash/record-one-holdings-new-total-shares.md): Sets one holding to its new TOTAL share count and leaves every other holding alone. It opens a holding you don't own yet, and `shares: 0` closes one. The cash difference settles atomically against the portfolio's cash position: buying debits cash, selling credits it, and insufficient cash is rejecte…
- [Calculate a target share count for a position](https://docs.allocait.app/api-reference/holdings-and-cash/calculate-a-target-share-count-for-a-position.md): Pure calculation, no portfolio ownership involved: pass in current holding, price, portfolio value, and a sizing mode and get back the target share count, its cash impact, and whether it is affordable. MINIMUM, BALANCED and MAXIMUM size one holding to the bottom, midpoint or top of the position size…
- [Reconcile a portfolio's holdings to an absolute desired state](https://docs.allocait.app/api-reference/holdings-and-cash/reconcile-a-portfolios-holdings-to-an-absolute-desired-state.md): "Make Allocait match what I hold": the primary agent write (ADR-019). Pass the FULL desired set of non-cash holdings; anything currently held that is not listed is closed. Every change routes through the same RPC the app UI uses (position_create_with_cash/ position_update_with_cash/position_close),…
- [Deposit or withdraw cash from a portfolio](https://docs.allocait.app/api-reference/holdings-and-cash/deposit-or-withdraw-cash-from-a-portfolio.md): Recorded as an action with `symbol: "CASH"`; `GET /actions` lists it. The response names the action and the new cash balance only. A withdrawal larger than the cash balance is refused with `409` and `error_code: INSUFFICIENT_CASH`. The check runs on the server under a lock. This records the change i…
- [List watchlists](https://docs.allocait.app/api-reference/watchlists/list-watchlists.md): Returns every watchlist owned by this key's user, with each one's item count.
- [Create a watchlist](https://docs.allocait.app/api-reference/watchlists/create-a-watchlist.md): Creates a watchlist for the caller, empty or with `items` in display order. A caller has at most 50 watchlists, and a watchlist at most 200 symbols (`TIER_LIMIT_EXCEEDED`).
- [Change a watchlist's name and symbols in one call](https://docs.allocait.app/api-reference/watchlists/change-a-watchlists-name-and-symbols-in-one-call.md): Changes the name, the symbols, or both, in one transaction. The same function backs the MCP server's `save_watchlist`.
- [Delete a watchlist](https://docs.allocait.app/api-reference/watchlists/delete-a-watchlist.md): Cascades to the watchlist's items. Playbooks, monitors and charts that drew their symbols from it lose that source, and the response names them in `dependents`. There is no undo.
- [Rename a watchlist](https://docs.allocait.app/api-reference/watchlists/rename-a-watchlist.md): **Requires the API key to have the `write` permission.**
- [List items in a watchlist](https://docs.allocait.app/api-reference/watchlists/list-items-in-a-watchlist.md)
- [Add a symbol to a watchlist](https://docs.allocait.app/api-reference/watchlists/add-a-symbol-to-a-watchlist.md): Fails if the symbol is already in this watchlist. The symbol is uppercased and trimmed before the duplicate check. With no `asset_class_id` key, a symbol that Allocait's symbol catalog carries is filed under the class the app's symbol search gives it (ADR-236); one it does not carry stays unclassed.…
- [Reorder a watchlist's items](https://docs.allocait.app/api-reference/watchlists/reorder-a-watchlists-items.md): Sets each item's `sort_order` in one statement. `item_ids` and `sort_orders` are parallel arrays: `item_ids[i]` gets `sort_orders[i]`. Capped at 500 items per call, like every bulk write.
- [Remove a symbol from a watchlist](https://docs.allocait.app/api-reference/watchlists/remove-a-symbol-from-a-watchlist.md): **Requires the API key to have the `write` permission.**
- [List input (tracked-value) definitions](https://docs.allocait.app/api-reference/inputs/list-input-tracked-value-definitions.md): Input definitions are user-recorded time series (a support level, a macro reading, anything logged by hand), the raw material Playbooks and Monitors read from.
- [Create an Input (tracked-value) definition](https://docs.allocait.app/api-reference/inputs/create-an-input-tracked-value-definition.md): Defines a new tracked value's shape (name, data_type, display_mode, scope, chart_role, color, carry_forward, optional) and, for a CHOICE input, its `options` in the same transaction. Requires the data_charts feature entitlement (an Advanced plan, trial included). Complements `POST /inputs/entries`,…
- [Change an Input definition and its options in one call](https://docs.allocait.app/api-reference/inputs/change-an-input-definition-and-its-options-in-one-call.md): Patches the definition and replaces a CHOICE input's options by value, in one transaction. The same function backs the MCP server's `save_input`. A field you leave out keeps its value, and `description: null` clears it. `carry_forward: false` and `optional: false` are values, not omissions: each tur…
- [Delete an Input definition](https://docs.allocait.app/api-reference/inputs/delete-an-input-definition.md): Permanently deletes an Input definition and cascades every recorded value against it. The input is also taken out of the playbooks and charts that use it, and the response names them in `dependents`. Refused with `IN_USE` while a monitor uses it; the refusal names the monitors in `monitors`. There i…
- [Update an Input definition](https://docs.allocait.app/api-reference/inputs/update-an-input-definition.md): Every field is optional and independently no-op when omitted. `scope` can only change until the first value has been recorded for this definition (ADR-016); it is rejected once one exists. `chart_role` of `OVERLAY` requires `scope` of `SYMBOL` (ADR-013). `carry_forward` ("keep until changed"), `opti…
- [List recorded values for one input](https://docs.allocait.app/api-reference/inputs/list-recorded-values-for-one-input.md): Ordered most-recent-date first, then by symbol. One page at a time: `limit` (default 100, max 500) and `cursor` (a row offset), with `has_more` true while rows remain. An input records a value per symbol per day, so the list grows without a bound; `has_more` says when a page is not the end.
- [List dropdown options for one CHOICE input](https://docs.allocait.app/api-reference/inputs/list-dropdown-options-for-one-choice-input.md): Ordered by sort_order.
- [Add a dropdown option](https://docs.allocait.app/api-reference/inputs/add-a-dropdown-option.md): Adds one option to a CHOICE-type Input definition's dropdown list. Rejects a case-insensitive duplicate value within the same definition, and rejects a definition whose `data_type` isn't `CHOICE`.
- [Remove a dropdown option](https://docs.allocait.app/api-reference/inputs/remove-a-dropdown-option.md): Never cascades anything: recorded values store each reading as freeform text, not a reference to the option row.
- [Rename or reorder a dropdown option](https://docs.allocait.app/api-reference/inputs/rename-or-reorder-a-dropdown-option.md): Both fields optional and independently no-op when omitted.
- [Record (upsert) one or more custom input values](https://docs.allocait.app/api-reference/inputs/record-upsert-one-or-more-custom-input-values.md): Upserts on `(input_definition_id, symbol, date)`: recording the same day in a later call updates it rather than creating a duplicate, and `value: null` deletes that day's entry. One call may name each `(input_definition_id, symbol, date)` once, a `null` entry included; a repeat is `INVALID_INPUT` (4…
- [Delete one or more recorded input values](https://docs.allocait.app/api-reference/inputs/delete-one-or-more-recorded-input-values.md): Removes the "recorded values" half of an Input, the counterpart to this same path's `POST`. Pass a single id in a one-element array to delete just one. An id the caller does not own is silently skipped rather than erroring; `deleted_count` reflects only the rows actually removed. There is no undo.
- [List playbooks](https://docs.allocait.app/api-reference/playbooks/list-playbooks.md)
- [Create a playbook](https://docs.allocait.app/api-reference/playbooks/create-a-playbook.md): A playbook is a named symbol list plus a template of input columns to record/review values against, for one portfolio. Requires the playbooks feature entitlement (an Advanced plan, trial included). `source_watchlist_id` is required when `source_type` is `watchlist` and must belong to the caller; `cu…
- [Resolve a playbook's symbols and its input values for a date](https://docs.allocait.app/api-reference/playbooks/resolve-a-playbooks-symbols-and-its-input-values-for-a-date.md): Resolves the playbook's source_type into a concrete symbol list (positions held, a watchlist's items, or its custom_symbols array) and returns the value each configured input shows for the given date, per symbol.
- [Delete a playbook](https://docs.allocait.app/api-reference/playbooks/delete-a-playbook.md): Permanently delete a playbook. There is no undo.
- [Update a playbook](https://docs.allocait.app/api-reference/playbooks/update-a-playbook.md): Every field is optional and independently no-op when omitted. `source_watchlist_id` and every `input_columns` id must belong to the caller.
- [List condition monitors and their recorded levels](https://docs.allocait.app/api-reference/monitors/list-condition-monitors-and-their-recorded-levels.md): Returns each condition monitor's configuration and the user's recorded level(s) for its resolved symbol. Unpriced: no price, day change, or where-price-sits reading. Allocait never returns a value computed from its own stored quote on this surface (ADR-036). A priced reading is `PortfolioSnapshot.mo…
- [Create a condition monitor](https://docs.allocait.app/api-reference/monitors/create-a-condition-monitor.md): A condition monitor watches a recorded level (or range, in RANGE mode) against a symbol source. Requires the data_monitors feature entitlement (an Advanced plan, trial included). `input_1_id` (and `input_2_id` for RANGE mode) must be Input definitions belonging to the caller. Allocait computes no bo…
- [Delete a condition monitor](https://docs.allocait.app/api-reference/monitors/delete-a-condition-monitor.md): Permanently delete a condition monitor. There is no undo.
- [Update a condition monitor](https://docs.allocait.app/api-reference/monitors/update-a-condition-monitor.md): Every field is optional and independently no-op when omitted. `input_1_id`, `input_2_id`, and `source_watchlist_id` must belong to the caller when provided.
- [List scenarios](https://docs.allocait.app/api-reference/rules/list-scenarios.md): Scenarios are the environments Position Rules and each portfolio's `active_scenario_id` are defined against.
- [Create a scenario](https://docs.allocait.app/api-reference/rules/create-a-scenario.md): Scenarios are user-scoped, not portfolio-scoped: there is no `portfolio_id` here. Enforces the caller's tier scenario limit (seed scenarios are exempt from the count).
- [Delete a scenario](https://docs.allocait.app/api-reference/rules/delete-a-scenario.md): Cascades to the scenario's position rules and unsets it wherever it is a portfolio's (or the caller's) active scenario. There is no undo.
- [Rename a scenario and/or replace its description](https://docs.allocait.app/api-reference/rules/rename-a-scenario-andor-replace-its-description.md): Unlike `PATCH /portfolios/{id}` and `PATCH /watchlists/{id}`, both fields are optional and independently no-op when omitted: pass only `name` to rename without touching the description, or only `description` to edit the description without renaming. Omitting `description` leaves it unchanged; send `…
- [List asset classes](https://docs.allocait.app/api-reference/rules/list-asset-classes.md)
- [Create a custom asset class](https://docs.allocait.app/api-reference/rules/create-a-custom-asset-class.md): Rejects a duplicate name against both the caller's own classes and every system class (Cash, Equities, Fixed Income, etc.), case-insensitive. `is_system` is always `false` for a class created this way.
- [Delete a custom asset class](https://docs.allocait.app/api-reference/rules/delete-a-custom-asset-class.md): Refuses a system class or Cash (`INVALID_INPUT`), and a class that any position, watchlist item, or position rule still references (`IN_USE`, naming them). Reassign those first. There is no undo.
- [Rename an asset class and/or replace its description](https://docs.allocait.app/api-reference/rules/rename-an-asset-class-andor-replace-its-description.md): Both fields are optional and independently no-op when omitted: pass only `name` to rename without touching the description, or only `description` to edit the description without renaming. Omitting `description` leaves it unchanged; send `description: null` to clear it, as `PATCH /portfolios/{id}` do…
- [List position rules (allocation band and position size per asset class)](https://docs.allocait.app/api-reference/rules/list-position-rules-allocation-band-and-position-size-per-asset-class.md): One row per asset class per scenario. Each row carries the allocation band on the asset class total (`min_position_pct` / `max_position_pct`, optional `target_allocation_pct`) that `/compliance/check` and `/rebalance/preview` evaluate against, and an optional position size range (`size_min_pct` / `s…
- [Set one asset class's rule in a scenario](https://docs.allocait.app/api-reference/rules/set-one-asset-classs-rule-in-a-scenario.md): Changes one class's band, target, size range or short size range and keeps every other rule in the scenario. The same function backs the MCP server's `save_class_rule` and runs the checks the app's one-rule dialog runs. A field you leave out keeps its value.
- [Reconcile a scenario's position rules to an absolute desired state](https://docs.allocait.app/api-reference/rules/reconcile-a-scenarios-position-rules-to-an-absolute-desired-state.md): The same "make Allocait match what I declared" shape `/portfolios/ {id}/positions/apply` uses, applied to the rules themselves rather than the holdings (ADR-019-style agent write). Pass the FULL desired set of rules for the scenario; any asset class not listed has its existing rule removed.
- [Get a scenario's rules as rules text](https://docs.allocait.app/api-reference/rules/get-a-scenarios-rules-as-rules-text.md): Renders the scenario's current position rules as canonical rules text (`rules_text`) and as structured rules (`rules`), both in class display order. `rules_text` round-trips with `POST /scenarios/{id}/rules`: sending it straight back unchanged reports every class `unchanged`, nothing `added` or `rem…
- [Import rules text into a scenario's rules, or preview it with dry_run](https://docs.allocait.app/api-reference/rules/import-rules-text-into-a-scenarios-rules-or-preview-it-with-dry_run.md): Parses `rules_text` with the same shared module the app and `GET /rules/spec` use, then reconciles the scenario's rules to exactly what it describes: the same absolute-state shape `POST /scenarios/{id}/position-rules/apply` uses, but by class NAME rather than `asset_class_id`. Each name resolves ser…
- [List rules restore points, newest first](https://docs.allocait.app/api-reference/rules/list-rules-restore-points-newest-first.md): One row per import or restore (ADR-050), holding the scenario's rules from immediately before that write. An undo point, not a change log (past values per class rule are `rule_changes` on `GET /scenarios/{id}/rules`). Allocait keeps no reasoning, and this list is already capped to the most recent 20…
- [Undo an import or an earlier restore](https://docs.allocait.app/api-reference/rules/undo-an-import-or-an-earlier-restore.md): Re-applies the rules a restore point saved, by `asset_class_id`: the same absolute-state reconciliation `POST /scenarios/{id}/rules` and `POST /scenarios/{id}/position-rules/apply` use. A saved rule whose class no longer exists, or is no longer this key's to use, is skipped and named in `skipped` ra…
- [Get the rules text format spec, ready-to-import examples, and copy/paste AI prompts](https://docs.allocait.app/api-reference/rules/get-the-rules-text-format-spec-ready-to-import-examples-and-copypaste-ai-prompts.md): Everything an agent needs to learn the rules text format from the API itself, with no other document to fetch: the full spec as markdown (`spec`), four ready-to-import example files spanning a beginner's 3-class file to a converted advisor IPS (`examples`), and copy/paste prompts for writing, conver…
- [List a portfolio's actions](https://docs.allocait.app/api-reference/actions/list-a-portfolios-actions.md): Ordered most-recent first.
- [Delete one or more actions](https://docs.allocait.app/api-reference/actions/delete-one-or-more-actions.md): Removes rows from the record of a portfolio's position and cash changes. Holdings and cash stay as they are. Pass a single id in a one-element array to delete just one. An id the caller does not own, or one already gone, comes back in `not_found` rather than failing the call; `deleted_ids` lists the…
- [Edit an action's comment](https://docs.allocait.app/api-reference/actions/edit-an-actions-comment.md): Edits only the comment on one action/decision row from the audit trail; trade and cash data itself is immutable. Pass `null` to clear an existing comment.
- [List your support requests, newest first](https://docs.allocait.app/api-reference/support-and-feedback/list-your-support-requests-newest-first.md)
- [File a support request](https://docs.allocait.app/api-reference/support-and-feedback/file-a-support-request.md): A bug report, billing question, feature request, or anything else, the same form the in-app "Contact support" dialog uses. `source` is always recorded as `agent` for requests filed this way, and the team's notification carries only the category, the source and the request id, never the subject or me…
- [List your agent feedback, newest first](https://docs.allocait.app/api-reference/support-and-feedback/list-your-agent-feedback-newest-first.md)
- [Report feedback about the agent surface itself](https://docs.allocait.app/api-reference/support-and-feedback/report-feedback-about-the-agent-surface-itself.md): Feedback about Allocait's own tools, routes or docs: a tool that returned an unexpected error, a description that is ambiguous, a capability that is missing, or docs that are wrong. This is not a user's own support request: use POST /support-requests for anything about the user's account, billing, o…
- [List saved charts for a portfolio](https://docs.allocait.app/api-reference/charts/list-saved-charts-for-a-portfolio.md)
- [Create a saved chart](https://docs.allocait.app/api-reference/charts/create-a-saved-chart.md): Saves a chart configuration for a portfolio: which symbols to plot, which OVERLAY Input definitions overlay it, the date range, and overlay display. Requires the data_charts feature entitlement (an Advanced plan, trial included). `input_ids`/`level_marker_ids` must be Input definitions belonging to…
- [Delete a saved chart](https://docs.allocait.app/api-reference/charts/delete-a-saved-chart.md): Permanently delete a saved chart. There is no undo.
- [Update a saved chart](https://docs.allocait.app/api-reference/charts/update-a-saved-chart.md): Every field is optional and independently no-op when omitted. Changing `source_type` re-validates and normalizes the fields specific to the new source, e.g. moving away from `single` clears `ticker_symbol`, moving to `watchlist` requires `source_watchlist_id`. `clear_ticker_symbol` moves a single-sy…
- [Get what the app opens to, and the theme](https://docs.allocait.app/api-reference/preferences/get-what-the-app-opens-to-and-the-theme.md): Every page in the app (Dashboard, Compliance, Allocation, Watchlists, Playbooks, Monitors) falls back to this row to decide what to show by default.
- [Set which portfolio/watchlist/chart/playbook/monitor the app shows, or the theme](https://docs.allocait.app/api-reference/preferences/set-which-portfoliowatchlistchartplaybookmonitor-the-app-shows-or-the-theme.md): `active_scenario_id` here is a display fallback only. The app and every agent read the portfolio's own active scenario first, so to switch the scenario compliance is judged against, use `PATCH /portfolios/{id}` with `active_scenario_id`.
- [List webhook endpoints](https://docs.allocait.app/api-reference/webhooks/list-webhook-endpoints.md): Never includes the signing secret; that is only ever returned once, by `createWebhook`, at registration time (ADR-005).
- [Register a webhook endpoint](https://docs.allocait.app/api-reference/webhooks/register-a-webhook-endpoint.md): Register a URL to receive signed event notifications: the same registration the app's Settings > Webhooks tab makes. `url` must start with `https://`. Returns the HMAC-SHA256 signing secret once, in this response only; it is never readable again afterward. There is no rotate-in-place: delete and re-…
- [Delete a webhook endpoint](https://docs.allocait.app/api-reference/webhooks/delete-a-webhook-endpoint.md): Permanently delete a webhook endpoint. There is no undo.
- [Update a webhook endpoint](https://docs.allocait.app/api-reference/webhooks/update-a-webhook-endpoint.md): Every field is optional and independently no-op when omitted. Never touches the signing secret. There is no way to rotate it through this endpoint. Changing an endpoint needs the Advanced plan, like creating one (`error_code: "FEATURE_NOT_AVAILABLE"` otherwise).
- [Export your watchlists, Inputs, playbooks, monitors and saved charts as one JSON document](https://docs.allocait.app/api-reference/setup-file/export-your-watchlists-inputs-playbooks-monitors-and-saved-charts-as-one-json-document.md): This is the account's own definitions as JSON, not an ALLOCAIT.md file: `POST /setup/preview` reads the Markdown file, and does not accept this document.
- [Preview an ALLOCAIT.md setup file](https://docs.allocait.app/api-reference/setup-file/preview-an-allocaitmd-setup-file.md): Shows what the file would add to the account and what stays the user's, and writes nothing. An ALLOCAIT.md is one Markdown file with a YAML frontmatter block: scenarios with their rules, custom asset classes, watchlists, Inputs, and one portfolio's playbooks, monitors and charts. It holds definition…
- [Apply a previewed ALLOCAIT.md setup file](https://docs.allocait.app/api-reference/setup-file/apply-a-previewed-allocaitmd-setup-file.md): Adds and updates exactly what the preview with this `digest` showed, through the same save functions the app uses, and records a receipt (`receipt_id`) that `POST /setup/receipts/{id}/undo` reads. It never writes holdings, cash, prices, recorded values, the active scenario, a playbook's date or sort…
- [List the account's setup file receipts](https://docs.allocait.app/api-reference/setup-file/list-the-accounts-setup-file-receipts.md): One receipt per applied import, newest first, at most 100. Only the newest receipt of a file can be undone (`can_undo`); an older one is refused with `IN_USE`. A receipt is removed when it is undone, and the app keeps the newest three of each file. A receipt holds no file text. **Needs the `read` pe…
- [Undo an applied setup file, or preview the undo](https://docs.allocait.app/api-reference/setup-file/undo-an-applied-setup-file-or-preview-the-undo.md): Removes what the import created that the user has not changed or used since and nothing else uses, puts back what it updated, and keeps the rest, naming each kept item and why. Recorded values, holdings, cash and the active scenario are never touched. The receipt is removed once the undo has run.
- [Support](https://docs.allocait.app/support.md): How to get help.
- [Security](https://docs.allocait.app/security-and-privacy.md): What Allocait does and never does with your data
- [Keys and apps](https://docs.allocait.app/security/keys-and-apps.md): How API keys and connected apps are stored, scoped and revoked.
- [Report a vulnerability](https://docs.allocait.app/security/disclosure.md): How to report a security issue.

## OpenAPI Specs

- [openapi](/openapi.yaml)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.