API reference

Build with the VIABLE Lab API.

One model-first API for chat, multimodal input, VETTING workflows, published agent orchestration, embeddings, image generation, audio, and encryption utilities, documented the way you and your agents read.

Manage API keys Model catalog Full OpenAPI reference

Agent context

Building with a coding agent?

Drop the maintained API guide into Claude Code, Codex, Cursor, Gemini CLI, or another AI-assisted workflow. Your agent can use direct endpoints when they fit, or draft VIABLE Lab agent workflow JSON when you need orchestration.

Codex Claude Code Gemini CLI Cursor Windsurf

Open the agent guide

I am building with the VIABLE Lab API. Read https://developers.viablelab.org/agents/viablelab-api.md as the source of truth. Prefer direct endpoints for one-step chat, VETTING, embeddings, image, speech, transcription, or encryption; suggest Dashboard Agents only when a product flow needs branching, loops, or multiple coordinated model/tool calls behind one endpoint. Auth uses Bearer VIABLE Lab API keys with endpoint scopes such as model:request, utils:crypto, and agents:execute. For published agent runs, call POST /v1/agents/{slug}/runs and persist conversation_id per end-user thread + agent slug; run_id is one execution and request_id is for log/support correlation. Treat any direct-endpoint or provider-level session state as separate from this agent conversation_id.

Tool resources

OpenAPI referenceComplete schema-backed view for generated clients and exact endpoint details.Agent guideCopy-ready API, VETTING, Playground, and agent orchestration context for coding agents.Live metadataModel catalog, endpoint list, agent quickstarts, and pricing notes in JSON.Raw OpenAPI JSONCanonical schema file for generators, CI checks, and tooling.

AUTHDeveloper dashboard

Authentication and API keys

Create project keys in the dashboard, store them as server-side secrets, and send them as bearer tokens to protected model and utility endpoints.

When to use

Use the dashboard whenever you need to reveal, pause, resume, revoke, scope, or limit a key. Client applications should call your own backend, not expose VIABLE Lab API keys directly.

Key details

Authorization: Bearer $VIABLE_API_KEY for protected API calls
Scopes: model:request for model endpoints, utils:crypto for encryption utilities, agents:execute for published agent runs
Optional limits: requests per minute, daily token cap, monthly cost cap; Optional allowedModels list to restrict a key to exact model IDs or aliases

Notes

Bearer keys do not change request bodies.
Paused keys can be resumed without rotation. Revoked keys are permanent.
Dashboard management endpoints are for signed-in dashboard sessions, not normal product integrations.

Authorization: Bearer $VIABLE_API_KEY

POST

Chat completions

OpenAI-compatible chat requests with model-first routing, aliases, multimodal content arrays, and optional streaming.

When to use

Use this endpoint for general generation, analysis, coding, tutoring, classification, and agent workflows that need normal chat responses.

Parameters

model: model ID or supported alias
messages: array of role/content messages
stream: true for server-sent events
provider: optional only when a future model name would be ambiguous

Notes

Do not include provider for ordinary calls; the API resolves it from the model registry.
Streaming starts before logging finishes, and logging continues asynchronously after the response completes.
Unknown future model IDs are allowed when their provider can be inferred from a safe prefix.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.viablelab.org/v1",
    api_key="<VIABLE_API_KEY>",  # load from your app's secret store
)

response = client.chat.completions.create(
    model="viable-2",
    messages=[
        {"role": "user", "content": "Write one sentence about retrieval."}
    ],
)

print(response.choices[0].message.content)

curl -N https://api.viablelab.org/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -d '{
    "model": "gemini-2.5-flash",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Stream a concise project plan." }
    ]
  }'

POST

Published agent runs

Run a published visual/code agent workflow behind one endpoint. The agent graph can chain models, branch, loop within budgets, and return text plus generated assets.

When to use

Use this endpoint when one product turn needs orchestration, such as deciding whether to call an image model, running several model steps, or coordinating multiple tools behind one stable API path.

Parameters

slug: published agent path segment from the dashboard
input: latest end-user turn as a string, content-part array, or OpenAI Responses-style user message array
message: text-only alias for input
messages: compatibility alias whose last user message supplies the current turn
conversation_id: optional on the first turn; resend the returned value on later turns to continue the same agent chat thread

Notes

Use conversation_id only with published agent runs. For direct chat or VETTING, include the context required by that request and treat any app- or provider-level session state as separate from this field.
For image input, use input_text/text plus input_image/image_url parts. The LLM node that receives the user turn must use a model whose input_modalities include image.
Inline Agent images are limited to 8 MiB each and 10 MiB total (12 MiB JSON body). Up to 8 MiB of prior media is materialized per model request; omitted history media remains downloadable to authorized researchers.
Exact bytes and filenames are archived privately; logs, traces, exports, and conversation history use authenticated research asset references rather than base64.
HTTPS image URLs are retained exactly as restricted provenance, including query parameters, but are not fetched automatically and may expire at the source. URLs with embedded username/password credentials are rejected.
A custom LLM user prompt keeps current media unless includeInputMedia is false. The response input_assets array identifies archived media from that turn.
Save conversation_id per end-user session and agent slug. If a client drops it, the next request starts a new agent conversation even if the input manually includes prior context.
conversation_id is bound to the creating API key or user and the agent. A different key cannot continue someone else's conversation.
Each run returns run_id for one orchestration execution. Request logs show both the run summary and the internal provider calls tagged by agent/run/node.
To design a workflow with a coding agent, create or open an agent in Dashboard > Agents, paste graph JSON in Code / AI, Sync to canvas, Validate, Save, test, then Publish.
Dashboard agent test chat uses the same metered execution path with a selected API key before publish.

