CHNLSYNC Customer Agent API

openapi: 3.2.0
info:
  title: Chnlsync Com Customer Agent API
  version: 0.1.0
  x-refined-note:
  - x-source differs across the merged source definitions and was not carried
  description: 'Operations tagged customer-agent across 2 of this provider''s published API definitions: chnlsync-com-openapi.json, chnlsync-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.chnlsync.dev
  description: CHNLSYNC API host advertised in https://chnlsync.com/llms.txt (servers[] absent in the served spec; added here)
tags:
- name: customer-agent
paths:
  /api/v1/agent/sessions:
    post:
      tags:
      - customer-agent
      summary: Post Agent Session
      description: Create a provisional workspace on behalf of an external agent's user.
      operationId: post_agent_session_api_v1_agent_sessions_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentSessionCreateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSessionCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /api/v1/agent/sessions/{session_id}/chat:
    post:
      tags:
      - customer-agent
      summary: Post Agent Chat
      description: Run one advisor turn for an agent session (full trust-rail stack).
      operationId: post_agent_chat_api_v1_agent_sessions__session_id__chat_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: X-Agent-Session-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Session-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentChatRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentChatResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agent/sessions/{session_id}/callback-request:
    post:
      tags:
      - customer-agent
      summary: Post Agent Callback Request
      description: 'Record a buyer-consented broker-callback request (the handoff).


        The callback stays the terminal state; ``book_url`` is a soft extension

        the assistant MAY offer. With ``agent_callback_email_enabled`` on, the

        buyer also gets one confirmation email (claim link + booking link) as a

        background task after the response — never on the request path.'
      operationId: post_agent_callback_request_api_v1_agent_sessions__session_id__callback_request_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Session Id
      - name: X-Agent-Session-Token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Session-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCallbackRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCallbackResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agent/copper-retirement:
    get:
      tags:
      - customer-agent
      summary: Get Copper Retirement
      description: 'Credentialed alias of the public dataset read (no LLM, no tenant).


        Same payload as the keyless ``GET /api/v1/copper-retirement``; only the

        tracker-link attribution differs (``ref=agent-``).'
      operationId: get_copper_retirement_api_v1_agent_copper_retirement_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: carrier
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Carrier
      - name: state
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: State
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CopperRetirementResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AgentCallbackRequest:
      properties:
        contact_name:
          type: string
          maxLength: 255
          minLength: 1
          title: Contact Name
        contact_email:
          type: string
          maxLength: 255
          minLength: 3
          pattern: ^[^@\s]+@[^@\s]+\.[^@\s]+$
          title: Contact Email
      type: object
      required:
      - contact_name
      - contact_email
      title: AgentCallbackRequest
      description: Buyer-consented human-handoff request with contact details.
    CopperRetirementResponse:
      properties:
        records:
          items:
            $ref: '#/components/schemas/CopperRetirementRecord'
          type: array
          title: Records
        source:
          type: string
          title: Source
        source_url:
          type: string
          title: Source Url
        license:
          type: string
          title: License
          default: CC BY 4.0
        as_of:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: As Of
          description: As-of date of the static (carrier, state) records; filings carry their own dates.
        latest_filings:
          items:
            $ref: '#/components/schemas/CopperFilingRead'
          type: array
          title: Latest Filings
          description: Newest founder-approved filings (most recent 20, narrowed by the same filters).
      type: object
      required:
      - records
      - source
      - source_url
      title: CopperRetirementResponse
      description: Deterministic copper-retirement dataset slice for agent consumers.
    AgentSessionCreateResponse:
      properties:
        session_id:
          type: string
          format: uuid
          title: Session Id
        session_token:
          type: string
          title: Session Token
        claim_url:
          type: string
          title: Claim Url
        environment_summary:
          type: string
          title: Environment Summary
        missing_info:
          items:
            type: string
          type: array
          title: Missing Info
        fact_count:
          type: integer
          title: Fact Count
          default: 0
        disclosure:
          type: string
          title: Disclosure
          default: A human broker reviews every recommendation; supplier names and pricing come only after that review.
      type: object
      required:
      - session_id
      - session_token
      - claim_url
      - environment_summary
      title: AgentSessionCreateResponse
      description: Session handle returned exactly once at creation.
    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
    AgentSessionCreateRequest:
      properties:
        company_name:
          type: string
          maxLength: 255
          minLength: 1
          title: Company Name
        domain:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Domain
        site_count:
          anyOf:
          - type: integer
            maximum: 10000.0
            minimum: 1.0
          - type: 'null'
          title: Site Count
        current_providers:
          items:
            type: string
          type: array
          maxItems: 20
          title: Current Providers
        contract_end_dates:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Contract End Dates
        pain:
          type: string
          maxLength: 4000
          minLength: 1
          title: Pain
      type: object
      required:
      - company_name
      - pain
      title: AgentSessionCreateRequest
      description: Structured environment intro an external agent submits for its user.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CopperFilingRead:
      properties:
        carrier:
          type: string
          title: Carrier
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
        kind:
          type: string
          title: Kind
        filer:
          anyOf:
          - type: string
          - type: 'null'
          title: Filer
        docket:
          anyOf:
          - type: string
          - type: 'null'
          title: Docket
        filed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Filed At
        granted_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Granted At
        retirement_effective_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Retirement Effective At
        geography_detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Geography Detail
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
      type: object
      required:
      - carrier
      - state
      - kind
      - filer
      - docket
      - filed_at
      - granted_at
      - retirement_effective_at
      - geography_detail
      - source_url
      title: CopperFilingRead
      description: 'One founder-approved copper-retirement filing from the copper-watch detector.


        Public-filing facts only (FCC ECFS / carrier disclosure pages) — never

        prospect or buyer data. ``kind`` is the detector''s notice type

        (``ecfs_application`` | ``fcc_public_notice`` | ``fcc_grant`` |

        ``carrier_website_notice``).'
    AgentCallbackResponse:
      properties:
        status:
          type: string
          const: received
          title: Status
          default: received
        book_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Book Url
          description: Optional scheduling link the user may use to pick a time now. The callback is already queued; a broker reaches out either way.
        disclosure:
          type: string
          title: Disclosure
          default: A human broker reviews every recommendation; supplier names and pricing come only after that review.
      type: object
      title: AgentCallbackResponse
      description: Acknowledgement that a broker callback was recorded.
    AgentChatRequest:
      properties:
        message:
          type: string
          maxLength: 8000
          minLength: 1
          title: Message
        conversation_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Conversation Id
      type: object
      required:
      - message
      title: AgentChatRequest
      description: One advisor turn asked on behalf of the agent's user.
    AgentChatResponse:
      properties:
        assistant_message:
          type: string
          title: Assistant Message
        follow_up_questions:
          items:
            type: string
          type: array
          title: Follow Up Questions
        conversation_id:
          type: string
          format: uuid
          title: Conversation Id
        review_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Review Status
        claim_url:
          type: string
          title: Claim Url
        disclosure:
          type: string
          title: Disclosure
          default: A human broker reviews every recommendation; supplier names and pricing come only after that review.
      type: object
      required:
      - assistant_message
      - conversation_id
      - claim_url
      title: AgentChatResponse
      description: Buyer-safe advisor reply for an external agent.
    CopperRetirementRecord:
      properties:
        carrier:
          type: string
          title: Carrier
        state:
          type: string
          title: State
        retirement_date:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          title: Retirement Date
        status:
          type: string
          enum:
          - date_filed
          - program_active
          title: Status
        notes:
          type: string
          title: Notes
      type: object
      required:
      - carrier
      - state
      - retirement_date
      - status
      - notes
      title: CopperRetirementRecord
      description: One (carrier, state) copper-retirement program entry.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-Agent-API-Key
x-refined-from:
- chnlsync-com-openapi.json
- chnlsync-com-openapi.yml