Barndoor Platform API

openapi: 3.1.0
info:
  title: Barndoor Platform API
  version: 1.0.0
  description: 'REST API for the Barndoor Platform - manage MCP servers, OAuth connections, and proxy MCP requests.


    ## Authentication


    All endpoints require a JWT Bearer token obtained through Auth0 OAuth 2.0 flow with PKCE.

    The SDK handles the OAuth flow automatically using interactive login.


    ## MCP Integration


    The `/mcp/{mcp_server_name}` endpoints provide streaming proxy access to third-party MCP servers

    (Salesforce, Notion, Slack, etc.) with automatic authentication and session management.

    '
  contact:
    name: Barndoor Support
    url: https://barndoor.ai
servers:
- url: https://{organization_id}.platform.barndoor.ai
  description: Trial (Production)
  variables:
    organization_id:
      description: Your organization identifier
      default: your-org
- url: https://{organization_id}.mcp.barndoor.ai
  description: Enterprise (Production)
  variables:
    organization_id:
      description: Your organization identifier
      default: your-org
- url: https://{organization_id}.platform.barndooruat.com
  description: Enterprise (Production)
  variables:
    organization_id:
      description: Your organization identifier
      default: your-org
- url: https://{organization_id}.platform.barndoordev.com
  description: Enterprise (Production)
  variables:
    organization_id:
      description: Your organization identifier
      default: your-org
security:
- BearerAuth: []
tags:
- name: Servers
  description: Manage MCP server instances
- name: Connections
  description: Manage OAuth connections to MCP servers
- name: Policies
  description: Manage access control policies for agents and servers
- name: Agents
  description: Manage AI agent registrations
- name: MCP Proxy
  description: Proxy requests to MCP servers
