> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Expose BindAI agents, workflows, projects, and background runs through the BindAI REST API.

# REST API

BindAI v0.1 includes a FastAPI-based REST API package for exposing configured BindAI applications over HTTP.

The API provides a lightweight service boundary around:

* Agents
* Workflows
* Projects
* Background automation runs

The API package is:

```text theme={null}
bindai-api
```

It exposes capabilities from an existing BindAI application rather than replacing the underlying Python framework.

***

# Installation

Install the API package from PyPI:

```bash theme={null}
pip install bindai-api
```

The API package depends on the BindAI framework and uses:

* FastAPI
* Pydantic
* Uvicorn
* BindAI

The package can be used independently of the repository's Docker configuration.

For local BindAI repository development, the package is part of the workspace and can be installed through the repository's normal `uv` workflow.

***

# API Application

The main FastAPI application is exposed as:

```python theme={null}
from bindai_api import app
```

Serve it with Uvicorn:

```bash theme={null}
uv run uvicorn bindai_api.app:app --host 0.0.0.0 --port 8000
```

For local development, the API is normally available at:

```text theme={null}
http://localhost:8000
```

FastAPI also provides its standard interactive API documentation through the running application.

The API application itself does not automatically discover and configure a BindAI application.

A host application can configure the application exposed by the API:

```python theme={null}
from bindai_api import configure_application

configure_application(application)
```

The configured application then provides the agents and runtime resources used by the API.

***

# API Version

The current REST API uses versioned resource paths:

```text theme={null}
/api/v1
```

Resource endpoints therefore follow the general structure:

```text theme={null}
/api/v1/<resource>
```

Versioned paths provide a stable boundary for future API versions.

The health endpoint is intentionally outside the versioned resource namespace:

```text theme={null}
/health
```

***

# Health Check

The API provides a public health endpoint:

```http theme={null}
GET /health
```

Example:

```bash theme={null}
curl http://localhost:8000/health
```

Example response:

```json theme={null}
{
  "status": "ok",
  "service": "bindai-api"
}
```

The health endpoint does not require authentication.

It can be used for:

* Local development
* Docker health checks
* Deployment infrastructure
* Basic service monitoring

The endpoint represents API application availability. It does not perform a complete health check of configured model providers, connections, or other external services.

***

# Authentication

Protected API endpoints require API-key authentication.

Configure the API key through the environment:

```text theme={null}
BINDAI_API_KEY=your-secret-key
```

Clients send the key using the HTTP `Authorization` header:

```http theme={null}
Authorization: Bearer your-secret-key
```

For example:

```bash theme={null}
curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/agents
```

The `/health` endpoint remains public.

The v0.1 authentication implementation intentionally uses a single environment-based API key.

It does not provide:

* User accounts
* OAuth
* Persistent API-key management
* Role-based access control
* Multi-tenant authorization

If `BINDAI_API_KEY` is configured, a missing or incorrect Bearer token results in `401 Unauthorized`.

If `BINDAI_API_KEY` itself is not configured, the current authentication dependency raises a server-side configuration error rather than performing normal API-key validation.

See the Authentication documentation for complete details.

***

# Agents

The Agents API provides agent discovery and execution.

Base path:

```text theme={null}
/api/v1/agents
```

The current agent endpoints are:

```text theme={null}
GET  /api/v1/agents
POST /api/v1/agents/{agent_name}/run
POST /api/v1/agents/{agent_name}/stream
```

All agent endpoints require API authentication.

***

# List Agents

Retrieve the agents available from the configured BindAI application:

```http theme={null}
GET /api/v1/agents
```

Example:

```bash theme={null}
curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/agents
```

The API resolves agents from the configured application.

The API does not create a separate agent registry independent of the BindAI application.

If no application has been configured, the API cannot serve application-backed resources normally.

***

# Run an Agent

Execute an agent synchronously:

```http theme={null}
POST /api/v1/agents/{agent_name}/run
```

The request body contains a message:

```json theme={null}
{
  "message": "Explain how BindAI works."
}
```

Example:

