# GENERATED - do not edit; synced from the Tako monorepo.
# Produced by the Tako monorepo OpenAPI sync workflows.
openapi: 3.1.0
info:
  title: Knowledge Search API
  version: 1.0.0
servers:
- url: https://tako.com/api/
  description: Tako Production API Server
paths:
  /v3/search:
    post:
      tags:
      - tako
      summary: Search
      description: Fast-pipeline knowledge search. Returns Tako cards (and web results
        when requested) with no LLM synthesis.
      operationId: search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        required: true
      responses:
        '200':
          description: Fast-pipeline search results (Tako cards + web results)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '408':
          description: The request exceeded the processing time limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '529':
          description: 'Tako is overloaded and did not process this request. Do not
            retry automatically. The response carries the header x-should-retry: false.
            Send the request again later.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
  /v1/answer:
    post:
      tags:
      - tako
      summary: Answer
      description: 'Fast-pipeline retrieval plus an LLM-synthesized answer. Tako may
        omit sources that cannot provide usable text. This endpoint returns 3 web
        results when you omit sources.web.count. The effort level also selects the
        synthesis model: ''instant'' answers with the fastest model, and ''fast''
        (the default) and ''deep'' answer with a stronger one. Pass output_schema
        on effort ''fast'' or ''deep'' to also receive structured output.'
      operationId: answer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnswerRequest'
        required: true
      responses:
        '200':
          description: Synthesized answer grounded in Tako results, web results, or
            both
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnswerResponse'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '408':
          description: The request exceeded the processing time limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '529':
          description: 'Tako is overloaded and did not process this request. Do not
            retry automatically. The response carries the header x-should-retry: false.
            Send the request again later.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
  /v1/graph/search:
    get:
      tags:
      - tako
      summary: Search the data graph
      description: Resolve a metric or entity in Tako's data graph by name. Use this
        to discover and confirm what data exists before you query. For example, resolve
        the entity here, find its metric with /v1/graph/related (relation=metrics,
        q=<one keyword from the metric name, such as gdp>), then ask /v3/search or
        /v1/answer for that entity + metric combination. Resolving the metric here
        instead can return a same-named metric that has no data for that entity. Each
        result's match_kind tells you whether q named it exactly; treat a fuzzy result
        with suspicion. Requires an API key. Search checks each returned id against
        the graph when it responds. Ids aren't durable across graph rebuilds, so search
        again instead of storing an id for later. Pass label to prefer a NER label
        (a ranking boost, not a filter); by default Tako infers the label from q.
        This endpoint was previously at /beta/graph/search. That path still works
        until 1 February 2027. Move to /v1/graph/search.
      operationId: graphSearch
      parameters:
      - description: Search text (min 1 char).
        required: true
        schema:
          type: string
          minLength: 1
        name: q
        in: query
      - description: Facets to include. Defaults to metric and entity.
        required: false
        style: form
        explode: false
        schema:
          items:
            $ref: '#/components/schemas/GraphNodeType'
          type: array
        name: types
        in: query
      - description: Max results (default 20, max 50).
        required: false
        schema:
          type: integer
          minimum: 1
        name: limit
        in: query
      - description: Prefer results with this NER label (boost, not a filter — matching
          nodes rank higher; others still return). Supplying label disables inference.
        required: false
        schema:
          type: string
          enum:
          - PERSON
          - ORG
          - GPE
          - LOC
          - PRODUCT
          - EVENT
          - LANGUAGE
          - MONEY
          - METRIC
          - STOCK_TICKER
          - WEBSITE
        name: label
        in: query
      - description: When true, Tako NER infers the label and grounded-node boosts
          from q. Set false to disable. Tako ignores this parameter when you supply
          label. Default true.
        required: false
        schema:
          type: boolean
        name: infer_label
        in: query
      responses:
        '200':
          description: Matching metrics and entities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphSearchResponse'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '503':
          description: A backing data store is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
  /v1/graph/related:
    get:
      tags:
      - tako
      summary: Get a graph node's related nodes
      description: 'Explore what a node connects to. The overview returns an ordered
        `relations` list: named relationships (for example `rel:competes_with`, `rel:in_industry`)
        first, then a node''s metrics and entities, then similar nodes and membership
        (part_of, members), then breakdowns. The metrics and entities are the entity
        + metric combinations Tako covers — query /v3/search or /v1/answer for one.
        A breakdown, keyed `breakdown:<dimension>`, lists the values a node''s data
        is split by. For example, `breakdown:segment` lists the business and geographic
        segments a company reports, such as Data Center for NVIDIA, and `breakdown:soc_code`
        lists the occupations in an employer''s visa filings. A node can have several.
        To get a segment''s figures, read the segment''s own `metrics` group, then
        call /v3/search with the company, segment, and metric ids pinned in its data
        `node_ids` field. A segment''s `metrics` lists what any company reports for
        that segment, so the search shows which figures exist for this company. Each
        group carries a stable `key`. Pass `relation`=<key> plus cursor to paginate
        that one group. Pass the optional q to narrow by a case-insensitive substring
        on names and aliases (for example, the metrics of an entity that match ''gdp'').
        Requires an API key. This endpoint was previously at /beta/graph/related.
        That path still works until 1 February 2027. Move to /v1/graph/related.'
      operationId: graphRelated
      parameters:
      - description: Opaque public id of the node.
        required: true
        schema:
          type: string
        name: node_id
        in: query
      - description: Relation key to paginate. Read the keys from the overview, for
          example `rel:competes_with`, `breakdown:segment`, `breakdown:soc_code`,
          `metrics`, `entities`, `siblings`, or `members`.
        required: false
        schema:
          type: string
        name: relation
        in: query
      - description: 'Deprecated: use `relation`. A legacy facet name (metric, entity,
          sibling, or member) that maps to a key.'
        required: false
        deprecated: true
        schema:
          type: string
        name: relation_type
        in: query
      - description: Optional case-insensitive substring filter on the related nodes'
          names and aliases. It filters every group of the overview, or the single
          paginated group when you set `relation`.
        required: false
        schema:
          type: string
        name: q
        in: query
      - description: Opaque pagination cursor.
        required: false
        schema:
          type: string
        name: cursor
        in: query
      - description: Page size (default 50, max 100).
        required: false
        schema:
          type: integer
        name: limit
        in: query
      - description: Maximum number of nodes counted and paginated in each relation
          (default 250, max 2000). A relation with more nodes reports this total with
          `total_capped` set, and pagination ends at it. Higher values make the request
          slower.
        required: false
        schema:
          type: integer
        name: max_per_relation
        in: query
      - description: 'Prefer related nodes with this NER label. This is a boost, not
          a filter: matching nodes rank higher within each relation, and totals do
          not change. Supplying label disables inference.'
        required: false
        schema:
          type: string
          enum:
          - PERSON
          - ORG
          - GPE
          - LOC
          - PRODUCT
          - EVENT
          - LANGUAGE
          - MONEY
          - METRIC
          - STOCK_TICKER
          - WEBSITE
        name: label
        in: query
      - description: When true, Tako NER infers the label and grounded-node boosts
          from q. Set false to disable. Tako ignores this parameter when you supply
          label. It applies only when q is present. Default true.
        required: false
        schema:
          type: boolean
        name: infer_label
        in: query
      responses:
        '200':
          description: A node's details plus related nodes by facet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphRelatedResponse'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: The requested resource does not exist or has no exportable
            data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '503':
          description: A backing data store is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '504':
          description: A graph query exceeded its time limit. This doesn't mean the
            node is missing or has no connections. Narrow the request or try again
            later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
  /v1/graph/node/{id}:
    get:
      tags:
      - tako
      summary: Get a graph node by id
      description: Resolve a single node by its opaque public id. Search cards, /v1/graph/search,
        and /v1/graph/related return these ids. Returns the node's name, type, aliases,
        and description. Requires an API key. This endpoint was previously at /beta/graph/node/{id}.
        That path still works until 1 February 2027. Move to /v1/graph/node/{id}.
      operationId: graphNode
      parameters:
      - description: Opaque public id of the node.
        required: true
        schema:
          type: string
        name: id
        in: path
      responses:
        '200':
          description: A single graph node
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphNode'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: The requested resource does not exist or has no exportable
            data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '503':
          description: A backing data store is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '504':
          description: A graph query exceeded its time limit. This doesn't mean the
            node is missing or has no connections. Narrow the request or try again
            later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
  /v1/contents:
    post:
      tags:
      - tako
      summary: Download content
      description: 'Download the content behind a search result: a CSV of a Tako card''s
        underlying data, or the full text of a web page. Returns a short-lived presigned
        download URL. Send `content_format: card_json` for a rich, card-type-specific
        JSON object under `card_data` (for example a weather forecast with hourly
        and daily records). A card_json export is truncated to `max_rows` like every
        other format, so Tako never delivers more record rows than it bills. A card
        whose record array is unbounded caps that array at the platform export ceiling
        and sets `truncated`. A card type without a card_json shape returns 422. A
        card returns 403 when Tako cannot export its data. A data provider that does
        not permit export and a card whose sources Tako cannot confirm both return
        403, and the error message states which. Send `quote_only: true` to get only
        the export''s price (`cost` + `export_pricing`) with an empty payload. A quote
        charges nothing, fetches nothing, and calls no data provider. Every format
        prices a quote from `max_rows`, so the quote is an upper bound on the charge
        and never falls below it.'
      operationId: contents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContentsRequest'
        required: true
      responses:
        '200':
          description: 'Downloadable content for a result: a presigned URL plus format
            and cost metadata. For a `quote_only` request the item instead carries
            only the price (`cost` + `export_pricing`) with all payload and url fields
            null.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContentsResponse'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '403':
          description: Action not permitted for this resource. For a data export,
            either a data provider does not permit export, or Tako cannot confirm
            the data sources for the card. The message states which.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: The requested resource does not exist or has no exportable
            data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '422':
          description: 'The card can''t be served in the requested form. The response
            body''s error_type names the case. UNSUPPORTED_CONTENT_FORMAT: this card
            type doesn''t support content_format=''card_json''; use ''csv'', ''json_records'',
            or ''json_compact'' for that card. PLACEHOLDER_CARD: the card is a placeholder
            whose data is withheld from this caller, and every content format refuses
            it. VARIABLE_COST_NOT_REQUESTED: the card''s data comes from a variable-cost
            source that is not served to this caller. Both apply to an MPP request
            and to a contract account whose terms are not signed yet. Any other caller
            gets the card''s data. For an MPP request, call the API with an API key.
            For a contract account, contact your account manager to sign terms.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '503':
          description: An upstream data provider is temporarily unavailable or rate-limited.
            Retry after the interval in the Retry-After header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
  /v1/thin_viz/create/:
    post:
      tags:
      - tako
      description: 'Create a visualization card directly from component configurations.
        Supported component types: header, generic_timeseries, categorical_bar, stock_boxes,
        financial_boxes, table.'
      operationId: createCard
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCardRequest'
        required: true
      responses:
        '200':
          description: Card created successfully from schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThinVizCard'
        '400':
          description: Bad request - validation error or component mismatch
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
                required:
                - error
        '404':
          description: Schema not found
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
                required:
                - error
        '402':
          description: Payment required. The PAYG API-credit balance is empty or depleted
            (error_type, error_message, balance_cents).
          content:
            application/json:
              schema:
                properties:
                  error_type:
                    type: string
                  error_message:
                    type: string
                  balance_cents:
                    type: integer
                type: object
                required:
                - error_type
                - error_message
                - balance_cents
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                properties:
                  error:
                    type: string
                type: object
                required:
                - error
      security:
      - apiKey: []
  /v1/agent/answer/runs:
    get:
      tags:
      - agent
      summary: List answer agent runs
      description: List the authenticated caller's answer agent runs, newest first.
        Returns trimmed run summaries. Fetch full detail via GET /v1/agent/answer/runs/{run_id}.
      operationId: listAnswerAgentRuns
      parameters:
      - description: Opaque pagination cursor from a previous response's next_cursor.
        required: false
        schema:
          type: string
        name: cursor
        in: query
      - description: Max items to return (default 20, max 100).
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
        name: limit
        in: query
      responses:
        '200':
          description: A page of the caller's answer agent runs, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnswerAgentRunList'
        '400':
          description: Invalid pagination parameter (limit or cursor).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
      security:
      - apiKey: []
    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'. A run that returns data from sources priced per unit, such as
        web traffic and SEO data, adds a charge above the run's own price, which the
        completed run's `usage` object reports as `variable_cost`. A failed run pays
        no such charge.
      operationId: createAnswerAgentRun
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnswerAgentRunRequest'
        required: true
      responses:
        '202':
          description: 'Run dispatched. With Accept: application/json, poll GET /v1/agent/answer/runs/{run_id}
            for the run status. With Accept: text/event-stream, the response is an
            SSE stream of AnswerAgentStreamEnvelope events. The stream ends at stream_done.
            If the stream ends without an agent_result event, poll GET /v1/agent/answer/runs/{run_id}
            for the terminal status.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnswerAgentRun'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AnswerAgentStreamEnvelope'
        '400':
          description: Invalid request (for example, a blank query or a 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 already
            has a run in flight); ''thread_product_mismatch'' (the thread belongs
            to a different agent product); ''source_indexes_mismatch'' (a follow-up
            changed the thread''s pinned source_indexes); ''effort_mismatch'' (a follow-up
            changed the thread''s pinned effort).'
          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: []
  /v1/agent/answer/runs/{run_id}:
    get:
      tags:
      - agent
      summary: Poll an answer agent run
      description: Retrieve the current state of an answer agent run. Poll until status
        is 'completed' or 'failed'. The response includes result when status is 'completed'.
      operationId: getAnswerAgentRun
      parameters:
      - description: The run ID from the POST /v1/agent/answer/runs response.
        required: true
        schema:
          type: string
        name: run_id
        in: path
      - description: 'SSE resume cursor (Accept: text/event-stream only). The stream
          replays events with seq greater than this value. It is equivalent to the
          Last-Event-ID header.'
        required: false
        schema:
          type: integer
          minimum: 0
        name: starting_after
        in: query
      responses:
        '200':
          description: 'Current state of the agent run. With Accept: text/event-stream,
            the response replays and then follows the run as an SSE stream of AnswerAgentStreamEnvelope
            events. Use starting_after or Last-Event-ID to resume. If the stream ends
            without an agent_result event, poll this endpoint with Accept: application/json
            for the terminal status.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnswerAgentRun'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AnswerAgentStreamEnvelope'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '403':
          description: The run is not owned by the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '404':
          description: Run not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
      security:
      - apiKey: []
  /v1/agent/retrieval/runs:
    get:
      tags:
      - agent
      summary: List retrieval agent runs
      description: List the authenticated caller's retrieval agent runs, newest first.
        Returns trimmed run summaries. Fetch full detail via GET /v1/agent/retrieval/runs/{run_id}.
      operationId: listRetrievalAgentRuns
      parameters:
      - description: Opaque pagination cursor from a previous response's next_cursor.
        required: false
        schema:
          type: string
        name: cursor
        in: query
      - description: Max items to return (default 20, max 100).
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
        name: limit
        in: query
      responses:
        '200':
          description: A page of the caller's retrieval agent runs, newest first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievalAgentRunList'
        '400':
          description: Invalid pagination parameter (limit or cursor).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
      security:
      - apiKey: []
    post:
      tags:
      - agent
      summary: Dispatch a retrieval agent run
      description: Dispatch a retrieval agent run. Returns 202 with a RetrievalAgentRun
        object. Poll GET /v1/agent/retrieval/runs/{run_id} until status is 'completed'
        or 'failed'. A run that returns data from sources priced per unit, such as
        web traffic and SEO data, adds a charge above the run's own price, which the
        completed run's `usage` object reports as `variable_cost`. A failed run pays
        no such charge.
      operationId: createRetrievalAgentRun
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrievalAgentRunRequest'
        required: true
      responses:
        '202':
          description: 'Run dispatched. With Accept: application/json, poll GET /v1/agent/retrieval/runs/{run_id}
            for the run status. With Accept: text/event-stream, the response is an
            SSE stream of RetrievalAgentStreamEnvelope events. The stream ends at
            stream_done. If the stream ends without an agent_result event, poll GET
            /v1/agent/retrieval/runs/{run_id} for the terminal status.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievalAgentRun'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/RetrievalAgentStreamEnvelope'
        '400':
          description: Invalid request (for example, a blank query or a 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 already
            has a run in flight); ''thread_product_mismatch'' (the thread belongs
            to 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: []
  /v1/agent/retrieval/runs/{run_id}:
    get:
      tags:
      - agent
      summary: Poll a retrieval agent run
      description: Retrieve the current state of a retrieval agent run. Poll until
        status is 'completed' or 'failed'. The response includes result when status
        is 'completed'.
      operationId: getRetrievalAgentRun
      parameters:
      - description: The run ID from the POST /v1/agent/retrieval/runs response.
        required: true
        schema:
          type: string
        name: run_id
        in: path
      - description: 'SSE resume cursor (Accept: text/event-stream only). The stream
          replays events with seq greater than this value. It is equivalent to the
          Last-Event-ID header.'
        required: false
        schema:
          type: integer
          minimum: 0
        name: starting_after
        in: query
      responses:
        '200':
          description: 'Current state of the agent run. With Accept: text/event-stream,
            the response replays and then follows the run as an SSE stream of RetrievalAgentStreamEnvelope
            events. Use starting_after or Last-Event-ID to resume. If the stream ends
            without an agent_result event, poll this endpoint with Accept: application/json
            for the terminal status.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievalAgentRun'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/RetrievalAgentStreamEnvelope'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '403':
          description: The run is not owned by the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
        '404':
          description: Run not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
      security:
      - apiKey: []
  /v1/notification_channels:
    get:
      tags:
      - monitors
      summary: List notification channels
      description: 'Your notification channels, newest first.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: listNotificationChannels
      parameters:
      - description: Opaque pagination cursor from a previous response's next_cursor.
        required: false
        schema:
          type: string
        name: cursor
        in: query
      - description: Max items to return (default 20, max 100).
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
        name: limit
        in: query
      responses:
        '200':
          description: Your notification channels, newest first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelList'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
    post:
      tags:
      - monitors
      summary: Create a notification channel
      description: 'Register an https destination that monitors post to when they
        fire. The response includes a signing secret that Tako generates. Store it
        when you read the response, because no later request returns it.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: createNotificationChannel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationChannelCreate'
        required: true
      responses:
        '201':
          description: The new channel, including the signing secret that only this
            response returns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelCreated'
        '400':
          description: Invalid request, or you've reached your notification channel
            limit. The error_type is LIMIT_REACHED, and limit is the cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorCreateRejected'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
  /v1/notification_channels/{id}:
    get:
      tags:
      - monitors
      summary: Get a notification channel
      description: 'One notification channel. The response never includes the signing
        secret.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: getNotificationChannel
      responses:
        '200':
          description: One notification channel, without its signing secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: You don't own a resource with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
    delete:
      tags:
      - monitors
      summary: Delete a notification channel
      description: 'Delete the channel and its signing secret. Monitors that posted
        to it lose that destination and keep running. The firings list stops reporting
        deliveries to it.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: deleteNotificationChannel
      responses:
        '204':
          description: Deleted. Monitors that posted only to this channel keep running
            with no destination, and their firings stay readable.
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: You don't own a resource with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
    patch:
      tags:
      - monitors
      summary: Pause or resume a notification channel
      description: 'Set status to paused to stop deliveries, or to active to resume
        them. Tako pauses a channel after 2 consecutive failed deliveries, and resuming
        clears that count.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: patchNotificationChannel
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationChannelPatch'
        required: true
      responses:
        '200':
          description: One notification channel, without its signing secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationChannelResponse'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: You don't own a resource with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
    parameters:
    - description: Resource id
      required: true
      schema:
        type: string
        format: uuid
      name: id
      in: path
  /v1/monitors:
    get:
      tags:
      - monitors
      summary: List monitors
      description: 'Your monitors, newest first.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: listMonitors
      parameters:
      - description: Opaque pagination cursor from a previous response's next_cursor.
        required: false
        schema:
          type: string
        name: cursor
        in: query
      - description: Max items to return (default 20, max 100).
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
        name: limit
        in: query
      responses:
        '200':
          description: Your monitors, newest first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorList'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
    post:
      tags:
      - monitors
      summary: Create a monitor
      description: 'Create a condition on data. Set type to a registered monitor type,
        and Tako validates parameters against that type''s schema. A monitor fires
        only for an occurrence that happens after you create it, so you can''t use
        a monitor to search history. To find out what each type counts as an occurrence,
        and how long its source takes to report one, call listMonitorTypes. Every
        channel_ids entry must be a notification channel you own; otherwise the request
        returns 404. If the parameters match more than one subject, the 400 response
        lists the candidates.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: createMonitor
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorCreate'
        required: true
      responses:
        '201':
          description: The new monitor, in the same shape every later read returns
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorResponse'
        '400':
          description: Invalid request, an ambiguous subject with its candidates,
            or you've reached your active monitor limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorCreateRejected'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: A channel_ids entry isn't a notification channel you own.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
  /v1/monitors/{id}:
    get:
      tags:
      - monitors
      summary: Get a monitor
      description: 'One monitor.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: getMonitor
      responses:
        '200':
          description: One monitor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: You don't own a resource with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
    delete:
      tags:
      - monitors
      summary: Delete a monitor
      description: 'Delete the monitor and every firing it recorded. To keep the history,
        pause the monitor instead.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: deleteMonitor
      responses:
        '204':
          description: Deleted, along with every firing the monitor recorded.
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: You don't own a resource with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
    patch:
      tags:
      - monitors
      summary: Update a monitor's status, channels, or actions
      description: 'Set status to paused to stop evaluating the monitor, or to active
        to resume it. Set channel_ids to replace the monitor''s destinations; an empty
        list keeps the monitor recording firings with no destination. Set actions
        to replace what the monitor does after it fires; an empty list removes every
        action. Send any combination of the three. If the monitor''s active_until
        has already passed, resuming returns 400. No other field changes after you
        create a monitor.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: patchMonitor
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonitorPatch'
        required: true
      responses:
        '200':
          description: One monitor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorResponse'
        '400':
          description: Invalid request, or resuming the monitor would put you over
            your active monitor limit. The error_type is LIMIT_REACHED, and limit
            is the cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorCreateRejected'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: You don't own a resource with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
    parameters:
    - description: Resource id
      required: true
      schema:
        type: string
        format: uuid
      name: id
      in: path
  /v1/monitor_types:
    get:
      tags:
      - monitors
      summary: List monitor types
      description: 'Every registered monitor type, with the JSON Schema that its parameters
        must satisfy. Each type''s description says what it watches and when it fires.
        stocks.pct_change and stocks.new_52w_extreme are state alerts. If you create
        one while its condition already holds, it fires on the first trading session
        that closes after you create it.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: listMonitorTypes
      responses:
        '200':
          description: Every registered monitor type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorTypeList'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
  /v1/monitors/{id}/firings:
    get:
      tags:
      - monitors
      summary: List a monitor's firings
      description: 'The occurrences this monitor has fired for, newest first. Tako
        removes firings older than the monitor type''s lookback window. The deliveries
        list covers the last 30 days; an older firing lists none.


        **Experimental.** Request and payload shapes can change without a deprecation
        window. Monitors isn''t recommended for production workflows.'
      operationId: listMonitorFirings
      parameters:
      - description: Opaque pagination cursor from a previous response's next_cursor.
        required: false
        schema:
          type: string
        name: cursor
        in: query
      - description: Max items to return (default 20, max 100).
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
        name: limit
        in: query
      responses:
        '200':
          description: The monitor's firings, newest first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FiringList'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '404':
          description: You don't own a resource with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
      security:
      - apiKey: []
    parameters:
    - description: Resource id
      required: true
      schema:
        type: string
        format: uuid
      name: id
      in: path
  /v1/sports/games:
    get:
      tags:
      - sports
      summary: List games
      description: 'Games from one day back to seven days ahead by default, soonest
        first. Use this endpoint to find the ids that sports monitors take as subjects:
        a row''s id is the game_id, and its home.id and away.id are team ids. odds_available
        reports whether the game document already holds a market. Prematch odds arrive
        inside a per-sport window, so a game further out reports false until that
        window opens. You can create a monitor either way.


        **Experimental.** The sports endpoints supply monitor subjects, and their
        shapes can change without a deprecation window.'
      operationId: listSportsGames
      parameters:
      - description: A league id, such as NBA or EPL. Case-insensitive.
        required: false
        schema:
          type: string
        name: league
        in: query
      - description: A team id. Matches games where the team plays on either side.
        required: false
        schema:
          type: string
        name: team
        in: query
      - description: Window start, ISO 8601. Defaults to one day ago, which is the
          earliest the schedule covers. A naive value reads as UTC.
        required: false
        schema:
          type: string
          format: date-time
        name: from
        in: query
      - description: Window end, ISO 8601. Defaults to seven days ahead, which is
          the furthest the schedule covers. A window outside that range returns 400.
        required: false
        schema:
          type: string
          format: date-time
        name: to
        in: query
      - description: Keep only games in these states, comma-separated. Defaults to
          scheduled,live, because you can't monitor a finished game. To include the
          games that finished inside the one-day lookback, pass final.
        required: false
        schema:
          type: string
          default: scheduled,live
          examples:
          - scheduled,live
          - final
        name: status
        in: query
      - description: Games per page. Defaults to 100, maximum 500.
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 100
        name: limit
        in: query
      - description: The next_cursor from the previous page. Opaque; pass it back
          unchanged.
        required: false
        schema:
          type: string
        name: cursor
        in: query
      responses:
        '200':
          description: Games in the window, soonest first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GamesResponse'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '429':
          description: 'Rate limit exceeded: 60 requests a minute or 5,000 a day,
            per user.'
          content:
            application/json:
              schema:
                properties:
                  detail:
                    type: string
                type: object
                required:
                - detail
      security:
      - apiKey: []
  /v1/sports/teams:
    get:
      tags:
      - sports
      summary: Search teams
      description: 'Teams that match a name or play in a league, best match first.
        Use this endpoint to find the team_id a sports monitor takes when the team
        has no game in the next seven days. monitorable reports whether a monitor
        accepts the id. Each team carries up to three upcoming games from the same
        window GET /v1/sports/games lists, and a live_event game''s id is the game_id.
        Pass q, league, or both.


        **Experimental.** The sports endpoints supply monitor subjects, and their
        shapes can change without a deprecation window.'
      operationId: listSportsTeams
      parameters:
      - description: Text to match against the team's name, other names, market, and
          abbreviation. Case-insensitive, at least 2 characters. Lakers, LAL, and
          Los Angeles all find the Los Angeles Lakers.
        required: false
        schema:
          type: string
          minLength: 2
        name: q
        in: query
      - description: A league id, such as NBA or EPL. Case-insensitive.
        required: false
        schema:
          type: string
        name: league
        in: query
      - description: Pass true to keep only teams a sports monitor accepts, or false
          to keep only the teams it refuses. Omit it to get both.
        required: false
        schema:
          type: boolean
        name: monitorable
        in: query
      - description: Teams to return. Defaults to 25, maximum 100.
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
        name: limit
        in: query
      responses:
        '200':
          description: Teams that match the search, best match first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamsResponse'
        '400':
          description: Invalid request data (validation or malformed body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseAPIError'
        '429':
          description: 'Rate limit exceeded: 60 requests a minute or 5,000 a day,
            per user.'
          content:
            application/json:
              schema:
                properties:
                  detail:
                    type: string
                type: object
                required:
                - detail
      security:
      - apiKey: []
components:
  schemas:
    TakoDataset:
      properties:
        columns:
          items:
            $ref: '#/components/schemas/TakoDatasetColumn'
          type: array
          title: Columns
          description: Ordered column headers (name + type), one per position in every
            row.
        rows:
          items:
            items:
              anyOf:
              - type: string
              - type: number
              - type: integer
              - type: boolean
              - type: 'null'
            type: array
          type: array
          title: Rows
          description: Row data as positional cell arrays aligned to `columns` order.
            Cells are string/number/boolean/null; nulls are preserved, never coerced.
        total_rows:
          type: integer
          title: Total Rows
          description: True total number of rows in the underlying data, before any
            truncation.
        truncated:
          type: boolean
          title: Truncated
          description: True when `rows` was capped and total_rows exceeds the number
            returned.
        ref:
          type: string
          title: Ref
          description: Source URL the dataset was derived from (e.g. the Tako card
            URL).
        sources:
          items:
            $ref: '#/components/schemas/TakoDatasetSource'
          type: array
          title: Sources
          description: 'Provenance for the dataset: the sources the rows were drawn
            from.'
        provenance:
          type: string
          enum:
          - query
          - web_extraction
          title: Provenance
          description: 'How the rows were produced: ''query'' (Tako data) or ''web_extraction''.'
          default: query
        redacted_cells:
          anyOf:
          - additionalProperties:
              items:
                type: integer
              type: array
            type: object
          - type: 'null'
          title: Redacted Cells
          description: Column name to the 0-based positions in `rows` whose premium
            value was withheld; those cells are null. Set on a structured-output dataset
            slot when a premium cell was withheld, and null otherwise. An inline /contents
            dataset reports this on the content item instead.
      type: object
      required:
      - columns
      - rows
      - total_rows
      - truncated
      - ref
      - sources
      title: TakoDataset
      description: 'The dataset-slot envelope: exact retrieved rows as positional
        arrays

        in `columns` order. The rows come directly from the data source; the LLM

        never transcribes them.'
    APIErrorType:
      type: string
      enum:
      - BAD_REQUEST
      - AUTHENTICATION_ERROR
      - INTERNAL_SERVER_ERROR
      - RELEVANT_RESULTS_NOT_FOUND
      - RATE_LIMIT_EXCEEDED
      - PAYMENT_REQUIRED
      - REQUEST_TIMEOUT
      - FORBIDDEN
      - NOT_FOUND
      - SERVICE_UNAVAILABLE
      - SERVICE_OVERLOADED
      - UNSUPPORTED_CONTENT_FORMAT
      - PLACEHOLDER_CARD
      - VARIABLE_COST_NOT_REQUESTED
      title: APIErrorType
    ActionOutput:
      properties:
        text:
          type: string
          maxLength: 8000
          title: Text
          description: What the action produced, as text a person reads.
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: A link to what the action produced, such as a card, a thread,
            or a report. Null when there's none.
        structured:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Structured
          description: The structured output the action filled, when it was asked
            for one. Null otherwise.
        structured_error:
          anyOf:
          - $ref: '#/components/schemas/AnswerStructuredOutputError'
          - type: 'null'
          description: Why `structured` is null when the action was asked for structured
            output and couldn't fill it. Null otherwise.
      type: object
      required:
      - text
      title: ActionOutput
    ActionRunEndReason:
      type: string
      enum:
      - error
      - timeout
      - lease_expired
      - not_implemented
      - unknown_kind
      - unbindable
      - disabled
      - insufficient_balance
      - stale
      title: ActionRunEndReason
    ActionRunState:
      type: string
      enum:
      - pending
      - running
      - succeeded
      - failed
      - skipped
      title: ActionRunState
    ActionRunStatus:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        position:
          type: integer
          title: Position
          description: The action's index in the monitor's actions list when the monitor
            fired.
        kind:
          type: string
          title: Kind
        state:
          $ref: '#/components/schemas/ActionRunState'
          description: How the run is going, or how it ended. pending and running
            are live. succeeded carries output. failed and skipped carry ended_reason
            and no output, and are delivered too.
        ended_reason:
          anyOf:
          - $ref: '#/components/schemas/ActionRunEndReason'
          - type: 'null'
          description: Why a run failed or was skipped. Null while the run is live
            and when it succeeded.
        output:
          anyOf:
          - $ref: '#/components/schemas/ActionOutput'
          - type: 'null'
          description: What the action produced. Null unless the run succeeded.
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
        deliveries:
          items:
            $ref: '#/components/schemas/DeliveryStatus'
          type: array
          title: Deliveries
          description: One entry per channel the run was delivered to, whatever its
            state. Empty when the action names no channels.
      type: object
      required:
      - id
      - position
      - kind
      - state
      - ended_reason
      - output
      - started_at
      - finished_at
      - deliveries
      title: ActionRunStatus
    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
    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. A citation can also back the answer

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

        This covers web and Tako sources alike, and it is the single shared

        citation object across both agent products. The extended fields

        (source_index, excerpt, publish_date, content) are additive and nullable.

        The Answer Agent populates source_index and leaves the rest null. The

        Retrieval Agent also populates excerpt and publish_date for web

        sources.'
    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
    AgentAnswerMetadata:
      properties:
        citations:
          anyOf:
          - items:
              $ref: '#/components/schemas/AgentAnswerCitation'
            type: array
          - type: 'null'
          title: Citations
        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: AgentAnswerMetadata
      description: 'Supplementary answer metadata. All fields are optional — population

        varies by effort and engine (low fills citations only today). Tako adds

        new components here additively.'
    AgentAnswerMethodologyNote:
      properties:
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
      type: object
      required:
      - title
      - description
      title: AgentAnswerMethodologyNote
    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
    AnswerAgentEffort:
      type: string
      enum:
      - medium
      - high
      title: AnswerAgentEffort
      description: 'Effort levels for the Answer Agent (POST /v1/agent/answer/runs).


        ''medium'' is the default. ''high'' uses the same models and the same data.
        It only

        makes the model reason more, and it gives the run more time. A ''high'' run
        can

        give a better answer, and it always takes longer. ''low'' is not available.
        A

        request that sends ''low'' gets a 400 response.


        The effort is fixed for the life of a thread. A follow-up that sends a different

        effort gets a 409 response with the code ''effort_mismatch''. To use a different

        effort, start a new thread.'
    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 live in the top-level `citations`

        registry, so this carries only definitions, assumptions, and methodology.

        Distinct from the shared AgentAnswerMetadata, which retains citations for

        the legacy AgentResult.'
    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'
        refusal_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Refusal Code
          description: Set when Tako rejected the query before the agent ran. Null
            on normal runs. Tako can add new codes, so accept a code you do not recognize.
            The current code is 'rejected_input_classifier'.
        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 that the [n] markers

        join. cards reuse the sibling TakoCard. metadata carries definitions,

        assumptions, and methodology. There is no inline data, no structured

        output, and no web_results — ever. A prose-only result (empty cards) is

        legitimate.'
    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
    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).
    AnswerAgentRunList:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        data:
          items:
            $ref: '#/components/schemas/AnswerAgentRunSummary'
          type: array
          title: Data
        has_more:
          type: boolean
          title: Has More
          default: false
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - data
      title: AnswerAgentRunList
      description: 'List envelope for GET /v1/agent/answer/runs. The shape follows
        the

        OpenAI and Exa list convention.'
    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:
          anyOf:
          - $ref: '#/components/schemas/AnswerAgentEffort'
          - type: 'null'
          description: 'The effort level. Omit it on a new thread and Tako uses medium.
            ''high'' makes the model reason more on the same data, and the run takes
            longer. The effort is fixed for the life of a thread: omit it on a follow-up
            and the run keeps the thread''s effort; send a different one and the request
            gets a 409 response with the code ''effort_mismatch''.'
        source_indexes:
          anyOf:
          - items:
              type: string
              enum:
              - data
              - web
            type: array
          - type: 'null'
          title: Source Indexes
          description: 'Which sources the agent may use: ''data'' (curated knowledge),
            ''web'' (open-web search), or both. Omit it on a new thread and the agent
            uses both; omit it on a follow-up and the run keeps the thread''s sources.
            Tako accepts the legacy value ''tako'' 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.
          default: en-US
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
          description: IANA timezone (for example, 'America/New_York'). The agent
            uses it to render dates and times in card preview images. It does not
            affect the returned data.
        output_settings:
          anyOf:
          - $ref: '#/components/schemas/AgentOutputSettings'
          - type: 'null'
          description: Settings that control the response and rendering.
      type: object
      required:
      - query
      title: AnswerAgentRunRequest
      description: 'Request body for POST /v1/agent/answer/runs.


        Frozen contract: no output_schema, no structured outputs, and no inline

        data — ever. Cards are the only data-export path (via /v1/contents).'
    AnswerAgentRunSummary:
      properties:
        run_id:
          type: string
          title: Run Id
        status:
          $ref: '#/components/schemas/AgentRunStatus'
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
        thread_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Thread Id
        usage:
          anyOf:
          - $ref: '#/components/schemas/Usage'
          - type: 'null'
        object:
          type: string
          const: agent.run
          title: Object
          default: agent.run
      type: object
      required:
      - run_id
      - status
      - created_at
      title: AnswerAgentRunSummary
    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: '#/components/schemas/AnswerAgentResultEvent'
              data_pipeline_answer: '#/components/schemas/DataPipelineAnswerEvent'
              heartbeat: '#/components/schemas/HeartbeatEvent'
              reasoning: '#/components/schemas/ReasoningEvent'
              run_summary: '#/components/schemas/RunSummaryEvent'
              status: '#/components/schemas/StatusEvent'
              stream_done: '#/components/schemas/StreamDoneEvent'
              stream_reset: '#/components/schemas/StreamResetEvent'
              subagent: '#/components/schemas/SubagentEvent'
              text: '#/components/schemas/TextEvent'
              tool_call: '#/components/schemas/ToolCallEvent'
              tool_error: '#/components/schemas/ToolErrorEvent'
              tool_result: '#/components/schemas/ToolResultEvent'
              tool_retry: '#/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).'
    AnswerOutputSettings:
      properties:
        image_dark_mode:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Image Dark Mode
          description: Whether to render card preview images in dark mode. Omit it
            and Tako renders dark.
        force_refresh:
          type: boolean
          title: Force Refresh
          description: 'Instant mode only, and currently informational: on these endpoints,
            instant (effort=''instant'') always operates in build-and-refresh mode
            regardless of this flag. Instant retrieves data for embeds that are missing
            or stale, then creates or refreshes their static embeds. Embeds that are
            already fresh (within the refresh cadence) return as-is; Tako does not
            re-retrieve them. Identical queries therefore reuse the same content-addressed
            embed and return a stable embed URL.'
          default: false
      additionalProperties: false
      type: object
      title: AnswerOutputSettings
      description: Settings that control the response shape.
    AnswerRequest:
      properties:
        query:
          type: string
          minLength: 1
          pattern: \S
          title: Query
          description: Natural language search query.
          examples:
          - Intel vs Nvidia headcount since 2013
        effort:
          $ref: '#/components/schemas/SearchEffortLevel'
          description: 'Search effort level: ''fast'', ''instant'', or ''deep''.'
          default: fast
        sources:
          $ref: '#/components/schemas/Sources'
          description: Per-source settings. The search includes an index only if its
            key is present. Omit it and Tako searches data and web with no counts
            set. Tako accepts the legacy key 'tako' as a synonym for 'data'.
        location:
          anyOf:
          - $ref: '#/components/schemas/GeoLocation'
          - type: 'null'
          description: Optional coordinates of the end user. Resolves the location
            for implicit-location queries (for example, weather) and, when `timezone`
            is absent, the timezone Tako renders preview images in. An explicit location
            in the query overrides these coordinates.
        country_code:
          type: string
          title: Country Code
          description: ISO 3166-1 alpha-2 country code for localization.
          default: US
        locale:
          type: string
          title: Locale
          description: BCP-47 locale tag for language and formatting.
          default: en-US
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
          description: IANA timezone (for example, 'America/New_York') Tako renders
            preview images in. Defaults to the zone at `location` when you send coordinates.
            Card text keeps each surface's own timezone.
        output_settings:
          anyOf:
          - $ref: '#/components/schemas/AnswerOutputSettings'
          - type: 'null'
          description: Settings that control the response shape.
        include_related:
          anyOf:
          - type: integer
            maximum: 20
            minimum: 1
          - type: 'null'
          title: Include Related
          description: 'Applies to POST /v3/search only. Return follow-up query suggestions
            in `related`. Omit this field to disable them. The value sets the maximum
            number of suggestions, from 1 to 20. POST /v1/answer accepts this field
            but ignores it: the answer response has no `related` field.'
        variable_cost:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Variable Cost
          description: 'Return data from sources priced per unit, such as web traffic
            and SEO data. Such data adds a charge above the request''s own price,
            which the response''s `usage` object reports as `variable_cost`. Set it
            to false and each such card is a placeholder with its title and no data
            points. Leave it out and your account''s default applies: on for a contract
            account with signed terms, off otherwise. A contract account without signed
            terms gets placeholders whatever you send.'
        output_schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Output Schema
          description: 'JSON Schema for structured output. Tako fills it from the
            same evidence it uses to write `answer`, and returns it in `structured_output`.
            Requires effort ''fast'' or ''deep''; on ''instant'' the request returns
            400. Supported subset: the object, array, string, number, integer, and
            boolean types, plus `items`, `enum`, `required`, `description`, and `additionalProperties:
            false`. A type may be nullable as `["number", "null"]`, which is how you
            let Tako signal ''no evidence'' rather than filling a zero. `title`, `examples`,
            `format`, and `default` are accepted and ignored — they constrain nothing.
            Caps: 16KB total, depth 5, 64 properties, 512 characters per description.
            Violations return 400. If Tako can''t fill the schema, `structured_output`
            is absent and `structured_output_error` says why — the answer and the
            cards still return.'
      additionalProperties: false
      type: object
      required:
      - query
      title: AnswerRequest
      description: Request for POST /api/v1/answer.
    AnswerResponse:
      properties:
        answer:
          type: string
          title: Answer
          description: Synthesized text answer.
        cards:
          items:
            $ref: '#/components/schemas/TakoCard'
          type: array
          title: Cards
          description: Tako cards backing the answer; cards[0] is the lead card —
            the best one to show alongside the answer.
        web_results:
          items:
            $ref: '#/components/schemas/WebResult'
          type: array
          title: Web Results
        request_id:
          type: string
          title: Request Id
        usage:
          anyOf:
          - $ref: '#/components/schemas/Usage'
          - type: 'null'
        structured_output:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Structured Output
          description: Your output_schema, filled. Absent when the request carried
            no output_schema, or when Tako couldn't fill it — check structured_output_error.
        structured_output_error:
          anyOf:
          - $ref: '#/components/schemas/AnswerStructuredOutputError'
          - type: 'null'
          description: Why structured_output is absent. Present only on a structured
            request that failed.
      type: object
      required:
      - answer
      - request_id
      title: AnswerResponse
      description: 'Response for POST /api/v1/answer: the synthesized answer plus
        the

        retrieval behind it.'
    AnswerStructuredOutputError:
      properties:
        code:
          $ref: '#/components/schemas/AnswerStructuredOutputErrorCode'
        message:
          type: string
          title: Message
      type: object
      required:
      - code
      - message
      title: AnswerStructuredOutputError
      description: Why structured_output is absent. The answer and the cards still
        return.
    AnswerStructuredOutputErrorCode:
      type: string
      enum:
      - arbiter_failed
      - validation_failed
      - internal_error
      title: AnswerStructuredOutputErrorCode
      description: 'Why Tako couldn''t return structured output. Values are a public
        wire

        contract — never rename.'
    BaseAPIError:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/APIErrorType'
      type: object
      required:
      - error_message
      - error_type
      title: BaseAPIError
    ChannelKind:
      type: string
      enum:
      - webhook
      - slack_workflow
      title: ChannelKind
      description: How Tako shapes the request body it posts to a channel. `webhook`
        sends nested JSON that namespaces the monitor, the firing, and the payload.
        `slack_workflow` sends a flat body of strings for a Slack Workflow Builder
        trigger, which rejects any nested value.
    ChannelStatus:
      type: string
      enum:
      - active
      - paused
      title: ChannelStatus
    ChannelStatusReason:
      type: string
      enum:
      - delivery_failures
      title: ChannelStatusReason
    ColumnDescriptor:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: The column header as exported. This is the CSV header, the
            json_records key, and the dataset column label for this column.
        metric:
          anyOf:
          - type: string
          - type: 'null'
          title: Metric
          description: What the column measures, for example 'Median Sales Price'.
        entity:
          anyOf:
          - type: string
          - type: 'null'
          title: Entity
          description: 'What the column is measured FOR: the resolved values of every
            dimension the series is filtered to, joined with an em dash — for example
            ''Austin, TX — Condo''. A card filtered on one dimension reports that
            one value. This field reports resolved display values only and never an
            internal identifier.'
        unit:
          anyOf:
          - type: string
          - type: 'null'
          title: Unit
          description: The unit of every value in the column, for example 'USD'.
        dtype:
          anyOf:
          - $ref: '#/components/schemas/TakoDatasetColumnType'
          - type: 'null'
          description: The data type of the column, inferred from the exported values.
        premium_class:
          anyOf:
          - $ref: '#/components/schemas/PremiumClass'
          - type: 'null'
          description: 'Set when the column is premium: ''company_record'' or ''person_contact''.
            Unless the export passed premium=true, a cell that held a value reads
            [premium: withheld] in CSV and is null in JSON formats, so a CSV reader
            can''t parse this column as its dtype; the item''s redacted_cells says
            which rows held a value. Null for every other column.'
      type: object
      title: ColumnDescriptor
      description: 'Structured description of one exported value column.


        Producers set the semantic parts they know (``metric``, ``entity``,

        ``unit``). ``name`` and ``dtype`` are filled centrally: ``name`` is the

        rendered canonical header (set by ``apply_descriptor_names``), and ``dtype``

        is inferred from the real column data in ``finalize_export_frame``. A

        producer-set ``dtype`` would drift from the cells, and a producer cannot know

        the disambiguated ``name`` before the whole frame is rendered.


        In the exported manifest ``name`` equals the column''s actual header, and
        the

        manifest is positionally aligned with the exported columns (manifest entry

        ``i`` describes column ``i``).'
    ComponentConfig:
      properties:
        component_type:
          $ref: '#/components/schemas/ComponentTypeEnum'
          description: 'Component type:

            - bubble: Bubble chart (scatter plot with size dimension for 3-variable
            data)

            - categorical_bar: Bar chart with categorical x-axis (for example, regions
            or products)

            - choropleth: Choropleth map showing geographic data with color intensity
            by region (US states or world)

            - data_table_chart: Bar chart with auto-generated data table below showing
            values

            - financial_boxes: Financial metric boxes with values and growth indicators
            (for example, Revenue or EPS)

            - generic_timeseries: timeseries chart

            - header: Card header with title and description, automatically styled
            with theme

            - heatmap: 2D heatmap with color intensity representing values (for example,
            a correlation matrix)

            - histogram: Histogram chart showing frequency distribution of values

            - person_card: Person profile card from an Exa person search result (includes
            career, education, and about tabs)

            - pie: Pie chart showing proportional data as slices of a circle

            - scatter: Scatter plot showing relationships between two continuous variables

            - table: Data table with configurable columns and rows

            - boxplot: Box plot showing statistical distributions (min, Q1, median,
            Q3, max)

            - treemap: Treemap chart showing hierarchical data as proportional rectangles

            - waterfall: Waterfall chart showing incremental positive and negative
            changes (for example, an income statement breakdown)'
        component_variant:
          anyOf:
          - type: string
          - type: 'null'
          title: Component Variant
          description: Component variant (for example, 'simple' or 'financial').
        config:
          additionalProperties: true
          type: object
          title: Config
          description: Component configuration data
      type: object
      required:
      - component_type
      - config
      title: ComponentConfig
      description: Configuration for a single component in a card.
    ComponentTypeEnum:
      type: string
      enum:
      - categorical_bar
      - choropleth
      - data_table_chart
      - financial_boxes
      - generic_timeseries
      - header
      - heatmap
      - histogram
      - marimekko
      - pie
      - scatter
      - table
      - boxplot
      - treemap
      - waterfall
      - sankey
      - bubble
      - person_card
      - timeline
      - top_level_metric
      title: ComponentTypeEnum
      description: 'Component types supported for thin viz schemas with builder support.


        These component types have dedicated builders that process configurations,

        add defaults, and apply theme styling automatically.'
    ContentItem:
      properties:
        content_format:
          anyOf:
          - $ref: '#/components/schemas/ContentsFormat'
          - type: 'null'
          description: 'Serialization of the returned card data: ''csv'', ''json_records'',
            ''json_compact'', or ''card_json''. Null for web text (always returned
            as raw text) and for a quote-only response (nothing was serialized).'
        cost:
          type: number
          title: Cost
          description: 'Price of this item in USD. On a /contents response this is
            the amount actually billed. On a quote_only response it is a prospective
            /contents export price, because Tako fetched nothing and billed nothing.
            On a search or answer downloadable card it is also a prospective price,
            unless Tako inlined rows for the card; then it is the amount this response
            billed for the card. Use export_pricing on its own to price a /contents
            export of the same card. Do not add this value to that result: they are
            two prices for the same rows, not two charges.'
          default: 0.0
        data:
          anyOf:
          - type: string
          - type: 'null'
          title: Data
          description: 'Inline payload as text: card data serialized to CSV, or a
            web page''s extracted text. Set only for the ''csv'' card format and for
            web text; null otherwise. A card export can hold up to 100,000 rows. Don''t
            read a large export directly into a model''s context: at about 15 tokens
            per row, 10,000 rows cost about 150,000 tokens. Write the export to a
            file, on disk or in memory, and have the agent parse it with code. Give
            the model only the rows or results it needs. To cap the export instead,
            set max_rows.'
        records:
          anyOf:
          - items:
              additionalProperties:
                anyOf:
                - type: string
                - type: number
                - type: integer
                - type: boolean
                - type: 'null'
              type: object
            type: array
          - type: 'null'
          title: Records
          description: 'Inline card data as verbose JSON: a list of row objects keyed
            by column name. Set only when content_format is ''json_records''. A card
            export can hold up to 100,000 rows. Don''t read a large export directly
            into a model''s context: at about 15 tokens per row, 10,000 rows cost
            about 150,000 tokens. Write the export to a file, on disk or in memory,
            and have the agent parse it with code. Give the model only the rows or
            results it needs. To cap the export instead, set max_rows.'
        dataset:
          anyOf:
          - $ref: '#/components/schemas/TakoDataset'
          - type: 'null'
          description: 'Inline card data as a compact TakoDataset (typed column headers
            plus positional row arrays). Set only when content_format is ''json_compact''.
            A card export can hold up to 100,000 rows. Don''t read a large export
            directly into a model''s context: at about 15 tokens per row, 10,000 rows
            cost about 150,000 tokens. Write the export to a file, on disk or in memory,
            and have the agent parse it with code. Give the model only the rows or
            results it needs. To cap the export instead, set max_rows.'
        card_data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Card Data
          description: 'Inline card data as a card-type-specific JSON object. The
            ''card_type'' field inside the object names its shape. Set only when content_format
            is ''card_json''. Tako truncates the record rows in the object to ''max_rows'',
            the same cap every other format takes, and bills the rows it returns.
            A card whose record array is unbounded caps that array at the platform
            export ceiling and reports ''truncated'': true. The payload then also
            carries the true count for its record array. Card types without a card_json
            shape return 422 on /contents and fall back to ''json_compact'' on search
            and answer include_contents. A card export can hold up to 100,000 rows.
            Don''t read a large export directly into a model''s context: at about
            15 tokens per row, 10,000 rows cost about 150,000 tokens. Write the export
            to a file, on disk or in memory, and have the agent parse it with code.
            Give the model only the rows or results it needs. To cap the export instead,
            set max_rows.'
        card_data_schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Card Data Schema
          description: 'JSON Schema for the object in ''card_data''. Read it to learn
            the shape of the payload without parsing the payload. Tako sets this whenever
            content_format is ''card_json''. It is also set in ''url'' delivery mode
            and on a Contents quote, where ''card_data'' is null and the shape is
            all Tako returns. A search or answer card that you did not ask to inline
            carries a price but no schema. The ''title'' field and the ''card_type''
            default inside the schema name the shape. The schema describes the payload
            type, so ''card_data'' can omit a field the schema declares: Tako drops
            a measure the provider did not supply. Null for every other content_format
            and for web text.'
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: Presigned download URL for the content, returned in 'url' delivery
            mode. Null for inline delivery and for quotes; pair with expires_at.
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
          description: ISO-8601 timestamp after which the presigned url stops working.
            Null whenever url is null.
        total_rows:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Rows
          description: Total number of rows in the card's data, independent of how
            many rows were returned. Compare with the rows returned to tell whether
            a larger max_rows returns more. A card that lists a capped slice of a
            larger set, such as the 30 soonest-closing of 330 open solicitations,
            has only that slice as its data, so total_rows is 30 and total_matching
            gives the set's size. On an agent run card, it's set for a card whose
            rows are stored with the card, such as a people list, and null for other
            agent run cards. Null for web text.
        total_matching:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Matching
          description: 'Size of the whole set behind a card that lists a capped slice
            of it, such as 330 for a card listing the 30 soonest-closing of 330 open
            solicitations. It''s the count the card''s description states, and it''s
            the same on every content format. A larger max_rows doesn''t return more
            of that set. Tako reports it for the cards that list such a slice: open
            solicitations, international tenders, a federal agency''s contracts, and
            a company''s news. Null when the card''s rows are the whole set, when
            Tako doesn''t count the set (truncated is still true), and for web text.'
        truncated:
          type: boolean
          title: Truncated
          description: True when the card has more rows than Tako returned. Tako caps
            a card at the request max_rows or at the card's max_rows_ceiling (at most
            100,000), and then total_rows is larger than the rows returned. It's also
            true when the card itself lists a capped slice of a larger set; then total_matching
            gives the set's size when Tako counts it. An inline /contents export that
            omits max_rows returns up to 2,000 rows. On a search or answer response,
            all cards share a budget of 2,000 billable rows and a budget of 20,000
            inline rows, both spent in card order, so a later card can return fewer
            rows than max_rows asked for. A card the billable budget can no longer
            pay for still returns a small preview. A card that arrives after the inline
            budget runs out returns no inline rows, and its export_pricing still prices
            a /contents export of them.
          default: false
        export_pricing:
          anyOf:
          - $ref: '#/components/schemas/ExportPricing'
          - type: 'null'
          description: Rate card for a downloadable card CSV, so a caller can compute
            a full export's cost before fetching. Null for web text and other non-downloadable
            content.
        manifest:
          anyOf:
          - items:
              $ref: '#/components/schemas/ColumnDescriptor'
            type: array
          - type: 'null'
          title: Manifest
          description: 'Per-column metadata, one entry per exported column, in column
            order: entry i describes column i (CSV header i, json_records key i, or
            dataset.columns[i]). Each entry carries name (the column header), dtype,
            unit, metric, entity, and premium_class. On an agent run card, it''s set
            wherever total_rows is. Null for web text and for other quotes that carry
            no tabular columns.'
        premium:
          type: boolean
          title: Premium
          description: 'True when this item''s premium cells are revealed: a /contents
            response to premium=true. False on every search and answer card and on
            a /contents response without the flag. There, a withheld premium cell
            reads [premium: withheld] in CSV and is null in JSON formats, and redacted_cells
            says which rows held a value.'
          default: false
        premium_rows:
          anyOf:
          - additionalProperties:
              type: integer
            type: object
          - type: 'null'
          title: Premium Rows
          description: Per premium class ('company_record', 'person_contact'), the
            number of delivered rows with at least one non-null cell in a column of
            that class, whether revealed or withheld. Multiply by export_pricing.premium_row_cpm_usd[class]
            / 1000 to price the premium part of an export before asking for it. A
            row with cells of two classes counts once in each. Empty for a card with
            no premium columns; null for web text. On an agent run card, it counts
            every row of the card, so a premium=true export of all total_rows rows
            bills exactly these rows when total_rows is within max_rows_ceiling. It's
            set wherever total_rows is.
        redacted_cells:
          anyOf:
          - additionalProperties:
              items:
                type: integer
              type: array
            type: object
          - type: 'null'
          title: Redacted Cells
          description: 'Column header to the 0-based positions, among the delivered
            rows, whose premium value was withheld. Present only when a premium cell
            was withheld; null when premium=true, when nothing was withheld, and for
            web text. Positions index the delivered rows: CSV data rows in order,
            json_records entries, or dataset.rows. In CSV, the same cells read [premium:
            withheld]; a premium cell with no value is blank.'
        source_url:
          type: string
          title: Source Url
          description: The originating result URL from the request.
      type: object
      required:
      - source_url
      title: ContentItem
      description: 'A single downloadable artifact.


        It inherits `content_format`, `cost`, the payload fields (`data`,

        `records`, `dataset`, `total_rows`, `truncated`), and the presigned `url`

        and `expires_at` from ResultContent. URL mode populates `url` and

        `expires_at`. INLINE mode populates one of the payload fields and leaves

        `url` and `expires_at` null. A `quote_only` request yields a third shape:

        `cost` (plus `export_pricing` for a card) with every payload and url

        field null and `content_format` null — the price of the export, with

        nothing fetched or charged.


        `card_data_schema` is the one field that does NOT follow that rule: a

        card_json quote and a card_json `url` delivery both return it beside a null

        `card_data`, because the shape is what those two shapes have to offer. Test

        `content_format` for null to tell a quote from a delivery; a null payload

        field cannot do it.'
    ContentsDeliveryMode:
      type: string
      enum:
      - url
      - inline
      title: ContentsDeliveryMode
      description: 'How contents reach the caller. URL returns a short-lived presigned
        file

        download; INLINE returns the content in the response body.'
    ContentsFormat:
      type: string
      enum:
      - csv
      - json_records
      - json_compact
      - card_json
      title: ContentsFormat
      description: 'Serialization of tabular (Tako card) data. Web content is always
        raw text

        and carries no content format (content_format is null).'
    ContentsHighlights:
      properties:
        query:
          anyOf:
          - type: string
          - type: 'null'
          title: Query
          description: The question the passages should answer. Omit it to receive
            the page's leading passages.
          examples:
          - funded backlog fiscal 2027 guidance
        max_characters:
          type: integer
          maximum: 20000
          minimum: 100
          title: Max Characters
          description: Total character budget for the returned passages.
          default: 4000
      additionalProperties: false
      type: object
      title: ContentsHighlights
      description: Return the passages of a web page instead of its full text.
    ContentsRequest:
      properties:
        url:
          type: string
          title: Url
          description: The result URL to fetch downloadable content for (a TakoCard.webpage_url
            or a WebResult.url). A Tako card URL yields a CSV of the card's data;
            any other URL yields the page's extracted text.
          examples:
          - https://tako.com/card/abc123
        mode:
          $ref: '#/components/schemas/ContentsDeliveryMode'
          description: 'Delivery mode. ''url'' returns a presigned download link.
            ''inline'' returns the content in the response body: card data up to 2,000
            rows unless max_rows asks for more, up to the card''s export_pricing.max_rows_ceiling,
            at most 100,000 (with total_rows and truncated reported), or web text.
            A card export can hold up to 100,000 rows. Don''t read a large export
            directly into a model''s context: at about 15 tokens per row, 10,000 rows
            cost about 150,000 tokens. Write the export to a file, on disk or in memory,
            and have the agent parse it with code. Give the model only the rows or
            results it needs. To cap the export instead, set max_rows.'
          default: url
        content_format:
          $ref: '#/components/schemas/ContentsFormat'
          description: 'Serialization for Tako card data: ''csv'', ''json_records'',
            ''json_compact'', or ''card_json'' (a rich card-type-specific JSON object;
            not all card types support it). Ignored for web URLs (always text).'
          default: csv
        max_rows:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          title: Max Rows
          description: 'Optional cap on the rows a Tako card export returns and is
            priced against. When omitted, it depends on mode: ''url'' returns the
            whole card, up to the card''s export_pricing.max_rows_ceiling (at most
            100,000 rows), and ''inline'' returns up to 2,000 rows. Tako clamps larger
            values to that ceiling. When a card holds more rows than the cap, csv,
            json_records, and json_compact keep the rows with the latest dates, counting
            back from the card''s latest date even when that date is in the future,
            as on a forecast. A card without a date column keeps its first rows instead.
            Sports cards cut differently: a league schedule keeps the tab the card
            shows, then the tabs nearest to it, and a game, standings, or team stats
            card keeps an even share of each table. The kept rows stay in the card''s
            own order. card_json cuts each card type its own way: a price or indicator
            series keeps its newest readings, a forecast or ranking keeps its first
            records, and those sports cards keep rows from the same tabs and tables
            as their csv. Every row returned bills at the per-1,000-row rate, on top
            of the flat per-export baseline. Tako never bills more rows than it returns,
            so a card holding fewer rows than this cap bills only what it holds. Every
            card format returns the rows up to this cap and bills them, including
            card_json. Web URLs ignore this field. A card export can hold up to 100,000
            rows. Don''t read a large export directly into a model''s context: at
            about 15 tokens per row, 10,000 rows cost about 150,000 tokens. Write
            the export to a file, on disk or in memory, and have the agent parse it
            with code. Give the model only the rows or results it needs. To cap the
            export instead, set max_rows.'
          examples:
          - 100
        max_chars:
          type: integer
          maximum: 1000000
          minimum: 1
          title: Max Chars
          description: Character cap on extracted web page text. Ignored for Tako
            card URLs (they use max_rows). Omit it and Tako returns the full page
            text, up to the maximum this field allows. To truncate, pass a smaller
            value.
          default: 1000000
          examples:
          - 50000
        quote_only:
          type: boolean
          title: Quote Only
          description: 'When true, return only the price of the export (cost + export_pricing)
            without fetching content or charging. The response item''s payload and
            url fields are null, and the request is free. One exception: a card_json
            quote returns ''card_data_schema'', the shape the export would deliver.
            Test ''content_format'' for null to tell a quote from a delivery. `max_rows`
            shapes the quote. An omitted `max_rows` defaults the way a real export
            does: the whole card for mode ''url'', and 2,000 rows for ''inline''.
            The quote reads `mode` only for that default. Every format prices a quote
            from `max_rows`, so a quote is instant and makes no call to a data provider.
            A quote is an upper bound on the charge: an export of a card with fewer
            rows than the cap bills less. For a card with data from a source priced
            per unit, the quote also covers the most that data can charge, which `export_pricing`
            reports as `variable_cost_max_usd`. A card_json export is truncated to
            `max_rows` like every other format, so the charge can never exceed the
            quote for the same cap. A card_json quote reports no `total_rows`, because
            it does not build the payload. The same export-safe gate applies, so an
            unexportable card still returns 403, and a card type with no card_json
            shape still returns 422.'
          default: false
        premium:
          type: boolean
          title: Premium
          description: 'When true, reveal premium cells and bill them. A card''s premium
            columns (see manifest[].premium_class) are withheld by default: a withheld
            cell reads [premium: withheld] in CSV and is null in JSON formats. This
            is the only way to receive their values. The export then adds export_pricing.premium_row_cpm_usd[class]
            per 1,000 rows that hold a value in a column of that class, on top of
            the standard row rate; premium_rows on the item reports the counts. The
            flag has no effect on a card without premium columns and on web URLs,
            and is rejected with content_format=card_json, which carries no premium
            plumbing.'
          default: false
        highlights:
          anyOf:
          - $ref: '#/components/schemas/ContentsHighlights'
          - type: 'null'
          description: Return only the passages of a web page that match highlights.query,
            instead of its full text. The passages arrive in the same text payload,
            joined with ' … ', and max_chars doesn't apply. Tako card URLs reject
            it, and so do accounts whose web provider can't return highlights. It
            bills at the same flat rate as full text.
      additionalProperties: false
      type: object
      required:
      - url
      title: ContentsRequest
      description: 'Request body for POST /api/v1/contents.


        The caller passes the result URL it wants downloadable content for, and

        the endpoint detects the right content from the URL itself. A Tako card

        URL resolves to the card''s underlying data. Any other URL resolves to

        the page''s extracted full text. `mode` controls delivery: `url` returns a

        presigned download link, and `inline` returns the content in the

        response. `content_format` selects the card serialization

        (csv, json_records, json_compact, or card_json); web URLs ignore it

        (always text).'
    ContentsResponse:
      properties:
        contents:
          items:
            $ref: '#/components/schemas/ContentItem'
          type: array
          title: Contents
          description: Downloadable artifacts for the requested URL.
        request_id:
          type: string
          title: Request Id
          description: Unique identifier for this request.
        usage:
          anyOf:
          - $ref: '#/components/schemas/Usage'
          - type: 'null'
      type: object
      required:
      - request_id
      title: ContentsResponse
      description: 'Response for POST /api/v1/contents.


        `contents` is a list so that the contract stays stable if a single result

        ever yields multiple artifacts. Today it always carries exactly one

        item.'
    CreateCardRequest:
      properties:
        components:
          items:
            $ref: '#/components/schemas/ComponentConfig'
          type: array
          title: Components
          description: Full component configurations
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: Card title (falls back to header component title)
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Card description
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Data source attribution (displayed in footer)
        height:
          anyOf:
          - type: integer
            maximum: 2000
            minimum: 100
          - type: 'null'
          title: Height
          description: Chart height in pixels. When set, overrides the default aspect-ratio-based
            height for all chart components in this card. Must be between 100 and
            2000.
        postmessage_embed:
          type: boolean
          title: Postmessage Embed
          description: When True, the embed iframe operates in postMessage mode. The
            parent page injects visualization_data via window.postMessage after the
            iframe loads; the embed URL carries no inline data. The response includes
            embed_mode='postmessage' when this is True, and embed_mode='post' otherwise.
          default: false
        normalize_currencies:
          anyOf:
          - type: string
          - type: 'null'
          title: Normalize Currencies
          description: Target ISO 4217 currency code (for example, 'USD' or 'EUR').
            When set, Tako converts datasets with recognized currency units to this
            currency with historical exchange rates. Tako also adds a methodology
            section that explains the conversion.
        image_ttl_minutes:
          anyOf:
          - type: integer
            maximum: 1440
            minimum: 1
          - type: 'null'
          title: Image Ttl Minutes
          description: Minutes to keep the preview image available for download (zero-data-retention
            (ZDR) cards only). Min 1, max 1440 (24 hours). When set on a ZDR card,
            Tako generates a temporary preview image and keeps it available for download
            until the TTL expires. Non-ZDR cards ignore this field.
      type: object
      required:
      - components
      title: CreateCardRequest
      description: Request model for creating a card directly with components.
    DataFreshness:
      properties:
        coverage_end:
          anyOf:
          - type: string
          - type: 'null'
          title: Coverage End
          description: The last data point in the card's data, at the granularity
            of the underlying series. An annual series reports a year (2026). A monthly
            or quarterly series reports a month (2026-06). A daily or intraday series
            reports a full date (2026-06-30). This value can be in the future when
            the card includes projections. Null for card types without a coverage
            date. The value uses ISO 8601 reduced precision, so examine the length
            before you parse it. A date parser reads 2026 as 2026-01-01, which is
            the start of the period and not the end. On a card with tabs, only the
            tab this response built is rendered, so this date describes THAT tab --
            the same card can report a different date on a request that opens a different
            tab. Cache it against the response, not against the card id.
          examples:
          - '2026'
          - 2026-06
          - '2026-06-30'
        data_as_of:
          anyOf:
          - type: string
          - type: 'null'
          title: Data As Of
          description: 'Deprecated: use coverage_end. The same point, always as a
            full ISO date (YYYY-MM-DD). For a series whose points are periods, this
            date is the period boundary. It is not a day on which Tako observed a
            value.'
          deprecated: true
          examples:
          - '2026-10-01'
        last_updated:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Updated
          description: 'Date Tako last refreshed the underlying data, as an ISO date
            (YYYY-MM-DD). On a card with tabs this is the ACTIVE tab''s refresh date,
            for the same reason coverage_end is tab-scoped: only the tab this response
            built is rendered.'
          examples:
          - '2026-07-14'
      type: object
      title: DataFreshness
      description: 'When the card''s data ends and when Tako last refreshed it. Either
        field

        may be null when that date is not available for the card type.'
    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 one or more charts for
        the

        answer. It carries only chart references. The answer text streams in

        `text` events, and the structured result arrives in the terminal

        `agent_result` event, not here.'
    DataSourceSettings:
      properties:
        count:
          anyOf:
          - type: integer
            maximum: 20
            minimum: 1
          - type: 'null'
          title: Count
          description: Maximum number of data cards to return, 1 to 20. Omit it and
            Tako uses 5, unless a result cap set elsewhere in the request sizes retrieval
            instead. Fast and instant return at most 4 cards and deep at most 8, whatever
            count you send.
        include_contents:
          type: boolean
          title: Include Contents
          description: Inline this source's underlying data directly in the response.
            For the Tako data source, that is serialized card data (see content_format).
            For web results, that is the page text.
          default: false
        mode:
          $ref: '#/components/schemas/ContentsDeliveryMode'
          description: Delivery for inlined card data when include_contents is true.
            For Tako cards, include_contents always returns the most-recent rows in
            the response body, up to max_rows, or up to the default inline row cap
            for your account if you omit max_rows. This field therefore has no effect
            on Tako cards; it stays for schema stability. total_rows and truncated
            on the returned content indicate when more data is available. For a presigned
            download link, call POST /api/v1/contents with mode='url'.
          default: inline
        content_format:
          $ref: '#/components/schemas/ContentsFormat'
          description: 'Serialization for card data: ''json_compact'', ''json_records'',
            ''csv'', or ''card_json''. The first three return a row-capped preview.
            ''card_json'' returns a rich card-type-specific JSON object under card_data,
            truncated to the same row cap. Tako bills the rows it returns on every
            one of the four. A card type with no card_json shape falls back to ''json_compact''
            for that card.'
          default: json_compact
        max_rows:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          title: Max Rows
          description: 'Maximum number of card data rows to inline when include_contents
            is true. Omit it and Tako uses your account''s inline row cap. That cap
            is deliberately smaller than the whole card POST /api/v1/contents returns
            by default: a search response inlines many cards, so the same number bills
            once per card. Raise it to inline more rows, up to the card''s export_pricing.max_rows_ceiling
            (at most 100,000). Tako clamps a larger value to that ceiling. Every inlined
            row is billed: a flat per-card baseline fee plus the per-1,000-row rate,
            the same rate POST /api/v1/contents charges. total_rows and truncated
            report whether more rows remain. A single response also has a 2,000 billable-row
            budget and a 20,000-row total budget, both shared across all cards. A
            later card can therefore return fewer rows than you requested, or no inlined
            rows at all. Such a card still carries its export_pricing quote, so you
            can fetch its rows with POST /api/v1/contents. A card export can hold
            up to 100,000 rows. Don''t read a large export directly into a model''s
            context: at about 15 tokens per row, 10,000 rows cost about 150,000 tokens.
            Write the export to a file, on disk or in memory, and have the agent parse
            it with code. Give the model only the rows or results it needs. To cap
            the export instead, set max_rows.'
          examples:
          - 100
        node_ids:
          items:
            type: string
          type: array
          maxItems: 20
          title: Node Ids
          description: 'Graph node ids to pin into the search, from /v1/graph/search
            or /v1/graph/related. For example, pin a company, one of its segments,
            and a metric to get that segment''s figures without wording the query
            exactly. Pinned nodes always become retrieval candidates and get a strong
            boost; organic results do not change. Ids are not durable across knowledge-graph
            rebuilds: the search skips an id that no longer resolves (in strict mode
            it simply cannot match). Malformed ids fail the request with a 400. Max
            20.'
        strict:
          type: boolean
          title: Strict
          description: When true, return only data cards that match at least one node
            in node_ids (which must then be non-empty). When false, pinned nodes rank
            first but organic results still return. Web results do not change either
            way.
          default: false
      additionalProperties: false
      type: object
      title: DataSourceSettings
      description: 'Tako data (card) source settings. It adds the two contents-export

        fields on top of the base count and include_contents. Web sources use the

        base SourceSettings: Tako always inlines web content as raw text, so web

        carries neither field.'
    DeliveryState:
      type: string
      enum:
      - pending
      - retrying
      - delivered
      - failed
      - channel_paused
      title: DeliveryState
      description: How a delivery to one channel is going, or how it ended. `pending`
        and `retrying` are live, and Tako is still working the retry ladder. `delivered`
        got a 2xx. `failed` means the delivery ended without a 2xx, which covers an
        endpoint that rejected every attempt and a row that expired before Tako posted
        at all; read `attempts` and `last_status_code` to tell those apart. `channel_paused`
        means the delivery ended without a 2xx because the channel is paused. Usually
        Tako stopped short of a request; when the pause landed while a request was
        out, `attempts` counts that request too. Resume the channel to receive later
        firings, and ask Tako to re-drive the firings the pause already stopped.
    DeliveryStatus:
      properties:
        channel_id:
          type: string
          format: uuid
          title: Channel Id
        state:
          $ref: '#/components/schemas/DeliveryState'
          description: How this delivery ended, or that it's still running. A paused
            channel reads channel_paused rather than failed, so you can tell a pause
            you caused from an endpoint that stopped accepting.
        attempts:
          type: integer
          title: Attempts
          description: How many delivery attempts Tako has started on the current
            run. Zero when it hasn't started one, which includes a delivery Tako re-drove
            for you.
        last_status_code:
          anyOf:
          - type: integer
          - type: 'null'
          title: Last Status Code
          description: The status code the most recent attempt received, which a re-drive
            keeps until the next attempt overwrites it. Null when no attempt got a
            response.
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
      type: object
      required:
      - channel_id
      - state
      - attempts
      - last_status_code
      - finished_at
      title: DeliveryStatus
    EntityClassName:
      type: string
      enum:
      - Companies
      - Cryptocurrencies
      - Financial Instruments
      - Internet Browsers
      - Commodities
      - People
      - Currencies
      - Stock Exchanges
      - Securities
      - IPOs
      - Government Debt Instruments
      - Treasury Securities
      - Segments
      - Airports
      - Airlines
      - Vehicle Types
      - Transportation Modes
      - Drugs
      - Drug Categories
      - Diseases
      - Injury Mechanisms
      - Injury Intents
      - Chemical Elements
      - Chemical Compounds
      - Celestial Bodies
      - Occupations
      - Social Media Platforms
      - Operating Systems
      - Search Engines
      - Device Types
      - LLMs
      - LLM Families
      - LLM Benchmarks
      - AI Gateway Entity
      - Industries
      - NAICS Industries
      - BLS Industries
      - PSC Categories
      - Purchase Categories
      - Federal Contractors
      - Federal Agencies
      - Federal Subagencies
      - ICE Contracts
      - ICE Contractors
      - Elections
      - Political Offices
      - Pollsters
      - Agricultural Products
      - Tobacco Products
      - Prediction Markets
      - Prediction Events
      - Real Estate Property Types
      - Continents
      - World Regions
      - Countries
      - States
      - Counties
      - Metro Areas
      - Cities
      - F1 Drivers
      - F1 Teams
      - F1 Circuits
      - F1 Events
      - NASCAR Drivers
      - NASCAR Teams
      - NASCAR Tracks
      - NASCAR Events
      - NASCAR Races
      - NASCAR Owners
      - NASCAR Manufacturers
      - Golf Players
      - Golf Tournaments
      - Golf Venues
      - Golf Courses
      - Soccer Teams
      - Soccer Players
      - Soccer Competitions
      - Soccer Conferences
      - Basketball Teams
      - Basketball Players
      - Basketball Conferences
      - Basketball Divisions
      - Baseball Teams
      - Baseball Players
      - Baseball Conferences
      - Baseball Divisions
      - Baseball Competitions
      - Football Teams
      - Football Players
      - Football Conferences
      - Football Divisions
      - Ice Hockey Teams
      - Ice Hockey Conferences
      - Ice Hockey Divisions
      - Sports
      - Sports Leagues
      title: EntityClassName
    ErrorObject:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
      type: object
      required:
      - code
      - message
      title: ErrorObject
    EvaluationOutcome:
      type: string
      enum:
      - fired
      - already_fired
      - no_occurrence
      - predates_monitor
      - outside_lookback
      - unloadable
      - completed
      - unknown_type
      - inactive
      - deleted
      - expired
      - before_window
      - crashed
      title: EvaluationOutcome
      description: How one evaluation of a monitor ended. `fired` recorded a firing,
        and `already_fired` found that occurrence already recorded. `no_occurrence`
        found the condition unmet, which includes finding no usable data to compare.
        `predates_monitor` and `before_window` found an occurrence from before the
        monitor or its `active_from`, and `outside_lookback` found one too old to
        report. `expired`, `unloadable`, and `unknown_type` say why the evaluation
        stopped before it read any data. `completed` means the subject reached an
        end state, so the condition can never be met again, and `crashed` means the
        type failed while reading the data. `deleted` and `inactive` never appear
        on a monitor.
    ExportPricing:
      properties:
        baseline_usd:
          type: number
          title: Baseline Usd
          description: Flat USD charged once per card export, independent of row count.
        row_cpm_usd:
          type: number
          title: Row Cpm Usd
          description: USD charged per 1,000 rows delivered. Card-level rate; use
            this value rather than deriving one from the card's sources. It is the
            sum of the rates of the card's separately priced data feeds, or the standard
            rate once for a card with none. Credited producers and cited web pages
            never add to it. This is 0 if your account's row charges are waived, in
            which case an export costs baseline_usd whatever its size.
        premium_row_cpm_usd:
          additionalProperties:
            type: number
          type: object
          title: Premium Row Cpm Usd
          description: USD charged per 1,000 premium rows, keyed by premium class
            ('company_record', 'person_contact'), added on top of row_cpm_usd when
            a /contents export passes premium=true. A premium row is a delivered row
            with at least one non-null cell in a column of that class; the item's
            premium_rows reports the count per class. Empty when the card has no premium
            columns. Not affected by a row-charge waiver.
        free_rows:
          type: integer
          title: Free Rows
          description: 'Deprecated and always 0. Row allowances are gone: an account
            that pays nothing per row now reports row_cpm_usd of 0 instead, which
            the cost formula already accounts for. Stop reading this field; it will
            be removed.'
          default: 0
          deprecated: true
        max_rows_ceiling:
          type: integer
          title: Max Rows Ceiling
          description: Hard cap on rows a single export can return and bill; a larger
            requested max_rows is clamped to this. No format bills more than the clamped
            max_rows, and none bills more rows than it returns. Every format obeys
            this ceiling, including card_json.
        variable_cost_max_usd:
          anyOf:
          - type: number
          - type: 'null'
          title: Variable Cost Max Usd
          description: 'Set only for a card with data from a source priced per unit:
            the most the source''s minimum charge for an export of this card can be.
            An export charges whichever is larger, its own price or that minimum,
            and the quoted cost already accounts for it. The minimum is known only
            after the export, so the actual charge can be lower. The export''s usage.variable_cost
            reports a different amount: only what the export charged above its own
            price.'
      type: object
      required:
      - baseline_usd
      - row_cpm_usd
      - max_rows_ceiling
      title: ExportPricing
      description: 'Card-CSV export pricing RATE for the /contents endpoint, published
        so a

        caller can compute an export''s cost before fetching. A /contents export''s

        own price = baseline_usd + row_cpm_usd * rows / 1000 + sum over classes c
        of

        premium_row_cpm_usd[c] * premium_rows[c] / 1000, rows <= max_rows_ceiling.

        For a card with data from a source priced per unit, the export charges the

        larger of its own price and that source''s minimum, and

        variable_cost_max_usd is the most that minimum can be.


        row_cpm_usd is the card-level rate and is authoritative: don''t derive it

        from the card''s listed sources. It is the sum of the rates of the card''s

        separately priced data feeds. A card with no separately priced feed bills

        the standard rate once, however many sources it lists. An organization the

        card credits only as the producer of a redistributed number, and a web page

        it cites, never adds to the rate. There is no per-source breakdown. It is

        per-CALLER: an account whose row charges are waived sees 0 here, and the

        same formula then yields the baseline alone, which is exactly what that

        account is billed.'
    FiringList:
      properties:
        items:
          items:
            $ref: '#/components/schemas/FiringResponse'
          type: array
          title: Items
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - items
      title: FiringList
    FiringResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        monitor_id:
          type: string
          format: uuid
          title: Monitor Id
        fired_at:
          type: string
          format: date-time
          title: Fired At
        occurred_at:
          type: string
          format: date-time
          title: Occurred At
        trigger:
          $ref: '#/components/schemas/FiringTrigger'
        occurrence_key:
          type: string
          title: Occurrence Key
        payload:
          additionalProperties:
            $ref: '#/components/schemas/Scalar'
          type: object
          title: Payload
        deliveries:
          items:
            $ref: '#/components/schemas/DeliveryStatus'
          type: array
          title: Deliveries
        actions:
          items:
            $ref: '#/components/schemas/ActionRunStatus'
          type: array
          title: Actions
          description: One entry per action the monitor declared when it fired, in
            declaration order. deliveries lists only the firing's own event.
      type: object
      required:
      - id
      - monitor_id
      - fired_at
      - occurred_at
      - trigger
      - occurrence_key
      - payload
      - deliveries
      - actions
      title: FiringResponse
    FiringTrigger:
      type: string
      enum:
      - push
      - diff
      title: FiringTrigger
    FlatResult:
      properties:
        type:
          $ref: '#/components/schemas/TakoSourceIndex'
          description: data for a Tako card, web for a web page.
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: The card page for a card, the page URL for a web result.
        snippet:
          anyOf:
          - type: string
          - type: 'null'
          title: Snippet
          description: 'Markdown. For a card: the data description, then sections
            headed ### Sources, ### Methodology, and ### Metrics, each omitted when
            empty. For a web page: the matching excerpt.'
        published_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Published Date
          description: Calendar date, YYYY-MM-DD, or null. For a card, the date Tako
            last refreshed the data. For a web page, its publication date.
        sources:
          items:
            $ref: '#/components/schemas/ResultSource'
          type: array
          title: Sources
          description: Publishers behind this result.
        relevance:
          anyOf:
          - $ref: '#/components/schemas/KnowledgeCardRelevance'
          - type: 'null'
          description: 'Tako''s relevance label for a card. Omitted for a web page.
            On `effort: deep` an LLM scores cards as integers 1 to 5, so a 5 is High
            and a 4 is Medium. A card the LLM leaves unscored keeps its continuous
            retrieval score and can be High below 5. Other efforts score continuously
            and can label the same card higher.'
        content:
          anyOf:
          - $ref: '#/components/schemas/ResultContent'
          - type: 'null'
        image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Image Url
          description: Chart image for a card. Omitted for a web page.
        card_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Card Id
          description: Tako card id. Omitted for a web page.
      type: object
      required:
      - type
      title: FlatResult
      description: 'One row of results: a Tako card or a web page in the same shape.'
    FlatResultsSettings:
      properties:
        max_results:
          anyOf:
          - type: integer
            maximum: 40
            minimum: 1
          - type: 'null'
          title: Max Results
          description: The number of results you want in results. The range is 1 to
            40. Each source retrieves up to this many, capped at 20, unless you gave
            that source its own count, which always stands. Either way Tako cuts the
            merged list to this length, dropping Low-relevance cards first, then trailing
            web results, then trailing Medium-relevance cards, then trailing High-relevance
            cards. High- and Medium-relevance cards rank above every web result, so
            a small max_results can return cards alone. Omit it for no cut.
        snippet_max_chars:
          anyOf:
          - type: integer
            maximum: 20000
            minimum: 1
          - type: 'null'
          title: Snippet Max Chars
          description: Character cap on every snippet in results. Tako sends it to
            the web source as its snippet cap and truncates card snippets by section.
            Don't combine it with sources.web.snippet_max_chars; Tako rejects a request
            that sets both. Omit it for no cap.
      additionalProperties: false
      type: object
      title: FlatResultsSettings
      description: 'Settings for the flat results mode. Sending this object turns
        the mode

        on. Send an empty object to turn it on with defaults.'
    GamePhase:
      type: string
      enum:
      - scheduled
      - live
      - final
      title: GamePhase
    GameResponse:
      properties:
        id:
          type: string
          title: Id
          description: The game's id. Pass a live_event row's id to a sports monitor
            as game_id. A schedule_table row's id belongs to the football schedule
            table, and no monitor accepts it.
        league:
          type: string
          title: League
          description: League id, such as NBA.
        start_time:
          type: string
          format: date-time
          title: Start Time
        status:
          $ref: '#/components/schemas/GamePhase'
          description: scheduled, live, or final.
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: The event's own name. The only label F1 and NASCAR rows carry.
        home:
          anyOf:
          - $ref: '#/components/schemas/GameTeam'
          - type: 'null'
          description: Null for events without teams, such as F1 and NASCAR.
        away:
          anyOf:
          - $ref: '#/components/schemas/GameTeam'
          - type: 'null'
        odds_available:
          type: boolean
          title: Odds Available
          description: True when the game document already holds a market. Prematch
            odds arrive inside a per-sport window, so a game further out reports false
            until that window opens. You can create a monitor either way. For a game
            that already holds a market, Tako validates your level against the line
            it holds now.
        source:
          $ref: '#/components/schemas/GameSource'
          description: live_event for a game the live pipelines cover, schedule_table
            for an FBS or FCS game that only the football schedule table records.
            Only live_event rows can carry odds.
      type: object
      required:
      - id
      - league
      - start_time
      - status
      - title
      - home
      - away
      - odds_available
      - source
      title: GameResponse
      description: A game in the listing window.
    GameSource:
      type: string
      enum:
      - live_event
      - schedule_table
      title: GameSource
      description: 'Which table a row came from, which decides what its id is good
        for.


        A ``live_event`` row''s id is a ScheduledEvent key, the id a sports monitor
        takes as

        ``game_id``. A ``schedule_table`` row is an FBS or FCS game, which no

        ScheduledEvent pipeline covers: its id belongs to the football schedule

        table, no live document exists for it, and no monitor accepts it.'
    GameTeam:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
          description: The team's id. Pass it to a sports monitor as team_id. Null
            for a placeholder side.
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Display name. Null when the feed didn't carry one.
      type: object
      required:
      - id
      - name
      title: GameTeam
      description: One side of a game.
    GamesResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/GameResponse'
          type: array
          title: Items
        generated_at:
          type: string
          format: date-time
          title: Generated At
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Pass as 'cursor' to get the next page. Null on the last page.
      type: object
      required:
      - items
      - generated_at
      title: GamesResponse
      description: Games in the window, soonest first.
    GeoLocation:
      properties:
        latitude:
          type: number
          maximum: 90.0
          minimum: -90.0
          title: Latitude
          description: Latitude of the end user (degrees, -90 to 90).
        longitude:
          type: number
          maximum: 180.0
          minimum: -180.0
          title: Longitude
          description: Longitude of the end user (degrees, -180 to 180).
      additionalProperties: false
      type: object
      required:
      - latitude
      - longitude
      title: GeoLocation
    GraphMatchKind:
      type: string
      enum:
      - name
      - alias
      - mention
      - fuzzy
      title: GraphMatchKind
      description: How a search result matched the query text.
    GraphNode:
      properties:
        id:
          type: string
          title: Id
          description: Opaque, human-friendly public id (<prefix>::<name>::<hash>,
            where prefix is ent for an entity or mt for a metric). Ids are not durable
            across knowledge-graph rebuilds — resolve them at request time rather
            than storing them.
        type:
          $ref: '#/components/schemas/GraphNodeType'
          description: Whether the node is a metric or an entity.
        name:
          type: string
          title: Name
          description: Display name. Several metrics can share a name when publishers
            report different series, such as two GDP metrics; read `description` to
            tell them apart.
        aliases:
          items:
            type: string
          type: array
          title: Aliases
          description: Other names Tako matches to this node, such as abbreviations,
            tickers, and former names. /v1/graph/search matches `q` against these
            as well as `name`.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: What the node is. For a metric, what it measures, often with
            its unit and basis. For an entity, a short identification. Absent when
            Tako has none.
        subtype:
          anyOf:
          - $ref: '#/components/schemas/EntityClassName'
          - type: 'null'
          description: The entity's class, such as Companies, Countries, or People.
            Absent for metrics, and for an entity whose class Tako didn't resolve
            for this response. /v1/graph/search and /v1/graph/related resolve it;
            /v1/graph/node doesn't.
        label:
          anyOf:
          - $ref: '#/components/schemas/NerLabel'
          - type: 'null'
          description: Public NER label of the node (PERSON, ORG, GPE, ...). Derived
            from the node's stored annotation; null when the internal annotation has
            no public equivalent.
        match_kind:
          anyOf:
          - $ref: '#/components/schemas/GraphMatchKind'
          - type: 'null'
          description: 'How this result matched `q`: `name` when `q` is the node''s
            name, `alias` when `q` is one of its aliases, `mention` when a phrase
            in `q` is the node''s name or alias (Apple Inc. for `q=Apple revenue`),
            and `fuzzy` for any other partial or approximate match. A `fuzzy` result
            can be unrelated to what you asked for, so check it before you rely on
            it. Set on /v1/graph/search results only.'
      type: object
      required:
      - id
      - type
      - name
      title: GraphNode
    GraphNodeType:
      type: string
      enum:
      - metric
      - entity
      title: GraphNodeType
      description: A `metric` is a measurable quantity, such as GDP; an `entity` is
        what one is measured for, such as France.
    GraphRelatedResponse:
      properties:
        node:
          $ref: '#/components/schemas/GraphNode'
        relations:
          anyOf:
          - items:
              $ref: '#/components/schemas/GraphRelation'
            type: array
          - type: 'null'
          title: Relations
        relation:
          anyOf:
          - $ref: '#/components/schemas/GraphRelationPage'
          - type: 'null'
        inferred_labels:
          anyOf:
          - items:
              $ref: '#/components/schemas/NerLabel'
            type: array
          - type: 'null'
          title: Inferred Labels
          description: Labels that Tako NER inferred from `q` when infer_label ran
            (boost applied). An empty list means inference ran and found nothing.
            The field is absent when you supplied an explicit `label`, when infer_label=false,
            or when there was no q.
      type: object
      required:
      - node
      title: GraphRelatedResponse
    GraphRelation:
      properties:
        key:
          type: string
          title: Key
          description: 'Stable pagination handle. Fixed keys: metrics, entities, siblings,
            part_of, members. Named relations: rel:<phrase>. Breakdowns: breakdown:<dimension>.'
        kind:
          $ref: '#/components/schemas/RelationKind'
        label:
          type: string
          title: Label
          description: Human-readable group label.
        items:
          items:
            $ref: '#/components/schemas/GraphNode'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        total_capped:
          type: boolean
          title: Total Capped
          description: True when `total` hit the server-side fetch cap; the true count
            is at least `total`. Render as 'total+'.
          default: false
      type: object
      required:
      - key
      - kind
      - label
      - items
      - total
      title: GraphRelation
    GraphRelationPage:
      properties:
        key:
          type: string
          title: Key
          description: The relation key of this page.
        kind:
          $ref: '#/components/schemas/RelationKind'
        label:
          type: string
          title: Label
          description: Human-readable group label.
        items:
          items:
            $ref: '#/components/schemas/GraphNode'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        total_capped:
          type: boolean
          title: Total Capped
          description: True when `total` hit the server-side fetch cap; the true count
            is at least `total`. Pagination ends at the cap — narrow with `q` to reach
            the tail.
          default: false
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - key
      - kind
      - label
      - items
      - total
      title: GraphRelationPage
    GraphSearchResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/GraphNode'
          type: array
          title: Results
        inferred_labels:
          anyOf:
          - items:
              $ref: '#/components/schemas/NerLabel'
            type: array
          - type: 'null'
          title: Inferred Labels
          description: Labels that Tako NER inferred from `q` when infer_label ran
            (boost applied). An empty list means inference ran and found nothing.
            The field is absent when you supplied an explicit `label`, when infer_label=false,
            or when there was no q.
      type: object
      required:
      - results
      title: GraphSearchResponse
    HeartbeatEvent:
      properties:
        kind:
          type: string
          const: heartbeat
          title: Kind
          default: heartbeat
      type: object
      title: HeartbeatEvent
    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: 'A concise, one-sentence summary of the methodology: the source
            and what it measures. When no concise summary is available, this carries
            the full methodology text.'
          examples:
          - Financial metrics standardized by S&P Global from company regulatory filings,
            press releases, and restatements.
      type: object
      required:
      - methodology_name
      - methodology_description
      title: KnowledgeCardMethodology
    KnowledgeCardRelevance:
      type: string
      enum:
      - High
      - Medium
      - Low
      title: KnowledgeCardRelevance
    MetricDefinition:
      properties:
        name:
          type: string
          title: Name
          description: The metric's display name
          examples:
          - Gross Domestic Product (current US$)
        definition:
          type: string
          title: Definition
          description: Human-readable definition of the metric
      type: object
      required:
      - name
      - definition
      title: MetricDefinition
      description: 'Definition of a metric shown on a card. Sourced from the metric''s

        ValueType definition — the same text as the in-app methodology ''Metrics''

        tab.'
    MonitorCreate:
      properties:
        name:
          type: string
          maxLength: 255
          title: Name
          description: Your label for the monitor. Tako never fills one in, and never
            reads it.
          default: ''
        type:
          type: string
          maxLength: 64
          title: Type
          description: A registered monitor type name, domain.subtype, for example
            stocks.pct_change.
        parameters:
          additionalProperties: true
          type: object
          title: Parameters
          description: Tako validates these against the type's parameter schema.
        fire_once:
          type: boolean
          title: Fire Once
          description: Pause the monitor after its first firing. To fire on every
            new occurrence, set it to false, which a type that reports fire_once_only
            rejects.
          default: true
        channel_ids:
          items:
            type: string
            format: uuid
          type: array
          maxItems: 20
          title: Channel Ids
          description: 'Destinations to post each firing to. Empty means no delivery:
            the firings are still recorded and readable through listMonitorFirings.'
        actions:
          items:
            additionalProperties: true
            type: object
          type: array
          maxItems: 5
          title: Actions
          description: 'What Tako does after the monitor fires, in order. Each entry
            is an object with kind, that kind''s parameters, and optionally channel_ids.
            channel_ids sets where the action''s output goes: leave it out to use
            the monitor''s channels, list channels you own to use those, or send an
            empty list to keep the output in Tako. Actions aren''t available yet,
            so a non-empty list returns 400.'
        active_from:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Active From
          description: Ignore occurrences before this time. Null means from the moment
            you create the monitor.
        active_until:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Active Until
          description: Pause the monitor as expired after this time. Null means the
            monitor has no end. The value must be in the future and after active_from.
      type: object
      required:
      - type
      - parameters
      title: MonitorCreate
    MonitorCreateErrorType:
      type: string
      enum:
      - BAD_REQUEST
      - AMBIGUOUS_SUBJECT
      - LIMIT_REACHED
      title: MonitorCreateErrorType
      description: Why a monitors operation refused the request.
    MonitorCreateRejected:
      properties:
        error_message:
          type: string
          title: Error Message
        error_type:
          $ref: '#/components/schemas/MonitorCreateErrorType'
        candidates:
          items:
            additionalProperties:
              $ref: '#/components/schemas/Scalar'
            type: object
          type: array
          title: Candidates
          default: []
        limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Limit
      type: object
      required:
      - error_message
      - error_type
      title: MonitorCreateRejected
      description: 'The 400 response from createMonitor, createNotificationChannel,
        and patchMonitor. When

        error_type is AMBIGUOUS_SUBJECT, candidates lists every subject the parameters
        could have

        matched, best first, so you can narrow them and retry. When error_type is
        LIMIT_REACHED,

        limit is how many active monitors or notification channels you may hold. Tako
        counts that

        limit per user rather than pooling it across an account, and the message says
        how to free

        one, or where to ask for an enterprise limit. For any other error_type, candidates
        is empty

        and limit is null.'
    MonitorList:
      properties:
        items:
          items:
            $ref: '#/components/schemas/MonitorResponse'
          type: array
          title: Items
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - items
      title: MonitorList
    MonitorPatch:
      properties:
        status:
          anyOf:
          - $ref: '#/components/schemas/MonitorStatus'
          - type: 'null'
          description: Set paused to stop evaluating, or active to resume.
        channel_ids:
          anyOf:
          - items:
              type: string
              format: uuid
            type: array
            maxItems: 20
          - type: 'null'
          title: Channel Ids
          description: Replace the monitor's destinations with this set. Empty means
            the monitor keeps recording firings and delivers to none.
        actions:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
            maxItems: 5
          - type: 'null'
          title: Actions
          description: 'Replace the monitor''s actions with this list. An empty list
            removes every action. Each entry is an object with kind, that kind''s
            parameters, and optionally channel_ids. channel_ids sets where the action''s
            output goes: leave it out to use the monitor''s channels, list channels
            you own to use those, or send an empty list to keep the output in Tako.
            Actions aren''t available yet, so a non-empty list returns 400.'
      type: object
      title: MonitorPatch
    MonitorResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        type:
          type: string
          title: Type
        parameters:
          additionalProperties: true
          type: object
          title: Parameters
          description: 'The parameters in the form createMonitor accepts, as this
            type''s parameters_schema describes them. The ids Tako resolved them to
            never appear here. The names come back as Tako resolved them rather than
            as you typed them, so a stock monitor created with ticker aapl reads back
            ticker AAPL and the exchange MIC that resolution picked. A type whose
            input accepts more than one name for a subject can return a different
            one than you sent: a crypto monitor names the asset by coinmarketcap_id
            whichever name you created it with. A monitor Tako can no longer render
            against its type''s current schema returns a reduced form; subject still
            names what it watches.'
        subject:
          additionalProperties:
            $ref: '#/components/schemas/Scalar'
          type: object
          title: Subject
          description: The subject the type resolved from your parameters, such as
            the listing that a ticker matched, in the shape listMonitorTypes returns
            as subject_schema. Check it before you rely on the monitor. Tako resolves
            it once, when you create the monitor, and never re-resolves it, so it
            names what the monitor watches rather than what that subject is called
            today. Empty for a type that resolves no subject.
        fire_once:
          type: boolean
          title: Fire Once
        status:
          $ref: '#/components/schemas/MonitorStatus'
        status_reason:
          anyOf:
          - $ref: '#/components/schemas/StatusReason'
          - type: 'null'
          description: Why Tako paused the monitor. Null while the monitor is active,
            and null when you paused it yourself.
        active_from:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Active From
        active_until:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Active Until
        last_evaluated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Evaluated At
          description: When Tako last evaluated this monitor. Null until the first
            evaluation.
        last_evaluation_outcome:
          anyOf:
          - $ref: '#/components/schemas/EvaluationOutcome'
          - type: 'null'
          description: How that evaluation ended. Null until the first evaluation,
            and null again after you resume a paused monitor, because the pause makes
            the earlier outcome meaningless. On an active monitor with no firings,
            a recent predates_monitor or before_window means the monitor is running
            and waiting for an occurrence that happens after you created it. no_occurrence
            means the type found no occurrence, which includes finding no usable data
            to compare.
        channel_ids:
          items:
            type: string
            format: uuid
          type: array
          title: Channel Ids
        actions:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Actions
          description: 'The monitor''s actions as Tako stored them: the fields you
            set on each action, and channel_ids only on an action where you set it.
            A field you left out takes the kind''s default when the action runs. Empty
            for a monitor with no actions.'
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - name
      - type
      - parameters
      - subject
      - fire_once
      - status
      - status_reason
      - active_from
      - active_until
      - last_evaluated_at
      - last_evaluation_outcome
      - channel_ids
      - actions
      - created_at
      - updated_at
      title: MonitorResponse
    MonitorStatus:
      type: string
      enum:
      - active
      - paused
      title: MonitorStatus
    MonitorTypeInfo:
      properties:
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
          description: What the type watches and when it fires.
        parameters_schema:
          additionalProperties: true
          type: object
          title: Parameters Schema
          description: JSON Schema for the parameters createMonitor accepts.
        lookback_seconds:
          type: integer
          title: Lookback Seconds
          description: How far back an occurrence may have happened and still fire.
        fire_once_only:
          type: boolean
          title: Fire Once Only
          description: Whether this type reports an occurrence that stays true once
            it happens. When it's true, createMonitor accepts only fire_once=true.
        subject_schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Subject Schema
          description: JSON Schema for the resolved subject this type returns, and
            for each entry in candidates.
      type: object
      required:
      - name
      - description
      - parameters_schema
      - lookback_seconds
      - fire_once_only
      title: MonitorTypeInfo
    MonitorTypeList:
      properties:
        items:
          items:
            $ref: '#/components/schemas/MonitorTypeInfo'
          type: array
          title: Items
        firing_enabled:
          type: boolean
          title: Firing Enabled
          description: Whether this environment evaluates monitors. While it's false,
            createMonitor still accepts a monitor and the monitor stays active, but
            nothing evaluates it and it reports no firings.
      type: object
      required:
      - items
      - firing_enabled
      title: MonitorTypeList
    NerLabel:
      type: string
      enum:
      - PERSON
      - ORG
      - GPE
      - LOC
      - PRODUCT
      - EVENT
      - LANGUAGE
      - MONEY
      - METRIC
      - STOCK_TICKER
      - WEBSITE
      title: NerLabel
    NotificationChannelCreate:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
        kind:
          $ref: '#/components/schemas/ChannelKind'
          description: How Tako shapes the body it posts. Use slack_workflow for a
            Slack Workflow Builder trigger, which rejects nested values.
          default: webhook
        url:
          type: string
          maxLength: 2048
          format: uri
          title: Url
          description: The https destination that Tako posts to. Tako rejects http,
            a URL that embeds credentials, and a host that resolves to a private or
            loopback address.
      type: object
      required:
      - name
      - url
      title: NotificationChannelCreate
    NotificationChannelCreated:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        kind:
          $ref: '#/components/schemas/ChannelKind'
        url:
          type: string
          title: Url
        status:
          $ref: '#/components/schemas/ChannelStatus'
        status_reason:
          anyOf:
          - $ref: '#/components/schemas/ChannelStatusReason'
          - type: 'null'
          description: Why Tako paused the channel. Null while the channel is active,
            and null when you paused it yourself.
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        secret:
          type: string
          title: Secret
          description: The signing secret for this channel. Store it now, because
            this response is the only place it appears and no later request returns
            it. Tako signs every delivery to this channel with it.
      type: object
      required:
      - id
      - name
      - kind
      - url
      - status
      - status_reason
      - created_at
      - updated_at
      - secret
      title: NotificationChannelCreated
    NotificationChannelList:
      properties:
        items:
          items:
            $ref: '#/components/schemas/NotificationChannelResponse'
          type: array
          title: Items
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - items
      title: NotificationChannelList
    NotificationChannelPatch:
      properties:
        status:
          $ref: '#/components/schemas/ChannelStatus'
          description: Set paused to stop deliveries, or active to resume. Resuming
            a paused channel clears the consecutive-failure count.
      type: object
      required:
      - status
      title: NotificationChannelPatch
    NotificationChannelResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        kind:
          $ref: '#/components/schemas/ChannelKind'
        url:
          type: string
          title: Url
        status:
          $ref: '#/components/schemas/ChannelStatus'
        status_reason:
          anyOf:
          - $ref: '#/components/schemas/ChannelStatusReason'
          - type: 'null'
          description: Why Tako paused the channel. Null while the channel is active,
            and null when you paused it yourself.
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - name
      - kind
      - url
      - status
      - status_reason
      - created_at
      - updated_at
      title: NotificationChannelResponse
    OutputSettings:
      properties:
        image_dark_mode:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Image Dark Mode
          description: Whether to render card preview images in dark mode. Omit it
            and Tako renders dark.
        force_refresh:
          type: boolean
          title: Force Refresh
          description: 'Instant mode only, and currently informational: on these endpoints,
            instant (effort=''instant'') always operates in build-and-refresh mode
            regardless of this flag. Instant retrieves data for embeds that are missing
            or stale, then creates or refreshes their static embeds. Embeds that are
            already fresh (within the refresh cadence) return as-is; Tako does not
            re-retrieve them. Identical queries therefore reuse the same content-addressed
            embed and return a stable embed URL.'
          default: false
        flat_results:
          anyOf:
          - $ref: '#/components/schemas/FlatResultsSettings'
          - type: 'null'
          description: Return cards and web results as one list, results, of one shape.
            Send an object to turn the mode on; an empty object uses the defaults.
            Omit it for the grouped cards and web_results lists.
      additionalProperties: false
      type: object
      title: OutputSettings
      description: Settings that control the response shape.
    PlaceholderInfo:
      properties:
        withheld_source:
          type: string
          title: Withheld Source
          description: The name of the source whose data the card withholds.
      type: object
      required:
      - withheld_source
      title: PlaceholderInfo
      description: Why a card carries no data points.
    PremiumClass:
      type: string
      enum:
      - person_contact
      - company_record
      title: PremiumClass
      description: The price class of a premium column. Person and company records
        are licensed at different per-record rates.
    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
    RelatedSuggestion:
      properties:
        query:
          type: string
          title: Query
          description: The follow-up query. Send it as the `query` of another search
            request.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: What the query asks for, in words. Tako sets this only when
            the query text does not say on its own, such as a lookup by identifier.
            Most suggestions omit it because the query already reads as a question.
            Tako composes it from the data on the card; no language model writes it.
        node_ids:
          items:
            type: string
          type: array
          title: Node Ids
          description: Graph node ids that identify the data this query asks for.
            Pass them as `sources.data.node_ids` on the follow-up search to make the
            search return that data. The list is empty when Tako cannot resolve the
            ids; the query still works on its own.
      type: object
      required:
      - query
      title: RelatedSuggestion
      description: 'One follow-up query for the caller to run next.


        A suggestion is deterministic: Tako derives it from the data a returned

        card already holds. No language model writes these.'
    RelationKind:
      type: string
      enum:
      - related
      - data
      - sibling
      - membership
      title: RelationKind
      description: How Tako derived a relation group.
    ResultContent:
      properties:
        content_format:
          anyOf:
          - $ref: '#/components/schemas/ContentsFormat'
          - type: 'null'
          description: 'Serialization of the returned card data: ''csv'', ''json_records'',
            ''json_compact'', or ''card_json''. Null for web text (always returned
            as raw text) and for a quote-only response (nothing was serialized).'
        cost:
          type: number
          title: Cost
          description: 'Price of this item in USD. On a /contents response this is
            the amount actually billed. On a quote_only response it is a prospective
            /contents export price, because Tako fetched nothing and billed nothing.
            On a search or answer downloadable card it is also a prospective price,
            unless Tako inlined rows for the card; then it is the amount this response
            billed for the card. Use export_pricing on its own to price a /contents
            export of the same card. Do not add this value to that result: they are
            two prices for the same rows, not two charges.'
          default: 0.0
        data:
          anyOf:
          - type: string
          - type: 'null'
          title: Data
          description: 'Inline payload as text: card data serialized to CSV, or a
            web page''s extracted text. Set only for the ''csv'' card format and for
            web text; null otherwise. A card export can hold up to 100,000 rows. Don''t
            read a large export directly into a model''s context: at about 15 tokens
            per row, 10,000 rows cost about 150,000 tokens. Write the export to a
            file, on disk or in memory, and have the agent parse it with code. Give
            the model only the rows or results it needs. To cap the export instead,
            set max_rows.'
        records:
          anyOf:
          - items:
              additionalProperties:
                anyOf:
                - type: string
                - type: number
                - type: integer
                - type: boolean
                - type: 'null'
              type: object
            type: array
          - type: 'null'
          title: Records
          description: 'Inline card data as verbose JSON: a list of row objects keyed
            by column name. Set only when content_format is ''json_records''. A card
            export can hold up to 100,000 rows. Don''t read a large export directly
            into a model''s context: at about 15 tokens per row, 10,000 rows cost
            about 150,000 tokens. Write the export to a file, on disk or in memory,
            and have the agent parse it with code. Give the model only the rows or
            results it needs. To cap the export instead, set max_rows.'
        dataset:
          anyOf:
          - $ref: '#/components/schemas/TakoDataset'
          - type: 'null'
          description: 'Inline card data as a compact TakoDataset (typed column headers
            plus positional row arrays). Set only when content_format is ''json_compact''.
            A card export can hold up to 100,000 rows. Don''t read a large export
            directly into a model''s context: at about 15 tokens per row, 10,000 rows
            cost about 150,000 tokens. Write the export to a file, on disk or in memory,
            and have the agent parse it with code. Give the model only the rows or
            results it needs. To cap the export instead, set max_rows.'
        card_data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Card Data
          description: 'Inline card data as a card-type-specific JSON object. The
            ''card_type'' field inside the object names its shape. Set only when content_format
            is ''card_json''. Tako truncates the record rows in the object to ''max_rows'',
            the same cap every other format takes, and bills the rows it returns.
            A card whose record array is unbounded caps that array at the platform
            export ceiling and reports ''truncated'': true. The payload then also
            carries the true count for its record array. Card types without a card_json
            shape return 422 on /contents and fall back to ''json_compact'' on search
            and answer include_contents. A card export can hold up to 100,000 rows.
            Don''t read a large export directly into a model''s context: at about
            15 tokens per row, 10,000 rows cost about 150,000 tokens. Write the export
            to a file, on disk or in memory, and have the agent parse it with code.
            Give the model only the rows or results it needs. To cap the export instead,
            set max_rows.'
        card_data_schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Card Data Schema
          description: 'JSON Schema for the object in ''card_data''. Read it to learn
            the shape of the payload without parsing the payload. Tako sets this whenever
            content_format is ''card_json''. It is also set in ''url'' delivery mode
            and on a Contents quote, where ''card_data'' is null and the shape is
            all Tako returns. A search or answer card that you did not ask to inline
            carries a price but no schema. The ''title'' field and the ''card_type''
            default inside the schema name the shape. The schema describes the payload
            type, so ''card_data'' can omit a field the schema declares: Tako drops
            a measure the provider did not supply. Null for every other content_format
            and for web text.'
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: Presigned download URL for the content, returned in 'url' delivery
            mode. Null for inline delivery and for quotes; pair with expires_at.
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
          description: ISO-8601 timestamp after which the presigned url stops working.
            Null whenever url is null.
        total_rows:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Rows
          description: Total number of rows in the card's data, independent of how
            many rows were returned. Compare with the rows returned to tell whether
            a larger max_rows returns more. A card that lists a capped slice of a
            larger set, such as the 30 soonest-closing of 330 open solicitations,
            has only that slice as its data, so total_rows is 30 and total_matching
            gives the set's size. On an agent run card, it's set for a card whose
            rows are stored with the card, such as a people list, and null for other
            agent run cards. Null for web text.
        total_matching:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Matching
          description: 'Size of the whole set behind a card that lists a capped slice
            of it, such as 330 for a card listing the 30 soonest-closing of 330 open
            solicitations. It''s the count the card''s description states, and it''s
            the same on every content format. A larger max_rows doesn''t return more
            of that set. Tako reports it for the cards that list such a slice: open
            solicitations, international tenders, a federal agency''s contracts, and
            a company''s news. Null when the card''s rows are the whole set, when
            Tako doesn''t count the set (truncated is still true), and for web text.'
        truncated:
          type: boolean
          title: Truncated
          description: True when the card has more rows than Tako returned. Tako caps
            a card at the request max_rows or at the card's max_rows_ceiling (at most
            100,000), and then total_rows is larger than the rows returned. It's also
            true when the card itself lists a capped slice of a larger set; then total_matching
            gives the set's size when Tako counts it. An inline /contents export that
            omits max_rows returns up to 2,000 rows. On a search or answer response,
            all cards share a budget of 2,000 billable rows and a budget of 20,000
            inline rows, both spent in card order, so a later card can return fewer
            rows than max_rows asked for. A card the billable budget can no longer
            pay for still returns a small preview. A card that arrives after the inline
            budget runs out returns no inline rows, and its export_pricing still prices
            a /contents export of them.
          default: false
        export_pricing:
          anyOf:
          - $ref: '#/components/schemas/ExportPricing'
          - type: 'null'
          description: Rate card for a downloadable card CSV, so a caller can compute
            a full export's cost before fetching. Null for web text and other non-downloadable
            content.
        manifest:
          anyOf:
          - items:
              $ref: '#/components/schemas/ColumnDescriptor'
            type: array
          - type: 'null'
          title: Manifest
          description: 'Per-column metadata, one entry per exported column, in column
            order: entry i describes column i (CSV header i, json_records key i, or
            dataset.columns[i]). Each entry carries name (the column header), dtype,
            unit, metric, entity, and premium_class. On an agent run card, it''s set
            wherever total_rows is. Null for web text and for other quotes that carry
            no tabular columns.'
        premium:
          type: boolean
          title: Premium
          description: 'True when this item''s premium cells are revealed: a /contents
            response to premium=true. False on every search and answer card and on
            a /contents response without the flag. There, a withheld premium cell
            reads [premium: withheld] in CSV and is null in JSON formats, and redacted_cells
            says which rows held a value.'
          default: false
        premium_rows:
          anyOf:
          - additionalProperties:
              type: integer
            type: object
          - type: 'null'
          title: Premium Rows
          description: Per premium class ('company_record', 'person_contact'), the
            number of delivered rows with at least one non-null cell in a column of
            that class, whether revealed or withheld. Multiply by export_pricing.premium_row_cpm_usd[class]
            / 1000 to price the premium part of an export before asking for it. A
            row with cells of two classes counts once in each. Empty for a card with
            no premium columns; null for web text. On an agent run card, it counts
            every row of the card, so a premium=true export of all total_rows rows
            bills exactly these rows when total_rows is within max_rows_ceiling. It's
            set wherever total_rows is.
        redacted_cells:
          anyOf:
          - additionalProperties:
              items:
                type: integer
              type: array
            type: object
          - type: 'null'
          title: Redacted Cells
          description: 'Column header to the 0-based positions, among the delivered
            rows, whose premium value was withheld. Present only when a premium cell
            was withheld; null when premium=true, when nothing was withheld, and for
            web text. Positions index the delivered rows: CSV data rows in order,
            json_records entries, or dataset.rows. In CSV, the same cells read [premium:
            withheld]; a premium cell with no value is blank.'
      type: object
      title: ResultContent
      description: 'Describes the downloadable content behind a result.


        Pricing: for a Tako card CSV export, the charge is a flat per-export

        baseline plus a per-row CPM on every row returned, at the rate that

        ``export_pricing.row_cpm_usd`` publishes. Web text bills at the standard Contents

        rate on POST /v1/contents; web text inlined on a search or answer response

        is free.


        The meaning of `cost` depends on the surface. On `/contents` responses,

        `cost` is the actual charge, and it reconciles with what that response

        billed. The exception is a `quote_only` response, where `cost` is a

        prospective price: Tako neither fetched nor billed the export, and the

        payload and url fields are null. On a search or answer downloadable

        card, `cost` is a prospective `/contents` quote (the per-export baseline

        floor) unless Tako inlined rows for the card, in which case it is what this

        response billed for the card. The billed cards sum to

        `usage.data.cost_usd`, never to `usage.total_cost_usd` (which always adds

        the flat per-request compute rate).


        On a search or answer WEB result, `cost` is always a prospective

        `/v1/contents` quote and NEVER a charge -- including when Tako inlined the

        page text, because inlined web text is free, so the card rule above does not

        carry over. That quote arrives on `cost` alone: `export_pricing` is null for

        web text, so zeroing `cost` on an inlined result would leave a caller no way

        to price a later fetch. A response whose only inlined contents were web text

        therefore reports `usage.data` as null -- nothing was billed for data.


        `export_pricing` carries the `/contents` export rate, so a caller can

        compute the full charge of a later export before fetching: baseline_usd +

        row_cpm_usd * billed_rows / 1000 + sum over classes c of

        premium_row_cpm_usd[c] * premium_rows[c] / 1000, where `billed_rows` is the

        SMALLER of the rows the export returns and `max_rows` clamped to

        `max_rows_ceiling`, `premium_rows` is this item''s per-class count, and the

        premium term applies only to an export that passes `premium=true`. One

        formula covers every format, card_json included: every export returns no

        more rows than that cap, so a card with fewer rows than the cap bills only

        the rows it returns. `row_cpm_usd` is the CALLER''S rate -- 0 where their
        row

        charges are waived, the same waiver a billed inline card''s `cost` uses, and

        /contents resolves it too. `export_pricing` is null for web text

        and non-downloadable content.


        Do NOT combine `cost` with `export_pricing` on a billed inline card. There,

        `cost` is the amount THIS response charged, over the rows this response

        inlined, so it is not a `/contents` price for the same card: the two cover

        different row counts, because a search response''s default inline cap is far

        smaller than what `/contents` returns. Read `cost` for what this response

        billed. Use `export_pricing` alone

        to price a `/contents` export of the same card.


        Tako populates exactly one payload group once it delivers contents:

        `data` (CSV or web text), `records` (verbose JSON), `dataset` (compact

        TakoDataset), `card_data` (rich card-type-specific JSON), or `url` plus

        `expires_at` (presigned download).

        `content_format` names the serialization; it is null for web text and

        for an undelivered quote. Read `content_format` to tell a quote from a

        delivery: when it is null, this is just the quote (`cost`); fetch the

        content later via the Contents endpoint.


        Do NOT use "every payload field is null" as that test. `card_data_schema`

        is set on a card_json quote and on a card_json `url` delivery, where

        `card_data` is null, so a caller reading absent payloads as "quote" reads

        those two as quotes.'
    ResultSource:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Publisher name.
          examples:
          - S&P Global
          - bea.gov
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: Publisher URL.
          examples:
          - https://www.bea.gov
      type: object
      title: ResultSource
      description: One publisher behind a flat result.
    RetrievalAgentEffort:
      type: string
      enum:
      - medium
      title: RetrievalAgentEffort
      description: 'Effort taxonomy for the Retrieval Agent (POST /v1/agent/retrieval/runs).


        Only ''medium'' is available today. `effort` stays a request field for

        forward compatibility and for parity with AnswerAgentEffort. The values

        ''low'' and ''high'' return 400 at validation.'
    RetrievalAgentResult:
      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/AgentAnswerMetadata'
          - type: 'null'
        structured_output:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Structured Output
          description: Caller-shaped structured output (present only if the request
            carried output_schema and status is not 'failed'). Dataset slots contain
            a TakoDataset envelope of exact retrieved rows, or null when the agent
            left them unfilled.
        structured_output_status:
          anyOf:
          - $ref: '#/components/schemas/StructuredOutputStatus'
          - type: 'null'
          description: complete | partial | failed. Present when the request supplied
            output_schema and the run reached the finalize step. It can be absent
            when the whole run failed or timed out before finalize; the run-level
            status and error convey that, and the echoed request.output_schema still
            identifies the run as structured.
        structured_output_citations:
          anyOf:
          - additionalProperties:
              items:
                type: integer
              type: array
            type: object
          - type: 'null'
          title: Structured Output Citations
          description: Best-effort field-path -> citation-index map joining the top-level
            citations registry (same [n] index space as the answer). Absent when status
            is 'failed'.
        unfilled_fields:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Unfilled Fields
          description: Dot-separated paths of unfilled dataset slots; present only
            if status is 'partial'.
        structured_output_error:
          anyOf:
          - $ref: '#/components/schemas/ErrorObject'
          - type: 'null'
          description: Why structured output failed; present only if status is 'failed'.
        refusal_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Refusal Code
          description: Set when Tako rejected the query before the agent ran. Null
            on normal runs. Tako can add new codes, so accept a code you do not recognize.
            The current code is 'rejected_input_classifier'.
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
      type: object
      title: RetrievalAgentResult
      description: 'Final retrieval-agent output. answer is markdown prose with [n]

        citation markers. cards reuse the sibling TakoCard. citations is the

        unified top-level registry for data and web sources — there is no

        web_results field. metadata carries definitions, assumptions, and

        methodology. The structured_output_* fields carry the caller-shaped

        output_schema result; they are present only if the request supplied

        output_schema. See each field''s description for the exact presence

        rules.'
    RetrievalAgentResultEvent:
      properties:
        kind:
          type: string
          const: agent_result
          title: Kind
          default: agent_result
        id:
          type: string
          title: Id
        data:
          $ref: '#/components/schemas/RetrievalAgentResult'
      type: object
      required:
      - id
      - data
      title: RetrievalAgentResultEvent
    RetrievalAgentRun:
      properties:
        run_id:
          type: string
          title: Run Id
        object:
          type: string
          const: agent.retrieval.run
          title: Object
          default: agent.retrieval.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/RetrievalAgentResult'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorObject'
          - type: 'null'
        usage:
          anyOf:
          - $ref: '#/components/schemas/Usage'
          - type: 'null'
        request:
          anyOf:
          - $ref: '#/components/schemas/RetrievalAgentRunRequest'
          - type: 'null'
      type: object
      required:
      - run_id
      - status
      - created_at
      title: RetrievalAgentRun
      description: The retrieval-agent run resource returned by dispatch (202) and
        poll (GET).
    RetrievalAgentRunList:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        data:
          items:
            $ref: '#/components/schemas/RetrievalAgentRunSummary'
          type: array
          title: Data
        has_more:
          type: boolean
          title: Has More
          default: false
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - data
      title: RetrievalAgentRunList
      description: 'List envelope for GET /v1/agent/retrieval/runs. The shape follows
        the

        OpenAI and Exa list convention.'
    RetrievalAgentRunRequest:
      properties:
        query:
          type: string
          title: Query
          description: Natural-language data-retrieval request for the retrieval agent.
          examples:
          - S&P 500 semiconductor companies' 2024 revenue and YoY growth
        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:
          anyOf:
          - $ref: '#/components/schemas/RetrievalAgentEffort'
          - type: 'null'
          description: Retrieval-agent effort. Only 'medium' is supported; omit it
            and Tako uses medium.
        source_indexes:
          anyOf:
          - items:
              type: string
              enum:
              - data
              - web
            type: array
          - type: 'null'
          title: Source Indexes
          description: 'Which sources the agent may use: ''data'' (curated knowledge),
            ''web'' (open-web search), or both. Omit it on a new thread and the agent
            uses both; omit it on a follow-up and the run keeps the thread''s sources.
            Tako accepts the legacy value ''tako'' as a synonym for ''data''.'
          examples:
          - - data
          - - web
          - - data
            - web
        cards:
          type: boolean
          title: Cards
          description: 'Whether the agent may build visualization cards. True is permissive:
            the agent may build cards, but it does not have to (a completed run with
            no cards is legitimate). Set false to suppress card building entirely.'
          default: true
        output_schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Output Schema
          description: 'JSON Schema for structured output. The agent writes the synthesized
            fields. Dataset slots (marked with x-tako-dataset: true) receive exact
            retrieved rows as a TakoDataset. Supported subset: the object, array,
            string, number, integer, and boolean types, plus enum, required, and description.
            Caps: 16KB, depth 5, 64 properties, 4 dataset slots. Violations return
            400 output_schema_invalid.'
        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.
          default: en-US
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
          description: IANA timezone (for example, 'America/New_York'). The agent
            uses it to render dates and times in card preview images. It does not
            affect the returned data.
        output_settings:
          anyOf:
          - $ref: '#/components/schemas/AgentOutputSettings'
          - type: 'null'
          description: Settings that control the response and rendering.
      type: object
      required:
      - query
      title: RetrievalAgentRunRequest
      description: Request body for POST /v1/agent/retrieval/runs.
    RetrievalAgentRunSummary:
      properties:
        run_id:
          type: string
          title: Run Id
        status:
          $ref: '#/components/schemas/AgentRunStatus'
        created_at:
          type: string
          title: Created At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
        thread_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Thread Id
        usage:
          anyOf:
          - $ref: '#/components/schemas/Usage'
          - type: 'null'
        object:
          type: string
          const: agent.retrieval.run
          title: Object
          default: agent.retrieval.run
      type: object
      required:
      - run_id
      - status
      - created_at
      title: RetrievalAgentRunSummary
    RetrievalAgentStreamEnvelope:
      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/RetrievalAgentResultEvent'
          - $ref: '#/components/schemas/RunSummaryEvent'
          - $ref: '#/components/schemas/HeartbeatEvent'
          - $ref: '#/components/schemas/StreamResetEvent'
          - $ref: '#/components/schemas/StreamDoneEvent'
          title: Block
          discriminator:
            propertyName: kind
            mapping:
              agent_result: '#/components/schemas/RetrievalAgentResultEvent'
              data_pipeline_answer: '#/components/schemas/DataPipelineAnswerEvent'
              heartbeat: '#/components/schemas/HeartbeatEvent'
              reasoning: '#/components/schemas/ReasoningEvent'
              run_summary: '#/components/schemas/RunSummaryEvent'
              status: '#/components/schemas/StatusEvent'
              stream_done: '#/components/schemas/StreamDoneEvent'
              stream_reset: '#/components/schemas/StreamResetEvent'
              subagent: '#/components/schemas/SubagentEvent'
              text: '#/components/schemas/TextEvent'
              tool_call: '#/components/schemas/ToolCallEvent'
              tool_error: '#/components/schemas/ToolErrorEvent'
              tool_result: '#/components/schemas/ToolResultEvent'
              tool_retry: '#/components/schemas/ToolRetryEvent'
      type: object
      required:
      - seq
      - run_id
      - category
      - block
      title: RetrievalAgentStreamEnvelope
      description: 'Public SSE envelope for the Retrieval Agent run stream. It has
        the same

        wire shape as AgentStreamEnvelope. The only difference is that the

        terminal agent_result block carries RetrievalAgentResult (unified

        top-level citations, no web_results), so the SSE terminal matches the

        GET poll result.'
    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. The stream emits it once, immediately before

        stream_done. It mirrors the GET-poll run fields that the stream otherwise

        lacks; the result stays in the agent_result event. status, created_at,

        and completed_at are always present. error appears only on failure. usage

        appears only on metered (pay-as-you-go) runs and is null otherwise.

        agent_result plus run_summary equals the GET poll object, with one exception:

        for up to the durability grace window after a run completes, the GET poll
        can

        report it still running while this frame reports it completed. The poll holds

        such a run so the client asks again; this frame is emitted once with nothing

        after it, so it cannot. Read the frame as authoritative on status.


        It carries the same envelope `seq` as the stream_done that follows it (it

        has no seq of its own), and the stream suppresses its SSE `id:`, so it

        advances no resume cursor. Identify it by `kind`; never assume `seq` is

        unique per frame.'
    Scalar:
      anyOf:
      - type: string
      - type: integer
      - type: number
      - type: boolean
      - type: 'null'
    SearchEffortLevel:
      type: string
      enum:
      - fast
      - instant
      - deep
      title: SearchEffortLevel
      description: 'Public effort taxonomy for search and answer. FAST is the default.

        INSTANT serves cached embeds without a new data retrieval and works in all

        environments. On /v1/answer it also writes the answer with the fastest

        synthesis model, so it trades answer quality for latency. On /v1/answer FAST

        and DEEP both write the answer with a stronger model. DEEP also widens Tako

        retrieval and adds a second, higher-quality reranking pass; it''s slower and

        bills at a premium tier.'
    SearchRequest:
      properties:
        query:
          type: string
          minLength: 1
          pattern: \S
          title: Query
          description: Natural language search query.
          examples:
          - Intel vs Nvidia headcount since 2013
        effort:
          $ref: '#/components/schemas/SearchEffortLevel'
          description: 'Search effort level: ''fast'', ''instant'', or ''deep''.'
          default: fast
        sources:
          $ref: '#/components/schemas/Sources'
          description: Per-source settings. The search includes an index only if its
            key is present. Omit it and Tako searches data and web with no counts
            set. Tako accepts the legacy key 'tako' as a synonym for 'data'.
        location:
          anyOf:
          - $ref: '#/components/schemas/GeoLocation'
          - type: 'null'
          description: Optional coordinates of the end user. Resolves the location
            for implicit-location queries (for example, weather) and, when `timezone`
            is absent, the timezone Tako renders preview images in. An explicit location
            in the query overrides these coordinates.
        country_code:
          type: string
          title: Country Code
          description: ISO 3166-1 alpha-2 country code for localization.
          default: US
        locale:
          type: string
          title: Locale
          description: BCP-47 locale tag for language and formatting.
          default: en-US
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
          description: IANA timezone (for example, 'America/New_York') Tako renders
            preview images in. Defaults to the zone at `location` when you send coordinates.
            Card text keeps each surface's own timezone.
        output_settings:
          anyOf:
          - $ref: '#/components/schemas/OutputSettings'
          - type: 'null'
          description: Settings that control the response shape.
        include_related:
          anyOf:
          - type: integer
            maximum: 20
            minimum: 1
          - type: 'null'
          title: Include Related
          description: 'Applies to POST /v3/search only. Return follow-up query suggestions
            in `related`. Omit this field to disable them. The value sets the maximum
            number of suggestions, from 1 to 20. POST /v1/answer accepts this field
            but ignores it: the answer response has no `related` field.'
        variable_cost:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Variable Cost
          description: 'Return data from sources priced per unit, such as web traffic
            and SEO data. Such data adds a charge above the request''s own price,
            which the response''s `usage` object reports as `variable_cost`. Set it
            to false and each such card is a placeholder with its title and no data
            points. Leave it out and your account''s default applies: on for a contract
            account with signed terms, off otherwise. A contract account without signed
            terms gets placeholders whatever you send.'
      additionalProperties: false
      type: object
      required:
      - query
      title: SearchRequest
      description: Shared request for POST /api/v3/search and POST /api/v1/answer.
    SearchResponse:
      properties:
        cards:
          items:
            $ref: '#/components/schemas/TakoCard'
          type: array
          title: Cards
        web_results:
          items:
            $ref: '#/components/schemas/WebResult'
          type: array
          title: Web Results
        request_id:
          type: string
          title: Request Id
        usage:
          anyOf:
          - $ref: '#/components/schemas/Usage'
          - type: 'null'
        related:
          anyOf:
          - items:
              $ref: '#/components/schemas/RelatedSuggestion'
            type: array
          - type: 'null'
          title: Related
          description: Follow-up queries you can run next. Set `include_related` on
            the request to receive them. Absent when you did not ask for them, or
            when Tako found none.
        results:
          anyOf:
          - items:
              $ref: '#/components/schemas/FlatResult'
            type: array
          - type: 'null'
          title: Results
          description: Cards and web results as one list, present only when the request
            set output_settings.flat_results. cards and web_results are then empty.
      type: object
      required:
      - request_id
      title: SearchResponse
    Sources:
      properties:
        data:
          $ref: '#/components/schemas/DataSourceSettings'
          description: Tako data source (curated knowledge). The search includes it
            only if present. Tako accepts the legacy key 'tako' as a synonym.
        web:
          $ref: '#/components/schemas/WebSourceSettings'
          description: Web source. The search includes it only if present.
      additionalProperties: false
      type: object
      minProperties: 1
      title: Sources
      description: 'Per-source settings. The search includes an index only if its
        field is

        present.


        The Tako data source is named `data`. Tako still accepts the legacy key

        `tako` as a synonym and maps it to `data` before validation.'
    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
    StatusReason:
      type: string
      enum:
      - fired_once
      - unloadable
      - expired
      - completed
      title: StatusReason
    StreamCategory:
      type: string
      enum:
      - content
      - activity
      - control
      title: StreamCategory
    StreamDoneEvent:
      properties:
        kind:
          type: string
          const: stream_done
          title: Kind
          default: stream_done
      type: object
      title: StreamDoneEvent
    StreamResetEvent:
      properties:
        kind:
          type: string
          const: stream_reset
          title: Kind
          default: stream_reset
      type: object
      title: StreamResetEvent
    StructuredOutputStatus:
      type: string
      enum:
      - complete
      - partial
      - failed
      title: StructuredOutputStatus
      description: Terminal status of the structured-output channel.
    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
    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'
          description: 'Tako''s relevance label for this card, from the same ladder
            the flat `results` relevance uses. On `effort: deep` an LLM scores cards
            as integers 1 to 5, so a 5 is High and a 4 is Medium. A card the LLM leaves
            unscored keeps its continuous retrieval score and can be High below 5.
            Other efforts score continuously and can label the same card higher.'
        content:
          anyOf:
          - $ref: '#/components/schemas/ResultContent'
          - type: 'null'
        exportable:
          type: boolean
          title: Exportable
          description: Whether the /contents endpoint can download this card's data.
            false means the export is not available; use the card's chart and inline
            preview instead. true means the export is eligible but not guaranteed;
            the /contents endpoint can still return 403, so fall back to the preview
            on error.
          default: false
        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) behind this card. The response
            includes them by default. Absent for web-only cards or when node resolution
            was not available. Use each id with /v1/graph/node/{id} for full detail
            (aliases, subtype), or pass ids in sources.data.node_ids to pin these
            nodes in future searches.
        metric_definitions:
          anyOf:
          - items:
              $ref: '#/components/schemas/MetricDefinition'
            type: array
          - type: 'null'
          title: Metric Definitions
          description: Definitions of the metrics this card displays (name + definition).
            Null when no displayed metric has a definition available.
        data_freshness:
          anyOf:
          - $ref: '#/components/schemas/DataFreshness'
          - type: 'null'
          description: 'Freshness dates for the card''s data: where the data ends
            (coverage_end), the same point as a full date (data_as_of, deprecated),
            and the last refresh date (last_updated). Null when no date is available.'
        placeholder:
          anyOf:
          - $ref: '#/components/schemas/PlaceholderInfo'
          - type: 'null'
          description: 'Set when the card is a placeholder: it carries its title and
            no data points, because the request didn''t include its source''s data.
            Null on every card that carries its data.'
      type: object
      title: TakoCard
      description: 'A Tako knowledge card on the search and answer surfaces. It carries
        a

        `content` download descriptor.'
    TakoCardNode:
      properties:
        id:
          type: string
          title: Id
          description: Opaque, human-friendly public id (<prefix>::<name>::<hash>,
            where prefix is ent for an entity or mt for a metric). Ids are not durable
            across knowledge-graph rebuilds — resolve them at request time rather
            than storing them.
        type:
          $ref: '#/components/schemas/GraphNodeType'
          description: Whether the node is a metric or an entity.
        name:
          type: string
          title: Name
          description: Display name. Several metrics can share a name when publishers
            report different series, such as two GDP metrics; read `description` to
            tell them apart.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: What the node is. For a metric, what it measures, often with
            its unit and basis. For an entity, a short identification. Absent when
            Tako has none.
      type: object
      required:
      - id
      - type
      - name
      title: TakoCardNode
      description: 'Slim graph node for the search and answer card surface

        (TakoCard.nodes). It is deliberately narrower than GraphNode: it carries

        no `aliases` and no `subtype`. For a node''s aliases, resolve the id via

        /v1/graph/node/{id}; for an entity''s subtype, use /v1/graph/related.'
    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 excerpts retrieved from the source page — the unmodified
            web content that grounded the answer. Present for WEB sources; null for
            DATA sources.
      type: object
      required:
      - source_index
      title: TakoCardSource
      description: 'A source that backs a TakoCard on the SDK surfaces. It uses the

        {data, web} TakoSourceIndex taxonomy.'
    TakoDatasetColumn:
      properties:
        name:
          type: string
          title: Name
          description: Column name.
        type:
          $ref: '#/components/schemas/TakoDatasetColumnType'
          description: 'Logical column type: ''string'', ''number'', ''boolean'',
            ''date'', or ''datetime''. Temporal cells are ISO-8601 strings.'
        unit:
          anyOf:
          - type: string
          - type: 'null'
          title: Unit
          description: Structured unit for the column values, e.g. 'USD billions',
            '%'. Null when unitless.
      type: object
      required:
      - name
      - type
      title: TakoDatasetColumn
      description: Typed header entry; `type` is the JSON-facing column type.
    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. Each column declares ''date'' or ''datetime'' on its

        own: a temporal column whose non-null values are all timezone-naive

        midnights declares ''date''.'
    TakoDatasetSource:
      properties:
        name:
          type: string
          title: Name
          description: Human-readable source name (e.g. 'FRED', 'S&P Global').
        index:
          type: string
          enum:
          - data
          - web
          title: Index
          description: 'Source index the rows came from: ''data'' (Tako) or ''web''.'
          default: data
      type: object
      required:
      - name
      title: TakoDatasetSource
      description: 'Per-dataset provenance entry. `index` names the source index,
        not a

        citation display number. It is "data" for every dataset today — web

        content never fills a dataset slot.'
    TakoSourceIndex:
      type: string
      enum:
      - data
      - web
      title: TakoSourceIndex
      description: 'Public source taxonomy for the SDK card surfaces (v3 search, v1
        answer,

        agent). It is symmetric with the request taxonomy {data, web}.'
    TeamResponse:
      properties:
        id:
          type: string
          title: Id
          description: The team's id, the same id GET /api/v1/sports/games returns
            as home.id or away.id. When monitorable is true, pass it to a sports monitor
            as team_id.
        name:
          type: string
          title: Name
        abbreviation:
          anyOf:
          - type: string
          - type: 'null'
          title: Abbreviation
          description: Short name, such as LAL. Null when the team has none.
        leagues:
          items:
            type: string
          type: array
          title: Leagues
          description: League ids the team plays in, such as NBA or EPL. A soccer
            club lists the leagues of its latest season in each competition.
        sport:
          anyOf:
          - type: string
          - type: 'null'
          title: Sport
          description: Sport id, such as basketball. Null when Tako has no record
            of the sport.
        monitorable:
          type: boolean
          title: Monitorable
          description: True when sports monitors accept id as team_id. sports.score_event
            doesn't take an NBA team. False for teams no live feed covers, such as
            college football, F1, and NASCAR.
        upcoming_games:
          items:
            $ref: '#/components/schemas/GameResponse'
          type: array
          title: Upcoming Games
          description: Up to three scheduled or live games from one day back to seven
            days ahead, soonest first. Empty when the team has none in that window,
            or when generated_at is null.
      type: object
      required:
      - id
      - name
      - abbreviation
      - leagues
      - sport
      - monitorable
      - upcoming_games
      title: TeamResponse
      description: A team the search matched.
    TeamsResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/TeamResponse'
          type: array
          title: Items
        generated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Generated At
          description: When Tako read the upcoming games. Null when they failed to
            load. Every upcoming_games list is then empty, even for a team that has
            games.
      type: object
      required:
      - items
      - generated_at
      title: TeamsResponse
      description: Teams that match the search, best match first.
    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
    ThinVizCard:
      properties:
        card_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Card Id
          description: Public ID of the created card.
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: Card title.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Card description.
        webpage_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Webpage Url
          description: Hosted page URL for the card.
        image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Image Url
          description: Static preview image URL for the card.
        embed_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Embed Url
          description: Embeddable URL for the card.
        card_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Card Type
          description: The card's chart type (for example, 'bar').
        visualization_data:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Visualization Data
          description: Inline chart config + data for rendering the card.
          examples:
          - data:
            - x: '2013'
              y: 10000
            viz_config:
              title: Revenue
        embed_mode:
          anyOf:
          - type: string
            enum:
            - post
            - postmessage
          - type: 'null'
          title: Embed Mode
          description: 'How Tako delivers the embed: ''postmessage'' for postMessage
            embeds, and ''post'' otherwise.'
      type: object
      title: ThinVizCard
      description: 'Response for POST /api/v1/thin_viz/create — a created visualization
        card.


        Distinct from KnowledgeCard: thin_viz builds a self-contained chart from

        a caller-supplied component schema, so it never carries retrieval

        provenance (sources, source_indexes) or downloadable raw data. Render the

        card via `embed_url` and preview it via `image_url`.

        `visualization_data` carries the inline chart config and data.


        This schema documents the populated subset of the response. The wire

        payload also includes the remaining KnowledgeCard fields (sources,

        source_indexes, methodologies, data_url, and so on) as null.'
    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
    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
    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
    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
    Usage:
      properties:
        total_cost_usd:
          type: number
          title: Total Cost Usd
          description: 'Total quoted USD cost of this request: the sum of the components
            present.'
        compute:
          anyOf:
          - $ref: '#/components/schemas/UsageCompute'
          - type: 'null'
          description: Compute cost breakdown. Present only on surfaces with a compute
            step (absent for contents).
        data:
          anyOf:
          - $ref: '#/components/schemas/UsageData'
          - type: 'null'
          description: Inline-data cost breakdown. Present only when the surface emitted
            billable inline data.
        variable_cost:
          anyOf:
          - $ref: '#/components/schemas/UsageVariableCost'
          - type: 'null'
          description: 'Variable-cost charge. Present only when the data a request
            or agent run served had a per-unit minimum above its own price: on a search,
            answer or contents request that set variable_cost, and on an agent run
            once it completes.'
      type: object
      required:
      - total_cost_usd
      title: Usage
      description: 'Usage for one metered request. `total_cost_usd` is always present
        (the

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

        each appears only where it applies. total_cost_usd always equals the sum

        of the components that appear.'
    UsageCompute:
      properties:
        cost_usd:
          type: number
          title: Cost Usd
          description: USD cost of running the operation.
      type: object
      required:
      - cost_usd
      title: UsageCompute
      description: 'The cost of running the operation. Absent on surfaces with no
        compute

        step (contents).'
    UsageData:
      properties:
        cost_usd:
          type: number
          title: Cost Usd
          description: USD cost of the inline data delivered in the response.
        datasets:
          type: integer
          title: Datasets
          description: Number of billed datasets or content items included in the
            response.
        data_points:
          anyOf:
          - type: integer
          - type: 'null'
          title: Data Points
          description: Number of billed quantitative data points included in the response.
      type: object
      required:
      - cost_usd
      - datasets
      title: UsageData
      description: 'The cost and quantity of data delivered in the response.


        `datasets` counts billed datasets or content items. `data_points` counts

        billed quantitative values in generated answer output.'
    UsageVariableCost:
      properties:
        cost_usd:
          type: number
          title: Cost Usd
          description: USD cost of the variable-cost charge.
      type: object
      required:
      - cost_usd
      title: UsageVariableCost
      description: 'The variable-cost charge: the per-unit minimum of a variable-cost
        source

        the response served, above the response''s own price.'
    WebCategory:
      type: string
      enum:
      - news
      - sports
      - finance
      title: WebCategory
      description: 'Web search category filter. Only ''news'' maps to a provider category

        today; ''sports'' and ''finance'' are accepted but have no effect yet.'
    WebResult:
      properties:
        title:
          type: string
          title: Title
          description: Title of the web page.
        url:
          type: string
          title: Url
          description: URL of the web page.
        snippet:
          anyOf:
          - type: string
          - type: 'null'
          title: Snippet
          description: Excerpt(s) from the page that matched the query.
        source_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Name
          description: Publisher or domain name, when Tako can extract it from the
            URL.
        publish_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Publish Date
          description: Publication date of the page, when available.
        content:
          anyOf:
          - $ref: '#/components/schemas/ResultContent'
          - type: 'null'
          description: Downloadable content descriptor for this result, fetched via
            the Contents endpoint. Web results are always downloadable as text. None
            for callers that do not populate it.
      type: object
      required:
      - title
      - url
      title: WebResult
      description: 'A single raw web search result from the WEB source index.


        Distinct from `KnowledgeCardSource` (a citation inside a synthesized

        answer) and `KnowledgeCard` (a Tako visualization). Web results are

        raw retrieval output — title, URL, optional snippet. They do not depend

        on any LLM synthesis that may also happen over them.'
    WebSourceSettings:
      properties:
        count:
          anyOf:
          - type: integer
            maximum: 20
            minimum: 1
          - type: 'null'
          title: Count
          description: Maximum number of web results to return, 1 to 20. Omit it and
            Tako uses 5 on search and 3 on answer, unless a result cap set elsewhere
            in the request sizes retrieval instead.
        include_contents:
          type: boolean
          title: Include Contents
          description: 'Inline the page text of each web result in the response. Tako
            returns it free of charge, on a best-effort basis: if a page''s text isn''t
            available at search time, content.data is null. To fetch a page directly,
            use POST /api/v1/contents.'
          default: false
        category:
          anyOf:
          - $ref: '#/components/schemas/WebCategory'
          - type: 'null'
          description: Restrict web results to a category. 'news' filters to news
            sources. 'sports' and 'finance' are accepted but have no effect yet. Omit
            for a general web search.
        include_domains:
          items:
            type: string
          type: array
          maxItems: 20
          title: Include Domains
          description: 'Return only results from these domains. Max 20. Send a bare
            host that includes a top-level domain: ''cnn.com'', not ''cnn''.'
        exclude_domains:
          items:
            type: string
          type: array
          maxItems: 20
          title: Exclude Domains
          description: 'Drop results from these domains. Max 20. Send a bare host
            that includes a top-level domain: ''cnn.com'', not ''cnn''.'
        snippet_max_chars:
          anyOf:
          - type: integer
            maximum: 20000
            minimum: 1
          - type: 'null'
          title: Snippet Max Chars
          description: Character cap on the text excerpt returned per web result,
            up to 20000. Omit it and Tako uses 4000 on search and 1000 on answer,
            unless Tako has agreed a different cap for your account. Send a value
            and Tako uses it exactly.
        highlights:
          type: boolean
          title: Highlights
          description: 'Return query-relevant highlight passages as each web result''s
            snippet, instead of the opening text of the page. Highlights usually carry
            the answer-bearing sentences, and stay within snippet_max_chars. Unless
            you also set include_contents, Tako requests no page text, so a page with
            no highlight returns snippet: null. The snippet can also hold more than
            one passage from different parts of the page, joined by '' … ''. Read
            the snippet as a whole. Do not cut the snippet to a fixed length. Do not
            quote the snippet as one continuous sentence.'
          default: false
        article_content_max_chars:
          type: integer
          maximum: 1000000
          minimum: 1
          title: Article Content Max Chars
          description: Character cap on the full article text when include_contents
            is true.
          default: 30000
        published_after:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Published After
          description: Keep only web results published on or after this date (ISO
            'YYYY-MM-DD'). Tako applies the date on the provider where possible, and
            always filters the returned results. Results with no known publication
            date are kept. Omit for no lower bound.
        published_before:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Published Before
          description: Keep only web results published on or before this date (ISO
            'YYYY-MM-DD'). Results with no known publication date are kept. Omit for
            no upper bound.
      additionalProperties: false
      type: object
      title: WebSourceSettings
      description: 'Web source settings. Adds category, domain filters, and character
        caps

        on top of the base count and include_contents.'
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header