OpenAI-Compatible API

Tako exposes its Answer and Agent products through an OpenAI-compatible gateway. Point the official OpenAI SDK at Tako with just a base_url and a model — no SDK swap, no new client — and get answers grounded in real-time, trusted data alongside the Tako cards and citations that back them.

Endpoint	OpenAI interface	Models	Use case
`/chat/completions`	Chat Completions API	`tako-answer`, `tako-retrieval-agent`, `tako-answer-agent`	Single-shot, stateless requests.
`/responses`	Responses API	`tako-answer`, `tako-retrieval-agent`, `tako-answer-agent`	Event-based; supports stateful agent follow-ups.

This is a wire-compatible gateway over Answer and the two Agent products, not a chat model. A tako-answer request is a stateless, single-shot query. The agents run deep research: tako-retrieval-agent returns a data-first listing with cards, and tako-answer-agent returns a synthesized, cited answer. On the Responses API, both agents support stateful follow-ups. A few OpenAI behaviors do not carry over — see Compatibility.

Overview

Set two things on your OpenAI client:

base_url → https://tako.com/api/openai/v1
api_key → your Tako API key (sent as the Authorization: Bearer header)

Then choose a model:

Model	Backed by	Best for
`tako-answer`	Answer	A fast, synchronous grounded answer.
`tako-retrieval-agent`	Retrieval Agent	Deep research that returns a data-first listing plus visualization cards (slower — stream it).
`tako-answer-agent`	Answer Agent	Deep research synthesized into a written, citation-backed answer plus cards (slower — stream it).

Python
cURL

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://tako.com/api/openai/v1",
    api_key=os.environ["TAKO_API_KEY"],
)

# Set your key once for the examples below.
export TAKO_API_KEY=<your tako key>

Choosing sources

By default the gateway grounds answers in both Tako’s curated knowledge and the live web. Pass source_indexes to restrict that — an array containing "data", "web", or both. It applies to both APIs and both models. Since it isn’t a native OpenAI field, pass it through extra_body with the SDK (or as a top-level field in a raw request).

completion = client.chat.completions.create(
    model="tako-answer",
    messages=[{"role": "user", "content": "What is the price of silver?"}],
    extra_body={"source_indexes": ["data"]},   # Tako curated data only; omit to use both
)

curl https://tako.com/api/openai/v1/chat/completions \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tako-answer",
    "messages": [{"role": "user", "content": "What is the price of silver?"}],
    "source_indexes": ["data"]
  }'

Allowed values are "data" and "web". The legacy value "tako" is accepted as a synonym for "data". The list must be non-empty — an empty or invalid list returns 400. On the Responses API, pass source_indexes the same way.

Chat Completions

Answer

tako-answer returns a synthesized answer in one synchronous call — the OpenAI equivalent of Answer. The prose lands in message.content; the Tako cards and citations that back it ride a namespaced tako extension on the message.

completion = client.chat.completions.create(
    model="tako-answer",
    messages=[{"role": "user", "content": "What is the price of silver?"}],
)

message = completion.choices[0].message
print(message.content)                 # the grounded answer
for card in message.tako["cards"]:      # the backing Tako cards
    print(card["title"], card["embed_url"])

curl https://tako.com/api/openai/v1/chat/completions \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tako-answer",
    "messages": [{"role": "user", "content": "What is the price of silver?"}]
  }'

Example response

A standard chat.completion. The answer is in choices[0].message.content; the backing cards and citations are in choices[0].message.tako.

