Birk API
The main integration surface for connecting Birk models, agents, tool calls, and orchestration flows to your own products. From a single chat request to a production-grade pipeline run, it uses the same secure API contract.
01Overview
Single entry point
Chat, model selection, tool use, streaming, orchestration, and pipeline outputs work under the same API family. This lets you keep the integration surface stable while moving from prototype to production.
Production-oriented contract
Each request includes authentication, request identity, error codes, usage metrics, and observability fields. Your application does not only receive responses; it can measure behavior.
const BRIQ_BASE_URL = "https://api.briqmind.com"; const BRIQ_API_VERSION = "v1";
02Models Exposed Through the API
The developer surface should treat five model families together. Fast, Light, and Heavy cover text and agents; Blink handles image generation, and Blip handles speech generation. When orchestration is needed, these models can work together inside one workflow.
| Model | Model ID | Main endpoint | Use case |
|---|---|---|---|
| Birk Fast | birk-fast-v1 | /v1/chat/completions | Low-latency text, summarization, classification, routing, and fast response generation. |
| Birk-Agent-Light | birk-agent-light-v1 | /v1/chat/completions | Daily agent work, tool calling, structured output, and medium-depth analysis. |
| Birk-Agent-Heavy | birk-agent-heavy-v1 | /v1/chat/completions | Deep reasoning, long context, complex analysis, and multi-step enterprise tasks. |
| Blink | blink-v1 | /v1/images/generations | Image generation, creative variation, product visuals, and approved brief-based output. |
| Blip | blip-v1 | /v1/audio/speech | Speech generation, voice-based responses, voice-over, and real-time audio experiences. |
curl https://api.briqmind.com/v1/images/generations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $BRIQ_API_KEY" \
-d '{
"model": "blink-v1",
"prompt": "Generate a dark-themed product visual for a modern SaaS dashboard.",
"size": "1024x1024"
}'curl https://api.briqmind.com/v1/audio/speech \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $BRIQ_API_KEY" \
-d '{
"model": "blip-v1",
"voice": "tr-natural",
"input": "The weekly report is ready. Three critical action items were detected."
}'03Authentication
All API requests use a Bearer token in the Authorization header. Do not keep API keys in clients, mobile apps, or public repositories; route requests through your own backend layer.
API key
Generated per environment. Separate development and production keys.
Scope
Restrict model, tool, file, and pipeline access by key scope.
Rotation
Use regular rotation and revocation policies for long-lived service keys.
curl https://api.briqmind.com/v1/models \ -H "Authorization: Bearer $BRIQ_API_KEY"
04Request Structure
A Birk API request does more than send a prompt; it carries the model, message history, output format, tools, temperature, token limit, and tracing settings together.
Specifies which model will run.
Carries system, user, and assistant message history.
Defines the secure functions the agent can call.
Defines the expected JSON, text, or schema-based output.
Controls response variety.
Sets the upper limit for the generated response.
Used to receive the response in chunks.
Lets you attach your own tracing and user context.
05Chat Completion
The basic use is the POST /v1/chat/completions endpoint. It works close to the existing OpenAI-compatible client logic, while Birk agents are designed for deeper tasks with tools and enterprise context.
curl https://api.briqmind.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $BRIQ_API_KEY" \
-d '{
"model": "birk-agent-heavy-v1",
"messages": [
{ "role": "system", "content": "Act like an enterprise data analyst. Split your answer into evidence and action." },
{ "role": "user", "content": "Analyze the sales decline over the last 30 days and report possible causes." }
],
"temperature": 0.2,
"max_tokens": 1200
}'{
"id": "chatcmpl_9f2a1c",
"object": "chat.completion",
"created": 1767326400,
"model": "birk-agent-heavy-v1",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Summary: The sales decline concentrates around three main signals..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 842,
"completion_tokens": 386,
"total_tokens": 1228
},
"trace": {
"request_id": "req_01HV8K...",
"latency_ms": 1840
}
}import BriqMind from "@briqmind/sdk";
const client = new BriqMind({
apiKey: process.env.BRIQ_API_KEY,
});
const response = await client.chat.completions.create({
model: "birk-agent-light-v1",
messages: [
{
role: "user",
content: "Summarize these customer support records and group recurring issues.",
},
],
temperature: 0.2,
});
console.log(response.choices[0].message.content);from briqmind import BriqMind
client = BriqMind(api_key="BRIQ_API_KEY")
response = client.chat.completions.create(
model="birk-agent-light-v1",
messages=[
{
"role": "user",
"content": "Extract action items from these operations notes."
}
],
temperature=0.2,
)
print(response.choices[0].message.content)06Streaming Responses
First token arrives faster
For long reports, chat interfaces, and live operations screens, you can show the response chunk by chunk instead of waiting for the full output.
const stream = await client.chat.completions.create({
model: "birk-fast-v1",
stream: true,
messages: [
{ role: "user", content: "Summarize this report in 5 bullet points." }
],
});
for await (const event of stream) {
if (event.type === "content.delta") {
process.stdout.write(event.delta);
}
}07Tool Calling
Agent models can call secure tools that you define. These tools represent controlled actions such as database queries, log search, file reads, task creation, or notifications.
{
"model": "birk-agent-light-v1",
"messages": [
{
"role": "user",
"content": "Find payment errors from the last 7 days and summarize their causes."
}
],
"tools": [
{
"type": "function",
"function": {
"name": "search_logs",
"description": "Searches application logs by time range.",
"parameters": {
"type": "object",
"properties": {
"query": { "type": "string" },
"from": { "type": "string" },
"to": { "type": "string" }
},
"required": ["query", "from", "to"]
}
}
}
],
"tool_choice": "auto"
}Tool safety
A tool should accept only required parameters and must not open broad system access.
Parameters returned by the model must be validated in the backend before execution.
Add approval steps for critical actions such as data deletion, payments, or customer notifications.
Every tool call must be logged with request identity, user, and result.
08Orchestration and Pipeline Execution
You do not have to manually choose which model will be used inside the application. The orchestration flow determines the model, agent, and required substeps according to request difficulty.
curl https://api.briqmind.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $BRIQ_API_KEY" \
-d '{
"workflow": "orchestration",
"messages": [
{
"role": "user",
"content": "Analyze the CSV sales file, find anomalies, and write an executive summary."
}
],
"output": {
"format": "json",
"schema": "executive_analysis"
}
}'When orchestration?
09Errors, Limits, and Retries
HTTP behavior
async function briqFetch(path, options, attempt = 1) {
const response = await fetch(`https://api.briqmind.com${path}`, options);
if ((response.status === 429 || response.status >= 500) && attempt < 4) {
const waitMs = Math.min(1000 * 2 ** attempt, 8000);
await new Promise((resolve) => setTimeout(resolve, waitMs));
return briqFetch(path, options, attempt + 1);
}
if (!response.ok) {
throw await response.json();
}
return response.json();
}{
"error": {
"type": "invalid_request_error",
"code": "model_not_available",
"message": "The selected model is not available for this API key.",
"param": "model",
"request_id": "req_01HV8K..."
}
}10Production Checklist
Carry request identity
Send your own request_id or metadata.trace_id value with every call.
Record usage metrics
Track tokens, latency, model, error code, and tool calls.
Separate keys
Use separate keys for development, testing, production, and service accounts.
Validate output
If you expect JSON, run schema validation; do not blindly show raw model output to users.
Use pipelines for critical work
Use auditable pipelines instead of a single prompt for multi-step production workflows.
Track async jobs with webhooks
For long-running jobs, listen to status events instead of making the user wait.
{
"id": "evt_01HV9A...",
"type": "pipeline.completed",
"created": 1767326500,
"data": {
"run_id": "run_sales_audit_042",
"status": "completed",
"duration_ms": 18420,
"output_url": "https://api.briqmind.com/v1/runs/run_sales_audit_042/output"
}
}Next technical reference
This page explains the integration logic. Move to the API Reference page for endpoint contracts, parameter tables, and version behavior.
Go to API Reference