Chat
Tool Calling
Connect Chat Completions to your application functions.
POST /v1/chat/completions
Declare functions in tools. Your application executes requested calls and returns results so the model can continue.
Tool Definition
json
{
"tools": [
{
"type": "function",
"function": {
"name": "lookup_stock",
"description": "Look up inventory for a product SKU.",
"parameters": {
"type": "object",
"properties": {
"sku": {
"type": "string"
}
},
"required": [
"sku"
],
"additionalProperties": false
}
}
}
]
}Chat nests the definition inside function. Read choices[0].message.tool_calls, parse function.arguments as JSON, preserve the assistant message, then append a role: "tool" message for each call using its id as tool_call_id.
First Request in Each Language
These requests obtain a tool-call request; they do not execute the tool. Use the complete workflow below to return results with the actual call IDs and continue the conversation.
See language setup. Set API_KEY and replace model, file URL, and ID placeholders first. Each version displays the raw response to the same request.
bash
curl --fail-with-body --silent --show-error --max-time 180 \
--request POST \
--url "https://api.tokatlas.ai/v1/chat/completions" \
--header "Authorization: Bearer $API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "gpt-4o",
"tools": [
{
"type": "function",
"function": {
"name": "lookup_stock",
"description": "Look up inventory for a product SKU.",
"parameters": {
"type": "object",
"properties": {
"sku": {
"type": "string"
}
},
"required": [
"sku"
],
"additionalProperties": false
}
}
}
],
"stream": false,
"messages": [
{
"role": "user",
"content": "Check stock for DEMO-001."
}
]
}'python
import os
import requests
headers = {
'Authorization': 'Bearer ' + os.environ["API_KEY"],
'Content-Type': 'application/json',
}
payload = {'model': 'gpt-4o',
'tools': [{'type': 'function',
'function': {'name': 'lookup_stock',
'description': 'Look up inventory for a product SKU.',
'parameters': {'type': 'object',
'properties': {'sku': {'type': 'string'}},
'required': ['sku'],
'additionalProperties': False}}}],
'stream': False,
'messages': [{'role': 'user', 'content': 'Check stock for DEMO-001.'}]}
response = requests.request(
'POST', 'https://api.tokatlas.ai/v1/chat/completions', headers=headers,
json=payload,
timeout=180,
)
response.raise_for_status()
print(response.text)js
if (!process.env.API_KEY) throw new Error("Set API_KEY first.");
const response = await fetch("https://api.tokatlas.ai/v1/chat/completions", {
method: "POST",
headers: {
"Authorization": "Bearer " + process.env.API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "gpt-4o",
"tools": [
{
"type": "function",
"function": {
"name": "lookup_stock",
"description": "Look up inventory for a product SKU.",
"parameters": {
"type": "object",
"properties": {
"sku": {
"type": "string"
}
},
"required": [
"sku"
],
"additionalProperties": false
}
}
}
],
"stream": false,
"messages": [
{
"role": "user",
"content": "Check stock for DEMO-001."
}
]
}),
signal: AbortSignal.timeout(180_000),
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.text());java
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
public class Example {
public static void main(String[] args) throws Exception {
String apiKey = System.getenv("API_KEY");
if (apiKey == null || apiKey.isBlank()) {
throw new IllegalArgumentException("Set API_KEY first.");
}
String payload = String.join("\n",
"{",
" \"model\": \"gpt-4o\",",
" \"tools\": [",
" {",
" \"type\": \"function\",",
" \"function\": {",
" \"name\": \"lookup_stock\",",
" \"description\": \"Look up inventory for a product SKU.\",",
" \"parameters\": {",
" \"type\": \"object\",",
" \"properties\": {",
" \"sku\": {",
" \"type\": \"string\"",
" }",
" },",
" \"required\": [",
" \"sku\"",
" ],",
" \"additionalProperties\": false",
" }",
" }",
" }",
" ],",
" \"stream\": false,",
" \"messages\": [",
" {",
" \"role\": \"user\",",
" \"content\": \"Check stock for DEMO-001.\"",
" }",
" ]",
"}"
);
HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(30)).build();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.tokatlas.ai/v1/chat/completions"))
.timeout(Duration.ofSeconds(180))
.header("Authorization", "Bearer " + apiKey)
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = client.send(
request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() < 200 || response.statusCode() >= 300) {
throw new IllegalStateException("HTTP " + response.statusCode() + ": "
+ response.body());
}
System.out.println(response.body());
}
}Complete Python Example
Install requests, set API_KEY, and choose an enabled model. Inventory values are demo fixtures; replace execute with your business service.
python
import json
import os
import requests
URL = "https://api.tokatlas.ai/v1/chat/completions"
HEADERS = {'Authorization': "Bearer " + os.environ["API_KEY"], 'Content-Type': 'application/json'}
TOOLS = [{'type': 'function',
'function': {'name': 'lookup_stock',
'description': 'Look up inventory for a product SKU.',
'parameters': {'type': 'object',
'properties': {'sku': {'type': 'string'}},
'required': ['sku'],
'additionalProperties': False}}}]
def post(payload):
response = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
response.raise_for_status()
body = response.json()
# Accept the documented gateway envelope or a direct protocol response.
data = body.get("data", body)
if not isinstance(data, dict):
raise RuntimeError("Unexpected API response")
if data.get("error"):
raise RuntimeError(data["error"])
return data
def execute(name, args):
if name != "lookup_stock":
return {"error": "Unknown tool"}
if not isinstance(args, dict) or set(args) != {"sku"}:
return {"error": "Expected exactly one sku argument"}
if not isinstance(args["sku"], str) or not args["sku"].strip():
return {"error": "sku must be a non-empty string"}
# Demo fixture only; replace with your inventory service.
stock = {"DEMO-001": 18}
if args["sku"] not in stock:
return {"error": "SKU not found"}
return {"sku": args["sku"], "available": stock[args["sku"]]}
messages = [{"role": "user", "content": "Check stock for DEMO-001."}]
for _ in range(6):
reply = post({"model": "gpt-4o", "stream": False,
"tools": TOOLS, "messages": messages})
choice = reply["choices"][0]
if choice.get("finish_reason") in ("length", "content_filter"):
raise RuntimeError("Response was not completed")
message = choice["message"]
calls = message.get("tool_calls") or []
if not calls:
print(message.get("content") or "")
break
messages.append(message)
for call in calls:
try:
args = json.loads(call["function"]["arguments"])
result = execute(call["function"]["name"], args)
except (ValueError, TypeError):
result = {"error": "Invalid JSON arguments"}
messages.append({"role": "tool", "tool_call_id": call["id"],
"content": json.dumps(result)})
else:
raise RuntimeError("Tool round limit reached")Selection and Streaming
Use tool_choice: "auto" for automatic selection, "required" to require a call, or "none" to disable calls. To select one function, use {"type":"function","function":{"name":"lookup_stock"}}. Avoid forcing calls on every round.
With streaming, collect delta.tool_calls by choice and tool-call index. Concatenate argument fragments and execute only complete calls. Return results for every call, validate arguments, and cap retries.