```bash theme={null}
curl \
  -X POST \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"message":"Explain how BindAI works."}' \
  http://localhost:8000/api/v1/agents/assistant/run
```

The response identifies the agent and contains its result.

Conceptually:

```json theme={null}
{
  "agent": "assistant",
  "response": "..."
}
```

The exact response value depends on the configured agent and its model provider.

***

# Agent Streaming

Agents can also be executed through the streaming endpoint:

```http theme={null}
POST /api/v1/agents/{agent_name}/stream
```

The request uses the same message structure:

```json theme={null}
{
  "message": "Write a short explanation of AI agents."
}
```

Example:

```bash theme={null}
curl \
  -X POST \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"message":"Write a short explanation of AI agents."}' \
  http://localhost:8000/api/v1/agents/assistant/stream
```

The endpoint returns a plain HTTP streaming response using FastAPI's `StreamingResponse`.

The v0.1 implementation is intentionally lightweight.

It is not a separate distributed streaming service and does not define persistent stream-management infrastructure.

For additional details, see the Streaming documentation.

***

# Agent Execution Flow

A typical request follows this flow:

```text theme={null}
HTTP Client
    |
    v
POST /api/v1/agents/{agent}/run
    |
    v
BindAI API
    |
    v
Configured Application
    |
    v
Agent
    |
    v
Model / Tools / Memory
    |
    v
Agent Result
    |
    v
HTTP Response
```

The REST API is therefore a transport boundary around the existing BindAI agent execution system.

***

# Workflows

The Workflows API provides workflow discovery and execution.

Base path:

```text theme={null}
/api/v1/workflows
```

The current workflow endpoints are:

```text theme={null}
GET  /api/v1/workflows
POST /api/v1/workflows/{workflow_id}/run
```

All workflow endpoints require API authentication.

***

# List Workflows

Retrieve the configured workflows:

```http theme={null}
GET /api/v1/workflows
```

Example:

```bash theme={null}
curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/workflows
```

The API obtains workflows from the configured BindAI workflow registry.

***

# Run a Workflow

Execute a workflow:

```http theme={null}
POST /api/v1/workflows/{workflow_id}/run
```

The request body contains workflow variables:

```json theme={null}
{
  "variables": {
    "customer": "Example",
    "priority": "high"
  }
}
```

Example:

```bash theme={null}
curl \
  -X POST \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"variables":{"customer":"Example","priority":"high"}}' \
  http://localhost:8000/api/v1/workflows/research/run
```

The variables are added to the workflow execution context before execution.

Conceptually:

```text theme={null}
HTTP Request
    |
    v
Workflow
    |
    v
ExecutionContext
    |
    v
Workflow Nodes
    |
    v
Workflow Result
```

***

# Workflow Execution

Workflow execution remains part of the BindAI runtime.

The API does not replace workflow orchestration.

A configured workflow can use the BindAI capabilities available to it, such as:

* Agents
* Tools
* Conditions
* Loops
* Parallel execution
* Retry policies
* Timeouts
* Human tasks
* Connections

The exact capabilities depend on the configured workflow.

***

# Projects

The Projects API exposes projects configured in the current API process.

Base path:

```text theme={null}
/api/v1/projects
```

The current project endpoints are:

```text theme={null}
GET /api/v1/projects
GET /api/v1/projects/{project_name}
```

All project endpoints require API authentication.

***

# List Projects

Retrieve configured projects:

```http theme={null}
GET /api/v1/projects
```

Example:

```bash theme={null}
curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/projects
```

The API returns projects configured in the current application process.

The v0.1 API does not provide a persistent project-management service.

***

# Get a Project

Retrieve a project by name:

```http theme={null}
GET /api/v1/projects/{project_name}
```

Example:

```bash theme={null}
curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/projects/my-project
```

If the requested project is not configured, the API returns a not-found response.

***

# Project Storage

The v0.1 Projects API uses an in-process project registry.

It does not provide a persistent project-management database.

Conceptually:

```text theme={null}
BindAI API Process
       |
       v
Configured Projects
       |
       +---- Project A
       +---- Project B
       +---- Project C
```