{
  "id": "chatcmpl-2b7a4f0a9c2e7b1a2c3d4e5f",
  "object": "chat.completion",
  "created": 1750000000,
  "model": "tako-answer",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Silver is trading at about $34.80 per troy ounce ...",
        "tako": {
          "cards": [
            {
              "card_id": "KfYeym50vtsF93LMsIFW",
              "title": "Silver Price",
              "description": "Spot price of silver per troy ounce in USD.",
              "embed_url": "https://tako.com/embed/KfYeym50vtsF93LMsIFW/",
              "webpage_url": "https://tako.com/card/KfYeym50vtsF93LMsIFW/",
              "image_url": "https://tako.com/api/v1/image/KfYeym50vtsF93LMsIFW/",
              "sources": [
                {"source_name": "Tako Markets", "source_index": "tako"}
              ]
            }
          ],
          "citations": [
            {
              "index": 1,
              "title": "Silver price today: rises on July 22",
              "url": "https://www.fxstreet.com/news/silver-price-today-silver-rises-according-to-fxstreet-data-202607220930",
              "source_name": "fxstreet.com",
              "source_index": "web",
              "excerpt": "Silver trades at $59.50 per troy ounce, up 1.19% from the $58.80 it cost on Tuesday.",
              "publish_date": "2026-07-22T09:30:30.000Z"
            }
          ],
          "request_id": "f20f965b-6bbd-40df-b50b-a8861f34df24"
        }
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
}

Agents

Which agent? tako-retrieval-agent returns a data-first listing of the values it found, plus the visualization cards. tako-answer-agent synthesizes everything into a written answer with [n] citation markers. Both run deep research and can take minutes — prefer streaming. A non-streaming call holds the connection open until the run finishes, and returns 504 (run_timeout, carrying the run_id) if the run overruns ~290 seconds.

Retrieval Agent

tako-retrieval-agent runs the Retrieval Agent: multi-step retrieval that returns a data-first listing plus the visualization cards.

completion = client.chat.completions.create(
    model="tako-retrieval-agent",
    messages=[{"role": "user", "content": "US nominal GDP over the last 5 years"}],
)
print(completion.choices[0].message.content)
for card in completion.choices[0].message.tako["cards"]:
    print(card["title"], card["embed_url"])

curl https://tako.com/api/openai/v1/chat/completions \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tako-retrieval-agent",
    "messages": [{"role": "user", "content": "US nominal GDP over the last 5 years"}]
  }'

Answer Agent

tako-answer-agent runs the Answer Agent: deep research synthesized into a written, citation-backed answer.

completion = client.chat.completions.create(
    model="tako-answer-agent",
    messages=[{"role": "user", "content": "Compare Nvidia and AMD revenue since 2015"}],
)
print(completion.choices[0].message.content)

curl https://tako.com/api/openai/v1/chat/completions \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tako-answer-agent",
    "messages": [{"role": "user", "content": "Compare Nvidia and AMD revenue since 2015"}]
  }'

Streaming

Set stream=True to receive the answer as it is produced — recommended for the agents. The text arrives in delta.content chunks; the Tako cards and citations arrive in a single dedicated delta.tako chunk near the end of the stream.

stream = client.chat.completions.create(
    model="tako-answer-agent",
    messages=[{"role": "user", "content": "Compare Nvidia and AMD revenue since 2015"}],
    stream=True,
)

cards = []
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)
    tako = getattr(delta, "tako", None)   # the dedicated cards chunk
    if tako:
        cards = tako["cards"]

curl https://tako.com/api/openai/v1/chat/completions \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tako-answer-agent",
    "messages": [{"role": "user", "content": "Compare Nvidia and AMD revenue since 2015"}],
    "stream": true
  }'

For token-style usage accounting, pass stream_options={"include_usage": True} to emit a final usage frame before [DONE] (its values are zero — see below).

If a run fails mid-stream, the gateway emits an error chunk and closes the stream without a [DONE] marker. Treat a stream that ends without [DONE] as a failed run.

Responses API

OpenAI’s Responses API is the newer, event-based interface — POST /responses. Same models, auth, and tako extension; the differences are the request field (input instead of messages), the response shape (an output array), and — for the agents — stateful follow-ups, background runs, and a richer streaming event set. input accepts either a plain string or the OpenAI items array; Tako uses the last user turn as the query. instructions is accepted but not applied.

Answer

tako-answer is synchronous — one request, one grounded answer. The text is in output[].content[].text (the SDK aggregates it into response.output_text); cards and citations ride the top-level response.tako.

response = client.responses.create(
    model="tako-answer",
    input="What is the price of silver?",
)

