Stackmint API Reference (Draft v1)

Stackmint API Reference

Status: This is a draft API reference for Stackmint v1. Some endpoints are live, others are planned and will be rolled out progressively. Use this as the canonical spec when wiring clients, not as a legal guarantee of availability.

1. Overview

Stackmint provides a multi-level API designed around: Clients, Branches, Buds, Runs, and an MCP layer to expose Buds/Branches to LLMs. The API is multi-tenant, audit-first, and execution-focused.

  • Clients – tenant workspaces (per end-customer or environment)
  • Branches – composable workflows / agents
  • Buds – atomic units of logic, UI, or integration
  • Runs – executions of Buds or Branches
  • MCP Layer – Stackmint-native “tool” interface for LLMs

2. Base URL & Versioning

Base URL: https://api.stackmint.ai

Versioning: Prefix all routes with /v1

https://api.stackmint.ai/v1/clients/{clientId}/branches/{branchId}/run

3. Authentication

Stackmint uses Bearer tokens scoped to an org and, optionally, a client.

Authorization: Bearer YOUR_API_KEY
X-Stackmint-Org-Id: {orgId}

Additional scopes/roles: role=admin for admin endpoints, scope=mcp for MCP endpoints, scope=runtime for direct run endpoints.

Tokens are issued via the Stackmint admin console (not covered here).

4. Tenancy Model: /clients

A client represents an isolated runtime workspace – typically an end-customer or sub-tenant. All runtime-critical endpoints are namespaced under /clients/{clientId}. Admins can manage clients at org level.

4.1 List Clients (Admin)

Org admin only. Optional: limit, cursor.

GET /v1/clients

4.2 Get a Client (Admin)

Org admin or scoped client token.

GET /v1/clients/{clientId}

5. Branch API (Per Client)

Branches are full workflows/agents composed of Buds. Key endpoints:

List Branches

GET /v1/clients/{clientId}/branches

Run a Branch (sync/async)

POST /v1/clients/{clientId}/branches/{branchId}/run

Get Branch Run Status

GET /v1/clients/{clientId}/runs/{runId}

6. Bud API (Per Client)

Buds are atomic units of logic. Useful when exposing a single Bud, chaining your own logic, or debugging.

List Buds

GET /v1/clients/{clientId}/buds

Run a Bud (scope=bud.run)

POST /v1/clients/{clientId}/buds/{budId}/run

7. Admin API (Org / Platform Level)

Admin endpoints are used from the Stackmint console, internal tools, or secure services. role=admin required.

List Clients

GET /v1/clients

Assign Branch to Client

POST /v1/admin/clients/{clientId}/branches/{branchId}/assign

Configure Provider Tokens

POST /v1/admin/clients/{clientId}/providers/{providerId}/credentials

8. Stackmint MCP API (LLM Tooling Layer)

MCP exposes Buds and Branches as tools to LLMs in a normalized interface.

List Tools (scope=mcp)

GET /v1/clients/{clientId}/mcp/tools

Invoke Tool (scope=mcp.run)

POST /v1/clients/{clientId}/mcp/tools/{toolId}/invoke

9. Errors

Common error envelope and codes: unauthorized, forbidden, invalid_input, branch_not_found, bud_not_found, run_not_found, provider_not_configured, rate_limited, internal_error.

10. Rate Limiting

Rate limits applied per org, client, and API key. Headers may include X-RateLimit-Limit, Remaining, Reset.

For access or questions, email api@stackmint.ai.