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

# Ask a natural-language question

> Runs the full Shumi engine: classify, plan, execute tools, generate. Returns a streamed response.

This route does **not** use the standard envelope — it streams, and its errors are `{ "error": "..." }`.



## OpenAPI

````yaml /api-reference/openapi.json post /api/cli
openapi: 3.1.0
info:
  title: Shumi API
  description: >-
    Typed crypto trade-intelligence endpoints. Every response is wrapped in a
    versioned envelope, so a client can tell a successful payload from an error
    without inspecting HTTP status alone.


    The same surface backs the `shumi` CLI and the `@shumi-ai/mcp` MCP server.
  version: 1.0.0
servers:
  - url: https://api.shumi.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Ask
    description: Natural-language queries answered by the Shumi engine.
  - name: Coins
    description: Single-asset lookup, risk context, sentiment, and history.
  - name: Market
    description: Market-wide prices, breadth, and baselines.
  - name: Categories
    description: Category listings, membership, and sentiment.
  - name: Sentiment
    description: Crowd sentiment and narrative momentum.
  - name: Trade decisions
    description: Regime, funding, futures, pairs, and signal synthesis.
  - name: Tracking
    description: Watched holders, wallets, baskets, and transcripts.
  - name: RWA
    description: 'Real-world assets: equities, metals, and commodities.'
  - name: Streaming
    description: Long-lived NDJSON streams.
  - name: Account
    description: Entitlement and tier.
paths:
  /api/cli:
    post:
      tags:
        - Ask
      summary: Ask a natural-language question
      description: >-
        Runs the full Shumi engine: classify, plan, execute tools, generate.
        Returns a streamed response.


        This route does **not** use the standard envelope — it streams, and its
        errors are `{ "error": "..." }`.
      operationId: ask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messages
              properties:
                messages:
                  type: array
                  description: >-
                    Conversation history. The last message must have role
                    `user`.
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - user
                          - assistant
                      content:
                        type: string
                walletAddress:
                  type: string
                  description: Optional EVM address, used for entitlement resolution.
                deviceId:
                  type: string
                  description: Anonymous device identifier. Grants exactly one free query.
                raw:
                  type: boolean
                  description: Return the unformatted engine payload.
                archetype:
                  type: string
                  description: Optional persona applied to the answer.
                commandContext:
                  type: object
                  description: Prior CLI command context, folded into the prompt.
            examples:
              simple:
                summary: One-shot question
                value:
                  messages:
                    - role: user
                      content: Is BTC funding crowded right now?
      responses:
        '200':
          description: Streamed answer.
          content:
            text/plain:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/PlainError'
        '403':
          $ref: '#/components/responses/PlainError'
        '429':
          $ref: '#/components/responses/PlainError'
components:
  responses:
    PlainError:
      description: Error. The ask route predates the envelope and returns a bare object.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key (`shumi_sk_…`) or a session JWT. Create a key with `shumi
        login` and `shumi keys create`.

````

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