Clarity Connections Admin API

openapi: 3.2.0
info:
  title: Fast Connections Admin API
  version: 0.1.0
tags:
- name: connections_admin
paths:
  /api/admin/v1/connections:
    get:
      tags:
      - connections_admin
      summary: List Connections
      description: 'The project''s connections: id, name, provider slug, status, allowed

        methods/paths. Enough to choose one and call through it — nothing more.'
      operationId: list_connections_api_admin_v1_connections_get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentConnectionSummary'
                title: Response List Connections Api Admin V1 Connections Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/v1/connection-templates:
    get:
      tags:
      - connections_admin
      summary: List Connection Templates
      description: The provider catalog (for discovery / choosing what to request).
      operationId: list_connection_templates_api_admin_v1_connection_templates_get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentTemplateSummary'
                title: Response List Connection Templates Api Admin V1 Connection Templates Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - connections_admin
      summary: Create Connection Template
      description: 'Create a PROJECT-scoped template for a provider the catalog lacks. The global

        catalog is untouchable from here; a project slug colliding with a global one

        overrides it for this project only. Follow up with a connection request so a human

        can attach the key.'
      operationId: create_connection_template_api_admin_v1_connection_templates_post
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCreateTemplateBody'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTemplateDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/v1/connection-requests:
    post:
      tags:
      - connections_admin
      summary: Create Connection Request
      description: 'Ask a human to connect a provider. Returns the request to poll; it expires after

        the configured TTL (default 15 min) if nobody answers.'
      operationId: create_connection_request_api_admin_v1_connection_requests_post
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCreateRequestBody'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionRequestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/v1/connection-requests/{request_id}:
    get:
      tags:
      - connections_admin
      summary: Get Connection Request
      description: Poll a request; on ``approved`` the response carries the ``connection_id``.
      operationId: get_connection_request_api_admin_v1_connection_requests__request_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: request_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Request Id
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionRequestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/v1/proxy/{connection_id}:
    post:
      tags:
      - connections_admin
      summary: Proxy Call
      description: 'Call the provider through a connection. The target URL is built ONLY from the

        template''s base_url + the normalized ``path``; credentials are injected server-side.

        The upstream''s reply comes back WRAPPED ({status, headers, body}) — our own status is

        200 for any completed exchange.'
      operationId: proxy_call_api_admin_v1_proxy__connection_id__post
      security:
      - HTTPBearer: []
      parameters:
      - name: connection_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Connection Id
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentProxyCallBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProxyCallResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ProxyUploadFile:
      properties:
        field:
          type: string
          title: Field
          description: The multipart field name the provider expects (e.g. 'file')
        content_base64:
          type: string
          title: Content Base64
          description: File bytes, base64-encoded
        filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Filename
          description: Filename part; defaults to the field name
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
          description: Part Content-Type (default application/octet-stream)
      type: object
      required:
      - field
      - content_base64
      title: ProxyUploadFile
      description: 'One multipart file part. ``content_base64`` keeps the transport JSON — the proxy

        base64-decodes it to raw bytes server-side before forwarding.'
    ProxyCallResponse:
      properties:
        status:
          type: integer
          title: Status
          description: The UPSTREAM's HTTP status
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
          description: Whitelisted upstream headers
        body:
          type: string
          title: Body
          description: Upstream body; base64 when body_encoding='base64'
          default: ''
        body_encoding:
          type: string
          title: Body Encoding
          description: '''utf-8'' | ''base64'''
          default: utf-8
        latency_ms:
          type: integer
          title: Latency Ms
      type: object
      required:
      - status
      - latency_ms
      title: ProxyCallResponse
    AgentCreateRequestBody:
      properties:
        template_slug:
          type: string
          title: Template Slug
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
          description: Shown to the human deciding
        requested_by:
          type: string
          title: Requested By
          description: Agent run id, lands in the audit trail
      type: object
      required:
      - template_slug
      - requested_by
      title: AgentCreateRequestBody
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentCreateTemplateBody:
      properties:
        slug:
          type: string
          title: Slug
          description: 'Permanent id: lowercase, digits, dashes'
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Agents see it when discovering providers
        base_url:
          type: string
          title: Base Url
          description: Absolute public http(s) base URL
        auth_type:
          type: string
          title: Auth Type
          description: bearer | header | query_param
        auth_config:
          additionalProperties: true
          type: object
          title: Auth Config
        allow_rules:
          additionalProperties: true
          type: object
          title: Allow Rules
          description: '{methods: [..], path_patterns: [..]}'
        health_check_path:
          anyOf:
          - type: string
          - type: 'null'
          title: Health Check Path
        docs_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Docs Url
      type: object
      required:
      - slug
      - base_url
      - auth_type
      - allow_rules
      title: AgentCreateTemplateBody
      description: 'A custom provider shape. No secret material belongs here — auth_config carries

        only the auth FORM (header/param names); the key arrives later through a human.'
    ConnectionRequestResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        project_id:
          type: integer
          title: Project Id
        template_slug:
          type: string
          title: Template Slug
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        status:
          type: string
          title: Status
        connection_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Connection Id
        requested_by:
          type: string
          title: Requested By
        expires_at:
          type: string
          format: date-time
          title: Expires At
        created_at:
          type: string
          format: date-time
          title: Created At
        resolved_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Resolved At
        template_display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Display Name
        template_base_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Template Base Url
        template_is_global:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Template Is Global
      type: object
      required:
      - id
      - project_id
      - template_slug
      - status
      - requested_by
      - expires_at
      - created_at
      title: ConnectionRequestResponse
    AgentTemplateDetail:
      properties:
        slug:
          type: string
          title: Slug
        display_name:
          type: string
          title: Display Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        docs_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Docs Url
        base_url:
          type: string
          title: Base Url
        auth_type:
          type: string
          title: Auth Type
        allow_rules:
          additionalProperties: true
          type: object
          title: Allow Rules
        health_check_path:
          anyOf:
          - type: string
          - type: 'null'
          title: Health Check Path
      type: object
      required:
      - slug
      - display_name
      - base_url
      - auth_type
      - allow_rules
      title: AgentTemplateDetail
      description: Echo of a template the agent just created — its own data, nothing sensitive.
    AgentTemplateSummary:
      properties:
        slug:
          type: string
          title: Slug
        display_name:
          type: string
          title: Display Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        docs_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Docs Url
      type: object
      required:
      - slug
      - display_name
      title: AgentTemplateSummary
      description: Catalog entry for discovery.
    AgentConnectionSummary:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        template_slug:
          type: string
          title: Template Slug
        template_display_name:
          type: string
          title: Template Display Name
        status:
          type: string
          title: Status
        is_global:
          type: boolean
          title: Is Global
        allowed_methods:
          items:
            type: string
          type: array
          title: Allowed Methods
        allowed_path_patterns:
          items:
            type: string
          type: array
          title: Allowed Path Patterns
      type: object
      required:
      - id
      - name
      - template_slug
      - template_display_name
      - status
      - is_global
      - allowed_methods
      - allowed_path_patterns
      title: AgentConnectionSummary
      description: 'What an agent needs to pick a connection — and nothing else. No auth config, no

        secret ids/refs, no base_url.'
    AgentProxyCallBody:
      properties:
        path:
          type: string
          title: Path
          description: Path relative to the template's base URL — never a full URL
        method:
          type: string
          title: Method
          description: GET | POST | PUT | PATCH | DELETE | HEAD
        query_params:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Query Params
        headers:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Headers
          description: 'Whitelisted: Content-Type, Accept, plus template-declared extras. Auth headers are injected server-side and cannot be supplied.'
        body:
          anyOf:
          - {}
          - type: 'null'
          title: Body
          description: 'Request body: a JSON object/array (body_encoding=''json''), a string (''text''), or base64-encoded raw bytes (''base64'', e.g. a file). Omit when uploading via `files`.'
        body_encoding:
          type: string
          title: Body Encoding
          description: 'How to interpret `body`: ''json'' | ''text'' | ''base64'''
          default: json
        files:
          anyOf:
          - items:
              $ref: '#/components/schemas/ProxyUploadFile'
            type: array
          - type: 'null'
          title: Files
          description: multipart/form-data file parts. Mutually exclusive with `body`; the proxy builds the multipart request and owns the Content-Type/boundary.
        form_fields:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Form Fields
          description: Non-file multipart form fields sent alongside `files`.
        caller_type:
          type: string
          title: Caller Type
          description: '''agent'' or ''widget'''
          default: agent
        caller_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Caller Id
          description: Agent run id / widget id
      type: object
      required:
      - path
      - method
      title: AgentProxyCallBody
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic