sealgate-ai Instance API

openapi: 3.2.0
info:
  title: SealGate Instance API
  description: Open-source MCP security, aggregation, and monitoring. Self-hosted MCP proxy.
  version: 0.19.0
tags:
- name: Instance
paths:
  /api/v1/instance/roles:
    get:
      summary: List Instance Roles
      description: Every account holding an instance role.
      operationId: list_instance_roles_api_v1_instance_roles_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/InstanceRolesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
    post:
      summary: Grant Instance Role
      description: Grant the Super-Owner instance role to an existing account.
      operationId: grant_instance_role_api_v1_instance_roles_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/GrantInstanceRoleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceRoleEntry'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
  /api/v1/instance/roles/{user_id}:
    delete:
      summary: Revoke Instance Role
      description: Revoke the Super-Owner instance role. The last Super-Owner cannot be removed.
      operationId: revoke_instance_role_api_v1_instance_roles__user_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User 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:
                type: object
                additionalProperties:
                  type: string
                title: Response Revoke Instance Role Api V1 Instance Roles  User Id  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
  /api/v1/instance/accounts:
    get:
      summary: List Accounts
      description: 'Accounts with the orgs they belong to (instance data only: emails, org names).'
      operationId: list_accounts_api_v1_instance_accounts_get
      security:
      - HTTPBearer: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          description: Search email
          title: Q
        description: Search email
      - 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/InstanceAccountsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
  /api/v1/instance/accounts/{user_id}:
    delete:
      summary: Delete Account
      description: Delete an account and its data in every org (not while it owns an org with members).
      operationId: delete_account_api_v1_instance_accounts__user_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User 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/DeleteAccountResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
  /api/v1/instance/orgs:
    get:
      summary: List Orgs
      description: Every org of the instance with its active member count.
      operationId: list_orgs_api_v1_instance_orgs_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/InstanceOrg'
                title: Response List Orgs Api V1 Instance Orgs Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
    post:
      summary: Create Org
      description: 'Create an org and invite its first Owner by email.


        An existing account gets an ``invited`` Owner membership to accept from

        Settings > Organisations; a new address gets the normal invite email, and its key and

        Owner membership are waiting when it signs up.'
      operationId: create_org_api_v1_instance_orgs_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/CreateOrgRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrgResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
  /api/v1/instance/orgs/{org_id}/suspend:
    patch:
      summary: Suspend Org
      description: 'Suspend an org: the gateway refuses every tool call until it is resumed.'
      operationId: suspend_org_api_v1_instance_orgs__org_id__suspend_patch
      security:
      - HTTPBearer: []
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          title: Org 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/SuspendOrgRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgSuspensionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
  /api/v1/instance/orgs/{org_id}/resume:
    patch:
      summary: Resume Org
      description: Resume a suspended org.
      operationId: resume_org_api_v1_instance_orgs__org_id__resume_patch
      security:
      - HTTPBearer: []
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          title: Org 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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgSuspensionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
  /api/v1/instance/orgs/{org_id}:
    delete:
      summary: Delete Org
      description: Permanently delete an org and its members' data in it; their accounts stay.
      operationId: delete_org_api_v1_instance_orgs__org_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          title: Org 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/DeleteOrgResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
  /api/v1/instance/billing/usage:
    get:
      summary: List Billing Usage
      description: 'Every org''s credits used and allocation this month, with its active members.


        See :func:`src.billing.service.list_org_usage` for what ``allocation``

        means. Names, members and emails come from the auth tables, which the

        billing login cannot read.'
      operationId: list_billing_usage_api_v1_instance_billing_usage_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/InstanceOrgUsageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
  /api/v1/instance/sessions/daily-stats:
    get:
      summary: Instance Session Daily Stats
      description: Sessions per (UTC day, user) across every org, for the instance-wide activity view.
      operationId: instance_session_daily_stats_api_v1_instance_sessions_daily_stats_get
      security:
      - HTTPBearer: []
      parameters:
      - name: start
        in: query
        required: true
        schema:
          type: string
          format: date-time
          description: Window start (inclusive, UTC if naive)
          title: Start
        description: Window start (inclusive, UTC if naive)
      - name: end
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Window end (exclusive, UTC if naive)
          title: End
        description: Window end (exclusive, UTC if naive)
      - 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/SessionDailyStatsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Instance