Projects therefore belong to the running API process.

Applications requiring persistent project management need an external persistence layer or a future BindAI project-management implementation.

***

# Background Runs

BindAI v0.1 exposes background automation runs through:

```text theme={null}
/api/v1/runs
```

The current endpoints are:

```text theme={null}
POST /api/v1/runs
GET  /api/v1/runs/{run_id}
```

A background run can be submitted and queried later using its run ID.

All run endpoints require API authentication.

***

# Submit a Background Run

Create a background automation run:

```http theme={null}
POST /api/v1/runs
```

The request identifies an automation definition:

```json theme={null}
{
  "automation_id": "daily-report",
  "input": {
    "customer": "Example"
  }
}
```

Example:

```bash theme={null}
curl \
  -X POST \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"automation_id":"daily-report","input":{"customer":"Example"}}' \
  http://localhost:8000/api/v1/runs
```

A successful submission returns a run representation with HTTP `202 Accepted`.

The request is accepted for background execution rather than waiting for the automation to complete.

***

# Get Run Status

Retrieve a background run:

```http theme={null}
GET /api/v1/runs/{run_id}
```

Example:

```bash theme={null}
curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/runs/run-id
```

A run contains information such as:

* Run ID
* Automation definition ID
* Definition version
* Status
* Input
* Output
* Error
* Creation time
* Start time
* Completion time

Conceptually:

```json theme={null}
{
  "id": "run-id",
  "definition_id": "daily-report",
  "definition_version": 1,
  "status": "completed",
  "input": {},
  "output": {},
  "error": null,
  "created_at": "2026-01-01T12:00:00+00:00",
  "started_at": "2026-01-01T12:00:01+00:00",
  "completed_at": "2026-01-01T12:00:05+00:00"
}
```

The exact values depend on the automation execution.

***

# Background Execution Model

The REST API delegates background automation execution to `AutomationWorker`.

For v0.1, the worker uses an in-process thread pool.

Conceptually:

```text theme={null}
API Request
    |
    v
Automation Definition
    |
    v
AutomationWorker
    |
    v
AutomationRun
```

The worker creates and persists an `AutomationRun` before submitting the execution to its thread pool.

The API can therefore return the run representation without waiting for the automation to finish.

The background execution model is intentionally lightweight for the initial public release.

It does not require an external message broker or distributed queue.

***

# Background Run Input

The background-run request supports an `input` value:

```json theme={null}
{
  "automation_id": "daily-report",
  "input": {
    "customer": "Example"
  }
}
```

The input is stored on the resulting `AutomationRun`.

The current `AutomationWorker` implementation does **not** automatically pass that input as an argument to `AutomationDefinition.run()`.

Therefore, applications should not assume that the `input` field is automatically delivered to the automation target.

How an automation consumes input depends on the automation definition and surrounding application design.

***

# Background Execution Limitations

Background execution in v0.1 is process-local.

The worker uses a Python `ThreadPoolExecutor` and maintains its state and run history in process-local stores by default.

This has important operational consequences.

For example:

```text theme={null}
Application Process
       |
       +---- API
       |
       +---- AutomationWorker
              |
              +---- Background Run
```

If the process stops, in-process work can be interrupted.

Running multiple API instances does not automatically create a coordinated distributed worker system:

```text theme={null}
Instance A
    |
    +---- Local worker

Instance B
    |
    +---- Local worker
```

These instances do not automatically coordinate their in-process execution state.

Durable queue-based execution and coordinated distributed workers are planned for later releases.

***

# API and Runtime Configuration

The API application must be configured with the BindAI application it is intended to expose.

The API package provides:

```python theme={null}
from bindai_api import configure_application
```

Configure the application:

```python theme={null}
configure_application(application)
```

The configured application provides the agents and runtime resources used by the API.

The REST API should therefore be considered an interface to an existing BindAI application rather than a separate agent runtime.

If an application has not been configured, application-backed routes cannot operate normally.

***

# Docker

The BindAI repository includes a Dockerfile for running the API.

Build the image from the repository root:

```bash theme={null}
docker build -t bindai-api .
```

Run the container:

```bash theme={null}
docker run --rm -p 8000:8000 \
  -e BINDAI_API_KEY=your-secret-key \
  bindai-api
```

The API is then available at:

```text theme={null}
http://localhost:8000
```

Additional provider credentials can be supplied through environment variables as required by the configured application.

***

# Docker Compose

The repository also includes Docker Compose configuration.

Start the API:

```bash theme={null}
docker compose up --build
```

Stop the services:

```bash theme={null}
docker compose down
```

The default API port is:

```text theme={null}
8000
```

A typical deployment looks like:

```text theme={null}
Client
   |
   v
Docker Compose
   |
   v
BindAI API
   |
   +---- Agents
   +---- Workflows
   +---- Projects
   +---- Automation
   |
   v
External Providers / Services
```

Docker Compose provides a convenient deployment foundation for local and small-scale environments.

It does not turn the v0.1 background worker into a distributed queue-based system.

***

# Environment Variables

The API authentication layer requires:

```text theme={null}
BINDAI_API_KEY
```

The configured BindAI application may also require provider-specific variables.

Examples include:

```text theme={null}
OPENAI_API_KEY
ANTHROPIC_API_KEY
GEMINI_API_KEY
GROQ_API_KEY
OPENROUTER_API_KEY
PINECONE_API_KEY
```

The exact variables depend on the application's providers, memory systems, knowledge systems, and connections.

Never commit secrets to source control.

***

# Error Responses

The API uses HTTP status codes to represent request outcomes.

Examples include:

```text theme={null}
200 OK
```

for successful requests,

```text theme={null}
202 Accepted
```

for successfully submitted background runs,

```text theme={null}
401 Unauthorized
```

for invalid or missing API authentication,

and:

```text theme={null}
404 Not Found
```

when a requested resource such as an agent, workflow, or project cannot be found.

Application and execution failures may produce additional HTTP error responses depending on where the failure occurs.

If the API itself is misconfigured, such as when `BINDAI_API_KEY` is missing, the current authentication dependency can raise a server-side configuration error.

***

# API Security

The v0.1 API provides a deliberately simple authentication mechanism.

When exposing the API outside a trusted local environment, deployment infrastructure should additionally consider:

* HTTPS
* Network access controls
* Reverse proxies
* Rate limiting
* Request limits
* Secret management
* Logging
* Monitoring
* Process isolation

The BindAI v0.1 API does not provide a complete user-management or authorization platform.

Applications requiring advanced identity and authorization can place those controls in front of the BindAI API.

***

# API and Observability

BindAI's event system can be used alongside the REST API.

The runtime can emit structured events for areas such as:

* Application lifecycle
* Agent execution
* Workflow execution
* Node execution
* Human tasks
* Model requests and responses
* Tool execution
* Memory operations
* MCP connection events

BindAI also provides an in-memory `EventRecorder`.

The recorder can be used for:

* Development
* Debugging
* Execution inspection
* Custom logging
* Application-level monitoring integrations

The current recorder is process-local and is not a persistent tracing backend.

The REST API itself does not provide a hosted observability dashboard.

***

# API Deployment Architecture

A simple BindAI API deployment can be represented as:

```text theme={null}
Client
   |
   | HTTPS
   v
Reverse Proxy / Load Balancer
   |
   v
BindAI API
   |
   +---- Agents
   |
   +---- Workflows
   |
   +---- Projects
   |
   +---- Background Runs
   |
   v
External Providers / Services
```

The BindAI API provides the application-level HTTP boundary.

The surrounding infrastructure remains responsible for concerns such as:

* TLS
* Networking
* Secrets
* Process management
* Persistent storage
* Monitoring
* Scaling
* Backups

***

# Scaling

The v0.1 API can be deployed behind standard HTTP infrastructure.

However, horizontal scaling requires careful consideration of application state.

For example:

```text theme={null}
Load Balancer
      |
      +---- API Instance A
      |
      +---- API Instance B
      |
      +---- API Instance C
```

API instances do not automatically share all in-process state.

This is particularly important for:

* Configured projects
* Background execution
* Runtime state
* In-memory observability
* Other process-local resources

