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

Call

Resolve a request

High-speed native resolution and unified tool calling for conversational agents.

Bluwing provides two ways to resolve natural language into validated, strongly typed tool calls:

  1. Unified Chat Completions Endpoint (POST /v1/chat/completions with model: "bluwing"): Drop-in compatible with standard OpenAI SDKs; automatically matches ready bricks in < 1ms or compiles JIT on the fly.
  2. Native Resolve Endpoint (POST /v1/bricks/{id}/resolve): Ultra-fast (< 30ms) native endpoint for pre-compiled bricks with first-class confidence scores, grounding character offsets, and timing breakdowns.

#1. Unified Endpoint: POST /v1/chat/completions

For standard AI agents, send your prompt and tools directly to /v1/chat/completions with model: "bluwing":

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": "Charge customer cus_99214 for $250.00 USD" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "payments_create_charge",
          "description": "Charge a customer payment method for a specified amount and currency.",
          "parameters": {
            "type": "object",
            "required": ["amount", "currency", "customer_id"],
            "properties": {
              "amount": { "type": "number", "description": "Charge amount" },
              "currency": { "type": "string", "description": "ISO currency code" },
              "customer_id": { "type": "string", "description": "Customer ID" }
            }
          }
        }
      }
    ]
  }'
  • Dynamic Tool Masking: If you pass a subset of tools from an existing ready brick, Bluwing automatically restricts resolution to that subset, masking out non-passed tools and executing in under 40 milliseconds.
  • JIT Compilation: If the tools are novel, Bluwing compiles an ephemeral brick on the fly and returns the answer in the same HTTP call.

#2. Native Endpoint: POST /v1/bricks/{id}/resolve

For systems targeting an existing, pre-compiled brick:

Using cURL

bash
curl https://api.bluwing.si/v1/bricks/brk_7m2q9xk4hd3vfc8r/resolve \
  -H "Authorization: Bearer $BLUWING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: req_9a8b7c6d5e" \
  -d '{
    "input": "Book Nok for four people tomorrow at 7pm",
    "user_timezone": "Europe/Ljubljana",
    "facts": {
      "user_id": "usr_9421",
      "user_city": "Ljubljana"
    },
    "options": {
      "tool_choice": "auto",
      "parallel_tool_calls": true
    }
  }'

Using TypeScript (Node.js)

typescript
interface ResolveResponse {
  id: string;
  status: "tool_calls" | "needs_input" | "no_tool";
  tool_calls: Array<{
    id: string;
    name: string;
    arguments: Record<string, unknown>;
    confidence: number;
    side_effect: "read" | "write" | "irreversible";
    requires_confirmation: boolean;
    grounding: Record<string, string>;
  }>;
  needs_input: Array<{ parameter: string; question: string }>;
  message: string | null;
  timing_us: { total: number };
}

const response = await fetch("https://api.bluwing.si/v1/bricks/brk_7m2q9xk4hd3vfc8r/resolve", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.BLUWING_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    input: "Book Nok for four people tomorrow at 7pm",
    user_timezone: "Europe/Ljubljana",
    facts: { user_city: "Ljubljana" }
  })
});

const data = (await response.json()) as ResolveResponse;

Using Python

python
import os
import requests

response = requests.post(
    "https://api.bluwing.si/v1/bricks/brk_7m2q9xk4hd3vfc8r/resolve",
    headers={
        "Authorization": f"Bearer {os.environ['BLUWING_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "input": "Book Nok for four people tomorrow at 7pm",
        "user_timezone": "Europe/Ljubljana",
        "facts": {"user_city": "Ljubljana"},
    },
)

data = response.json()

#3. Request Fields (Native Endpoint)

FieldTypeRequiredDescription
inputstringYesThe raw user words or prompt, from 1 to 32,000 characters.
versionstring or numberNo"live" (default), an integer version number (e.g. 2), or a custom version alias.
factsobjectNoKey-value pairs known by your backend (up to 64 keys, 8 KiB total). Used to bind parameters without prompt stuffing.
user_timezonestringNoAn IANA timezone identifier (e.g. "America/New_York", "Europe/Berlin"). Resolves relative temporal words like "tomorrow", "next Tuesday", and "at 5pm". Defaults to UTC.
optionsobjectNoBehavioral flags (tool_choice, parallel_tool_calls, min_confidence).

#4. Facts (Deterministic Context Injection)

facts allow you to supply session state, authenticated user metadata, or device telemetry that the user did not explicitly type in their message:

json
{
  "input": "Show my recent orders",
  "facts": {
    "user_id": "usr_9812",
    "account_tier": "enterprise",
    "organization_id": "org_411"
  }
}
  • Zero Prompt Bloat: Facts are passed as structured key-value bindings rather than appending paragraphs of context to the prompt.
  • Safety First: Facts are only bound when a tool's parameter definition explicitly requests that value. They are never hallucinated into unrelated parameters.

#5. Intelligent Clarifications (needs_input)

When a user's instruction clearly targets a tool but omits a required parameter, Bluwing does not guess or hallucinate. Instead, it transitions to needs_input and provides a clear question prompting for the exact missing parameter:

json
{
  "status": "needs_input",
  "tool_calls": [],
  "needs_input": [
    {
      "tool": "audio_transcribe_clip",
      "missing": [{ "param": "language", "description": "Primary spoken language" }],
      "known": { "audio_url": "https://example.com/audio/interview.wav" }
    }
  ],
  "message": "To do that I need: language (primary spoken language)."
}

In your next conversational turn, simply send the user's answer (or inject it into facts) to immediately complete parameter resolution.

PreviousVersions and liveNext Reading responses

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

On this page

  • 1. Unified Endpoint: POST /v1/chat/completions
  • 2. Native Endpoint: POST /v1/bricks/{id}/resolve
  • 3. Request Fields (Native Endpoint)
  • 4. Facts (Deterministic Context Injection)
  • 5. Intelligent Clarifications (needs_input)