sealgate-ai Admin Chat API

openapi: 3.2.0
info:
  title: SealGate Admin Chat API
  description: Open-source MCP security, aggregation, and monitoring. Self-hosted MCP proxy.
  version: 0.19.0
tags:
- name: Admin Chat
paths:
  /api/v1/admin-chat:
    post:
      summary: Admin Chat
      operationId: admin_chat_api_v1_admin_chat_post
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional client-generated key that makes this write operation safe to retry. Reusing the same key returns the original response instead of performing the operation a second time. Keys are scoped to the caller and expire after 24 hours.
        schema:
          type: string
          maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminChatRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin Chat
  /api/v1/admin-chat/preview:
    post:
      summary: Admin Chat Preview
      description: 'The diff for a proposed write as of now.


        The page calls this when the admin clicks Apply on a card: if the snapshot

        the card was drawn from no longer matches (``fingerprint``), the host shows

        the fresh diff instead of applying, so a change made in the meantime is

        reviewed rather than overwritten.'
      operationId: admin_chat_preview_api_v1_admin_chat_preview_post
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional client-generated key that makes this write operation safe to retry. Reusing the same key returns the original response instead of performing the operation a second time. Keys are scoped to the caller and expire after 24 hours.
        schema:
          type: string
          maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin Chat
  /api/v1/admin-chat/skills:
    get:
      summary: Admin Chat Skills
      description: 'The caller''s saved skills, for the composer''s picker.


        Metadata only: the turn reads a skill''s content itself when a message

        invokes it, so the page never carries instructions it does not need.'
      operationId: admin_chat_skills_api_v1_admin_chat_skills_get
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChatSkill'
                title: Response Admin Chat Skills Api V1 Admin Chat Skills Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin Chat
  /api/v1/admin-chat/status:
    get:
      summary: Admin Chat Status
      operationId: admin_chat_status_api_v1_admin_chat_status_get
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminChatStatus'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin Chat
  /api/v1/admin-chat/conversations:
    get:
      summary: List Conversations
      operationId: list_conversations_api_v1_admin_chat_conversations_get
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConversationSummary'
                title: Response List Conversations Api V1 Admin Chat Conversations Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin Chat
  /api/v1/admin-chat/conversations/{conversation_id}:
    get:
      summary: Get Conversation
      operationId: get_conversation_api_v1_admin_chat_conversations__conversation_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin Chat
    put:
      summary: Save Conversation
      description: 'Create or replace the transcript; the id is the page''s, minted client-side.


        Without ``messages`` only the title changes (a rename).'
      operationId: save_conversation_api_v1_admin_chat_conversations__conversation_id__put
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional client-generated key that makes this write operation safe to retry. Reusing the same key returns the original response instead of performing the operation a second time. Keys are scoped to the caller and expire after 24 hours.
        schema:
          type: string
          maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveConversationRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationSummary'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin Chat
    delete:
      summary: Delete Conversation
      operationId: delete_conversation_api_v1_admin_chat_conversations__conversation_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: conversation_id
        in: path
        required: true
        schema:
          type: string
          title: Conversation Id
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Admin Chat
components:
  schemas:
    AdminChatRequest:
      properties:
        messages:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Messages
          description: UIMessage history
      additionalProperties: true
      type: object
      title: AdminChatRequest
      description: 'Body of ``POST /admin-chat``: what ``useChat``''s ``DefaultChatTransport`` posts.


        ``messages`` is the full ``UIMessage[]`` history; ``id``/``trigger``/

        ``messageId`` ride along and are ignored.'
    PreviewRequest:
      properties:
        tool:
          type: string
          title: Tool
          description: Write tool name, e.g. update_role
        arguments:
          additionalProperties: true
          type: object
          title: Arguments
          description: The proposed arguments
      type: object
      required:
      - tool
      title: PreviewRequest
      description: '``POST /admin-chat/preview``: recompute a proposed write''s diff right now.'
    ConversationSummary:
      properties:
        id:
          type: string
          title: Id
          description: Conversation id (minted by the page)
        title:
          type: string
          title: Title
          description: First user message, trimmed
        message_count:
          type: integer
          title: Message Count
          description: Messages in the transcript
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - title
      - message_count
      - created_at
      - updated_at
      title: ConversationSummary
    ChatSkill:
      properties:
        name:
          type: string
          title: Name
          description: Skill slug; typed as /name or $name in the composer
        description:
          type: string
          title: Description
          description: Summary from the skill's frontmatter, may be empty
          default: ''
        size_bytes:
          type: integer
          title: Size Bytes
          description: Size of the SKILL.md document
          default: 0
        updated_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated At
          description: ISO timestamp of the last save
      type: object
      required:
      - name
      title: ChatSkill
      description: One saved skill as the composer's picker lists it (no content).
    SaveConversationRequest:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
          description: Title to set; omit to keep the current one
        messages:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Messages
          description: Full UIMessage history; omit to keep the saved one (a rename)
      type: object
      title: SaveConversationRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    FieldChange:
      properties:
        key:
          type: string
          title: Key
        before:
          anyOf:
          - type: string
          - type: 'null'
          title: Before
        after:
          anyOf:
          - type: string
          - type: 'null'
          title: After
      type: object
      required:
      - key
      - before
      - after
      title: FieldChange
      description: One top-level field of the record, before and after the write; ``None`` is absent.
    DiffLine:
      properties:
        t:
          type: string
          enum:
          - +
          - '-'
          - ' '
          title: T
        s:
          type: string
          title: S
      type: object
      required:
      - t
      - s
      title: DiffLine
      description: 'One line of a before/after preview: added, removed, or unchanged context.'
    AdminChatStatus:
      properties:
        model:
          type: string
          title: Model
          description: Model id in provider/name form
        llm_configured:
          type: boolean
          title: Llm Configured
          description: Whether the model's provider key is set
        tool_count:
          type: integer
          title: Tool Count
          description: Number of tools the admin MCP server exposes
      type: object
      required:
      - model
      - llm_configured
      - tool_count
      title: AdminChatStatus
      description: What the Chat page needs to know before its first message.
    ConversationDetail:
      properties:
        id:
          type: string
          title: Id
          description: Conversation id (minted by the page)
        title:
          type: string
          title: Title
          description: First user message, trimmed
        message_count:
          type: integer
          title: Message Count
          description: Messages in the transcript
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        messages:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Messages
          description: UIMessage history
      type: object
      required:
      - id
      - title
      - message_count
      - created_at
      - updated_at
      - messages
      title: ConversationDetail
    ChangeDiff:
      properties:
        kind:
          type: string
          enum:
          - create
          - update
          - delete
          title: Kind
        label:
          type: string
          title: Label
        fingerprint:
          type: string
          title: Fingerprint
        fields:
          items:
            $ref: '#/components/schemas/FieldChange'
          type: array
          title: Fields
        after:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: After
        lines:
          items:
            $ref: '#/components/schemas/DiffLine'
          type: array
          title: Lines
        truncated:
          type: boolean
          title: Truncated
        adds:
          type: integer
          title: Adds
        dels:
          type: integer
          title: Dels
      type: object
      required:
      - kind
      - label
      - fingerprint
      - lines
      - truncated
      - adds
      - dels
      title: ChangeDiff
      description: 'What a proposed write would change, as the confirmation card paints it.


        Built by ``src.admin_mcp.preview.build_diff``; travels on the tool part''s

        ``callProviderMetadata.sealgate.diff`` and as the preview route''s answer.

        ``fields`` is what the card shows first (the changed fields, as words);

        ``lines`` is the JSON line diff behind its toggle.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PreviewResponse:
      properties:
        diff:
          anyOf:
          - $ref: '#/components/schemas/ChangeDiff'
          - type: 'null'
          description: The diff the card renders; null when there is no snapshot
      type: object
      title: PreviewResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    ClientBearer:
      type: http
      description: Opaque ewc_ client installation credential
      scheme: bearer
    ServiceToken:
      type: http
      description: 'A SealGate service token: `sgt_acct_...` (account token) or `sgt_org_...` (org token). Mint an account token in the dashboard.'
      scheme: bearer
    MCPGatewayOAuth:
      type: oauth2
      description: OAuth 2.1 authorization-code flow (PKCE required) against the SealGate MCP gateway's authorization server. Request only the scopes an agent needs; unrequested scopes are not granted.
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          refreshUrl: /oauth/token
          scopes:
            mcp: Connect to the MCP gateway and call the tools exposed by your enabled servers. Every call is still evaluated by the policy engine.
            offline_access: Issue a refresh token so the client can renew access without a new browser sign-in.