components:
  schemas:
    CreateOrgResponse:
      properties:
        org_id:
          type: string
          title: Org Id
        name:
          type: string
          title: Name
        owner_email:
          type: string
          title: Owner Email
        owner_invited:
          type: boolean
          title: Owner Invited
          description: True when the owner must accept an invite (existing or new account)
      type: object
      required:
      - org_id
      - name
      - owner_email
      - owner_invited
      title: CreateOrgResponse
    InstanceOrgUsageResponse:
      properties:
        orgs:
          items:
            $ref: '#/components/schemas/InstanceOrgUsage'
          type: array
          title: Orgs
      type: object
      required:
      - orgs
      title: InstanceOrgUsageResponse
    GrantInstanceRoleRequest:
      properties:
        email:
          type: string
          title: Email
          description: Email of an existing account
        role:
          type: string
          title: Role
          description: Instance role to grant (super_owner)
          default: super_owner
      type: object
      required:
      - email
      title: GrantInstanceRoleRequest
    InstanceOrgUsage:
      properties:
        org_id:
          type: string
          title: Org Id
        org_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Org Name
        used:
          type: number
          title: Used
          description: Credits the org spent this month
        allocation:
          type: number
          title: Allocation
          description: Most credits the org can reach this month
        members:
          items:
            $ref: '#/components/schemas/InstanceOrgMember'
          type: array
          title: Members
          description: Active members of the org
      type: object
      required:
      - org_id
      - org_name
      - used
      - allocation
      - members
      title: InstanceOrgUsage
      description: One org's credit position this month, for the instance usage view.
    AccountMembershipEntry:
      properties:
        org_id:
          type: string
          title: Org Id
        org_name:
          type: string
          title: Org Name
        org_role:
          type: string
          title: Org Role
        status:
          type: string
          title: Status
        key_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Status
      type: object
      required:
      - org_id
      - org_name
      - org_role
      - status
      title: AccountMembershipEntry
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    InstanceAccountsResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/InstanceAccount'
          type: array
          title: Items
        total:
          type: integer
          title: Total
      type: object
      required:
      - items
      - total
      title: InstanceAccountsResponse
    DeleteOrgResponse:
      properties:
        org_id:
          type: string
          title: Org Id
        deleted_users:
          type: integer
          title: Deleted Users
          description: Members who lost their membership
        total_deleted:
          type: integer
          title: Total Deleted
          description: Rows removed across both databases
      type: object
      required:
      - org_id
      - deleted_users
      - total_deleted
      title: DeleteOrgResponse
    InstanceOrgMember:
      properties:
        user_id:
          type: string
          title: User Id
        user_email:
          anyOf:
          - type: string
          - type: 'null'
          title: User Email
      type: object
      required:
      - user_id
      - user_email
      title: InstanceOrgMember
    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
    SuspendOrgRequest:
      properties:
        reason:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Reason
          description: Shown to the org's admins
      type: object
      title: SuspendOrgRequest
    DeleteAccountResponse:
      properties:
        status:
          type: string
          title: Status
          default: deleted
        user_id:
          type: string
          title: User Id
        total_deleted:
          type: integer
          title: Total Deleted
      type: object
      required:
      - user_id
      - total_deleted
      title: DeleteAccountResponse
    CreateOrgRequest:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          description: Organisation name
        owner_email:
          type: string
          title: Owner Email
          description: Email of the organisation's first Owner
      type: object
      required:
      - name
      - owner_email
      title: CreateOrgRequest
    InstanceRolesResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/InstanceRoleEntry'
          type: array
          title: Items
      type: object
      required:
      - items
      title: InstanceRolesResponse
    SessionDailyStatsResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/SessionDayStats'
          type: array
          title: Items
          description: One entry per (day, user) with at least one session in range
      type: object
      required:
      - items
      title: SessionDailyStatsResponse
    InstanceAccount:
      properties:
        user_id:
          type: string
          title: User Id
        email:
          type: string
          title: Email
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
        last_sign_in_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Sign In At
        is_super_owner:
          type: boolean
          title: Is Super Owner
          default: false
        memberships:
          items:
            $ref: '#/components/schemas/AccountMembershipEntry'
          type: array
          title: Memberships
      type: object
      required:
      - user_id
      - email
      title: InstanceAccount
    OrgSuspensionResponse:
      properties:
        org_id:
          type: string
          title: Org Id
        suspended:
          type: boolean
          title: Suspended
        suspended_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Suspended At
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
      type: object
      required:
      - org_id
      - suspended
      title: OrgSuspensionResponse
    InstanceOrg:
      properties:
        org_id:
          type: string
          title: Org Id
        name:
          type: string
          title: Name
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
        member_count:
          type: integer
          title: Member Count
          description: Active memberships
          default: 0
        suspended:
          type: boolean
          title: Suspended
          default: false
      type: object
      required:
      - org_id
      - name
      title: InstanceOrg
      description: One org as the Super-Owner's Instance page lists it.
    SessionDayStats:
      properties:
        date:
          type: string
          format: date
          title: Date
          description: UTC calendar day the sessions were created
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
          description: User the sessions belong to
        user_email:
          anyOf:
          - type: string
          - type: 'null'
          title: User Email
          description: Email of that user
        sessions:
          type: integer
          title: Sessions
          description: Sessions created that day
        tool_calls:
          type: integer
          title: Tool Calls
          description: Tool calls across those sessions
        trifecta_blocks:
          type: integer
          title: Trifecta Blocks
          description: Lethal-trifecta blocks across those sessions
        non_builtin_tool_calls:
          type: integer
          title: Non Builtin Tool Calls
          description: Tool calls to a connector's tool rather than a SealGate builtin
      type: object
      required:
      - date
      - sessions
      - tool_calls
      - trifecta_blocks
      - non_builtin_tool_calls
      title: SessionDayStats
    InstanceRoleEntry:
      properties:
        user_id:
          type: string
          title: User Id
          description: Account holding the instance role
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
          description: Account email
        role:
          type: string
          title: Role
          description: Instance role (super_owner)
        granted_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Granted At
          description: When the role was granted
        granted_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Granted By
          description: Account that granted it, if recorded
      type: object
      required:
      - user_id
      - role
      title: InstanceRoleEntry
  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.