TengoChatDevelopers

API reference

Everything the TengoChat API does: chat completions in the OpenAI format, agents with tools and connectors, threads, files and usage. Download the OpenAPI file to generate a client.

Base URL

Base URL
https://tengochat.com/api/v1

Every request goes over HTTPS. Bodies are JSON (except file uploads, which are multipart/form-data), and so are answers.

Authentication

Make a key in Create, Developers and send it as a bearer token. Keys start with tc_live_. Keep them on your server: anyone with a key spends your credits. You can also send it as X-API-Key.

Header
Authorization: Bearer tc_live_...

Errors

Errors answer with an HTTP status and a body that says what happened:

JSON
{
    "error": {
        "type": "insufficient_credits",
        "message": "You are out of credits.",
        "param": null,
        "code": "insufficient_credits"
    }
}
400invalid_requestSomething in the request is missing or wrong; param names it.
401authenticationNo key, or a key that does not work.
402insufficient_creditsOut of credits: add credits, then try again.
404not_foundNo such model, agent, thread or file on your account.
413file_too_large / storage_fullThe file is larger than your plan takes, or storage is full.
429rate_limited / spend_limitToo many requests (wait and retry), or a key's monthly limit.
502 / 503serverThe model did not answer, or the API is paused. Retry with backoff.

Limits

Each key may make 60 requests a minute; answers carry X-RateLimit-Limit and X-RateLimit-Remaining, and a 429 carries Retry-After. A key can have a monthly spending limit, set in the console. Answers can be up to 16,000 tokens; messages up to 600,000 characters.

Libraries

Chat completions follow the OpenAI format, so the OpenAI libraries work as they are: set the base URL and your key.

from openai import OpenAI

client = OpenAI(base_url="https://tengochat.com/api/v1", api_key=os.environ["TENGOCHAT_API_KEY"])
reply = client.chat.completions.create(
    model="tengo-1",
    messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)

List models

GET/api/v1/models

The models you can call, with their price in credits per million tokens.

curl https://tengochat.com/api/v1/models \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY"
Response
{
    "object": "list",
    "data": [
        {
            "id": "tengo-1",
            "object": "model",
            "name": "Tengo 1",
            "context_window": 128000,
            "pricing": {
                "unit": "credits per million tokens",
                "input": 1000,
                "output": 4000
            }
        }
    ]
}

Create a chat completion

POST/api/v1/chat/completions

OpenAI-compatible. Send messages, get the answer, or stream it with "stream": true.

modelstringThe model id, like tengo-1. Default: tengo-1.
messagesrequiredarrayThe conversation: objects with role (system, user, assistant) and content.
max_tokensintegerThe longest answer, in tokens (1 to 16,000). Default 2,048.
temperaturenumber0 to 2. Lower is steadier, higher is more varied.
streambooleanSend the answer piece by piece as server-sent events.
stream_options.include_usagebooleanWith stream: a last event with the tokens and credits used.
response_formatobject{"type": "json_object"} for an answer in JSON.
curl https://tengochat.com/api/v1/chat/completions \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tengo-1","messages":[{"role":"system","content":"You are a concise assistant."},{"role":"user","content":"Write a haiku about shipping on Friday."}]}'
Response
{
    "id": "chatcmpl-9f2c",
    "object": "chat.completion",
    "model": "tengo-1",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Merge at five p.m.\nThe pager hums all weekend.\nMonday has questions."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 31,
        "completion_tokens": 17,
        "total_tokens": 48,
        "credits": 1
    }
}

List agents

GET/api/v1/agents

The agents on your account.

curl https://tengochat.com/api/v1/agents \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY"
Response
{
    "object": "list",
    "data": [
        {
            "id": "ag_3f1a9c2b7d6e5f40",
            "object": "agent",
            "name": "Support helper",
            "model": "tengo-1",
            "tools": [
                "files"
            ],
            "memory": true
        }
    ]
}

Get an agent

GET/api/v1/agents/{agent_id}

One agent, with its tools and connectors.

agent_idrequiredpathThe agent id, like ag_3f1a9c2b7d6e5f40.
curl https://tengochat.com/api/v1/agents/ag_3f1a9c2b7d6e5f40 \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY"
Response
{
    "id": "ag_3f1a9c2b7d6e5f40",
    "object": "agent",
    "name": "Support helper",
    "model": "tengo-1",
    "tools": [
        "files"
    ],
    "connectors": [],
    "memory": true,
    "public": false
}

Message an agent

POST/api/v1/agents/{agent_id}/messages

The agent reads the thread, uses its tools and connectors, and answers. Leave thread_id out to start a new thread; send it back to continue.

