Minolith Bootstrap API

The Bootstrap endpoint provides single-call session initialisation. One request returns everything an AI agent needs to start working: its identity, curated instructions, pre-loaded context, available subagents, active project state, and follow-up suggestions.

Endpoint: GET https://api.minolith.io/v1/bootstrap

MCP Tool: bootstrap (no parameters required)

Authentication: API key via Authorization: Bearer mlth_your_api_key_here

Pricing: Free. Bootstrap should be called at the start of every session without cost concern.

Why Bootstrap?

Without bootstrap, an agent must manually:

Query for its role definition
Load high-priority context entries
Check for active runbook runs
Check for open feedback items
Load recent events
Discover available subagents

Bootstrap replaces all of this with a single call. The agent receives everything it needs immediately and can start working.

Response Structure

{
  "data": {
    "agent": { ... },
    "prompt": [ ... ],
    "context": [ ... ],
    "subagents": [ ... ],
    "active_state": { ... },
    "styleguide": { ... },
    "changes_since_last_session": { ... },
    "follow_up": [ ... ]
  }
}

Fields

Field	Source	Purpose
`agent`	Agent definition where `is_main: true`	The main thread's identity, role, prompt, and tool permissions. `null` if no main agent is defined.
`prompt`	Context entries tagged `bootstrap`	Curated instructions injected into every session. Behavioural directives the user wants the agent to follow.
`context`	Context entries with `priority: high`	Pre-loaded high-priority rules, warnings, and decisions.
`subagents`	Agent definitions where `is_main: false`	Available subagents with name, role, and scope. Use `get_agent` to load the full definition when spawning.
`active_state`	Runbooks, Feedback, Events, Tasks	What's currently in flight: active runbook runs, open feedback counts, recent events, assigned tasks, and team feed.
`styleguide`	Styleguide service	Lightweight summary of the project's design system. `null` if no styleguide data exists. See below.
`changes_since_last_session`	Context entries + session tracking	What changed in the knowledge base since your last bootstrap call. See below.
`follow_up`	Computed from project state	Suggested additional queries with reasons. Not mandatory but recommended.

active_state.open_feedback

Field	Description
`total`	Total feedback items in the project
`high_priority`	Open items with high or critical priority
`new_since_last_session`	Items created since the last bootstrap call for this API key

active_state.assigned_tasks

Returned when an agent identity is resolved (via X-Minolith-Agent header or main agent). Shows the calling agent's assigned tasks grouped by workflow status.

Field	Description
`tasks`	Object with workflow statuses as keys, arrays of `{id, title, priority}` as values
`total`	Total number of assigned tasks across all statuses

Returns null if no agent identity could be resolved.

active_state.recent_feed

The last 5 entries from the project's team feed. Shows recent task activity — status changes, notes, assignments — so the agent has situational awareness of what the team has been doing.

Each entry: {author_name, note_type, task_title, body, created_at}

changes_since_last_session

Shows what changed in the knowledge base between sessions. Helps agents understand if new rules, warnings, or decisions were added while they were offline.

Field	Description
`new_entries`	Context entries created since the last bootstrap call (excludes events)
`updated_entries`	Context entries updated since the last bootstrap call that were not newly created (excludes events)
`new_high_priority`	Array of `{id, title}` for new high-priority entries since last bootstrap (max 5)
`last_session_at`	Timestamp of the previous bootstrap call, or `null` if this is the first session

On the first bootstrap call (no prior session), all counts are 0 and last_session_at is null. Deletions are not tracked — if an entry was deleted between sessions, it will not appear in these counts.

styleguide

A lightweight summary of the project's design system. Returns null if no styleguide data exists. This is not the full styleguide — use get_styleguide or the /v1/styleguide/full endpoint for the complete data. The summary tells the agent what exists and provides asset usage rules immediately.

Field	Description
`tokens`	Array of `{section, updated_at}` — which token sections are defined and when they were last updated
`components`	Array of `{name, description}` — component names and descriptions
`patterns`	Array of `{name, description}` — pattern names and descriptions
`voice`	Array of `{name, description}` — voice rule set names and descriptions
`assets`	Array of `{name, download_url, usage_rules, usage_context, tags}` — asset names with download URLs and usage rules so the agent knows the constraints before placing any asset

The agent should use this summary to:

Know which token sections exist before querying get_tokens
Know which components/patterns/voice entries are available before querying for details
Have asset usage rules immediately — no extra call needed to know "only use the dark logo on dark backgrounds"

follow_up entries

Each entry suggests a tool call the agent should make for complete context:

{
  "tool": "list_feedback",
  "args": {"status": "new,acknowledged", "priority": "high,critical"},
  "reason": "3 high-priority feedback items are open."
}

What Bootstrap Does NOT Return

Full subagent prompts (use get_agent when spawning)
Full feedback item details (use list_feedback if follow_up suggests it)
Complete context dump (only high-priority entries — use get_context for targeted queries)
Changelog data (rarely needed at session start)
Full styleguide token/component/pattern/voice data (use get_styleguide or get_tokens/get_component for the full definitions — bootstrap returns only names and metadata)

Bootstrap is opinionated: it returns what you need immediately and points you at what to load on demand.

Bootstrap Prompt Entries

