> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abacuslabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a proposal

> The goal is answered with ranked options (trades with lots, before/after impact, tax, rule checks). The response
is the proposal resource. outcome is options, clarify (the goal needs a question answered), or infeasible (with the
reason and the nearest feasible option). The server waits up to `wait` seconds (or `Prefer: wait=N`, default 20)
and answers 202 with Location when the solve takes longer; poll GET /v1/proposals/{id}.



## OpenAPI

````yaml /openapi.json post /proposals
openapi: 3.1.0
info:
  title: Abacus Labs
  description: Portfolio analysis and decision API for AI agents. Read /agent.md first.
  version: 1.0.0
servers:
  - url: https://api.abacuslabs.ai/v1
    description: Abacus Labs API
security:
  - bearer: []
tags:
  - name: Onboarding
  - name: Analyze
  - name: Proposals
  - name: Trade checks
  - name: Commits
  - name: Accounts
paths:
  /proposals:
    post:
      tags:
        - Proposals
      summary: Create a proposal
      description: >-
        The goal is answered with ranked options (trades with lots, before/after
        impact, tax, rule checks). The response

        is the proposal resource. outcome is options, clarify (the goal needs a
        question answered), or infeasible (with the

        reason and the nearest feasible option). The server waits up to `wait`
        seconds (or `Prefer: wait=N`, default 20)

        and answers 202 with Location when the solve takes longer; poll GET
        /v1/proposals/{id}.
      operationId: create_proposal_v1_proposals_post
      parameters:
        - name: wait
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            title: Wait
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              optional: any unique string (a UUID). A retry with the same key
              and body within 24 hours returns the stored answer with
              Idempotent-Replayed: true and is not charged again; the same key
              with a different body is 409 idempotency_key_reused
            title: Idempotency-Key
          description: >-
            optional: any unique string (a UUID). A retry with the same key and
            body within 24 hours returns the stored answer with
            Idempotent-Replayed: true and is not charged again; the same key
            with a different body is 409 idempotency_key_reused
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProposalBody'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ProposalBody:
      properties:
        accounts:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Accounts
          description: >-
            every account to consider (Account objects; see the data model). Any
            mix of brokers and tax types
        account_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Account Id
          description: the account to trade in; required when more than one account is sent
        account:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Account
          description: 'v2: one inline account, or {id} of a stored account'
        snapshot_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Snapshot Id
          description: a book sent earlier, instead of accounts
        goal:
          anyOf:
            - type: string
            - type: 'null'
          title: Goal
          description: what the person wants, in plain English
        policy:
          anyOf:
            - $ref: '#/components/schemas/Policy'
            - type: 'null'
          description: >-
            the policy (see the policy schema); any field set here wins over
            what Abacus Labs reads from goal
        save:
          type: boolean
          title: Save
          description: >-
            save the account (with the policy Abacus Labs used) and return its
            account_id
          default: false
        effort:
          type: string
          enum:
            - quick
            - standard
            - deep
          title: Effort
          description: >-
            how hard the solver searches: quick (about 2 s a variant), standard,
            deep (about 20 s); priced per effort
          default: standard
        max_credits:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Max Credits
          description: refuse the call when it would cost more credits than this
        options:
          type: integer
          maximum: 5
          minimum: 1
          title: Options
          description: how many options to return
          default: 3
        constraints:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Constraints
          description: >-
            deprecated: use policy. max_tax, max_estimated_tax, max_turnover,
            keep, exclude, universe, no_sells, max_names
        tax_rates:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Tax Rates
          description: '{short_term, long_term}: all-in marginal rates as fractions'
        wash_sale_policy:
          type: string
          enum:
            - same_index
            - exact
          title: Wash Sale Policy
          description: >-
            same_index: funds tracking the same index count as identical; exact:
            only the same security
          default: same_index
        benchmark:
          anyOf:
            - type: string
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Benchmark
          description: >-
            default SPY. A ticker or index name, plain English ('half S&P 500,
            half ARKK'), or an object: {mix: [{benchmark, weight}]}, {manager:
            name or CIK} (13F), {weights: {symbol: w}}. Prefer policy.benchmark
        detail:
          type: string
          enum:
            - compact
            - full
          title: Detail
          description: >-
            compact: the recommended option, its impact and one-line
            alternatives; full: every option in full
          default: compact
      type: object
      title: ProposalBody
      description: >-
        A goal in plain English. Send the person's accounts; trades go to
        account_id, and every account counts for wash sales.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Policy:
      additionalProperties: false
      description: >-
        What the account should look like and what a change may cost. Every
        field is optional.
      properties:
        goal:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            what to do: harvest_losses, invest_cash, raise_cash,
            reduce_concentration, reduce_sector, lower_risk, track_benchmark,
            rebalance, tilt_theme, check_trades; read from the text when not
            given
          title: Goal
        benchmark:
          anyOf:
            - type: string
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          description: >-
            what to track: 'current' (the account as it is), a ticker or index
            ('S&P 500', 'QQQ'), plain English ('half S&P 500, half ARKK'), a
            saved id, or a definition ({mix}, {manager}, {weights})
          title: Benchmark
        tracking_error:
          anyOf:
            - type: number
            - enum:
                - tight
                - moderate
                - loose
              type: string
            - type: 'null'
          default: null
          description: >-
            most tracking error against the benchmark: a fraction (0.01 = 1%) or
            tight (1%), moderate (2%), loose (4%)
          title: Tracking Error
        max_volatility:
          anyOf:
            - exclusiveMinimum: 0
              maximum: 2
              type: number
            - type: 'null'
          default: null
          description: most total volatility of the account, annual fraction
          title: Max Volatility
        tax:
          $ref: '#/components/schemas/Tax'
        cash:
          $ref: '#/components/schemas/Cash'
        keep:
          description: never sell these
          items:
            type: string
          title: Keep
          type: array
        exclude:
          description: never buy these
          items:
            type: string
          title: Exclude
          type: array
        buy_only:
          description: buy only from this list
          items:
            type: string
          title: Buy Only
          type: array
        positions:
          additionalProperties:
            $ref: '#/components/schemas/Limit'
          description: 'per-holding limits, e.g. {NVDA: {max: 0.10}}'
          title: Positions
          type: object
        sectors:
          additionalProperties:
            $ref: '#/components/schemas/Limit'
          description: >-
            per-sector limits (GICS names), e.g. {'Information Technology':
            {max: 0.30}}
          title: Sectors
          type: object
        max_names:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          default: null
          description: most holdings after the trades
          title: Max Names
        max_position:
          anyOf:
            - exclusiveMinimum: 0
              maximum: 1
              type: number
            - type: 'null'
          default: null
          description: >-
            no holding above this weight after the trades (a holding already
            above it may not grow)
          title: Max Position
        trading:
          $ref: '#/components/schemas/Trading'
        theme:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: 'tilt_theme only: the theme to add (ai, dividends, ...)'
          title: Theme
        trades:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          default: null
          description: 'check_trades only: the drafted trades'
          title: Trades
        monitor:
          anyOf:
            - $ref: '#/components/schemas/Monitor'
            - type: 'null'
          default: null
          description: 'saved accounts only: what Abacus Labs watches for'
        exclude_themes:
          description: >-
            never buy names in these industries: alcohol, banks, defense,
            firearms, fossil fuels, gambling, oil and gas, pharma, reits,
            semiconductors, tobacco
          items:
            type: string
          title: Exclude Themes
          type: array
      title: Policy
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    Tax:
      additionalProperties: false
      properties:
        mode:
          anyOf:
            - enum:
                - harvest
                - minimize
                - neutral
                - ignore
              type: string
            - type: 'null'
          default: null
          description: >-
            harvest: realize losses; minimize: weigh tax against the goal;
            neutral: realize no net gain; ignore: tax plays no part
          title: Mode
        max_tax:
          anyOf:
            - type: number
            - type: 'null'
          default: null
          description: most estimated tax this change may cost, dollars
          title: Max Tax
        max_gain:
          anyOf:
            - minimum: 0
              type: number
            - type: 'null'
          default: null
          description: >-
            most net capital gain this change may realize, dollars ("no more
            than $5,000 of gains")
          title: Max Gain
        rates:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          description: '{short_term, long_term, state?, niit?}: marginal rates as fractions'
          title: Rates
      title: Tax
      type: object
    Cash:
      additionalProperties: false
      properties:
        min:
          anyOf:
            - minimum: 0
              type: number
            - type: 'null'
          default: null
          description: cash to hold after the trades, at least, dollars
          title: Min
        max:
          anyOf:
            - minimum: 0
              type: number
            - type: 'null'
          default: null
          description: cash to hold after the trades, at most, dollars
          title: Max
        invest:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          description: >-
            put the cash to work (keep about 1% as a buffer unless max says
            otherwise)
          title: Invest
      title: Cash
      type: object
    Limit:
      additionalProperties: false
      properties:
        min:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          default: null
          description: lowest weight, a fraction of the account
          title: Min
        max:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          default: null
          description: highest weight, a fraction of the account
          title: Max
      title: Limit
      type: object
    Trading:
      additionalProperties: false
      properties:
        whole_shares:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          description: 'trade whole shares only (default: the account''s rule, else true)'
          title: Whole Shares
        min_trade:
          anyOf:
            - minimum: 0
              type: number
            - type: 'null'
          default: null
          description: smallest trade, dollars (a full sale may be smaller)
          title: Min Trade
        max_trades:
          anyOf:
            - minimum: 1
              type: integer
            - type: 'null'
          default: null
          title: Max Trades
        max_turnover:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          default: null
          description: (bought + sold) / 2 / account value
          title: Max Turnover
        no_sells:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          description: buy only, sell nothing
          title: No Sells
        sell_lots:
          anyOf:
            - enum:
                - any
                - short_term_only
                - long_term_only
              type: string
            - type: 'null'
          default: null
          description: >-
            which lots may be sold: short_term_only ("don't sell anything held
            over a year": long-term lots stay), long_term_only ("no short-term
            sales"), or any
          title: Sell Lots
      title: Trading
      type: object
    Monitor:
      additionalProperties: false
      properties:
        webhook:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: https URL Abacus Labs posts events to
          title: Webhook
        secret:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: signs each delivery (HMAC-SHA256 in X-Abacus-Signature)
          title: Secret
        harvest:
          default: true
          description: tell me when a loss is worth harvesting
          title: Harvest
          type: boolean
        drift:
          anyOf:
            - maximum: 1
              minimum: 0
              type: number
            - type: 'null'
          default: null
          description: >-
            tell me when the account drifts this far from its benchmark or
            target (fraction)
          title: Drift
        rule_break:
          default: true
          description: tell me when a holding breaks one of the account's rules
          title: Rule Break
          type: boolean
      title: Monitor
      type: object
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: >-
        An API key: abacus_sk_test_... (sandbox, from POST /v1/keys) or
        abacus_sk_live_... (from https://app.abacuslabs.ai)

````

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