Response

Tool Calling

Connect model requests to your application functions and return results for the next turn.

POST /v1/responses

Custom functions run in your application. The model supplies the function name and arguments; your code performs the lookup and returns the result.

Request and Authentication

http

POST https://api.tokatlas.ai/v1/responses
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

json

{
  "model": "gpt-5",
  "tools": [
    {
      "type": "function",
      "name": "lookup_stock",
      "description": "Look up available inventory for a product SKU.",
      "parameters": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Product SKU, for example DEMO-001"
          }
        },
        "required": [
          "sku"
        ],
        "additionalProperties": false
      },
      "strict": true
    }
  ],
  "input": "Check stock for DEMO-001."
}

Tool Call Format

Illustrative call item; IDs and arguments come from the actual response.

json

{
  "type": "function_call",
  "id": "fc_example",
  "name": "lookup_stock",
  "arguments": "{\"sku\": \"DEMO-001\"}",
  "call_id": "call_example"
}

Inspect all output items. A function_call carries JSON-string arguments; send a function_call_output using its call_id, not its item id.
The example replays output, including reasoning, with store: false. Alternatively, use a stored previous_response_id and send the new results. Resend tool definitions.
tool_choice supports "auto", "required", "none", or {"type":"function","name":"lookup_stock"}. Strict schemas require all properties in required and additionalProperties: false.
For streaming, assemble response.function_call_arguments.delta per output item and wait for complete arguments before executing.

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.

cURLPythonJavaScriptJava

bash

curl --fail-with-body --silent --show-error --max-time 180 \
  --request POST \
  --url "https://api.tokatlas.ai/v1/responses" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "gpt-5",
  "tools": [
    {
      "type": "function",
      "name": "lookup_stock",
      "description": "Look up available inventory for a product SKU.",
      "parameters": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Product SKU, for example DEMO-001"
          }
        },
        "required": [
          "sku"
        ],
        "additionalProperties": false
      },
      "strict": true
    }
  ],
  "stream": false,
  "input": "Check stock for DEMO-001.",
  "store": false
}'

python

import os
import requests

headers = {
    'Authorization': 'Bearer ' + os.environ["API_KEY"],
    'Content-Type': 'application/json',
}
payload = {'model': 'gpt-5',
 'tools': [{'type': 'function',
            'name': 'lookup_stock',
            'description': 'Look up available inventory for a product SKU.',
            'parameters': {'type': 'object',
                           'properties': {'sku': {'type': 'string',
                                                  'description': 'Product SKU, for '
                                                                 'example DEMO-001'}},
                           'required': ['sku'],
                           'additionalProperties': False},
            'strict': True}],
 'stream': False,
 'input': 'Check stock for DEMO-001.',
 'store': False}
response = requests.request(
    'POST', 'https://api.tokatlas.ai/v1/responses', headers=headers,
    json=payload,
    timeout=180,
)
response.raise_for_status()
print(response.text)

if (!process.env.API_KEY) throw new Error("Set API_KEY first.");
const response = await fetch("https://api.tokatlas.ai/v1/responses", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-5",
  "tools": [
    {
      "type": "function",
      "name": "lookup_stock",
      "description": "Look up available inventory for a product SKU.",
      "parameters": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Product SKU, for example DEMO-001"
          }
        },
        "required": [
          "sku"
        ],
        "additionalProperties": false
      },
      "strict": true
    }
  ],
  "stream": false,
  "input": "Check stock for DEMO-001.",
  "store": false
}),
  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-5\",",
            "  \"tools\": [",
            "    {",
            "      \"type\": \"function\",",
            "      \"name\": \"lookup_stock\",",
            "      \"description\": \"Look up available inventory for a product SKU.\",",
            "      \"parameters\": {",
            "        \"type\": \"object\",",
            "        \"properties\": {",
            "          \"sku\": {",
            "            \"type\": \"string\",",
            "            \"description\": \"Product SKU, for example DEMO-001\"",
            "          }",
            "        },",
            "        \"required\": [",
            "          \"sku\"",
            "        ],",
            "        \"additionalProperties\": false",
            "      },",
            "      \"strict\": true",
            "    }",
            "  ],",
            "  \"stream\": false,",
            "  \"input\": \"Check stock for DEMO-001.\",",
            "  \"store\": false",
            "}"
        );
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(30)).build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.tokatlas.ai/v1/responses"))
            .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 (pip install requests) and set the API_KEY environment variable. The inventory result is demo data. Replace execute with your business service and select a model enabled for your account.

python

import json
import os
import requests

URL = "https://api.tokatlas.ai/v1/responses"
HEADERS = {'Authorization': "Bearer " + os.environ["API_KEY"], 'Content-Type': 'application/json'}
TOOLS = [{'type': 'function',
  'name': 'lookup_stock',
  'description': 'Look up available inventory for a product SKU.',
  'parameters': {'type': 'object',
                 'properties': {'sku': {'type': 'string',
                                        'description': 'Product SKU, for example '
                                                       'DEMO-001'}},
                 'required': ['sku'],
                 'additionalProperties': False},
  'strict': True}]


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"]]}

history = [{"role": "user", "content": "Check stock for DEMO-001."}]
for _ in range(6):
    reply = post({"model": "gpt-5", "store": False,
                  "tools": TOOLS, "input": history})
    if reply.get("status") != "completed":
        raise RuntimeError("Response did not complete")
    output = reply["output"]
    calls = [item for item in output if item["type"] == "function_call"]
    if not calls:
        for item in output:
            if item["type"] == "message":
                for block in item["content"]:
                    if block["type"] == "output_text":
                        print(block["text"])
        break
    history.extend(output)  # Preserve reasoning items as well as calls.
    for call in calls:
        try:
            args = json.loads(call["arguments"])
            result = execute(call["name"], args)
        except (TypeError, ValueError):
            result = {"error": "Invalid JSON arguments"}
        history.append({"type": "function_call_output", "call_id": call["call_id"],
                        "output": json.dumps(result)})
else:
    raise RuntimeError("Tool round limit reached")

Troubleshooting

Symptom	Check
Missing tool result	Return one result for every call; retain the exact IDs.
Repeated calls	Avoid forcing a tool on every round; cap the loop.
Invalid arguments	Validate names and parameters before dispatching.
Tool failure	Return a structured error instead of invented data.
Unsupported option	Check the selected model and gateway route capabilities.

Tool Calling ​

Request and Authentication ​

Tool Call Format ​

First Request in Each Language ​

Complete Python Example ​

Troubleshooting ​