This guide walks you through making your first tool-calling request with Bluwing. You will need an API key from the API keys page.
1. Set Your API Key
Copy your secret key and export it into your development environment:
export BLUWING_API_KEY="rk_live_..."Every API request requires this key in the Authorization: Bearer <KEY> header. Keep this key on your backend and never expose it in client-side applications.
2. Make Your First Call: Unified Endpoint (Recommended)
Bluwing provides a single, unified endpoint compatible with the OpenAI Chat Completions API. You pass your prompt and your tool definitions with model: "bluwing".
There is no need to pre-create or manage toolsets beforehand:
- Instant Match: If your tools match or are a subset of an existing brick in your account, Bluwing resolves immediately in sub-40 milliseconds.
- Automatic JIT Compilation: If you pass novel tools, Bluwing compiles them on the fly and returns your typed tool calls within the same request.
Using Python (OpenAI SDK)
from openai import OpenAI
import os
client = OpenAI(
base_url="https://api.bluwing.si/v1",
api_key=os.environ["BLUWING_API_KEY"],
)
response = client.chat.completions.create(
model="bluwing",
messages=[
{"role": "user", "content": "Book Nok for four people tomorrow at 7pm"}
],
tools=[
{
"type": "function",
"function": {
"name": "book_table",
"description": "Book a dining table at a restaurant for a party at a date and time.",
"parameters": {
"type": "object",
"properties": {
"restaurant": {"type": "string", "description": "Restaurant name"},
"party_size": {"type": "integer", "description": "Number of diners"},
"date": {"type": "string", "description": "Date YYYY-MM-DD"},
"time": {"type": "string", "description": "24-hour time HH:MM"},
},
"required": ["restaurant", "party_size", "date", "time"],
},
},
}
],
)
for tool_call in response.choices[0].message.tool_calls or []:
print(f"Tool: {tool_call.function.name}")
print(f"Arguments: {tool_call.function.arguments}")Using TypeScript (Node.js / Bun)
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.bluwing.si/v1",
apiKey: process.env.BLUWING_API_KEY,
});
const response = await client.chat.completions.create({
model: "bluwing",
messages: [{ role: "user", content: "Book Nok for four people tomorrow at 7pm" }],
tools: [
{
type: "function",
function: {
name: "book_table",
description: "Book a dining table at a restaurant for a party at a date and time.",
parameters: {
type: "object",
properties: {
restaurant: { type: "string", description: "Restaurant name" },
party_size: { type: "integer", description: "Number of diners" },
date: { type: "string", description: "Date YYYY-MM-DD" },
time: { type: "string", description: "24-hour time HH:MM" },
},
required: ["restaurant", "party_size", "date", "time"],
},
},
},
],
});
for (const call of response.choices[0].message.tool_calls ?? []) {
console.log(call.function.name, call.function.arguments);
}Using cURL
curl https://api.bluwing.si/v1/chat/completions \
-H "Authorization: Bearer $BLUWING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "bluwing",
"messages": [
{ "role": "user", "content": "Book Nok for four people tomorrow at 7pm" }
],
"tools": [
{
"type": "function",
"function": {
"name": "book_table",
"description": "Book a dining table at a restaurant for a party at a date and time.",
"parameters": {
"type": "object",
"properties": {
"restaurant": { "type": "string", "description": "Restaurant name" },
"party_size": { "type": "integer", "description": "Number of diners" },
"date": { "type": "string", "description": "YYYY-MM-DD" },
"time": { "type": "string", "description": "24-hour time HH:MM" }
},
"required": ["restaurant", "party_size", "date", "time"]
}
}
}
]
}'3. Inspect the Output
The engine matches book_table, normalizes "tomorrow at 7pm" into a concrete ISO date and 24-hour time, and returns standard OpenAI-compatible tool calls:
{
"id": "chatcmpl-res_01jc8w4n6f2q7v9k3d5t",
"object": "chat.completion",
"created": 1794838695,
"model": "bluwing",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_8f2k1q9d",
"type": "function",
"function": {
"name": "book_table",
"arguments": "{\"restaurant\":\"Nok\",\"party_size\":4,\"date\":\"2026-11-17\",\"time\":\"19:00\"}"
}
}
]
},
"finish_reason": "tool_calls"
}
],
"usage": {
"prompt_tokens": 32,
"completion_tokens": 0,
"total_tokens": 32
},
"rednet": {
"status": "complete",
"timing_us": { "gateway": 120, "mason": 18200, "mortar": 2400, "total": 20720 }
}
}Notice:
tool_calls: Fully parsed, validated JSON ready to pass directly to your backend functions or database.timing_us: Total latency breakdown showing sub-millisecond gateway routing and fast MASON/MORTAR execution.model: "bluwing": In-house routing and parameter binding with zero third-party LLMs used for tool execution.
4. Handling the Other Response States
- Missing Required Argument (
needs_input):
If the user says: "Book a table at Nok tomorrow at 7pm", the party size is absent. Rather than hallucinating a guess, Bluwing asks for clarification: ``json { "choices": [ { "message": { "role": "assistant", "content": "To do that I need: party_size (number of diners)." }, "finish_reason": "stop" } ], "rednet": { "status": "needs_input", "needs_input": [ { "tool": "book_table", "missing": [{ "param": "party_size" }] } ] } } ``
- Out of Domain / Conversational (
no_tool):
If the user says: "What is the capital of Peru?", the engine detects no semantic overlap with your tools, immediately answering with empty tool calls in under 20 ms.
5. Advanced: Pre-Compiled Enterprise Toolsets (Bricks)
For high-throughput enterprise applications managing hundreds or thousands of tools with strict immutable versioning, you can pre-compile a dedicated Brick:
- Send tool definitions to
POST /v1/bricks:
``bash curl https://api.bluwing.si/v1/bricks \ -H "Authorization: Bearer $BLUWING_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "enterprise-ops", "options": { "auto_activate": true }, "tools": [ ... ] }' ``
- Call the pre-compiled brick directly:
- Native Resolve:
POST /v1/bricks/{brick_id}/resolve - OpenAI SDK: pass
model: "brick:<brick_id>@live"
Compilation runs with parallel Perplexity embeddings (perplexity/pplx-embed-v1-0.6b), building 30 tools in 54ms and 70 tools in 1.08s.
Next Steps
- OpenAI & Anthropic Compatibility: Deep dive into SDK parameters, dynamic tool masking, and multi-turn workflows.
- Resolve in Depth: Advanced flags,
factsinjection, and timezone rules. - Reading Responses: Handling parallel and dependent sequential calls.
- Credits and Billing: Token metering ($0.015/1M input tokens) and subscription quotas.