print(response.output_text)             # the grounded answer
for card in response.tako["cards"]:      # the backing Tako cards
    print(card["title"], card["embed_url"])

curl https://tako.com/api/openai/v1/responses \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tako-answer",
    "input": "What is the price of silver?"
  }'

Example response

A standard response object. The text is in output[0].content[0].text; the backing cards and citations are in the top-level tako key.

{
  "id": "resp_8f0a9c2e7b1a2c3d",
  "object": "response",
  "created_at": 1750000000,
  "model": "tako-answer",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_8f0a9c2e7b1a2c3d",
      "role": "assistant",
      "status": "completed",
      "content": [
        {"type": "output_text", "text": "Silver is trading at about $34.80 per troy ounce ...", "annotations": []}
      ]
    }
  ],
  "usage": {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0},
  "tako": {
    "cards": [
      {
        "card_id": "KfYeym50vtsF93LMsIFW",
        "title": "Silver Price",
        "embed_url": "https://tako.com/embed/KfYeym50vtsF93LMsIFW/",
        "webpage_url": "https://tako.com/card/KfYeym50vtsF93LMsIFW/",
        "image_url": "https://tako.com/api/v1/image/KfYeym50vtsF93LMsIFW/"
      }
    ],
    "citations": [
      {
        "index": 1,
        "title": "Silver price today: rises on July 22",
        "url": "https://www.fxstreet.com/news/silver-price-today-silver-rises-according-to-fxstreet-data-202607220930",
        "source_name": "fxstreet.com",
        "source_index": "web",
        "excerpt": "Silver trades at $59.50 per troy ounce, up 1.19% from the $58.80 it cost on Tuesday.",
        "publish_date": "2026-07-22T09:30:30.000Z"
      }
    ],
    "request_id": "f20f965b-6bbd-40df-b50b-a8861f34df24"
  }
}

Agents

Both agents run deep research, which can take minutes. You have three ways to run each:

Stream it (stream=True) — recommended; see streaming events below.
Run it in the background (background=True) and poll GET /responses/{id}.
Call it synchronously — Tako drains the run inline and returns 504 (run_timeout, carrying the response id) past ~290 seconds.

Agent responses are stateful: pass a prior response’s id as previous_response_id to continue the thread. A follow-up stays on the product that started the thread — continuing a tako-retrieval-agent thread with tako-answer-agent (or the reverse) returns 409. Both previous_response_id and background are rejected with 400 for tako-answer.

# Background run, then poll.
response = client.responses.create(
    model="tako-answer-agent",
    input="Compare Nvidia and AMD revenue since 2015",
    background=True,
)
response = client.responses.retrieve(response.id)   # queued -> in_progress -> completed

# Stateful follow-up — same product as the thread.
followup = client.responses.create(
    model="tako-answer-agent",
    input="Now add Intel to that comparison",
    previous_response_id=response.id,
)

curl https://tako.com/api/openai/v1/responses \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tako-answer-agent",
    "input": "Compare Nvidia and AMD revenue since 2015",
    "background": true
  }'

Retrieving a response

GET /responses/{id} fetches a stored agent response — useful for polling a background run (answers are stateless and are not stored, so only agent ids are retrievable; access is owner-scoped). Add stream=true (or an SSE Accept header) to replay the run’s event stream from the start.

Python

response = client.responses.retrieve("resp_...")
print(response.status, response.output_text)

Streaming events

The Responses stream uses named SSE events and — unlike Chat Completions — has no [DONE] sentinel. Terminate on response.completed or response.failed. Answer text arrives in response.output_text.delta events; agent narration streams first as response.reasoning_summary_text.delta events. The Tako cards and citations arrive once, on the final response.completed event (in response.tako) — they are not streamed incrementally.

stream = client.responses.create(
    model="tako-answer-agent",
    input="Compare Nvidia and AMD revenue since 2015",
    stream=True,
)

cards = []
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        cards = event.response.tako["cards"]   # cards arrive once, at the end

curl https://tako.com/api/openai/v1/responses \
  -H "Authorization: Bearer $TAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tako-answer-agent",
    "input": "Compare Nvidia and AMD revenue since 2015",
    "stream": true
  }'

