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

# Dispatch an Answer Agent run

> Dispatch an Answer Agent run — deep research returning a synthesized, cited answer

The **Answer Agent** researches a natural-language question across Tako's knowledge and the live web, then returns a synthesized, opinionated `answer` (markdown) with the `citations` and `cards` that back it. Use it for open-ended questions that need reasoning across many entities.

See the **[Answer Agent guide](/documentation/integrating-tako/agent/answer)** for examples, citations, streaming, threads, and sources.

## Notes

* To authenticate, send your [Tako API key](https://tako.com/console/api-keys) in the `X-API-Key` header. Store it as an environment variable rather than hardcoding it.
* The agent is **asynchronous**: this endpoint returns `202` with an `AnswerAgentRun` whose `status` is `queued`. Poll [Poll an Answer Agent run](/api-reference/agent-answer-poll) until `status` is `completed` or `failed`.
* To stream progress live instead of polling, send `Accept: text/event-stream`. The response is then a Server-Sent Events stream of `AnswerAgentStreamEnvelope` events. See the [coding-agent reference](/documentation/integrating-tako/agent/for-coding-agent#stream-live-progress-sse).
* **Frozen contract:** the Answer Agent never accepts an `output_schema` and never returns structured output or inline data — the result is `answer` + `cards` + `citations` + `metadata`. For structured data, use the [Search Agent](/api-reference/agent-search-dispatch).

## Choosing sources

`source_indexes` is optional and defaults to `["data", "web"]` — both. Pass it only to **restrict**: `["data"]` (curated knowledge graph only) or `["web"]` (open web only). The legacy value `"tako"` is a synonym for `"data"`.

## Continuing a thread

Pass the `thread_id` from a prior run to ask a follow-up in the same conversation. Omit it to start a new thread. A thread is pinned to the Answer Agent and to one set of `source_indexes`.


## OpenAPI

````yaml POST /v1/agent/answer/runs
openapi: 3.1.0
info:
  title: Knowledge Search API
  version: 1.0.0
servers:
  - url: https://tako.com/api/
    description: Tako Production API Server
security: []
paths:
  /v1/agent/answer/runs:
    post:
      tags:
        - agent
      summary: Dispatch an answer agent run
      description: >-
        Dispatch an answer agent run. Returns 202 with an AnswerAgentRun object;
        poll GET /v1/agent/answer/runs/{run_id} until status is 'completed' or
        'failed'.
      operationId: createAnswerAgentRun
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnswerAgentRunRequest'
      responses:
        '202':
          description: >-
            Run dispatched. With Accept: application/json, poll GET
            /v1/agent/answer/runs/{run_id} for status. With Accept:
            text/event-stream, the response is an SSE stream of
            AnswerAgentStreamEnvelope events terminating at stream_done; if the
            stream ends without an agent_result event, poll GET
            /v1/agent/answer/runs/{run_id} for terminal status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnswerAgentRun'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AnswerAgentStreamEnvelope'
        '400':
          description: Invalid request (e.g. blank query or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '402':
          description: Insufficient API credit balance (PAYG pre-dispatch gate).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '404':
          description: thread_id does not exist or is not owned by the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '409':
          description: >-
            Conflict. code is one of: 'conflict' (the thread has an in-flight
            run — single-flight); 'thread_product_mismatch' (the thread was
            started on a different agent product); 'source_indexes_mismatch' (a
            follow-up changed the thread's pinned source_indexes).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '500':
          description: Failed to dispatch the agent run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
      security:
        - apiKey: []
components:
  schemas:
    AnswerAgentRunRequest:
      properties:
        query:
          type: string
          title: Query
          description: Natural-language request for the answer agent.
          examples:
            - How have American Airlines' margins held up against fuel shocks?
        thread_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Thread Id
          description: Existing thread to continue (follow-up). Omit to start a new thread.
        effort:
          $ref: '#/components/schemas/AnswerAgentEffort'
          description: Answer-agent effort. Only 'medium' is currently supported.
          default: medium
        source_indexes:
          items:
            type: string
            enum:
              - data
              - web
          type: array
          title: Source Indexes
          description: >-
            Which sources the agent may use: 'data' (curated knowledge) and/or
            'web' (open-web search). Defaults to ['data', 'web']. The legacy
            value 'tako' is accepted as a synonym for 'data'.
          examples:
            - - data
            - - web
            - - data
              - web
        locale:
          type: string
          title: Locale
          description: >-
            BCP-47 locale. Drives the language of the agent's answer and the
            locale used when rendering card preview images. Defaults to en-US.
          default: en-US
        timezone:
          anyOf:
            - type: string
            - type: 'null'
          title: Timezone
          description: >-
            IANA timezone (e.g. 'America/New_York') used to render dates/times
            in card preview images. Does not affect the returned data.
        output_settings:
          anyOf:
            - $ref: '#/components/schemas/AgentOutputSettings'
            - type: 'null'
          description: Settings controlling the response/rendering.
      type: object
      required:
        - query
      title: AnswerAgentRunRequest
      description: |-
        Request body for POST /v1/agent/answer/runs.

        Frozen contract: NO output_schema / structured outputs, NO inline data —
        ever. Cards are the only data-export path (via /v1/contents).
    AnswerAgentRun:
      properties:
        run_id:
          type: string
          title: Run Id
        object:
          type: string
          const: agent.run
          title: Object
          default: agent.run
        thread_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Thread Id
        status:
          $ref: '#/components/schemas/AgentRunStatus'
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Completed At
        result:
          anyOf:
            - $ref: '#/components/schemas/AnswerAgentResult'
            - type: 'null'
        error:
          anyOf:
            - $ref: '#/components/schemas/ErrorObject'
            - type: 'null'
        usage:
          anyOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
        request:
          anyOf:
            - $ref: '#/components/schemas/AnswerAgentRunRequest'
            - type: 'null'
      type: object
      required:
        - run_id
        - status
        - created_at
      title: AnswerAgentRun
      description: The answer-agent run resource returned by dispatch (202) and poll (GET).
    AnswerAgentStreamEnvelope:
      properties:
        seq:
          type: integer
          minimum: 0
          title: Seq
        run_id:
          type: string
          title: Run Id
        thread_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Thread Id
        category:
          $ref: '#/components/schemas/StreamCategory'
        block:
          oneOf:
            - $ref: '#/components/schemas/ToolCallEvent'
            - $ref: '#/components/schemas/ToolResultEvent'
            - $ref: '#/components/schemas/ToolErrorEvent'
            - $ref: '#/components/schemas/ToolRetryEvent'
            - $ref: '#/components/schemas/StatusEvent'
            - $ref: '#/components/schemas/SubagentEvent'
            - $ref: '#/components/schemas/ReasoningEvent'
            - $ref: '#/components/schemas/TextEvent'
            - $ref: '#/components/schemas/DataPipelineAnswerEvent'
            - $ref: '#/components/schemas/AnswerAgentResultEvent'
            - $ref: '#/components/schemas/RunSummaryEvent'
            - $ref: '#/components/schemas/HeartbeatEvent'
            - $ref: '#/components/schemas/StreamResetEvent'
            - $ref: '#/components/schemas/StreamDoneEvent'
          title: Block
          discriminator:
            propertyName: kind
            mapping:
              agent_result:
                $ref: '#/components/schemas/AnswerAgentResultEvent'
              data_pipeline_answer:
                $ref: '#/components/schemas/DataPipelineAnswerEvent'
              heartbeat:
                $ref: '#/components/schemas/HeartbeatEvent'
              reasoning:
                $ref: '#/components/schemas/ReasoningEvent'
              run_summary:
                $ref: '#/components/schemas/RunSummaryEvent'
              status:
                $ref: '#/components/schemas/StatusEvent'
              stream_done:
                $ref: '#/components/schemas/StreamDoneEvent'
              stream_reset:
                $ref: '#/components/schemas/StreamResetEvent'
              subagent:
                $ref: '#/components/schemas/SubagentEvent'
              text:
                $ref: '#/components/schemas/TextEvent'
              tool_call:
                $ref: '#/components/schemas/ToolCallEvent'
              tool_error:
                $ref: '#/components/schemas/ToolErrorEvent'
              tool_result:
                $ref: '#/components/schemas/ToolResultEvent'
              tool_retry:
                $ref: '#/components/schemas/ToolRetryEvent'
      type: object
      required:
        - seq
        - run_id
        - category
        - block
      title: AnswerAgentStreamEnvelope
      description: >-
        Public SSE envelope for the Answer Agent run stream. Identical wire
        shape

        to AgentStreamEnvelope; the only difference is the terminal agent_result

        block carries AnswerAgentResult (top-level citations, no web_results).
    ErrorObject:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      type: object
      required:
        - code
        - message
      title: ErrorObject
    AnswerAgentEffort:
      type: string
      enum:
        - medium
      title: AnswerAgentEffort
      description: >-
        Effort taxonomy for the Answer Agent (POST /v1/agent/answer/runs).


        Shares the low/medium/high vocabulary with the Search Agent, but only

        MEDIUM is wired at launch (-> orchestrator_medium_config). LOW/HIGH are

        reserved and added when the fast/deep orchestrator configs are wired to
        the

        public path. Unsupported values 400 (Pydantic StrEnum rejection). Effort
        no

        longer selects an engine (the endpoint pins ORCHESTRATOR); it is a

        forward-compat quality/pricing knob.
    AgentOutputSettings:
      properties:
        image_dark_mode:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Image Dark Mode
          description: >-
            Render card preview images in dark mode. Omit to use the default
            (dark).
      type: object
      title: AgentOutputSettings
    AgentRunStatus:
      type: string
      enum:
        - queued
        - running
        - completed
        - failed
      title: AgentRunStatus
    AnswerAgentResult:
      properties:
        answer:
          anyOf:
            - type: string
            - type: 'null'
          title: Answer
        cards:
          items:
            $ref: '#/components/schemas/TakoCard'
          type: array
          title: Cards
        citations:
          items:
            $ref: '#/components/schemas/AgentAnswerCitation'
          type: array
          title: Citations
        metadata:
          anyOf:
            - $ref: '#/components/schemas/AnswerAgentMetadata'
            - type: 'null'
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Request Id
      type: object
      title: AnswerAgentResult
      description: >-
        Final answer-agent output. answer is markdown prose with [n] citation

        markers; citations is the unified top-level registry the [n] markers
        join;

        cards reuse the sibling TakoCard; metadata carries
        definitions/assumptions/

        methodology. NO inline data, NO structured output, NO web_results —
        ever.

        Prose-only (empty cards) is legitimate.
    Usage:
      properties:
        total_cost_usd:
          type: number
          title: Total Cost Usd
        compute:
          anyOf:
            - $ref: '#/components/schemas/UsageCompute'
            - type: 'null'
        data:
          anyOf:
            - $ref: '#/components/schemas/UsageData'
            - type: 'null'
      type: object
      required:
        - total_cost_usd
      title: Usage
      description: >-
        Cost-plus usage for one metered request. `total_cost_usd` is always
        present

        (the total quoted charge). `compute` / `data` are the additive breakdown
        and

        appear only where they apply. See module docstring for the
        quote-vs-drawdown

        caveat and the total == compute + data invariant.
    StreamCategory:
      type: string
      enum:
        - content
        - activity
        - control
      title: StreamCategory
    ToolCallEvent:
      properties:
        kind:
          type: string
          const: tool_call
          title: Kind
          default: tool_call
        id:
          type: string
          title: Id
        tool:
          type: string
          title: Tool
        status_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Status Message
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
        done:
          type: boolean
          title: Done
          default: false
      type: object
      required:
        - id
        - tool
      title: ToolCallEvent
    ToolResultEvent:
      properties:
        kind:
          type: string
          const: tool_result
          title: Kind
          default: tool_result
        id:
          type: string
          title: Id
        tool:
          type: string
          title: Tool
        elapsed_ms:
          type: integer
          title: Elapsed Ms
          default: 0
        link:
          anyOf:
            - type: string
            - type: 'null'
          title: Link
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
      type: object
      required:
        - id
        - tool
      title: ToolResultEvent
    ToolErrorEvent:
      properties:
        kind:
          type: string
          const: tool_error
          title: Kind
          default: tool_error
        id:
          type: string
          title: Id
        tool:
          type: string
          title: Tool
        error:
          type: string
          title: Error
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
      type: object
      required:
        - id
        - tool
        - error
      title: ToolErrorEvent
    ToolRetryEvent:
      properties:
        kind:
          type: string
          const: tool_retry
          title: Kind
          default: tool_retry
        id:
          type: string
          title: Id
        tool:
          type: string
          title: Tool
        error:
          type: string
          title: Error
        elapsed_ms:
          type: integer
          title: Elapsed Ms
          default: 0
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
      type: object
      required:
        - id
        - tool
        - error
      title: ToolRetryEvent
    StatusEvent:
      properties:
        kind:
          type: string
          const: status
          title: Kind
          default: status
        message:
          type: string
          title: Message
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
      type: object
      required:
        - message
      title: StatusEvent
    SubagentEvent:
      properties:
        kind:
          type: string
          const: subagent
          title: Kind
          default: subagent
        agent_id:
          type: string
          title: Agent Id
        subagent_type:
          type: string
          title: Subagent Type
        parent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Id
        event:
          type: string
          enum:
            - dispatch
            - complete
          title: Event
      type: object
      required:
        - agent_id
        - subagent_type
        - event
      title: SubagentEvent
    ReasoningEvent:
      properties:
        kind:
          type: string
          const: reasoning
          title: Kind
          default: reasoning
        id:
          type: string
          title: Id
        delta:
          type: string
          title: Delta
        done:
          type: boolean
          title: Done
          default: false
      type: object
      required:
        - id
        - delta
      title: ReasoningEvent
    TextEvent:
      properties:
        kind:
          type: string
          const: text
          title: Kind
          default: text
        id:
          type: string
          title: Id
        delta:
          type: string
          title: Delta
        done:
          type: boolean
          title: Done
          default: false
      type: object
      required:
        - id
        - delta
      title: TextEvent
    DataPipelineAnswerEvent:
      properties:
        kind:
          type: string
          const: data_pipeline_answer
          title: Kind
          default: data_pipeline_answer
        id:
          type: string
          title: Id
        chart_refs:
          items:
            type: string
          type: array
          title: Chart Refs
      type: object
      required:
        - id
      title: DataPipelineAnswerEvent
      description: >-
        Signals that the data pipeline produced chart(s) for the answer. Carries

        only chart references; the answer text streams in `text` events and the

        structured result arrives in the terminal `agent_result` event, not
        here.
    AnswerAgentResultEvent:
      properties:
        kind:
          type: string
          const: agent_result
          title: Kind
          default: agent_result
        id:
          type: string
          title: Id
        data:
          $ref: '#/components/schemas/AnswerAgentResult'
      type: object
      required:
        - id
        - data
      title: AnswerAgentResultEvent
    RunSummaryEvent:
      properties:
        kind:
          type: string
          const: run_summary
          title: Kind
          default: run_summary
        status:
          $ref: '#/components/schemas/AgentRunStatus'
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Completed At
        error:
          anyOf:
            - $ref: '#/components/schemas/ErrorObject'
            - type: 'null'
        usage:
          anyOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
      type: object
      required:
        - status
        - created_at
      title: RunSummaryEvent
      description: >-
        Terminal run metadata, emitted once immediately before stream_done.
        Mirrors

        the GET-poll AgentRun fields the stream otherwise lacks; the result
        stays in the

        agent_result event. status/created_at/completed_at always present; error
        only on

        failure; usage only on metered/PAYG runs (null otherwise). Sourced from
        the same

        projection as the poll (run_projection.project_run), so

        agent_result + run_summary == the GET poll object. Synthesized by the
        stream

        generator — NOT a native block kind, so it is absent from
        PUBLIC_STREAM_KINDS.


        It carries the SAME envelope `seq` as the stream_done it precedes (it
        has no

        seq of its own) and its SSE `id:` is suppressed, so it advances no
        resume

        cursor — identify it by `kind`, never by assuming `seq` is unique per
        frame.
    HeartbeatEvent:
      properties:
        kind:
          type: string
          const: heartbeat
          title: Kind
          default: heartbeat
      type: object
      title: HeartbeatEvent
    StreamResetEvent:
      properties:
        kind:
          type: string
          const: stream_reset
          title: Kind
          default: stream_reset
      type: object
      title: StreamResetEvent
    StreamDoneEvent:
      properties:
        kind:
          type: string
          const: stream_done
          title: Kind
          default: stream_done
      type: object
      title: StreamDoneEvent
    TakoCard:
      properties:
        card_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        semantic_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Semantic Description
        webpage_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webpage Url
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
        embed_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Embed Url
        sources:
          anyOf:
            - items:
                $ref: '#/components/schemas/TakoCardSource'
              type: array
            - type: 'null'
          title: Sources
        methodologies:
          anyOf:
            - items:
                $ref: '#/components/schemas/KnowledgeCardMethodology'
              type: array
            - type: 'null'
          title: Methodologies
        source_indexes:
          anyOf:
            - items:
                $ref: '#/components/schemas/TakoSourceIndex'
              type: array
            - type: 'null'
          title: Source Indexes
        card_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Card Type
        relevance:
          anyOf:
            - $ref: '#/components/schemas/KnowledgeCardRelevance'
            - type: 'null'
        content:
          anyOf:
            - $ref: '#/components/schemas/ResultContent'
            - type: 'null'
        relevance_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Relevance Score
          description: >-
            Numeric relevance of this card to the query on a 1.0-5.0 scale (5.0
            = exact match; higher is more relevant). Only populated for entitled
            accounts; null otherwise.
        nodes:
          anyOf:
            - items:
                $ref: '#/components/schemas/TakoCardNode'
              type: array
            - type: 'null'
          title: Nodes
          description: >-
            Graph nodes (entities and metrics) this card was built from,
            returned by default. Absent for web-only cards or when node
            resolution was unavailable. Use each id with /beta/graph/node/{id}
            for full detail (aliases, subtype), or pass ids in
            sources.data.node_ids to pin these nodes in future searches.
      type: object
      title: TakoCard
      description: >-
        A Tako knowledge card on the new search/answer surface. Mirrors the

        legacy KnowledgeCard minus data_url / visualization_data /
        ideal_viz_decisions,

        plus a `content` download descriptor.
    AgentAnswerCitation:
      properties:
        index:
          type: integer
          title: Index
        title:
          type: string
          title: Title
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        source_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Name
        source_index:
          anyOf:
            - $ref: '#/components/schemas/TakoSourceIndex'
            - type: 'null'
        excerpt:
          anyOf:
            - type: string
            - type: 'null'
          title: Excerpt
        publish_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Publish Date
        content:
          anyOf:
            - $ref: '#/components/schemas/ResultContent'
            - type: 'null'
      type: object
      required:
        - index
        - title
      title: AgentAnswerCitation
      description: >-
        One indexed source behind the answer. Every inline [n] marker in the

        answer joins to a citation's index, but a citation may also back the
        answer

        without a surviving inline marker — markers map to citations, not 1:1.

        Covers web and Tako sources alike. This is the single shared top-level

        citation leaf across both agent products (S1 §5.2); the extended fields

        (source_index/excerpt/publish_date/content) are additive and nullable.
        The

        Answer Agent populates source_index and leaves the rest null at launch

        (TAKO-3385); the Search Agent additionally populates
        excerpt/publish_date for

        web sources.
    AnswerAgentMetadata:
      properties:
        definitions:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentAnswerDefinition'
              type: array
            - type: 'null'
          title: Definitions
        assumptions:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentAnswerAssumption'
              type: array
            - type: 'null'
          title: Assumptions
        methodology:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentAnswerMethodologyNote'
              type: array
            - type: 'null'
          title: Methodology
      type: object
      title: AnswerAgentMetadata
      description: |-
        Answer-agent metadata. Citations moved to the top-level `citations`
        registry (TAKO-3385), so this carries only definitions/assumptions/
        methodology. Distinct from the shared AgentAnswerMetadata (which retains
        citations for the legacy AgentResult until A3).
    UsageCompute:
      properties:
        cost_usd:
          type: number
          title: Cost Usd
      type: object
      required:
        - cost_usd
      title: UsageCompute
      description: |-
        Cost of running the operation (agent COGS x multiplier, or the flat
        search/answer per-request rate). Absent on surfaces with no compute step
        (contents).
    UsageData:
      properties:
        cost_usd:
          type: number
          title: Cost Usd
        datasets:
          type: integer
          title: Datasets
      type: object
      required:
        - cost_usd
        - datasets
      title: UsageData
      description: >-
        Cost + quantity of inline data delivered in the response (agent
        per-dataset

        surcharge, search/answer include_contents charge, or the contents
        per-item

        cost). `datasets` is the count of billed data units. Absent when the
        surface

        did not / cannot emit inline data (e.g. the answer agent).
    TakoCardSource:
      properties:
        source_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Name
          description: The name of the source
          examples:
            - S&P Global
            - The World Bank
        source_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Description
          description: The description of the source
        source_index:
          $ref: '#/components/schemas/TakoSourceIndex'
          description: The index of the source
          examples:
            - data
            - web
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: The URL of the source
          examples:
            - https://xignite.com
        source_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Text
          description: >-
            Raw excerpt(s) retrieved from the source page — the unmodified web
            content the answer was grounded in. Populated for WEB sources; null
            for DATA sources.
      type: object
      required:
        - source_index
      title: TakoCardSource
      description: >-
        A source backing a TakoCard, on the SDK surfaces. Mirrors the legacy

        KnowledgeCardSource minus the segment/private-index variants
        (unreachable on

        these surfaces) and using the {data, web} TakoSourceIndex taxonomy.
    KnowledgeCardMethodology:
      properties:
        methodology_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Methodology Name
          description: The name of the methodology
          examples:
            - Where the Data Comes From - S&P Global
        methodology_description:
          anyOf:
            - type: string
            - type: 'null'
          title: Methodology Description
          description: The description of the methodology
          examples:
            - >-
              The financial metrics are collected from S&P Global, where
              information is sourced from original regulatory filings, press
              releases, and subsequent restatements. Data points, including over
              5,000 financial, supplemental, segment, ratio, and
              industry-specific items, are standardized across over 180,000
              companies to ensure consistency and comparability across different
              reporting formats. This comprehensive and methodical process
              enables robust historical analysis and back-testing by seamlessly
              integrating diverse financial datasets while preserving the
              granularity of the original reports.
      type: object
      required:
        - methodology_name
        - methodology_description
      title: KnowledgeCardMethodology
    TakoSourceIndex:
      type: string
      enum:
        - data
        - web
      title: TakoSourceIndex
      description: >-
        Public source taxonomy for the SDK card surfaces (v3 search, v1 answer,

        agent). Symmetric with the request taxonomy {data, web}. Distinct from
        the

        internal/legacy CardSourceIndex used by the internal
        /v1/knowledge_search

        path, which carries additional internal-only index names.
    KnowledgeCardRelevance:
      type: string
      enum:
        - High
        - Medium
        - Low
      title: KnowledgeCardRelevance
    ResultContent:
      properties:
        content_format:
          anyOf:
            - $ref: '#/components/schemas/ContentsFormat'
            - type: 'null'
        cost:
          type: number
          title: Cost
          default: 0
        data:
          anyOf:
            - type: string
            - type: 'null'
          title: Data
        records:
          anyOf:
            - items:
                additionalProperties:
                  anyOf:
                    - type: string
                    - type: number
                    - type: integer
                    - type: boolean
                    - type: 'null'
                type: object
              type: array
            - type: 'null'
          title: Records
        dataset:
          anyOf:
            - $ref: '#/components/schemas/TakoDataset'
            - type: 'null'
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        expires_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Expires At
        total_rows:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Rows
        truncated:
          type: boolean
          title: Truncated
          default: false
        export_pricing:
          anyOf:
            - $ref: '#/components/schemas/ExportPricing'
            - type: 'null'
      type: object
      title: ResultContent
      description: >-
        Describes the downloadable content behind a result. For a Tako card CSV

        export the charge is a flat per-export baseline plus a per-source
        per-row CPM

        on the rows returned (beyond the free-row allowance); web text is the
        canonical

        Contents rate. On `/contents` responses `cost` is the ACTUAL charge and
        still

        reconciles with what that response billed — EXCEPT a `quote_only`
        response,

        where `cost` is a prospective price (the export was neither fetched nor
        billed;

        payload/url are null). On search/answer downloadable cards

        `cost` is a PROSPECTIVE `/contents` quote (the per-export baseline
        floor), NOT

        what this response billed — so on a metered `include_contents` request
        the

        per-card `cost` diverges from `usage.total_cost_usd` (the inline preview
        bills

        ≈$0) and summing per-card `cost` will not reconcile with `usage`; treat
        `cost`

        +`export_pricing` as "what a `/contents` export of this card would
        cost."

        `export_pricing` carries the rate so a caller can compute the full
        charge

        before fetching: baseline_usd + row_cpm_usd * max(0, rows - free_rows) /
        1000

        (rows <= max_rows_ceiling). `export_pricing` is null for web text and

        non-downloadable content. Exactly

        one payload group is populated once

        contents are delivered: `data` (CSV/web text), `records` (verbose JSON),

        `dataset` (compact TakoDataset), or `url`+`expires_at` (presigned
        download);

        `content_format` names the serialization (null for web text and for an

        undelivered quote). When every payload field is unset this is just the
        quote

        (cost), fetched later via the Contents endpoint (a Tako card URL ->

        ChartConfig -> data; any other URL -> page text).
    TakoCardNode:
      properties:
        id:
          type: string
          title: Id
          description: Opaque, human-friendly public id (<name-slug>-<token>).
        type:
          $ref: '#/components/schemas/GraphNodeType'
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
      type: object
      required:
        - id
        - type
        - name
      title: TakoCardNode
      description: >-
        Slim graph node for the search/answer card surface (TakoCard.nodes) and

        its internal carrier. Deliberately narrower than GraphNode: no `aliases`

        (bulky, and the card surface never needs them) and no `subtype` (the
        search

        hydration path resolves ids in one batch KG fetch and does not pay the

        second EntityClassResolver round-trip that subtype would require).
        Callers

        that need the full node — aliases, subtype — resolve the id via

        /beta/graph/node/{id}.
    AgentAnswerDefinition:
      properties:
        term:
          type: string
          title: Term
        definition:
          type: string
          title: Definition
        source_ref:
          anyOf:
            - type: integer
            - type: 'null'
          title: Source Ref
      type: object
      required:
        - term
        - definition
      title: AgentAnswerDefinition
    AgentAnswerAssumption:
      properties:
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
        category:
          anyOf:
            - type: string
            - type: 'null'
          title: Category
        source_ref:
          anyOf:
            - type: integer
            - type: 'null'
          title: Source Ref
      type: object
      required:
        - title
        - description
      title: AgentAnswerAssumption
    AgentAnswerMethodologyNote:
      properties:
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
      type: object
      required:
        - title
        - description
      title: AgentAnswerMethodologyNote
    ContentsFormat:
      type: string
      enum:
        - csv
        - json_records
        - json_compact
      title: ContentsFormat
      description: >-
        Serialization of tabular (Tako card) data. Web content is always raw
        text

        and carries no content format (content_format is null).
    TakoDataset:
      properties:
        columns:
          items:
            $ref: '#/components/schemas/TakoDatasetColumn'
          type: array
          title: Columns
        rows:
          items:
            items:
              anyOf:
                - type: string
                - type: number
                - type: integer
                - type: boolean
                - type: 'null'
            type: array
          type: array
          title: Rows
        total_rows:
          type: integer
          title: Total Rows
        truncated:
          type: boolean
          title: Truncated
        ref:
          type: string
          title: Ref
        sources:
          items:
            $ref: '#/components/schemas/TakoDatasetSource'
          type: array
          title: Sources
        provenance:
          type: string
          enum:
            - query
            - web_extraction
          title: Provenance
          default: query
      type: object
      required:
        - columns
        - rows
        - total_rows
        - truncated
        - ref
        - sources
      title: TakoDataset
      description: |-
        The slot envelope (S1 contract section 5.3): exact spliced rows as
        positional arrays in `columns` order — never LLM-transcribed.
        download_url/expires_at are reserved (full pulls, deferred).
    ExportPricing:
      properties:
        baseline_usd:
          type: number
          title: Baseline Usd
        row_cpm_usd:
          type: number
          title: Row Cpm Usd
        free_rows:
          type: integer
          title: Free Rows
        max_rows_ceiling:
          type: integer
          title: Max Rows Ceiling
      type: object
      required:
        - baseline_usd
        - row_cpm_usd
        - free_rows
        - max_rows_ceiling
      title: ExportPricing
      description: >-
        Card-CSV export pricing RATE, published so a caller can compute an
        export's

        cost before fetching. Full charge =

        baseline_usd + row_cpm_usd * max(0, rows - free_rows) / 1000, rows <=
        max_rows_ceiling.

        row_cpm_usd is the card-level total (sum of the card's distinct priced
        sources'

        per-1,000-row rate); no per-source breakdown.
    GraphNodeType:
      type: string
      enum:
        - metric
        - entity
      title: GraphNodeType
    TakoDatasetColumn:
      properties:
        name:
          type: string
          title: Name
        type:
          $ref: '#/components/schemas/TakoDatasetColumnType'
      type: object
      required:
        - name
        - type
      title: TakoDatasetColumn
      description: Typed header entry; `type` is the JSON-facing column type.
    TakoDatasetSource:
      properties:
        name:
          type: string
          title: Name
        index:
          type: string
          enum:
            - data
            - web
          title: Index
          default: data
      type: object
      required:
        - name
      title: TakoDatasetSource
      description: >-
        Per-dataset provenance entry. `index` is the SOURCE index ("data" for

        every v1 splice — web never splices, S1 contract section 7), not a
        citation

        display number. Mirrors the public TakoSourceIndex taxonomy as a plain

        Literal; S7 revisits naming when the component goes public.
    TakoDatasetColumnType:
      type: string
      enum:
        - string
        - number
        - boolean
        - date
        - datetime
      title: TakoDatasetColumnType
      description: >-
        Logical column type declared in a TakoDataset header. Temporal cells are

        ISO-8601 strings; date vs datetime is decided per column (a temporal
        column

        whose non-null values are all tz-naive midnights declares 'date').
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````