Bluwing provides two ways to resolve natural language into validated, strongly typed tool calls:
- Unified Chat Completions Endpoint (
POST /v1/chat/completionswithmodel: "bluwing"): Drop-in compatible with standard OpenAI SDKs; automatically matches ready bricks in < 1ms or compiles JIT on the fly. - 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":
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
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)
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
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)
| Field | Type | Required | Description |
|---|---|---|---|
input | string | Yes | The raw user words or prompt, from 1 to 32,000 characters. |
version | string or number | No | "live" (default), an integer version number (e.g. 2), or a custom version alias. |
facts | object | No | Key-value pairs known by your backend (up to 64 keys, 8 KiB total). Used to bind parameters without prompt stuffing. |
user_timezone | string | No | An IANA timezone identifier (e.g. "America/New_York", "Europe/Berlin"). Resolves relative temporal words like "tomorrow", "next Tuesday", and "at 5pm". Defaults to UTC. |
options | object | No | Behavioral 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:
{
"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:
{
"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.