The event order is response.created → response.output_item.added → response.content_part.added → response.output_text.delta (repeated) → response.output_text.done → response.content_part.done → response.output_item.done → response.completed. A failed run emits a single response.failed event (carrying error) and no response.completed.

The `tako` extension

Tako’s value-add — the cards (interactive charts with their underlying data), the citations (the unified registry of web and data sources that back the answer), and the request_id — rides on a namespaced tako object, never inside the text:

Chat Completions: choices[0].message.tako (non-streaming), or a dedicated choices[0].delta.tako chunk (streaming).
Responses: the top-level response.tako (non-streaming), or the response.completed event’s response.tako (streaming).

The official OpenAI SDK preserves unknown response fields, so tako is available with no custom client. Each card carries title, description, embed_url, image_url, webpage_url, and sources — everything you need to embed the interactive chart or cite the data. See Knowledge Cards. Each citations entry carries index, title, source_index (data or web), and — for web sources — url, source_name, excerpt, and publish_date. The [n] markers in the answer text join this registry by index. A data-only answer may return an empty citations array (its data rides the card).

{
  "cards": [
    {"title": "Silver Price", "embed_url": "https://tako.com/embed/...", "webpage_url": "https://tako.com/card/...", "sources": []}
  ],
  "citations": [
    {
      "index": 1,
      "title": "Silver price today: rises on July 22",
      "url": "https://www.fxstreet.com/news/silver-price-today-silver-rises-according-to-fxstreet-data-202607220930",
      "source_name": "fxstreet.com",
      "source_index": "web",
      "excerpt": "Silver trades at $59.50 per troy ounce, up 1.19% from the $58.80 it cost on Tuesday.",
      "publish_date": "2026-07-22T09:30:30.000Z"
    }
  ],
  "request_id": "f20f965b-6bbd-40df-b50b-a8861f34df24"
}

Listing models

GET /models lists the available Tako models:

for model in client.models.list():
    print(model.id)   # tako-answer, tako-retrieval-agent, tako-answer-agent

curl https://tako.com/api/openai/v1/models \
  -H "Authorization: Bearer $TAKO_API_KEY"

Compatibility

The gateway maps OpenAI’s APIs onto Tako’s query pipeline, so a few OpenAI behaviors don’t carry over:

Chat Completions is single-shot and stateless. Only the last user message becomes the Tako query; system messages and prior turns are ignored. For stateful, multi-turn agent conversations, use the Responses API (previous_response_id, agents only) or the native Agent API.
source_indexes is respected — see Choosing sources. Other request knobs are accepted for SDK compatibility and ignored: temperature, top_p, tools, tool_choice, response_format, and (on Responses) instructions and store. n > 1 is rejected.
No structured output over this wire. response_format is ignored, and the Retrieval Agent’s output_schema is not available through the gateway. For machine-usable structured data, use the native Retrieval Agent API.
usage is always zero. Tako bills per request, not per token — see pricing.
The Responses stream has no [DONE] marker. Terminate on response.completed or response.failed.

Want Tako inside an existing OpenAI agent instead of as the model itself? See OpenAI Tool Calling to register Tako as a function the model can call across turns.

Getting Started

Build with Tako

API Reference

Integrations

Additional Resources

OpenAI-Compatible API

Overview

Choosing sources

Chat Completions

Answer

Agents

Retrieval Agent

Answer Agent

Streaming

Responses API

Answer

Agents

Retrieving a response

Streaming events

The `tako` extension

Listing models

Compatibility

​Overview

​Choosing sources

​Chat Completions

​Answer

​Agents

​Retrieval Agent

​Answer Agent

​Streaming

​Responses API

​Answer

​Agents

​Retrieving a response

​Streaming events

​The tako extension

​Listing models

​Compatibility

Overview

Choosing sources

Chat Completions

Answer

Agents

Retrieval Agent

Answer Agent

Streaming

Responses API

Answer

Agents

Retrieving a response

Streaming events

The `tako` extension

Listing models

Compatibility