Local Brains API

Overview

The Local Brains API exposes the Allternit local brain surface. It lets clients perform keyword search across memory documents, events, and conversations; probe Ollama and embedding service health; pull local models; and manage models through the Gizzi sidecar. When no embedding service is available, search falls back to keyword search against the local SQLite memory tables.

Base URL

https://api.allternit.com/api

Authentication

All endpoints require a valid bearer token in the Authorization header. See Authentication for details.

Endpoints

Method	Path	Description
`GET`	`/api/local-brain`	Probe local brain status or search memory.
`POST`	`/api/local-brain`	Pull the default local brain model (SSE).
`GET`	`/api/local-brain/status`	Get Ollama and embedding service health.
`POST`	`/api/local-brain/pull-custom`	Pull an arbitrary Hugging Face GGUF model (SSE).
`GET`	`/api/local-brain/models`	List sidecar models.
`GET`	`/api/local-brain/models/search`	Search sidecar models.
`POST`	`/api/local-brain/models`	Install a sidecar model (SSE).
`DELETE`	`/api/local-brain/models/:tag`	Remove a sidecar model.

Probe local brain status

GET /api/local-brain

When called without a q parameter, returns the status of the local Ollama instance and the models that are already pulled.

Example response

{
  "ollamaRunning": true,
  "modelReady": true,
  "modelId": "llama3.2:3b",
  "pulledModels": ["llama3.2:3b", "nomic-embed-text:latest"]
}

Search local memory

GET /api/local-brain?q=:query&limit=:limit&type=:type

Searches memory documents, events, and conversations using keyword search. The type filter accepts documents, events, conversations, or all (default).

Query parameters

Parameter	Type	Description
`q`	string	Search query.
`limit`	integer	Maximum results (default `10`).
`type`	string	Result type filter (default `all`).

Example request

curl -G https://api.allternit.com/api/local-brain \
  -H "Authorization: Bearer $TOKEN" \
  -d "q=auth refactor" \
  -d "limit=5" \
  -d "type=documents"

Example response

{
  "query": "auth refactor",
  "results": [
    {
      "id": "doc_1a2b3c",
      "type": "document",
      "title": "Auth service refactor plan",
      "snippet": "Move password validation into a dedicated module...",
      "score": 0.85,
      "source_url": null,
      "created_at": "2026-08-13T10:00:00Z"
    }
  ],
  "count": 1,
  "note": "Keyword search (semantic search unavailable — no embedding service configured)"
}

Pull the default local brain

POST /api/local-brain

Streams an Ollama pull for the default local brain model (llama3.2:3b) over SSE.

Example curl

curl -N -X POST https://api.allternit.com/api/local-brain \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream"

Example event

data: {"status":"pulling manifest","completed":null,"total":null}

Get brain status

GET /api/local-brain/status

Returns the availability of Ollama and the embedding service, plus capability flags.

Example response

{
  "status": "healthy",
  "services": {
    "ollama": { "url": "http://127.0.0.1:11434", "available": true },
    "embedding": { "url": "http://127.0.0.1:8000", "available": true }
  },
  "capabilities": {
    "keyword_search": true,
    "semantic_search": true,
    "vector_store": true
  },
  "note": "Semantic search available"
}

Pull a custom model

POST /api/local-brain/pull-custom

Pulls an arbitrary Hugging Face GGUF model through Ollama. The response is an SSE stream of pull progress events.

Request body

Field	Type	Required	Description
`repo`	string	Yes	Hugging Face repo id, e.g. `bartowski/Llama-3.2-3B-Instruct-GGUF`.
`quant`	string	No	Quantization tag, e.g. `Q4_K_M`.

Example request

curl -N -X POST https://api.allternit.com/api/local-brain/pull-custom \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"repo": "bartowski/Llama-3.2-3B-Instruct-GGUF", "quant": "Q4_K_M"}'

Sidecar model management

The /api/local-brain/models endpoints proxy to the Gizzi sidecar model surface.

List sidecar models

GET /api/local-brain/models

Returns the sidecar model list. Response shape matches the Gizzi sidecar contract.

Search sidecar models

GET /api/local-brain/models/search?q=:query&limit=:limit

Install a sidecar model

POST /api/local-brain/models

Request body

Field	Type	Required	Description
`repo_id`	string	Yes	Model repo id.
`quant_tag`	string	No	Quantization tag.

The response is an SSE stream of installation progress events.

Remove a sidecar model

DELETE /api/local-brain/models/:tag

Error codes

Status	Meaning	Typical cause
`200 OK`	Success	Request succeeded.
`201 Created`	Created	Model installation started.
`400 Bad Request`	Invalid request	Invalid `repo` id.
`401 Unauthorized`	Unauthorized	Missing or invalid bearer token.
`502 Bad Gateway`	Upstream error	Gizzi sidecar or Ollama returned an error.
`503 Service Unavailable`	Unavailable	Ollama or sidecar is not running.
`500 Internal Server Error`	Server error	Contact support.

Overview

LLM Gateway

Agents & Runtime

Work Queue & Deployments

Files, Webhooks & Sandbox

Tools & Connectors

Collaboration & Workflows

Infrastructure & Platform

Canvases

Onboarding

A Labs

Playground

Users & Profiles

Overview

Base URL

Authentication

Endpoints

Probe local brain status

Example response

Search local memory

Query parameters

Example request

Example response

Pull the default local brain

Example curl

Example event

Get brain status

Example response

Pull a custom model

Request body

Example request

Sidecar model management

List sidecar models

Search sidecar models

Install a sidecar model

Request body

Remove a sidecar model

Error codes

​Overview

​Base URL

​Authentication

​Endpoints

​Probe local brain status

​Example response

​Search local memory

​Query parameters

​Example request

​Example response

​Pull the default local brain

​Example curl

​Example event

​Get brain status

​Example response

​Pull a custom model

​Request body

​Example request

​Sidecar model management

​List sidecar models

​Search sidecar models

​Install a sidecar model

​Request body

​Remove a sidecar model

​Error codes

​Related pages

Overview

Base URL

Authentication

Endpoints

Probe local brain status

Example response

Search local memory

Query parameters

Example request

Example response

Pull the default local brain

Example curl

Example event

Get brain status

Example response

Pull a custom model

Request body

Example request

Sidecar model management

List sidecar models

Search sidecar models

Install a sidecar model

Request body

Remove a sidecar model

Error codes

Related pages