agent_idrequiredpathThe agent id.
messagerequiredstringWhat to say to the agent.
thread_idstringContinue this thread (from an earlier answer).
userstringYour own id for the person talking, to keep their threads apart.
streambooleanEvents as they happen: delta (text), tool (a tool starts), done (the full answer).
curl https://tengochat.com/api/v1/agents/ag_3f1a9c2b7d6e5f40/messages \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Which pull requests need a review?","user":"customer-4821"}'
Response
{
    "id": "msg_a81c",
    "object": "agent.message",
    "agent_id": "ag_3f1a9c2b7d6e5f40",
    "thread_id": "th_5d0c2e7a",
    "content": "Two pull requests are waiting: #42 (login fix) and #45 (new pricing page).",
    "tools_used": [
        "github_list_pulls"
    ],
    "usage": {
        "input_tokens": 812,
        "output_tokens": 64,
        "credits": 3
    }
}

Get a thread

GET/api/v1/threads/{thread_id}

Everything said in a thread.

thread_idrequiredpathThe thread id.
curl https://tengochat.com/api/v1/threads/th_5d0c2e7a1b9f3c8d4e6a \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY"
Response
{
    "id": "th_5d0c2e7a",
    "object": "thread",
    "agent_id": "ag_3f1a9c2b7d6e5f40",
    "messages": [
        {
            "role": "user",
            "content": "Hi"
        },
        {
            "role": "assistant",
            "content": "Hello! How can I help?"
        }
    ]
}

Delete a thread

DELETE/api/v1/threads/{thread_id}

Forget a thread and its messages for good.

thread_idrequiredpathThe thread id.
curl -X DELETE https://tengochat.com/api/v1/threads/th_5d0c2e7a1b9f3c8d4e6a \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY"
Response
{
    "id": "th_5d0c2e7a",
    "object": "thread",
    "deleted": true
}

List files

GET/api/v1/files

Your stored files, newest first, and how much room is used.

qqueryOnly names containing this.
limitqueryUp to 1,000. Default 100.
curl https://tengochat.com/api/v1/files \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY"
Response
{
    "object": "list",
    "data": [
        {
            "id": "file_6a1f0e9b2c3d4e5f6a7b",
            "object": "file",
            "name": "handbook.md",
            "bytes": 18342,
            "visibility": "private"
        }
    ],
    "storage": {
        "plan": "free",
        "used_bytes": 18342,
        "quota_bytes": 268435456
    }
}

Upload a file

POST/api/v1/files

multipart/form-data with the file in "file". Public files get a permanent tengochat.com address; private ones a link that lasts an hour.

filerequiredfileThe file.
visibilitystringprivate (default) or public.
namestringA name for it (default: the file's own).
curl https://tengochat.com/api/v1/files \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY" \
  -F [email protected] \
  -F visibility=public
Response
{
    "id": "file_6a1f0e9b2c3d4e5f6a7b",
    "object": "file",
    "name": "logo.png",
    "bytes": 48211,
    "mime": "image/png",
    "visibility": "public",
    "url": "https://tengochat.com/f/file_6a1f0e9b2c3d4e5f6a7b/logo.png"
}

Get a file

GET/api/v1/files/{file_id}

A file and its address.

file_idrequiredpathThe file id.
curl https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY"
Response
{
    "id": "file_6a1f0e9b2c3d4e5f6a7b",
    "object": "file",
    "url": "https://tengochat.com/f/file_6a1f0e9b2c3d4e5f6a7b/logo.png?e=1763341200&s=..."
}

Change a file

POST/api/v1/files/{file_id}

Make it public or private.

file_idrequiredpathThe file id.
visibilityrequiredstringpublic or private.
curl https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"visibility":"public"}'
Response
{
    "id": "file_6a1f0e9b2c3d4e5f6a7b",
    "object": "file",
    "visibility": "public"
}

Download a file

GET/api/v1/files/{file_id}/content

Redirects to the file itself.

file_idrequiredpathThe file id.
curl https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b/content \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY"

Delete a file

DELETE/api/v1/files/{file_id}

Gone for good, and its room is free again.

file_idrequiredpathThe file id.
curl -X DELETE https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY"
Response
{
    "id": "file_6a1f0e9b2c3d4e5f6a7b",
    "object": "file",
    "deleted": true
}

Credits and usage

GET/api/v1/usage

Credits left, spent this month, the last 30 days day by day, and storage.

curl https://tengochat.com/api/v1/usage \
  -H "Authorization: Bearer $TENGOCHAT_API_KEY"
Response
{
    "object": "usage",
    "credits": 18450,
    "credits_usd": 18.45,
    "this_month": {
        "credits": 3120
    },
    "last_30_days": {
        "calls": 1204,
        "credits": 4580
    }
}