openapi: 3.1.0
info:
  title: CDOA Human Match API
  version: 0.1.0
  description: Request optional human matches from minimized AI session summaries.
servers:
  - url: https://api.cdoa.io
paths:
  /api/users:
    post:
      operationId: createUser
      summary: Create a CDOA public profile
      description: Creates an opt-in profile for human matching. Do not include secrets or raw chat logs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: Created user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '400':
          description: Invalid profile input
  /api/llm/session-match:
    post:
      operationId: requestHumanMatch
      summary: Request human matches from a minimized AI session summary
      description: Creates an active LMGram request from a short privacy-preserving summary, then compares it with other active requests using embedding distance. Ask for consent first. Never send raw transcripts, secrets, API keys, or private documents. It is normal for requests to be empty when no sufficiently similar active request exists yet; the request remains available for future matches.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionMatchRequest'
      responses:
        '200':
          description: Created session and match requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionMatchResponse'
        '400':
          description: Invalid match request
        '404':
          description: Requester user was not found
components:
  schemas:
    CreateUserRequest:
      type: object
      required:
        - displayName
      properties:
        displayName:
          type: string
          description: Public display name for the CDOA profile.
        bio:
          type: string
          description: Short public bio. Do not include private or sensitive data.
        timezone:
          type: string
          description: User timezone.
        languages:
          type: array
          description: Languages the user is comfortable using.
          items:
            type: string
        interests:
          type: array
          description: Topics the user is interested in.
          items:
            type: string
        offers:
          type: array
          description: Things the user can help others with.
          items:
            type: string
        needs:
          type: array
          description: Things the user wants help or peers for.
          items:
            type: string
        isAvailable:
          type: boolean
          description: Whether the user is open to match requests.
          default: true
    UserProfile:
      type: object
      properties:
        id:
          type: string
          description: Internal ID. Humans should normally use publicId instead.
        publicId:
          type: string
          description: Friendly LMGram user ID to use when GPT asks who is requesting the match. Example: damian-saez.
        displayName:
          type: string
        bio:
          type: string
        timezone:
          type: string
        languages:
          type: array
          items:
            type: string
        interests:
          type: array
          items:
            type: string
        offers:
          type: array
          items:
            type: string
        needs:
          type: array
          items:
            type: string
        isAvailable:
          type: boolean
        createdAt:
          type: string
          format: date-time
    SessionMatchRequest:
      type: object
      required:
        - requesterId
        - provider
        - topic
        - summary
        - need
      properties:
        requesterId:
          type: string
          description: Friendly LMGram user shown in the app, not a random GUID. Ask the user to open Profile and copy the line "Tell GPT my LMGram user is ...". Example: damian-saez.
          examples:
            - damian-saez
        provider:
          type: string
          enum:
            - chatgpt
            - grok
            - mobile-mock
            - smoke-test
          default: chatgpt
        topic:
          type: string
          description: Short title for the current session topic.
        summary:
          type: string
          description: Minimized summary of the user's current request. Write it in natural language with enough context for embedding similarity. Do not send raw transcripts.
        need:
          type: string
          description: The concrete human connection the user wants, phrased colloquially and explicitly enough to compare with other active requests.
        matchType:
          type: string
          enum:
            - peer
            - mentor
            - collaborator
            - helper
          default: peer
        urgency:
          type: number
          minimum: 0
          maximum: 1
          default: 0.5
        sensitivity:
          type: string
          enum:
            - normal
            - sensitive
            - high
          default: normal
        language:
          type: string
          description: Preferred language for the match.
        maxCandidates:
          type: integer
          minimum: 1
          maximum: 20
          default: 5
    SessionMatchResponse:
      type: object
      properties:
        session:
          type: object
          description: Created CDOA session record.
        requests:
          type: array
          description: Match requests created by CDOA.
          items:
            type: object
