openapi: 3.1.0
info:
  title: Stackmint Platform API
  version: "1.0.0"
  description: |
    Stackmint is a governed execution platform for enterprise AI workflows.
    REST API for managing clients, branches (workflows), buds (atomic units),
    runs, and MCP-compatible LLM tools.
  contact:
    name: Stackmint
    url: https://stackmint.ai
servers:
  - url: https://api.stackmint.ai/v1
    description: Stackmint Platform API
security:
  - BearerAuth: []
    OrgId: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: "Authorization: Bearer YOUR_API_KEY"
    OrgId:
      type: apiKey
      in: header
      name: X-Stackmint-Org-Id
      description: Stackmint organization identifier.
paths:
  /clients:
    get:
      summary: List clients
      description: Admin-only. Returns all clients in the organization.
      responses:
        "200":
          description: List of clients
  /clients/{clientId}:
    parameters:
      - in: path
        name: clientId
        required: true
        schema: { type: string }
    get:
      summary: Retrieve a client
      responses:
        "200":
          description: Client object
  /clients/{clientId}/branches:
    parameters:
      - in: path
        name: clientId
        required: true
        schema: { type: string }
    get:
      summary: List branches (workflows) for a client
      responses:
        "200":
          description: List of branches
  /clients/{clientId}/branches/{branchId}/run:
    parameters:
      - in: path
        name: clientId
        required: true
        schema: { type: string }
      - in: path
        name: branchId
        required: true
        schema: { type: string }
    post:
      summary: Execute a branch (synchronous or asynchronous)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  type: object
                async:
                  type: boolean
      responses:
        "200":
          description: Branch run result or run handle
  /clients/{clientId}/runs/{runId}:
    parameters:
      - in: path
        name: clientId
        required: true
        schema: { type: string }
      - in: path
        name: runId
        required: true
        schema: { type: string }
    get:
      summary: Check the status of a branch run
      responses:
        "200":
          description: Run status object
  /clients/{clientId}/buds:
    parameters:
      - in: path
        name: clientId
        required: true
        schema: { type: string }
    get:
      summary: List atomic units (buds) for a client
      responses:
        "200":
          description: List of buds
  /clients/{clientId}/buds/{budId}/run:
    parameters:
      - in: path
        name: clientId
        required: true
        schema: { type: string }
      - in: path
        name: budId
        required: true
        schema: { type: string }
    post:
      summary: Execute an individual bud
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  type: object
      responses:
        "200":
          description: Bud run result
  /clients/{clientId}/mcp/tools:
    parameters:
      - in: path
        name: clientId
        required: true
        schema: { type: string }
    get:
      summary: List MCP-compatible LLM tools available to the client
      responses:
        "200":
          description: List of tools
  /clients/{clientId}/mcp/tools/{toolId}/invoke:
    parameters:
      - in: path
        name: clientId
        required: true
        schema: { type: string }
      - in: path
        name: toolId
        required: true
        schema: { type: string }
    post:
      summary: Invoke an MCP-compatible LLM tool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                arguments:
                  type: object
      responses:
        "200":
          description: Tool invocation result
  /admin/clients/{clientId}/branches/{branchId}/assign:
    parameters:
      - in: path
        name: clientId
        required: true
        schema: { type: string }
      - in: path
        name: branchId
        required: true
        schema: { type: string }
    post:
      summary: Admin — assign a branch to a client
      responses:
        "200":
          description: Branch assigned
  /admin/clients/{clientId}/providers/{providerId}/credentials:
    parameters:
      - in: path
        name: clientId
        required: true
        schema: { type: string }
      - in: path
        name: providerId
        required: true
        schema: { type: string }
    post:
      summary: Admin — configure provider tokens for a client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
      responses:
        "200":
          description: Credentials stored