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
https://tengochat.com/api/v1Every 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.
Authorization: Bearer tc_live_...Errors
Errors answer with an HTTP status and a body that says what happened:
{
"error": {
"type": "insufficient_credits",
"message": "You are out of credits.",
"param": null,
"code": "insufficient_credits"
}
}400 | invalid_request | Something in the request is missing or wrong; param names it. |
401 | authentication | No key, or a key that does not work. |
402 | insufficient_credits | Out of credits: add credits, then try again. |
404 | not_found | No such model, agent, thread or file on your account. |
413 | file_too_large / storage_full | The file is larger than your plan takes, or storage is full. |
429 | rate_limited / spend_limit | Too many requests (wait and retry), or a key's monthly limit. |
502 / 503 | server | The 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)import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://tengochat.com/api/v1", apiKey: process.env.TENGOCHAT_API_KEY });
const reply = await client.chat.completions.create({
model: "tengo-1",
messages: [{ role: "user", content: "Hello" }],
});
console.log(reply.choices[0].message.content);List models
/api/v1/modelsThe 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"const res = await fetch("https://tengochat.com/api/v1/models", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://tengochat.com/api/v1/models",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
)
print(res.json()){
"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
/api/v1/chat/completionsOpenAI-compatible. Send messages, get the answer, or stream it with "stream": true.
modelstring | The model id, like tengo-1. Default: tengo-1. |
messagesrequiredarray | The conversation: objects with role (system, user, assistant) and content. |
max_tokensinteger | The longest answer, in tokens (1 to 16,000). Default 2,048. |
temperaturenumber | 0 to 2. Lower is steadier, higher is more varied. |
streamboolean | Send the answer piece by piece as server-sent events. |
stream_options.include_usageboolean | With 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."}]}'const res = await fetch("https://tengochat.com/api/v1/chat/completions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "tengo-1",
"messages": [
{
"role": "system",
"content": "You are a concise assistant."
},
{
"role": "user",
"content": "Write a haiku about shipping on Friday."
}
]
}),
});
const data = await res.json();import os, requests
res = requests.post(
"https://tengochat.com/api/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
json={
"model": "tengo-1",
"messages": [
{
"role": "system",
"content": "You are a concise assistant."
},
{
"role": "user",
"content": "Write a haiku about shipping on Friday."
}
]
},
)
print(res.json()){
"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
/api/v1/agentsThe agents on your account.
curl https://tengochat.com/api/v1/agents \
-H "Authorization: Bearer $TENGOCHAT_API_KEY"const res = await fetch("https://tengochat.com/api/v1/agents", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://tengochat.com/api/v1/agents",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
)
print(res.json()){
"object": "list",
"data": [
{
"id": "ag_3f1a9c2b7d6e5f40",
"object": "agent",
"name": "Support helper",
"model": "tengo-1",
"tools": [
"files"
],
"memory": true
}
]
}Get an agent
/api/v1/agents/{agent_id}One agent, with its tools and connectors.
agent_idrequiredpath | The agent id, like ag_3f1a9c2b7d6e5f40. |
curl https://tengochat.com/api/v1/agents/ag_3f1a9c2b7d6e5f40 \
-H "Authorization: Bearer $TENGOCHAT_API_KEY"const res = await fetch("https://tengochat.com/api/v1/agents/ag_3f1a9c2b7d6e5f40", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://tengochat.com/api/v1/agents/ag_3f1a9c2b7d6e5f40",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
)
print(res.json()){
"id": "ag_3f1a9c2b7d6e5f40",
"object": "agent",
"name": "Support helper",
"model": "tengo-1",
"tools": [
"files"
],
"connectors": [],
"memory": true,
"public": false
}Message an agent
/api/v1/agents/{agent_id}/messagesThe 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_idrequiredpath | The agent id. |
messagerequiredstring | What to say to the agent. |
thread_idstring | Continue this thread (from an earlier answer). |
userstring | Your own id for the person talking, to keep their threads apart. |
streamboolean | Events 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"}'const res = await fetch("https://tengochat.com/api/v1/agents/ag_3f1a9c2b7d6e5f40/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"message": "Which pull requests need a review?",
"user": "customer-4821"
}),
});
const data = await res.json();import os, requests
res = requests.post(
"https://tengochat.com/api/v1/agents/ag_3f1a9c2b7d6e5f40/messages",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
json={
"message": "Which pull requests need a review?",
"user": "customer-4821"
},
)
print(res.json()){
"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
/api/v1/threads/{thread_id}Everything said in a thread.
thread_idrequiredpath | The thread id. |
curl https://tengochat.com/api/v1/threads/th_5d0c2e7a1b9f3c8d4e6a \
-H "Authorization: Bearer $TENGOCHAT_API_KEY"const res = await fetch("https://tengochat.com/api/v1/threads/th_5d0c2e7a1b9f3c8d4e6a", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://tengochat.com/api/v1/threads/th_5d0c2e7a1b9f3c8d4e6a",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
)
print(res.json()){
"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
/api/v1/threads/{thread_id}Forget a thread and its messages for good.
thread_idrequiredpath | The thread id. |
curl -X DELETE https://tengochat.com/api/v1/threads/th_5d0c2e7a1b9f3c8d4e6a \
-H "Authorization: Bearer $TENGOCHAT_API_KEY"const res = await fetch("https://tengochat.com/api/v1/threads/th_5d0c2e7a1b9f3c8d4e6a", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.delete(
"https://tengochat.com/api/v1/threads/th_5d0c2e7a1b9f3c8d4e6a",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
)
print(res.json()){
"id": "th_5d0c2e7a",
"object": "thread",
"deleted": true
}List files
/api/v1/filesYour stored files, newest first, and how much room is used.
qquery | Only names containing this. |
limitquery | Up to 1,000. Default 100. |
curl https://tengochat.com/api/v1/files \
-H "Authorization: Bearer $TENGOCHAT_API_KEY"const res = await fetch("https://tengochat.com/api/v1/files", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://tengochat.com/api/v1/files",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
)
print(res.json()){
"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
/api/v1/filesmultipart/form-data with the file in "file". Public files get a permanent tengochat.com address; private ones a link that lasts an hour.
filerequiredfile | The file. |
visibilitystring | private (default) or public. |
namestring | A 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=publicconst form = new FormData();
form.append("file", fileInput.files[0]);
form.append("visibility", "public");
const res = await fetch("https://tengochat.com/api/v1/files", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}` },
body: form,
});
const file = await res.json();import os, requests
res = requests.post(
"https://tengochat.com/api/v1/files",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
files={"file": open("logo.png", "rb")},
data={"visibility": "public"},
)
print(res.json()["url"]){
"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
/api/v1/files/{file_id}A file and its address.
file_idrequiredpath | The file id. |
curl https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b \
-H "Authorization: Bearer $TENGOCHAT_API_KEY"const res = await fetch("https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
)
print(res.json()){
"id": "file_6a1f0e9b2c3d4e5f6a7b",
"object": "file",
"url": "https://tengochat.com/f/file_6a1f0e9b2c3d4e5f6a7b/logo.png?e=1763341200&s=..."
}Change a file
/api/v1/files/{file_id}Make it public or private.
file_idrequiredpath | The file id. |
visibilityrequiredstring | public 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"}'const res = await fetch("https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"visibility": "public"
}),
});
const data = await res.json();import os, requests
res = requests.post(
"https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
json={
"visibility": "public"
},
)
print(res.json()){
"id": "file_6a1f0e9b2c3d4e5f6a7b",
"object": "file",
"visibility": "public"
}Download a file
/api/v1/files/{file_id}/contentRedirects to the file itself.
file_idrequiredpath | The file id. |
curl https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b/content \
-H "Authorization: Bearer $TENGOCHAT_API_KEY"const res = await fetch("https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b/content", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b/content",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
)
print(res.json())Delete a file
/api/v1/files/{file_id}Gone for good, and its room is free again.
file_idrequiredpath | The file id. |
curl -X DELETE https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b \
-H "Authorization: Bearer $TENGOCHAT_API_KEY"const res = await fetch("https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b", {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.delete(
"https://tengochat.com/api/v1/files/file_6a1f0e9b2c3d4e5f6a7b",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
)
print(res.json()){
"id": "file_6a1f0e9b2c3d4e5f6a7b",
"object": "file",
"deleted": true
}Credits and usage
/api/v1/usageCredits 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"const res = await fetch("https://tengochat.com/api/v1/usage", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.TENGOCHAT_API_KEY}`,
},
});
const data = await res.json();import os, requests
res = requests.get(
"https://tengochat.com/api/v1/usage",
headers={"Authorization": f"Bearer {os.environ['TENGOCHAT_API_KEY']}"},
)
print(res.json()){
"object": "usage",
"credits": 18450,
"credits_usd": 18.45,
"this_month": {
"credits": 3120
},
"last_30_days": {
"calls": 1204,
"credits": 4580
}
}