Skip to main content

​
Overview

Tako supports the Machine Payments Protocol (MPP) — an open standard for machine-to-machine payments via HTTP 402. This allows AI agents to discover and pay for Tako API access automatically, without requiring API keys or account signup.

​
How It Works

  1. Discovery — Agents find Tako’s available endpoints at https://tako.com/.well-known/mpp.json
  2. 402 Challenge — When an agent calls an MPP endpoint without payment, Tako returns 402 Payment Required with pricing info
  3. Payment — The agent pays via Stripe or Tempo stablecoins
  4. Access — The agent retries with a payment credential and gets the response
Agent frameworks like mppx handle this flow automatically — from the agent’s perspective, it’s a single API call.

​
Available Endpoints

​
Sync endpoints

EndpointMethodDescription
/api/mpp/v1/search/fastPOSTFast data search
/api/mpp/v1/visualizePOSTVisualize data from a search query
/api/mpp/v1/thinviz/createPOSTCreate a ThinViz card from components
/api/mpp/v1/charts/editPOSTEdit a chart using a natural language prompt

​
Async endpoints

These endpoints return 202 Accepted with a task ID. Poll the corresponding status endpoint using the receipt token from the Payment-Receipt header.
EndpointMethodDescriptionPoll endpointExpected duration
/api/mpp/v1/threads/deepPOSTDeep knowledge search with full pipeline/api/mpp/v1/threads/status30s – 10 min
/api/mpp/v1/reports/generatePOSTGenerate a research report/api/mpp/v1/reports/status10 – 30 min

​
Poll endpoints (free)

EndpointMethodDescription
/api/mpp/v1/threads/statusGETPoll status for deep search tasks
/api/mpp/v1/reports/statusGETPoll status for report generation
Poll endpoints are free — authenticate with Authorization: MPP receipt <token> using the receipt from the original paid request. Live pricing is available at https://tako.com/.well-known/mpp.json.

​
Payment Methods

  • Stripe — Pay via Stripe PaymentIntent. Agents need a pre-configured Stripe customer with a payment method.
  • Tempo — Pay via Tempo stablecoin on-chain transaction.

​
Authentication Flow

# 1. Agent calls endpoint with no auth
POST /api/mpp/v1/search/fast

# 2. Tako returns 402 with challenge headers
HTTP/1.1 402 Payment Required
WWW-Authenticate: MPP realm="tako"
MPP-Price: 0.036667 USD
MPP-Payment-Methods: stripe, tempo

# 3. Agent pays and retries with credential
POST /api/mpp/v1/search/fast
Authorization: MPP stripe pi_xxxxx

# 4. Tako verifies payment and returns response
HTTP/1.1 200 OK
Payment-Receipt: <receipt-token>

​
Async endpoints (deep search, reports)

Async endpoints return 202 Accepted immediately. Use the receipt token to poll for results. 
# 1. Submit a deep search (paid)
POST /api/mpp/v1/threads/deep
Authorization: MPP stripe pi_xxxxx
Content-Type: application/json

{
  "knowledge_search_request": {
    "inputs": {"text": "How has NVIDIA's revenue grown vs AMD?"}
  },
  "skip_routing": true
}

# 2. Receive 202 with task ID and receipt
HTTP/1.1 202 Accepted
Payment-Receipt: <receipt-token>

{"task_id": "abc-123", "thread_id": "thread-456", "status": "pending"}

# 3. Poll for results (free, receipt-authenticated)
GET /api/mpp/v1/threads/status?task_id=abc-123
Authorization: MPP receipt <receipt-token>

# 4. Completed response includes full results with charts
HTTP/1.1 200 OK
{"status": "completed", "result": {...}}
Poll every 5–10 seconds for deep search, every 30–60 seconds for reports. Status values: pending, in_progress, completed, failed. Use the since_index query param for incremental event polling.

​
Request format

MPP endpoints accept the same request body as their non-MPP counterparts. For example, /api/mpp/v1/search/fast accepts the same body as /v1/knowledge_search: 
{
  "query": "Tesla stock price",
  "search_effort": "fast",
  "source_indexes": ["data"]
}

​
Report generation

Reports use a combined create + dispatch flow: 
POST /api/mpp/v1/reports/generate

{
  "report_type": "memo",
  "title": "NVIDIA Competitive Analysis",
  "config": {"query": "NVIDIA competitive landscape and market position"}
}
Poll with GET /api/mpp/v1/reports/status?report_id=<report_id>.

​
Discovery Manifest

Agents can discover all MPP-enabled endpoints at: 
GET https://tako.com/.well-known/mpp.json
Response: 
{
  "version": "1.0",
  "provider": "tako",
  "description": "Tako data visualization and research platform",
  "endpoints": [
    {
      "path": "/api/mpp/v1/search/fast",
      "method": "POST",
      "price": {"amount": "0.036667", "currency": "USD"},
      "response_type": "sync",
      "description": "Fast data search"
    },
    {
      "path": "/api/mpp/v1/threads/deep",
      "method": "POST",
      "price": {"amount": "0.550000", "currency": "USD"},
      "response_type": "async",
      "poll_path": "/api/mpp/v1/threads/status",
      "description": "Deep async knowledge search with full pipeline"
    }
  ],
  "payment_methods": ["stripe", "tempo"]
}

​
Idempotency

To handle network failures, include an Idempotency-Key header. If the payment was processed but the response was lost, retrying with the same key returns the cached response instead of charging again. 
POST /api/mpp/v1/search/fast
Authorization: MPP stripe pi_xxxxx
Idempotency-Key: my-unique-request-id

​
Error Codes

StatusMeaning
402Payment required — includes MPP challenge headers
400Malformed credential or unsupported payment method
409Payment credential already used (replay)
401Invalid receipt token (poll endpoints)
429Rate limit exceeded — back off and retry