Tag any Context entry with bootstrap to include it in the prompt field of every bootstrap response. This is how you shape agent behaviour persistently:

A rule tagged bootstrap: "Always check for active runbook runs before starting new work."
A workflow tagged bootstrap: "1. Review open feedback 2. Check failed checks 3. Resume paused runs 4. Ask what to work on."
A persona tagged bootstrap: "Communicate concisely. Push back on pattern violations."

Bootstrap entries retain their original type (rule, workflow, persona, etc.) — the bootstrap tag marks them for injection, it doesn't change what they are.

Managing Bootstrap Entries

There are three ways to manage bootstrap entries:

1. Via the Context API or MCP tools:

// Create a new entry with the bootstrap tag
{
  "type": "workflow",
  "title": "Session start workflow",
  "body": "1. Review open feedback\n2. Check for paused runs\n3. Ask what to work on",
  "tags": ["bootstrap"],
  "priority": "high"
}

2. Via the Dashboard: Navigate to Project > Agents > Bootstrap Settings to:

View all entries currently tagged bootstrap
Add the bootstrap tag to any existing context entry
Create new entries pre-tagged with bootstrap
Remove the bootstrap tag from entries (the entry itself is not deleted)

3. Via the Context API (tagging existing entries): Update an existing entry's tags to include bootstrap:

PUT /v1/context/entries/:id
{
  "tags": ["existing-tag", "bootstrap"]
}

Session Tracking

Bootstrap tracks the timestamp of each call per project + API key. This powers the new_since_last_session count in active_state.open_feedback and the changes_since_last_session object. The first call in a new session will show all feedback as "new" and report zero knowledge base changes. Subsequent calls will only count items created or updated after the previous bootstrap.

Integration Guide

Session Start (recommended workflow)

1. Call bootstrap
2. If agent is defined → adopt the identity (role + prompt)
3. If prompt entries exist → follow the behavioural directives
4. If active_state shows paused runs → present to the developer
5. If follow_up entries exist → execute the suggested queries
6. Ask the developer what they want to work on

Spawning a Subagent

1. Bootstrap told you which subagents are available (names + roles)
2. Decide which subagent to spawn based on the task
3. Call get_agent with the subagent's name
4. Pass the returned definition (role + prompt + context) to the subagent
5. The subagent starts with the right knowledge pre-loaded

Example Response

{
  "data": {
    "agent": {
      "name": "orchestrator",
      "role": "Senior developer and project orchestrator.",
      "prompt": "You are the lead developer on this project...",
      "tools_allowed": ["file_read", "file_write", "bash", "mcp:minolith"],
      "tools_denied": null,
      "tags": ["orchestrator"]
    },
    "prompt": [
      {
        "id": "ctx_abc123",
        "type": "workflow",
        "title": "Session start workflow",
        "body": "1. Review open feedback\n2. Check for paused runs\n3. Ask what to work on",
        "priority": "high"
      }
    ],
    "context": [
      {
        "id": "ctx_def456",
        "type": "rule",
        "title": "All CSS must be in external files",
        "body": "Never use inline styles...",
        "priority": "high"
      }
    ],
    "subagents": [
      {"name": "code-reviewer", "role": "Reviews code for correctness.", "scope": "project"},
      {"name": "test-writer", "role": "Writes tests for new code.", "scope": "global"}
    ],
    "active_state": {
      "runbook_runs": [],
      "open_feedback": {"total": 12, "high_priority": 3, "new_since_last_session": 5},
      "recent_events": [
        {"id": "ctx_evt001", "title": "Deployed v2.4.1", "created_at": "2026-03-27 09:30:00"}
      ]
    },
    "styleguide": {
      "tokens": [
        {"section": "colours", "updated_at": "2026-03-28 14:00:00"},
        {"section": "typography", "updated_at": "2026-03-28 14:05:00"},
        {"section": "spacing", "updated_at": "2026-03-28 14:10:00"}
      ],
      "components": [
        {"name": "button", "description": "Interactive button element for user actions."},
        {"name": "card", "description": "Contained surface for grouping related content."},
        {"name": "input", "description": "Text input field with label and validation states."}
      ],
      "patterns": [
        {"name": "page-layout", "description": "Standard page layout with sidebar and content area."}
      ],
      "voice": [
        {"name": "error-messages", "description": "How error messages should be written across the application."}
      ],
      "assets": [
        {
          "name": "dark-logo",
          "download_url": "https://api.minolith.io/v1/styleguide/assets/dark-logo/download?p=prj_xxx&expires=1743700800&sig=abc123...",
          "usage_rules": "Only place on backgrounds darker than #333. Minimum size 200x60px.",
          "usage_context": "Navigation header, footer",
          "tags": ["logo", "branding", "dark-theme"]
        }
      ]
    },
    "changes_since_last_session": {
      "new_entries": 3,
      "updated_entries": 2,
      "new_high_priority": [
        {"id": "ctx_abc789", "title": "New deployment rule for staging"},
        {"id": "ctx_def012", "title": "Redis connection pooling warning"}
      ],
      "last_session_at": "2026-03-27 06:02:09"
    },
    "follow_up": [
      {
        "tool": "list_feedback",
        "args": {"status": "new,acknowledged", "priority": "high,critical"},
        "reason": "3 high-priority feedback items are open."
      }
    ]
  }
}