Minolith Agents API

The Agents service is a central registry of agent definitions — blueprints for how AI agents should behave. Each definition includes the agent's role, system prompt, tool permissions, context requirements, and input/output schemas. Definitions can be user-created, installed from Minolith's curated registry, or customised per project.

Base URL: https://api.minolith.io/v1/agents

Authentication: All endpoints require an API key via the Authorization header:

Authorization: Bearer mlth_your_api_key_here

Pricing: Creating an agent definition costs 3 credits ($0.03). All other operations (reads, updates, deletes, registry install, sync, bootstrap) are free.

Core Concepts

Agent Definition

A blueprint containing: name, role (one-line description), system prompt (full instructions), tool permissions, context requirements (queries to pre-load), and input/output schemas.

Main Thread Agent

One agent per project can be marked is_main: true. This is the orchestrator — its identity is returned by the bootstrap endpoint at session start. It defines who the AI agent is for every session.

Subagents

All other agent definitions (is_main: false). The orchestrator spawns subagents for specialised tasks like code review, testing, or documentation. Call get_agent to load a subagent's full definition with pre-resolved context.

Scope

• project — available only to the project where it was created
• global — available to all projects in the account (project_id is NULL)

Source

• user — created by the user
• registry — installed from Minolith's curated template library
• override — a customised copy of a registry or user agent

Limits

Endpoints

Create Agent Definition

POST /v1/agents/

Request:

{
  "name": "code-reviewer",
  "role": "Reviews code changes for correctness, style, and potential bugs.",
  "prompt": "You are a code reviewer. Check for correctness, pattern adherence, bug potential, security, and performance.",
  "tools_allowed": ["file_read", "bash:grep", "bash:git"],
  "tools_denied": ["file_write", "bash:rm"],
  "context_requirements": [
    {"type": ["rule", "pattern"], "tags": ["code-review"]},
    {"type": ["preference"], "scope": "code-style"}
  ],
  "input_schema": {
    "type": "object",
    "properties": {
      "files": {"type": "array", "items": {"type": "string"}}
    },
    "required": ["files"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "findings": {"type": "array"},
      "approved": {"type": "boolean"}
    }
  },
  "scope": "project",
  "is_main": false,
  "tags": ["review", "quality"]
}

Response (201):

{
  "data": {
    "id": "agt_d7c39cf9717c",
    "name": "code-reviewer",
    "role": "Reviews code changes for correctness, style, and potential bugs.",
    "prompt": "You are a code reviewer...",
    "tools_allowed": ["file_read", "bash:grep", "bash:git"],
    "tools_denied": ["file_write", "bash:rm"],
    "context_requirements": [...],
    "input_schema": {...},
    "output_schema": {...},
    "tags": ["review", "quality"],
    "is_main": false,
    "source": "user",
    "parent_id": null,
    "is_active": true,
    "scope": "project",
    "created_at": "2026-03-27 05:41:58",
    "updated_at": "2026-03-27 05:41:58"
  }
}

Credits: 3

List Agent Definitions

GET /v1/agents/

Query parameters:

• source — filter by source: user, registry, override
• is_active — filter by active status: 1 or 0
• is_main — filter by main thread: 1 or 0
• tags — comma-separated tag filter (matches ANY)
• limit — max results (default 20, max 100)
• cursor — pagination cursor

Response (200): Paginated array of agent definitions.

Get Agent Definition

GET /v1/agents/:id_or_name

Accepts either the UUID (e.g. agt_d7c39cf9717c) or the agent name (e.g. code-reviewer).

The response includes a context field containing pre-resolved context entries matching the agent's context_requirements. Use this when spawning a subagent — the context is already loaded.

Response (200):

{
  "data": {
    "id": "agt_d7c39cf9717c",
    "name": "code-reviewer",
    "role": "Reviews code changes for correctness, style, and potential bugs.",
    "prompt": "You are a code reviewer...",
    "tools_allowed": ["file_read", "bash:grep", "bash:git"],
    "tools_denied": ["file_write", "bash:rm"],
    "context_requirements": [
      {"type": ["rule", "pattern"], "tags": ["code-review"]}
    ],
    "context": [
      {
        "id": "ctx_abc123",
        "type": "rule",
        "title": "All CSS must be in external files",
        "body": "Never use inline styles...",
        "tags": ["css", "code-review"],
        "priority": "high"
      }
    ],
    "input_schema": {...},
    "output_schema": {...},
    "tags": ["review", "quality"],
    "is_main": false,
    "scope": "project"
  }
}

Update Agent Definition

PUT /v1/agents/:id_or_name

Partial update — only include fields you want to change.

Credits: Free

Delete Agent Definition

DELETE /v1/agents/:id_or_name

Response: 204 No Content

Registry

Browse and install Minolith's curated agent templates.

List Registry Templates

GET /v1/agents/registry

Query parameters:

• category — filter by category: development, content, operations

Get Registry Template

GET /v1/agents/registry/:name

Install Registry Template

POST /v1/agents/registry/:name/install

Creates a user-owned copy in your account. The copy can be fully customised. The original template is never modified.

Request (optional):

{
  "scope": "global",
  "is_main": true
}

Credits: Free

Sync

POST /v1/agents/sync

Returns all active agent definitions for the current project with pre-resolved context. Each agent's context_requirements queries are executed and the results are included in a context field on each agent. Use to write agent configurations to your project.

Request (optional):

{
  "format": "json"
}

Response (200, format: json):

{
  "data": {
    "main": {
      "name": "orchestrator",
      "role": "Senior developer and project orchestrator.",
      "prompt": "You are the lead developer...",
      "tools_allowed": ["file_read", "file_write", "bash", "mcp:minolith"],
      "context_requirements": [{"priority": "high"}],
      "context": [
        {
          "id": "ctx_abc123",
          "type": "rule",
          "title": "All CSS must be in external files",
          "body": "Never use inline styles...",
          "tags": ["css"],
          "priority": "high"
        }
      ],
      "scope": "project"
    },
    "subagents": [
      {
        "name": "code-reviewer",
        "role": "Reviews code for correctness.",
        "prompt": "You are a code reviewer...",
        "context": [...],
        "scope": "project"
      }
    ]
  }
}

MCP Tools

All agent tools are available via the MCP server at https://mcp.minolith.io.

Validation Rules

Errors

All errors include a docs URL pointing to this documentation.