Open AgentsBuild, test, publish, unpublish, and inspect agent run traces from the dashboard.

curl https://api.viablelab.org/v1/agents/my-writing-tutor/runs \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -d '{
    "input": "Can you show me a cat and help me write about it?"
  }'

curl https://api.viablelab.org/v1/agents/my-writing-tutor/runs \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -d '{
    "input": [
      { "type": "input_text", "text": "What is this image?" },
      { "type": "input_image", "image_url": "https://example.com/image.png", "filename": "classroom.png" }
    ]
  }'

curl https://api.viablelab.org/v1/agents/my-writing-tutor/runs \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -d '{
    "input": "Can we make the cat green instead?",
    "conversation_id": "agtc_..."
  }'

POST

Text, image, file, and PDF input

Send OpenAI-style content arrays for models that support images, files, or PDFs. Provider adapters convert supported parts when needed.

When to use

Use this shape when asking a model to inspect an image, summarize a PDF, or reason over a small uploaded file represented as base64.

Parameters

content[].type=text with text

content[].type=image_url with image_url.url

content[].type=file or input_file with file.file_data

file_data can be a data URI such as data:application/pdf;base64,...

Notes

Gemini file/PDF input requires base64 data, preferably as a data URI.
Remote image URLs are accepted by compatible providers; base64 data URLs are safest for provider conversion.
Large file workflows should use a backend upload pipeline before calling the API.

curl https://api.viablelab.org/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Summarize the attached image and PDF." },
          { "type": "image_url", "image_url": { "url": "data:image/png;base64,..." } },
          { "type": "file", "file": { "filename": "brief.pdf", "mime_type": "application/pdf", "file_data": "data:application/pdf;base64,..." } }
        ]
      }
    ]
  }'

POST

Lightweight VETTING chat

A chat-completions shaped endpoint that generates a response, checks it against VETTING guidance, and returns chat choices plus vetting metadata.

When to use

Use it when you already have a chat request and want a guarded educational response without building the full VETTING context object.

Parameters

model: any chat-capable supported model
messages: normal chat messages
vettingConfig.maxAttempts: optional retry count
vettingConfig.guideline: optional response policy
vettingConfig.systemPrompt: optional hidden guidance; supports enc:: encrypted values
messages[].role=system content: supports enc:: encrypted values

Notes

This endpoint is intentionally non-streaming because it needs the full answer for verification.
It supports OpenAI, Gemini, and managed chat models through the same chat model registry.
Response format preserves chat choices and adds vetting_info.
Use the Encryption Tool at /dashboard/tools/encryption when a browser-facing product needs to protect hidden VETTING guidance.

Open Encryption ToolEncrypt vettingConfig.systemPrompt or system message content before using it in a browser-facing VETTING integration.

curl https://api.viablelab.org/v1/chat/vetting \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      { "role": "user", "content": "Explain photosynthesis without giving away my homework answer." }
    ],
    "vettingConfig": { "maxAttempts": 1 }
  }'

POST

Full VETTING workflow

A structured VETTING workflow with separate chat and verification model configs, prompts, answer keys, context items, attempts, and verification output.

When to use

Use it for educational products that need traceable answer-key verification, multi-attempt generation, and structured fields for downstream review.

Parameters

mode: vetting; config.chatModel.modelId and config.verificationModel.modelId; config.maxVerificationAttempts; prompts.chatSystemPrompt and optional verification prompt fields; context.items[].question and context.items[].answerKey
messages: user conversation that should be answered

Notes

The chat model and verification model can be different chat-capable models.
The endpoint is non-streaming by design because it must evaluate complete generated responses.
prompts.chatSystemPrompt and prompts.verificationSystemPrompt support enc:: encrypted values from the Encryption Tool.
Use lightweight VETTING chat when you do not need answer-key context or detailed verification fields.

Open Encryption ToolCreate enc:: values for chatSystemPrompt and verificationSystemPrompt fields.

curl https://api.viablelab.org/v1/vetting/full \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -d '{
    "mode": "vetting",
    "config": {
      "chatModel": { "modelId": "viable-2" },
      "verificationModel": { "modelId": "gemini-2.5-flash" },
      "maxVerificationAttempts": 1
    },
    "prompts": {
      "chatSystemPrompt": "Guide the student without revealing the answer."
    },
    "context": {
      "items": [
        {
          "question": { "text": "What is photosynthesis?" },
          "answerKey": { "correctAnswer": "Plants convert light, water, and carbon dioxide into glucose and oxygen." }
        }
      ]
    },
    "messages": [
      { "role": "user", "content": "What is photosynthesis?" }
    ]
  }'

