# Tako — Orthogonal API

> Pay-per-use API on Orthogonal. Each call is billed to your Orthogonal balance.
> Base API: `https://api.orth.sh/v1/run` · [llms.txt](https://orthogonal.com/llms.txt) · [browse all APIs](https://orthogonal.com/discover)

Tako is a knowledge search engine that visualizes the world's data. Search with natural language to get interactive knowledge cards with charts, tables, and insights powered by sources like S&P Global, World Bank, and more.

**Verified:** yes

## Access

**Run API:** `POST https://api.orth.sh/v1/run`
**Auth:** `Authorization: Bearer $ORTHOGONAL_API_KEY`
Get an API key at https://orthogonal.com/dashboard/settings/api-keys

Every call goes through the unified Run API: send the API `slug`, the endpoint `path`, and the `query`/`body` parameters. The response is `{ "success": true, "price": "<usd>", "data": { ... } }`.

## Endpoints

### Visualize Datasets

Turn your own data into interactive Tako Knowledge Card visualizations. Provide data as CSV strings and a natural language query describing what to visualize. Tako auto-selects the best chart type or you can specify one. Returns a knowledge card with chart image, interactive webpage, and embed URLs. Example: {"csv": ["quarter,revenue\nQ1,100\nQ2,200\nQ3,300"], "query": "Show revenue growth as a bar chart"}

`POST /v1/beta/visualize`

**Estimated cost:** $0.023

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `csv` | array | Yes | Array of CSV strings. Each string is a full CSV with headers in the first row. Example: ["name,value\nApple,3.7\nNVIDIA,3.4\nMicrosoft,3.1"]. Multiple CSVs can be passed for multi-dataset visualizations. |
| `query` | string | No | Natural language instructions for how to visualize the data (e.g. "Show as a bar chart", "Compare revenue trends", "Make a pie chart of market share"). |
| `viz_component_type` | string | No | Explicitly request a chart type. Options: bar, grouped_bar, stacked_bar, timeseries, area_timeseries, stacked_area_timeseries, pie, choropleth, map, scatter, boxplot, heatmap, timeline, waterfall, histogram, table, treemap. |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"tako","path":"/v1/beta/visualize","body":{"csv":"<array>","query":"<string>","viz_component_type":"<string>"}}'
```

### Create Card (Thin-Viz)

Create a custom embeddable knowledge card from your own data by specifying chart components directly. Returns card_id, image_url, webpage_url, and embed_url. Use List Default Schemas first to see available chart types and their required fields. Example body for a bar chart: {"components": [{"component_type": "header", "config": {"title": "Sales by Region"}}, {"component_type": "categorical_bar", "config": {"datasets": [{"label": "Revenue", "data": [{"x": "US", "y": 500}, {"x": "EU", "y": 300}]}]}}], "title": "Sales by Region", "source": "Internal Data"}

`POST /v1/thin_viz/create/`

**Estimated cost:** $0.023

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `components` | array | Yes | Array of component config objects. Each needs "component_type" (string: header, generic_timeseries, categorical_bar, pie, scatter, table, choropleth, heatmap, histogram, boxplot, treemap, waterfall, bubble, financial_boxes, data_table_chart) and "config" (object with type-specific fields). Use List Default Schemas endpoint to see required fields per type. |
| `title` | string | No | Card title displayed at the top. |
| `description` | string | No | Card description text. |
| `source` | string | No | Data source attribution shown in the card footer (e.g. "S&P Global", "Internal Data"). |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"tako","path":"/v1/thin_viz/create/","body":{"components":"<array>","title":"<string>","description":"<string>","source":"<string>"}}'
```

### Tool Descriptions

Get descriptions of Tako search tool capabilities and available data topics. Returns what types of data Tako can search across (finance, economics, demographics, sports, politics, climate, health) with example metrics for each category. Useful for understanding what queries Tako can answer before searching.

`GET /v1/tako_tools_description`

**Estimated cost:** $0.023

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `index_ids` | string | No | Comma-separated index IDs to get descriptions for specific indexes. Omit to get all available tool descriptions. |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"tako","path":"/v1/tako_tools_description","method":"GET","query":{"index_ids":"<string>"}}'
```

### Chart Insights

Analyze a Tako Knowledge Card and get AI-generated insights. Returns plain-text observations about trends, growth rates, comparisons, and anomalies in the data. Use this after Knowledge Search to extract key takeaways from a chart. Requires a card_id from a previous Knowledge Search or Create Card response.

`GET /v1/beta/chart_insights`

**Estimated cost:** $0.023

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `card_id` | string | Yes | The knowledge card ID to analyze (e.g. "UgwkpOEucRs955WG54B-"). Get this from the card_id field in Knowledge Search or Create Card responses. |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"tako","path":"/v1/beta/chart_insights","method":"GET","query":{"card_id":"<string>"}}'
```

### List Default Schemas

List all available chart/visualization templates that can be used with the Create Card endpoint. Returns schema names (e.g. stock_card, bar_chart, pie_chart, choropleth, treemap, heatmap, table, etc.) with descriptions and their component types. Call this first to understand what chart types are available before creating a card.

`GET /v1/thin_viz/default_schema/`

**Estimated cost:** $0.023

_No parameters required._

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"tako","path":"/v1/thin_viz/default_schema/","method":"GET"}'
```

### Knowledge Search

Search for data visualizations using natural language. Ask any question about finance, economics, demographics, sports, politics, climate, or health and get back interactive knowledge cards with charts, data, and source attribution. Example: {"inputs": {"text": "NVIDIA vs AMD revenue since 2018"}}. Returns cards with title, chart image URL, interactive webpage URL, embeddable URL, data description, and source information.

`POST /v1/knowledge_search`

**Estimated cost:** $0.023

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `inputs` | object | Yes | Object with "text" (string, required): your natural language query (e.g. "US GDP growth 2020-2024", "Tesla vs Ford market cap"). Optional "search_effort" (string): "fast" for quick results, "medium" for balanced, "deep" for thorough research, "auto" to let Tako decide. |
| `source_indexes` | array | No | Array of source index strings to search, in priority order. Options: "tako" (curated financial/economic data from S&P Global, World Bank, etc.), "web" (web sources), "tako_deep_v2" (deeper research). Default: ["tako"]. |
| `country_code` | string | No | ISO 3166-1 alpha-2 country code to localize results (e.g. "US", "GB", "DE"). Default: "US". |
| `locale` | string | No | Locale string (e.g. "en-US", "de-DE"). Default: "en-US". |
| `output_settings` | object | No | Optional. Set {"knowledge_card_settings": {"image_dark_mode": true}} to get dark-mode chart images. |

```bash
curl -X POST 'https://api.orth.sh/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"tako","path":"/v1/knowledge_search","body":{"inputs":"<object>","source_indexes":"<array>","country_code":"<string>","locale":"<string>","output_settings":"<object>"}}'
```

---

Full details and an interactive quickstart: https://orthogonal.com/discover/tako