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

Build

Toolsets and builds

Creating a toolset, build performance, ephemeral auto-management, and lifecycle.

A toolset is a collection of tools compiled into an optimized high-dimensional vector search index. Bluwing offers two modes:

  1. Ephemeral Auto-Managed Toolsets: Automatically managed when passing inline tools with model: "bluwing" to POST /v1/chat/completions. No manual build or slot management required.
  2. Persistent Toolsets (Bricks): Explicitly created with POST /v1/bricks and identified by an ID starting with brk_. Supports immutable versioning and custom aliases (e.g. live, staging).

#1. Create a Persistent Toolset

bash
curl https://api.bluwing.si/v1/bricks \
  -H "Authorization: Bearer $BLUWING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "support-desk", 
    "description": "Help widget tools", 
    "tools": [ ... ], 
    "options": { "auto_activate": true } 
  }'
FieldDescription
name1 to 128 characters, unique in your account.
descriptionOptional, up to 4,096 characters for organization.
tools1 to 10,000 tools, in any accepted shape.
options.auto_activateAutomatically points the live alias to this version upon build completion. Default false.

The response is 202 Accepted containing brick_id, version, and build_job_id. If an identical toolset was previously built, reused: true is returned immediately without charging build credits.


#2. Build Performance & Latency

Compilation is powered by asynchronous parallel embeddings using Perplexity (perplexity/pplx-embed-v1-0.6b):

  • 10 tools: ~25 ms
  • 30 tools: ~54 ms
  • 70 tools: ~1.08 s
  • 1,000 tools: ~12 s

Builds transition through the following automated pipeline: queued → preparing → embedding → tree → indexing → calibrating → publishing → succeeded.

Tracking Build Status

Poll the build job:

bash
curl https://api.bluwing.si/v1/jobs/job_4w8n2c6v1q9t3k7d \
  -H "Authorization: Bearer $BLUWING_API_KEY"
json
{
  "job_id": "job_4w8n2c6v1q9t3k7d",
  "brick_id": "brk_7m2q9xk4hd3vfc8r",
  "version": 1,
  "status": "succeeded",
  "progress": { "stage": "ready", "percent": 100 },
  "error": null
}

Or stream real-time events via Server-Sent Events from GET /v1/jobs/{job_id}/events.


#3. What a Build Costs

Build ActionCredits Charged
New Toolset20 credits for the first 20 tools, then 1 credit per tool. (e.g. 6 tools = 20 credits; 500 tools = 500 credits).
New Version1 credit per tool added or modified. Unchanged tools are 100% free. Minimum 1 credit.
Failed Build0 credits. Credits are automatically refunded on failure.

#4. Reading, Aliasing, and Deletion

RequestDescription
GET /v1/bricksList all toolsets in your account (paginated via ?cursor=).
GET /v1/bricks/{id}Inspect a specific toolset, its aliases, and active versions.
GET /v1/bricks/{id}/versions/{n}Inspect version metadata, tool count, quality scores, and build artifact status.
PUT /v1/bricks/{id}/aliases/{alias}Move an alias (e.g. live, canary) to a new version for zero-downtime rollouts or instant rollbacks.
DELETE /v1/bricks/{id}Deletes the toolset.

#5. Toolset Capacity

Toolsets and tools are completely unlimited across all plans. Bluwing does not restrict your account with artificial slot limits:

  • Free: Unlimited active toolsets · Standard execution
  • Plan A: Unlimited active toolsets · Accelerated execution
  • Plan S: Unlimited active toolsets · Ultra-fast execution
  • Plan S+: Unlimited active toolsets · Real-time execution

Plans differ by execution speed, priority lane, and monthly token allowances rather than toolset count.

PreviousMatching hintsNext Versions and live

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

On this page

  • 1. Create a Persistent Toolset
  • 2. Build Performance & Latency
  • 3. What a Build Costs
  • 4. Reading, Aliasing, and Deletion
  • 5. Toolset Capacity