openapi: 3.1.0
info:
  title: LMGram Human Match API
  version: 0.1.0
  description: Request optional human matches from minimized AI session summaries.
servers:
  - url: https://api.lmgram.com
paths:
  /api/me:
    get:
      operationId: getCurrentUser
      summary: Get the current linked LMGram profile
      description: Returns the LMGram profile linked through OAuth account linking.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Current LMGram profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          description: Missing or invalid OAuth token
  /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. The similarity threshold is dynamic: it is more flexible while the active request pool is small and becomes stricter as more requests exist.
      security:
        - bearerAuth: []
      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
        '401':
          description: Missing or invalid OAuth token
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    CreateUserRequest:
      type: object
      required:
        - displayName
      properties:
        displayName:
          type: string
          description: Public display name for the LMGram 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:
        - provider
        - topic
        - summary
        - need
      properties:
        requesterId:
          type: string
          description: Internal testing fallback only. OAuth-authenticated ChatGPT calls should omit this field because LMGram identifies the requester from the bearer token.
          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 LMGram session record.
        requests:
          type: array
          description: Match requests created by LMGram.
          items:
            type: object
        matchingQueued:
          type: boolean
          description: True when LMGram accepted the intent and will compute matches asynchronously.
          default: false