Applications requiring coordinated distributed execution should introduce shared persistent infrastructure.

***

# Distributed Background Execution

Queue-based background execution is outside the initial v0.1 API scope.

A future architecture could look like:

```text theme={null}
Client
   |
   v
BindAI API
   |
   v
Persistent Queue
   |
   +---- Worker A
   +---- Worker B
   +---- Worker C
   |
   v
Persistent State
```

This would provide a stronger foundation for:

* Durable execution
* Multiple workers
* Work recovery
* Coordinated execution
* Horizontal scaling

The current v0.1 API does not require this architecture.

***

# Testing

The API package has its own test suite.

Run the API tests with:

```bash theme={null}
uv run pytest packages/bindai-api/tests -q
```

The complete BindAI test suite can also be run with:

```bash theme={null}
uv run pytest tests -q
```

The API tests cover the implemented API resources and authentication behavior.

***

# Local API Validation

A simple local validation sequence is:

Start the API:

```bash theme={null}
uv run uvicorn bindai_api.app:app --host 0.0.0.0 --port 8000
```

Check health:

```bash theme={null}
curl http://localhost:8000/health
```

Configure the API key in the API process environment:

```text theme={null}
BINDAI_API_KEY=your-secret-key
```

Then test a protected endpoint:

```bash theme={null}
curl \
  -H "Authorization: Bearer your-secret-key" \
  http://localhost:8000/api/v1/projects
```

This verifies API availability and authentication.

Application-backed endpoints additionally require a configured BindAI application.

***

# Current API Scope

BindAI v0.1 provides the following public REST API surface.

## Health

```text theme={null}
GET /health
```

## Agents

```text theme={null}
GET  /api/v1/agents
POST /api/v1/agents/{agent_name}/run
POST /api/v1/agents/{agent_name}/stream
```

## Workflows

```text theme={null}
GET  /api/v1/workflows
POST /api/v1/workflows/{workflow_id}/run
```

## Projects

```text theme={null}
GET /api/v1/projects
GET /api/v1/projects/{project_name}
```

## Background Runs

```text theme={null}
POST /api/v1/runs
GET  /api/v1/runs/{run_id}
```

These endpoints form the initial public REST API surface for BindAI v0.1.

***

# Current Limitations

The v0.1 API intentionally keeps the service layer lightweight.

The current API does not provide:

* Persistent project management
* Persistent API-key management
* User accounts
* OAuth authentication
* RBAC
* Multi-tenancy
* Distributed job queues
* Durable distributed workers
* Kubernetes-specific infrastructure
* Hosted monitoring dashboards
* Built-in billing

These capabilities can be introduced in later releases or provided by the surrounding deployment environment.

***

# API Design Principles

The v0.1 REST API follows several simple principles:

* Keep the API surface small.
* Use versioned resource paths.
* Reuse the existing BindAI runtime.
* Keep authentication explicit.
* Keep deployment infrastructure separate from application logic.
* Avoid introducing persistent infrastructure unless required.
* Make background execution available without requiring an external queue.
* Preserve the Python API as the underlying framework interface.

The REST API provides a practical HTTP boundary without turning the BindAI core into a service-only framework.

***

# Summary

The BindAI REST API provides an HTTP interface for running and inspecting configured BindAI applications.

The main resource areas are:

```text theme={null}
BindAI API
   |
   +---- Agents
   |
   +---- Workflows
   |
   +---- Projects
   |
   +---- Background Runs
```

The v0.1 API provides:

* Health checks
* API-key authentication
* Agent discovery
* Agent execution
* Agent streaming
* Workflow discovery
* Workflow execution
* Project access
* Background automation runs
* Background run status
* Docker deployment
* Docker Compose deployment

The API is intentionally lightweight.

It exposes capabilities already provided by the BindAI framework while leaving advanced identity, distributed execution, persistence, monitoring, and infrastructure concerns to future releases or the surrounding deployment environment.

For authentication details, see the Authentication documentation.

For streaming behavior, see the Streaming documentation.

For background execution, see the Background Runs documentation.