ctlsurf Admin API

openapi: 3.2.0
info:
  title: Ctlsurf Com Admin API
  version: 0.1.0
  description: 'Operations tagged admin across 2 of this provider''s published API definitions: ctlsurf-com-openapi.json, ctlsurf-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.ctlsurf.com
  description: ctlsurf application host (documented MCP endpoint https://app.ctlsurf.com/api/mcp; spec served at /openapi.json)
tags:
- name: Admin
paths:
  /api/admin/metrics:
    get:
      tags:
      - Admin
      summary: Get Admin Metrics
      description: 'Get comprehensive system metrics for admin dashboard.

        Requires admin privileges.'
      operationId: get_admin_metrics_api_admin_metrics_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/admin/activation-funnel:
    get:
      tags:
      - Admin
      summary: Get Activation Funnel
      description: 'Activation funnel: signup -> email verified -> API key created -> first MCP call.


        Computed from existing timestamps (users, api_keys, mcp_tool_calls), so it

        covers all historical users with no new event logging required.

        Time-to-first-call is the north-star onboarding metric.'
      operationId: get_activation_funnel_api_admin_activation_funnel_get
      security:
      - HTTPBearer: []
      parameters:
      - name: days
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            maximum: 365
            minimum: 1
          - type: 'null'
          description: Only include users who signed up in the last N days
          title: Days
        description: Only include users who signed up in the last N days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/users:
    get:
      tags:
      - Admin
      summary: List Users
      description: 'List all users with pagination and basic stats.

        Requires admin privileges.'
      operationId: list_users_api_admin_users_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: search
        in: query
        required: false
        schema:
          type: string
          title: Search
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/users/{user_id}:
    get:
      tags:
      - Admin
      summary: Get User Details
      description: 'Get detailed stats for a specific user.

        Requires admin privileges.'
      operationId: get_user_details_api_admin_users__user_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Admin
      summary: Delete User
      description: 'Delete a user and all their data.

        Cannot delete self or other admins.'
      operationId: delete_user_api_admin_users__user_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/users/{user_id}/toggle-admin:
    post:
      tags:
      - Admin
      summary: Toggle User Admin
      description: 'Toggle admin status for a user.

        Cannot remove admin from self or last admin.'
      operationId: toggle_user_admin_api_admin_users__user_id__toggle_admin_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/users/{user_id}/suspend:
    post:
      tags:
      - Admin
      summary: Suspend User
      description: 'Suspend a user account.

        Cannot suspend self or other admins.'
      operationId: suspend_user_api_admin_users__user_id__suspend_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: reason
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Reason
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/users/{user_id}/unsuspend:
    post:
      tags:
      - Admin
      summary: Unsuspend User
      description: Unsuspend a user account.
      operationId: unsuspend_user_api_admin_users__user_id__unsuspend_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/users/{user_id}/upgrade:
    post:
      tags:
      - Admin
      summary: Upgrade User To Pro
      description: 'Upgrade a user to Pro tier.

        Requires billing_admin or super_admin role.'
      operationId: upgrade_user_to_pro_api_admin_users__user_id__upgrade_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpgradeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/users/{user_id}/downgrade:
    post:
      tags:
      - Admin
      summary: Downgrade User To Free
      description: 'Downgrade a user to Free tier.

        Requires billing_admin or super_admin role.'
      operationId: downgrade_user_to_free_api_admin_users__user_id__downgrade_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: reason
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/users/{user_id}/upgrade-history:
    get:
      tags:
      - Admin
      summary: Get User Upgrade History
      description: 'Get upgrade/downgrade history for a user.

        Requires billing_admin or super_admin role.'
      operationId: get_user_upgrade_history_api_admin_users__user_id__upgrade_history_get
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/users/{user_id}/set-admin-role:
    post:
      tags:
      - Admin
      summary: Set User Admin Role
      description: 'Set admin role for a user.

        Requires super_admin role.'
      operationId: set_user_admin_role_api_admin_users__user_id__set_admin_role_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      - name: role
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Role: super_admin, billing_admin, support_admin, or null to remove'
          title: Role
        description: 'Role: super_admin, billing_admin, support_admin, or null to remove'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/organizations:
    get:
      tags:
      - Admin
      summary: List Organizations Admin
      description: List organizations for the promote-to-Business picker. Super admin only.
      operationId: list_organizations_admin_api_admin_organizations_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/admin/users/{user_id}/promote-business:
    post:
      tags:
      - Admin
      summary: Promote User To Business
      description: 'Promote a user to a Business organization. Super admin only.


        mode="create" -> create a new Business org with the user as owner.

        mode="add" -> add the user to an existing org (default role: member).

        Super admins bypass the seat cap here by design.'
      operationId: promote_user_to_business_api_admin_users__user_id__promote_business_post
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          title: User Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromoteBusinessRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/orgs/{org_id}/billing/attach:
    post:
      tags:
      - Admin
      summary: Attach Org Billing
      description: 'Attach seat billing to an existing organization.


        Orgs are created by promote-business, which is deliberate: the billing

        relationship is established afterwards rather than at signup. This is that

        second step.


        Two modes, because both are real:


        - manual_only sets seats_purchased with no provider involved. Comped orgs,

        self-hosted deployments, and anyone invoiced outside Stripe live here, and

        they are a supported configuration rather than a broken one.

        - Otherwise a Stripe customer and a quantity-N subscription are created. The

        subscription may come back `incomplete` when the customer has no payment

        method yet; that is expected, not a failure. The response carries the

        status so the operator knows to send the owner a payment link.


        Never lowers seats below what is already assigned: doing so would put the

        org over its own limit the instant billing was attached.'
      operationId: attach_org_billing_api_admin_orgs__org_id__billing_attach_post
      security:
      - HTTPBearer: []
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          title: Org Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachBillingRequest'
              default:
                manual_only: false
                comped: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/orgs/{org_id}/billing:
    get:
      tags:
      - Admin
      summary: Get Org Billing
      description: Show an org's seat and billing state, for support.
      operationId: get_org_billing_api_admin_orgs__org_id__billing_get
      security:
      - HTTPBearer: []
      parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
          title: Org Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/services/llm-config:
    get:
      tags:
      - Admin
      summary: Llm Config
      operationId: llm_config_api_admin_services_llm_config_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
    put:
      tags:
      - Admin
      summary: Update Llm Config
      operationId: update_llm_config_api_admin_services_llm_config_put
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/admin/services/llm-config/validate:
    post:
      tags:
      - Admin
      summary: Validate Llm Config
      operationId: validate_llm_config_api_admin_services_llm_config_validate_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/admin/services/speech-config:
    get:
      tags:
      - Admin
      summary: Speech Config
      operationId: speech_config_api_admin_services_speech_config_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
    put:
      tags:
      - Admin
      summary: Update Speech Config
      operationId: update_speech_config_api_admin_services_speech_config_put
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/admin/services/speech-config/validate/{kind}:
    post:
      tags:
      - Admin
      summary: Validate Speech Config
      operationId: validate_speech_config_api_admin_services_speech_config_validate__kind__post
      security:
      - HTTPBearer: []
      parameters:
      - name: kind
        in: path
        required: true
        schema:
          enum:
          - listen
          - speak
          type: string
          title: Kind
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/services/page-agent-config:
    get:
      tags:
      - Admin
      summary: Agent Config
      operationId: agent_config_api_admin_services_page_agent_config_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
    put:
      tags:
      - Admin
      summary: Update Agent Config
      operationId: update_agent_config_api_admin_services_page_agent_config_put
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/admin/services/page-agent-pilot:
    get:
      tags:
      - Admin
      summary: Agent Pilot
      operationId: agent_pilot_api_admin_services_page_agent_pilot_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
    put:
      tags:
      - Admin
      summary: Save Agent Pilot
      operationId: save_agent_pilot_api_admin_services_page_agent_pilot_put
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/admin/services/page-agent-pilot/organizations:
    get:
      tags:
      - Admin
      summary: Agent Pilot Organizations
      operationId: agent_pilot_organizations_api_admin_services_page_agent_pilot_organizations_get
      security:
      - HTTPBearer: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          type: string
          maxLength: 100
          default: ''
          title: Q
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/services/page-agent-config/validate:
    post:
      tags:
      - Admin
      summary: Validate Agent Config
      operationId: validate_agent_config_api_admin_services_page_agent_config_validate_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/admin/services/page-agent-reservations:
    get:
      tags:
      - Admin
      summary: Agent Reservations
      operationId: agent_reservations_api_admin_services_page_agent_reservations_get
      security:
      - HTTPBearer: []
      parameters:
      - name: org_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Org Id
      - name: state
        in: query
        required: false
        schema:
          enum:
          - unresolved
          - reconciled
          - overrun
          type: string
          default: unresolved
          title: State
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          minimum: 0
          default: 0
          title: Offset
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/services/page-agent-reservations/{reservation_id}:
    get:
      tags:
      - Admin
      summary: Agent Reservation
      operationId: agent_reservation_api_admin_services_page_agent_reservations__reservation_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: reservation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Reservation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/services/page-agent-reservations/{reservation_id}/preview:
    post:
      tags:
      - Admin
      summary: Preview Agent Receipt
      operationId: preview_agent_receipt_api_admin_services_page_agent_reservations__reservation_id__preview_post
      security:
      - HTTPBearer: []
      parameters:
      - name: reservation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Reservation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/services/page-agent-reservations/{reservation_id}/reconcile:
    post:
      tags:
      - Admin
      summary: Reconcile Agent Receipt
      operationId: reconcile_agent_receipt_api_admin_services_page_agent_reservations__reservation_id__reconcile_post
      security:
      - HTTPBearer: []
      parameters:
      - name: reservation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Reservation Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/services/metrics:
    get:
      tags:
      - Admin
      summary: Services Metrics
      description: Platform managed-services totals, cost split, trend, and top orgs by spend.
      operationId: services_metrics_api_admin_services_metrics_get
      security:
      - HTTPBearer: []
      parameters:
      - name: range
        in: query
        required: false
        schema:
          type: string
          description: 'Window: current | 30d | 90d'
          default: current
          title: Range
        description: 'Window: current | 30d | 90d'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/services/orgs:
    get:
      tags:
      - Admin
      summary: Services Orgs
      description: 'Per-org managed-services table: seats, minutes vs included, cost, cap usage.'
      operationId: services_orgs_api_admin_services_orgs_get
      security:
      - HTTPBearer: []
      parameters:
      - name: range
        in: query
        required: false
        schema:
          type: string
          description: 'Window: current | 30d | 90d'
          default: current
          title: Range
        description: 'Window: current | 30d | 90d'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/services/events:
    get:
      tags:
      - Admin
      summary: Services Events
      description: 'Platform operational-event feed: counts by kind + recent failures across all orgs.


        Operational (no cost data), so visible to support_admin and up.'
      operationId: services_events_api_admin_services_events_get
      security:
      - HTTPBearer: []
      parameters:
      - name: range
        in: query
        required: false
        schema:
          type: string
          description: 'Window: current | 30d | 90d'
          default: current
          title: Range
        description: 'Window: current | 30d | 90d'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          default: 100
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AttachBillingRequest:
      properties:
        seats:
          anyOf:
          - type: integer
          - type: 'null'
          title: Seats
        manual_only:
          type: boolean
          title: Manual Only
          default: false
        comped:
          type: boolean
          title: Comped
          default: true
      type: object
      title: AttachBillingRequest
      description: Start an org's per-seat subscription, or set its seats manually.
    UpgradeRequest:
      properties:
        duration_days:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Days
          default: 90
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
      type: object
      title: UpgradeRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    PromoteBusinessRequest:
      properties:
        mode:
          type: string
          title: Mode
        org_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Org Name
        org_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Org Id
        role:
          anyOf:
          - type: string
          - type: 'null'
          title: Role
      type: object
      required:
      - mode
      title: PromoteBusinessRequest
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- ctlsurf-com-openapi.json
- ctlsurf-com-openapi.yml