Quickstart

Find a task for a job, then run it, with one token.

Get a token

Sign in to the dashboard, create or open an organization, then choose API keys → Create API key. Copy the tlp_ token while it is shown; it cannot be displayed again. Keep it in your server environment or secret store, outside committed source.

Shell

export TELIPOT_TOKEN='tlp_REPLACE_WITH_YOUR_TOKEN'

The requests below use the hosted gateway. For local development, replace https://api.telipot.com with http://localhost:3000 and use a token from that local dashboard.

Discover a task

POST /v1/discover takes a job in plain words and answers with candidates, best first.

Shell

curl https://api.telipot.com/v1/discover \
  -H "Authorization: Bearer $TELIPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task": "Hacker News stories about agent tools", "limit": 3}'

When nothing qualifies, candidates is empty and near_misses lists the closest tasks, with the words each matched and missed.

Run it

POST /v1/tasks/{id}/run runs a task. The body is the task's input.

This Hacker News task uses public data and costs $0 from telipot. Inspect any other task's price and input at GET /v1/tasks/{id} before running it.

Shell

curl https://api.telipot.com/v1/tasks/hackernews.news.search/run \
  -H "Authorization: Bearer $TELIPOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "agent tools", "hitsPerPage": 5}'

output is the vendor's answer, unchanged.
receipt is what telipot adds: call_id, identity and the principal it acted as, quoted_usd and charged_usd, and latency_ms.

Expect Hacker News hits under output and anonymous under receipt.identity. An empty hit list is still a successful response. Find receipt.call_id under Audit log on the dashboard.

Act as someone

To run in an end user's own account, add "receipt": {"principal": "user:ana"} beside the input, or send Telipot-Principal: user:ana. Missing consent returns grant_required. Follow its connect_url when present; otherwise create a connect session with an allowlisted callback.

Continue with the end-user connection guide, TypeScript SDK or CLI.