paths:
  /api/agents/counts:
    get:
      tags:
      - Agents
      summary: Get Agent Counts
      description: Get counts of agents grouped by type (internal vs external).
      operationId: getAgentCounts
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCounts'
  /api/agents/{agent_id}:
    delete:
      tags:
      - Agents
      summary: Unregister Agent
      description: "Unregister an agent from Barndoor.\n\nThis removes the agent's registration but does not delete the underlying\
        \ \napplication directory. The agent can be re-registered using the same \napplication_directory_id.\n"
      operationId: unregisterAgent
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Agents
      summary: Get Agent
      description: Get details of a specific agent by ID, including its application directory configuration.
      operationId: getAgent
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Agent Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/agents:
    get:
      tags:
      - Agents
      summary: List Agents
      description: List registered agents with pagination.
      operationId: listAgents
      parameters:
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search applications by name or description
          title: Search
        description: Search applications by name or description
      - name: agent_type
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/AgentType'
          - type: 'null'
          description: Filter by agent type
          title: Agent Type
        description: Filter by agent type
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Number of items per page (max 100)
          default: 10
          title: Limit
        description: Number of items per page (max 100)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginationResponse_AgentResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Agents
      summary: Register Agent
      description: 'Register a new agent with Barndoor.


        Agents represent AI applications that can access MCP servers through Barndoor.

        Each agent must be associated with an application directory (OAuth client configuration).

        '
      operationId: registerAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentPayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/servers/{server_id}/connection:
    delete:
      tags:
      - Connections
      summary: Delete Connection
      description: 'Delete the current user''s connection to this server.


        This will remove the connection record and clean up any stored OAuth credentials.

        The user will need to reconnect to use this server again.

        '
      operationId: deleteConnection
      parameters:
      - name: server_id
        in: path
        required: true
        description: Server UUID
        schema:
          type: string
          format: uuid
        example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '204':
          description: Connection deleted successfully
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Connection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      tags:
      - Connections
      summary: Get Connection Status
      description: 'Get the user''s connection status for a specific server.

        Used to poll connection status during OAuth flows.

        '
      operationId: getConnectionStatus
      parameters:
      - name: server_id
        in: path
        required: true
        description: Server UUID
        schema:
          type: string
          format: uuid
        example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Connection status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionStatusResponse'
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/servers/{server_id}/connect:
    post:
      tags:
      - Connections
      summary: Initiate OAuth Connection
      description: 'Initiate OAuth connection flow for a server. Returns an authorization URL

        that the user should visit to complete the OAuth flow.


        The server must have OAuth configuration set up by an admin.

        '
      operationId: initiateConnection
      parameters:
      - name: server_id
        in: path
        required: true
        description: Server UUID
        schema:
          type: string
          format: uuid
        example: 123e4567-e89b-12d3-a456-426614174000
      - name: return_url
        in: query
        required: false
        description: Optional return URL after OAuth completion
        schema:
          type: string
          format: uri
        example: https://myapp.com/oauth/callback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
              example: {}
      responses:
        '200':
          description: Connection initiation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionInitiationResponse'
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server missing OAuth configuration or other error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: OAuthConfigurationError
                message: Server is missing OAuth configuration. Ask an admin to configure credentials before initiating a
                  connection.
  /mcp/{mcp_server_name}:
    get:
      tags:
      - MCP Proxy
      summary: MCP Server Proxy Endpoint
      description: 'Proxies MCP JSON-RPC requests to third-party servers with automatic authentication.


        This endpoint supports both regular HTTP requests and Server-Sent Events (SSE) streaming

        for real-time MCP protocol communication.


        ## Usage


        - **JSON-RPC**: Send MCP protocol requests as JSON

        - **SSE Streaming**: Use `Accept: text/event-stream` for real-time communication

        - **Session Management**: Include `x-mcp-session-id` header for session tracking


        ## Authentication Flow


        1. User must first connect to the server via `/api/servers/{server_id}/connect`

        2. Complete OAuth flow for the third-party service

        3. Use this endpoint to proxy MCP requests with automatic credential injection

        '
      operationId: proxyMcpRequest
      parameters:
      - name: mcp_server_name
        in: path
        required: true
        description: MCP server name identifier
        schema:
          type: string
          pattern: ^[a-z0-9-]+$
        example: salesforce
      - name: x-mcp-session-id
        in: header
        required: false
        description: MCP session identifier for request tracking
        schema:
          type: string
        example: sess_1234567890abcdef
      requestBody:
        required: false
        description: MCP JSON-RPC request payload
        content:
          application/json:
            schema:
              type: object
              description: MCP JSON-RPC 2.0 request
              properties:
                jsonrpc:
                  type: string
                  enum:
                  - '2.0'
                  description: JSON-RPC version
                method:
                  type: string
                  description: MCP method name
                  example: tools/list
                params:
                  type: object
                  description: Method parameters
                  additionalProperties: true
                id:
                  oneOf:
                  - type: string
                  - type: number
                  description: Request identifier
              required:
              - jsonrpc
              - method
              example:
                jsonrpc: '2.0'
                method: tools/list
                params: {}
                id: 1
      responses:
        '200':
          description: MCP response or SSE stream
          content:
            application/json:
              schema:
                type: object
                description: MCP JSON-RPC 2.0 response
                properties:
                  jsonrpc:
                    type: string
                    enum:
                    - '2.0'
                  result:
                    type: object
                    description: Method result
                    additionalProperties: true
                  error:
                    type: object
                    description: Error object if method failed
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
                      data:
                        type: object
                        additionalProperties: true
                  id:
                    oneOf:
                    - type: string
                    - type: number
                    description: Request identifier
                required:
                - jsonrpc
                - id
                example:
                  jsonrpc: '2.0'
                  result:
                    tools:
                    - name: get_accounts
                      description: Get Salesforce accounts
                      parameters:
                        type: object
                        properties:
                          limit:
                            type: integer
                            description: Maximum number of accounts
                  id: 1
            text/event-stream:
              schema:
                type: string
                description: 'Server-Sent Events stream for real-time MCP communication.


                  Each event contains a JSON-RPC message with event metadata.


                  Example events:

                  ```

                  data: {"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}


                  data: {"jsonrpc": "2.0", "result": {"tools": [...]}, "id": 1}

                  ```

                  '
              example: 'data: {"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}


                data: {"jsonrpc": "2.0", "result": {"tools": []}, "id": 1}

                '
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - server not connected or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: ServerNotConnected
                message: Server 'salesforce' is not connected. Please initiate connection first.
        '404':
          description: Server not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Bad Gateway - upstream server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: UpstreamError
                message: Failed to connect to Salesforce API
  /api/v2/policies/{policy_id}/clone:
    post:
      summary: Clone Policy
      description: 'Clone an existing policy, creating a new policy with the same configuration

        but with a modified name (appending " Copy") and DRAFT status.'
      operationId: clone_policy_admin_v2_policies__policy_id__clone_post
      parameters:
      - name: policy_id
        in: path
        required: true
        schema:
          type: string
          title: Policy Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/policy:
    post:
      summary: Publish  Policy
      operationId: publish_cerbos_policy_admin_policy_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/policies/restrictions/disable/{restriction_name}:
    put:
      summary: Disable Restriction
      operationId: disable_restriction_admin_policies_restrictions_disable__restriction_name__put
      parameters:
      - name: restriction_name
        in: path
        required: true
        schema:
          type: string
          title: Restriction Name
      - name: id
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/policies/restrictions/enable/{restriction_name}:
    put:
      summary: Enable Restriction
      operationId: enable_restriction_admin_policies_restrictions_enable__restriction_name__put
      parameters:
      - name: restriction_name
        in: path
        required: true
        schema:
          type: string
          title: Restriction Name
      - name: id
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          title: Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v2/policies/filter-definitions:
    get:
      summary: Get Filter Definitions
      description: 'Return filter categories for the policies list UI.


        Static filter options for status, plus dynamic filters for

        MCP servers and agents based on the organization''s registry.'
      operationId: get_filter_definitions_admin_v2_policies_filter_definitions_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/FilterCategory'
                type: array
                title: Response Get Filter Definitions Admin V2 Policies Filter Definitions Get
      security:
      - HTTPBearer: []
  /api/v2/policies/summary:
    get:
      summary: Get Policies Summary
      description: Return summary counts of policies by status.
      operationId: get_policies_summary_admin_v2_policies_summary_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicySummaryResponse'
      security:
      - HTTPBearer: []
  /api/v2/policies/{policy_id}:
    get:
      summary: Get Policy
      operationId: get_policy_admin_v2_policies__policy_id__get
      parameters:
      - name: policy_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
    patch:
      summary: Update Policy
      operationId: update_policy_admin_v2_policies__policy_id__patch
      parameters:
      - name: policy_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePolicy'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v2/policies:
    get:
      summary: List Policies
      operationId: list_policies_admin_v2_policies_get
      parameters:
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search by policy ID, name, description, or support contact
          title: Search
        description: Search by policy ID, name, description, or support contact
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Filter by status values
          title: Status
        description: Filter by status values
      - name: mcp_server_id
        in: query
        required: false
        schema:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Filter by MCP server IDs
          title: Mcp Server Id
        description: Filter by MCP server IDs
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          description: Filter by agent/application IDs
          title: Agent Id
        description: Filter by agent/application IDs
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Number of items per page (max 100)
          default: 10
          title: Limit
        description: Number of items per page (max 100)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginationResponse_PolicySummary_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v2/policies/{policy_id}/revisions:
    get:
      summary: List Policy Revisions
      description: "List all revisions for a given policy with pagination.\n\nUses the same authorization as get_policy -\
        \ if a user can read a policy,\nthey can view its revision history.\n\nArgs:\n    changes_summary: Include human-readable\
        \ change descriptions in response"
      operationId: list_policy_revisions_admin_v2_policies__policy_id__revisions_get
      parameters:
      - name: policy_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Policy Id
      - name: changes_summary
        in: query
        required: false
        schema:
          type: boolean
          description: Include human-readable change descriptions in response
          default: false
          title: Changes Summary
        description: Include human-readable change descriptions in response
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          description: Page number (1-based)
          default: 1
          title: Page
        description: Page number (1-based)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Number of items per page (max 100)
          default: 10
          title: Limit
        description: Number of items per page (max 100)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginationResponse_PolicyRevisionSummary_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v2/policies/validate:
    post:
      summary: Validate Policy
      description: 'Validate a policy before creation or update.

        Checks for duplicate names and overlapping MCP server/agent combinations.

        When exclude_policy_id is provided (edit mode), that policy is excluded from validation.'
      operationId: validate_policy_admin_v2_policies_validate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidatePolicyRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidatePolicyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/servers:
    post:
      tags:
      - Servers
      summary: Create MCP Server
      description: 'Create a new MCP server instance from a server directory template.


        The server will be created in `pending` status until OAuth credentials are configured.

        If `client_id` and `client_secret` are provided, the server will be set to `active` status.

        '
      operationId: createServer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServerCreateRequest'
      responses:
        '200':
          description: Server created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerCreateResponse'
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Server directory template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Servers
      summary: List MCP Servers
      description: 'List all MCP servers available to the caller''s organization.

        Returns paginated results with server details including connection status.

        '
      operationId: listServers
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        description: Page number (1-based)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        description: Number of items per page (max 100)
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Search servers by name or slug
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - pending
          - active
          - error
        description: Filter by server status
      - name: connection_status
        in: query
        required: false
        schema:
          type: string
          enum:
          - available
          - pending
          - connected
          - error
          - not_connected
        description: Filter by connection status. `not_connected` expands to pending, error, and available.
      responses:
        '200':
          description: Paginated list of MCP servers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginationResponse_ServerResponse_'
        '401':
          description: Unauthorized - invalid or missing JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/servers/{server_id}:
    delete:
      tags:
      - Servers
      summary: Delete MCP Server
      description: 'Delete an MCP server and all associated connections.


        This will:

        - Remove all user connections to this server

        - Clean up stored OAuth credentials

        - Delete the server configuration


        For custom server types, this will also delete the associated server directory.

        '
      operationId: deleteServer
      parameters:
      - name: server_id
        in: path
        required: true
        description: Server UUID
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Server deleted successfully
          content:
            applicatio

# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/barndoor/refs/heads/main/openapi/barndoor-openapi.yml