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

# Submit intent

> Appends a create, replace, or cancel trading intent for the trading account named in the request body. Submission is authorized for API-key callers that belong to the account organization and have organization intent edit permission. Create intents on live accounts additionally require the Trading Live entitlement and must pass controls evaluation before an action and outbox record are written.



## OpenAPI

````yaml /api-reference/intents.openapi.json post /v1/intents
openapi: 3.1.0
info:
  title: intents
  description: ''
  license:
    name: ''
  version: 0.1.0
servers:
  - url: https://api.anthid.com
    description: Production
security: []
tags:
  - name: Intents - Create
    description: Intent submission operations
  - name: Intents - Get
    description: Single-intent read operations
  - name: Intents - List
    description: Intent action listing operations
  - name: Intents - Stats
    description: Intent aggregate statistics
paths:
  /v1/intents:
    post:
      tags:
        - Intents - Create
      summary: Submit intent
      description: >-
        Appends a create, replace, or cancel trading intent for the trading
        account named in the request body. Submission is authorized for API-key
        callers that belong to the account organization and have organization
        intent edit permission. Create intents on live accounts additionally
        require the Trading Live entitlement and must pass controls evaluation
        before an action and outbox record are written.
      operationId: submitIntent
      requestBody:
        description: >-
          Intent command to append, together with the `trading_account_id` that
          should execute it. Create starts a new intent lineage; replace and
          cancel append to the lineage referenced by the command payload's
          `ref_intent_id`. The top-level `client_reference_id` is accepted for
          caller correlation but is not currently persisted on newly created
          action records.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitIntentParams'
        required: true
      responses:
        '201':
          description: Intent accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateIntentResponse'
        '400':
          description: Request body or account scope is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Missing or invalid API key, missing intent edit permission, or
            missing live-trading entitlement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Caller organization does not own the account or controls evaluation
            blocked the create intent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No trading account or referenced intent exists for the provided id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Caller exceeded the request rate limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Unexpected server error while submitting the intent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    SubmitIntentParams:
      type: object
      required:
        - trading_account_id
        - command
      properties:
        client_reference_id:
          type:
            - string
            - 'null'
          description: >-
            Optional caller-provided correlation ID for downstream
            reconciliation.
        command:
          $ref: '#/components/schemas/IntentCommand'
          description: Requested intent operation and its payload.
        trading_account_id:
          type: string
          format: uuid
          description: >-
            Trading account that should execute the intent.


            Carried in the body rather than the path: submission is a command

            against the caller's organization, and the account it targets is
            part of

            the command.
    CreateIntentResponse:
      type: object
      required:
        - intent_id
      properties:
        intent_id:
          type: string
          format: uuid
    Error:
      oneOf:
        - type: object
          required:
            - EncryptionError
          properties:
            EncryptionError:
              type: string
        - type: object
          required:
            - WorkOsError
          properties:
            WorkOsError:
              type: string
        - type: object
          required:
            - KvError
          properties:
            KvError:
              type: string
        - type: object
          required:
            - StreamError
          properties:
            StreamError:
              type: string
        - type: object
          required:
            - InternalError
          properties:
            InternalError:
              type: string
        - type: object
          required:
            - ThirdPartyError
          properties:
            ThirdPartyError:
              type: string
        - type: object
          required:
            - ParseError
          properties:
            ParseError:
              type: string
        - type: object
          required:
            - NotFound
          properties:
            NotFound:
              type: string
        - type: object
          required:
            - AlreadyExists
          properties:
            AlreadyExists:
              type: string
        - type: object
          required:
            - BadRequest
          properties:
            BadRequest:
              type: string
        - type: object
          required:
            - Forbidden
          properties:
            Forbidden:
              type: string
        - type: object
          required:
            - Unauthorized
          properties:
            Unauthorized:
              type: string
        - type: object
          required:
            - Database
          properties:
            Database:
              type: string
        - type: object
          required:
            - TooManyRequests
          properties:
            TooManyRequests:
              type: string
        - type: object
          required:
            - BrokerError
          properties:
            BrokerError:
              type: string
        - type: object
          required:
            - AuthError
          properties:
            AuthError:
              type: string
        - type: object
          required:
            - InvalidInput
          properties:
            InvalidInput:
              type: string
        - type: object
          required:
            - ConnectionLimitExceeded
          properties:
            ConnectionLimitExceeded:
              type: string
    IntentCommand:
      oneOf:
        - type: object
          required:
            - payload
            - type
          properties:
            payload:
              $ref: '#/components/schemas/CreateOrder'
            type:
              type: string
              enum:
                - CREATE
        - type: object
          required:
            - payload
            - type
          properties:
            payload:
              $ref: '#/components/schemas/ReplaceOrder'
            type:
              type: string
              enum:
                - REPLACE
        - type: object
          required:
            - payload
            - type
          properties:
            payload:
              $ref: '#/components/schemas/CancelOrder'
            type:
              type: string
              enum:
                - CANCEL
    CreateOrder:
      type: object
      required:
        - symbol
        - order_side
        - spec
      properties:
        order_side:
          $ref: '#/components/schemas/OrderSide'
        route_strategy:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/RouteStrategy'
        spec:
          $ref: '#/components/schemas/OrderSpec'
        symbol:
          type: string
      additionalProperties: false
    ReplaceOrder:
      type: object
      required:
        - ref_intent_id
        - spec
      properties:
        ref_intent_id:
          type: string
          format: uuid
          description: Intent ID of the order being replaced.
        spec:
          $ref: '#/components/schemas/OrderSpec'
    CancelOrder:
      type: object
      required:
        - ref_intent_id
      properties:
        ref_intent_id:
          type: string
          format: uuid
          description: Intent ID of the order being cancelled.
    OrderSide:
      type: string
      enum:
        - UNSPECIFIED
        - BUY
        - SELL
        - SELL_SHORT
    RouteStrategy:
      type: string
      enum:
        - UNSPECIFIED
        - SMART
        - AMEX
        - ARCA
        - BATS
        - BATY
        - EDGA
        - EDGX
        - NSDQ
        - NYSE
    OrderSpec:
      oneOf:
        - type: object
          required:
            - Market
          properties:
            Market:
              $ref: '#/components/schemas/MarketOrderSpec'
        - type: object
          required:
            - Limit
          properties:
            Limit:
              $ref: '#/components/schemas/LimitOrderSpec'
        - type: object
          required:
            - Stop
          properties:
            Stop:
              $ref: '#/components/schemas/StopOrderSpec'
        - type: object
          required:
            - StopLimit
          properties:
            StopLimit:
              $ref: '#/components/schemas/StopLimitOrderSpec'
    MarketOrderSpec:
      type: object
      required:
        - quantity
      properties:
        quantity:
          $ref: '#/components/schemas/Quantity'
    LimitOrderSpec:
      type: object
      required:
        - price
        - quantity
        - time_in_force
      properties:
        price:
          $ref: '#/components/schemas/Price'
        quantity:
          $ref: '#/components/schemas/Quantity'
        time_in_force:
          $ref: '#/components/schemas/TimeInForce'
    StopOrderSpec:
      type: object
      required:
        - stop_price
        - quantity
        - time_in_force
      properties:
        quantity:
          $ref: '#/components/schemas/Quantity'
        stop_price:
          $ref: '#/components/schemas/Price'
        time_in_force:
          $ref: '#/components/schemas/TimeInForce'
    StopLimitOrderSpec:
      type: object
      required:
        - price
        - stop_price
        - quantity
        - time_in_force
      properties:
        price:
          $ref: '#/components/schemas/Price'
        quantity:
          $ref: '#/components/schemas/Quantity'
        stop_price:
          $ref: '#/components/schemas/Price'
        time_in_force:
          $ref: '#/components/schemas/TimeInForce'
    Quantity:
      type: string
    Price:
      type: string
    TimeInForce:
      type: string
      enum:
        - UNSPECIFIED
        - DAY
        - IMMEDIATE_OR_CANCEL
        - GOOD_TILL_CANCEL
        - AT_OPEN
        - AT_CLOSE
        - FILL_OR_KILL
        - EXT
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````