POST

Embeddings

OpenAI-compatible embedding requests for retrieval, semantic search, clustering, and reranking pipelines.

When to use

Use it when you need vectors for documents, chunks, questions, or other searchable text.

Parameters

model: embedding model ID
input: string or array of strings

Notes

The default registered embedding model is nomic-embed-text-v1.5.
Cost is logged when provider usage and registry pricing are available.

curl https://api.viablelab.org/v1/embeddings \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -d '{ "model": "nomic-embed-text-v1.5", "input": ["first document", "second document"] }'

POST

Image generation

OpenAI Images-style generation requests for text-to-image models.

When to use

Use it when a product flow needs generated images from prompts.

Parameters

model: image generation model ID
prompt: text prompt
size: optional image size
n: optional number of images
response_format: provider-supported format when available

Notes

Image pricing can vary by provider and resolution; registry cost is treated as an estimate when exact usage is unavailable.

curl https://api.viablelab.org/v1/images/generations \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -d '{ "model": "flux.2-klein", "prompt": "A clean classroom whiteboard UI mockup", "size": "1024x1024", "n": 1 }'

POST

Speech and transcription

Generate speech from text or transcribe uploaded audio with OpenAI-compatible audio request shapes.

When to use

Use speech for text-to-audio output. Use transcription for uploaded audio files and include duration when available for better cost logging.

Parameters

/v1/audio/speech: JSON with model, input, voice, response_format
/v1/audio/transcriptions: multipart/form-data with model and file; duration_seconds or duration_minutes: optional transcription cost metadata

Notes

OpenAI transcription models and registered VIABLE Lab transcription models are supported.
Transcription upload uses multipart form data, not JSON.

curl https://api.viablelab.org/v1/audio/speech \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -d '{ "model": "gpt-4o-mini-tts", "input": "Hello from VIABLE Lab.", "voice": "alloy", "response_format": "mp3" }' \
  --output speech.mp3

curl https://api.viablelab.org/v1/audio/transcriptions \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -F model=whisper-large-v3 \
  -F [email protected] \
  -F duration_seconds=42

POST

Encryption utilities

Encrypt and decrypt prompt or configuration text using the API utility endpoints.

When to use

Use these utilities when existing integrations need encrypted prompt/configuration values for documented encrypted fields, especially VETTING prompts.

Parameters

/v1/utils/encrypt: JSON with text
/v1/utils/decrypt: JSON with encryptedText
/v1/chat/vetting: vettingConfig.systemPrompt and system message content can use enc:: values
/v1/vetting/full: prompts.chatSystemPrompt and prompts.verificationSystemPrompt can use enc:: values

Notes

Use a key scoped to utils:crypto when possible.
Automatic enc:: handling is field-scoped. It currently applies to documented VETTING prompt fields, not every model endpoint.
The dashboard encryption tool is a convenience UI over the same endpoints.

Open Encryption ToolUse the dashboard tool to encrypt or verify prompt values with a scoped API key.

curl https://api.viablelab.org/v1/utils/encrypt \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $VIABLE_API_KEY' \
  -d '{ "text": "sensitive prompt text" }'

Reference

Current API surface

Model and utility endpoints use bearer API keys. Create and manage keys in the dashboard; dashboard control-plane APIs are intentionally not part of this public reference.

GETPublic

/

Service status and documentation links.

GETPublic

/v1/models

Public model catalog with modes, providers, capabilities, and pricing notes.

GETPublic

/v1/docs/metadata

Compact machine-readable metadata for developer portals and agents.

POSTAPI key

/v1/chat/completions

OpenAI-compatible chat JSON with optional streaming and multimodal content arrays.

POSTAPI key

/v1/chat/vetting

Chat-completions style JSON plus optional vettingConfig for lightweight verified educational chat.

POSTAPI key

/v1/vetting/full

Structured VETTING JSON with mode, config, prompts, context, and messages.

POSTAPI key

/v1/embeddings

OpenAI-compatible embeddings JSON with model and input.

POSTAPI key

/v1/images/generations

OpenAI Images-compatible JSON with model, prompt, size, and n.

POSTAPI key

/v1/audio/speech

OpenAI Audio Speech-compatible JSON with model, input, voice, and response_format.

POSTAPI key

/v1/audio/transcriptions

Multipart form upload with model and file.

POSTAPI key

/v1/utils/encrypt

JSON utility request with text. Automatic enc:: handling is limited to documented VETTING fields.

POSTAPI key

/v1/utils/decrypt

JSON utility request with encryptedText for QA or recovery from trusted sessions.

Machine-readable

Use metadata for portals and agents

The metadata endpoint returns the model catalog, endpoint list, agent quickstarts, Playground-ready examples, and pricing notes in one compact JSON payload, ideal for keeping a portal or agent in sync without hardcoding.

curl https://api.viablelab.org/v1/docs/metadata

Full schema

OpenAPI is the source of truth for public API details

This guide highlights common workflows. The schema-backed reference covers public paths, parameters, responses, and components from the canonical JSON.

Open full reference Raw JSON