Bluwing/Docsv0.9.0
Operational
API ReferenceConsole

Get started

  • Introduction
  • Quickstart
  • How it works

Build

  • Tool format
  • Matching hints
  • Toolsets and builds
  • Versions and live

Call

  • Resolve a request
  • Reading responses
  • OpenAI and Anthropic compatibility

Account

  • Authentication
  • Credits and billing
  • Limits
  • Errors
  • Security and data
  • FAQ

Get started

Quickstart

Call tools in a single request with model: "bluwing" in under five minutes.

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:

bash
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)

python
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)

typescript
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

bash
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:

json
{
  "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

  1. 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" }] } ] } } ``

  1. 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:

  1. 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": [ ... ] }' ``

  1. Call the pre-compiled brick directly:
  2. Native Resolve: POST /v1/bricks/{brick_id}/resolve
  3. 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, facts injection, and timezone rules.
  • Reading Responses: Handling parallel and dependent sequential calls.
  • Credits and Billing: Token metering ($0.015/1M input tokens) and subscription quotas.
PreviousIntroductionNext How it works

Something unclear or missing? Write to [email protected] and we'll fix the page.

On this page

  • 1. Set Your API Key
  • 2. Make Your First Call: Unified Endpoint (Recommended)
  • 3. Inspect the Output
  • 4. Handling the Other Response States
  • 5. Advanced: Pre-Compiled Enterprise Toolsets (Bricks)
  • Next Steps