confcall Rooms API

openapi: 3.2.0
info:
  title: Confcall App Rooms API
  version: post-phase-1
  x-canonical-url: https://docs.confcall.app/openapi/confcall-control-plane.json
  description: 'Operations tagged Rooms across 2 of this provider''s published API definitions: confcall-control-plane.json, confcall-app-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://meet.confcall.app
  description: Production
security:
- ApiKeyAuth: []
- OAuth2ClientCredentials:
  - confcall:rooms
  - confcall:history
tags:
- name: Rooms
paths:
  /api/rooms/{roomId}:
    get:
      operationId: getRoom
      summary: Read room metadata
      x-auth: public
      parameters:
      - name: roomId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Room metadata (coOrganizers only for the owner and co-organizers)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoomInfo'
        '404':
          description: Room not found
      tags:
      - Rooms
    delete:
      operationId: deleteRoom
      summary: Delete a room
      x-auth: jwtOrApiKey
      x-scope: confcall:rooms
      x-auth-note: 'Owner-scoped: a JWT must belong to the room''s human owner; an sk_ key must belong to the room''s account (RFC-Builder-Onboarding-And-Docs Phase 1). A different account''s key gets 403.'
      parameters:
      - name: roomId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Deleted
        '403':
          description: Caller does not own this room
        '404':
          description: Room not found
      tags:
      - Rooms
    servers:
    - url: https://meet.confcall.app
      description: Production
  /api/rooms/{roomId}/ai-agent/invite:
    post:
      operationId: inviteAiAgent
      summary: Invite the AI agent into a room
      x-auth: jwtOrApiKey
      x-scope: confcall:rooms
      x-auth-note: Owner/co-organizer (JWT) or the room's owning account (sk_ key). E2EE rooms refuse the agent (409) — confcall never distributes the room key to a server-side party.
      parameters:
      - name: roomId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  example: Notetaker
                inlineConfig:
                  type: object
                  properties:
                    language:
                      type: string
                      example: en
      responses:
        '200':
          description: Agent invited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiAgentInviteResult'
        '403':
          description: Caller is not an owner/co-organizer, or the key's account does not own the room
        '404':
          description: Room not found
        '409':
          description: Room is E2EE-enabled
        '503':
          description: AI Agent service unavailable
      tags:
      - Rooms
    servers:
    - url: https://meet.confcall.app
      description: Production
  /api/rooms/{roomId}/ai-agent/remove:
    post:
      operationId: removeAiAgent
      summary: Remove the AI agent from a room
      x-auth: jwtOrApiKey
      x-scope: confcall:rooms
      parameters:
      - name: roomId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Agent removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiAgentRemoveResult'
        '403':
          description: Caller is not an owner/co-organizer, or the key's account does not own the room
        '404':
          description: Room not found
        '503':
          description: AI Agent service unavailable
      tags:
      - Rooms
    servers:
    - url: https://meet.confcall.app
      description: Production
  /api/rooms/{roomId}/ai-agent/status:
    get:
      operationId: getAiAgentStatus
      summary: Check whether the AI agent is present in a room
      x-auth: public
      x-auth-note: 'Degrades to { agentPresent: false, available: false } rather than erroring when the downstream call can''t authenticate.'
      parameters:
      - name: roomId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Agent status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiAgentStatus'
        '404':
          description: Room not found
      tags:
      - Rooms
    servers:
    - url: https://meet.confcall.app
      description: Production
  /api/rooms/{roomId}/artifacts:
    get:
      operationId: listRoomArtifacts
      summary: List session artifacts (summarized) for a room
      x-auth: jwtOrApiKey
      x-scope: confcall:history
      x-auth-note: Owner/co-organizer/invited-member (JWT) or the room's owning account (sk_ key).
      parameters:
      - name: roomId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Artifact bundles for the room. Each bundle includes provenance { aiGenerated[], aiAssisted[], generator }; keep it when republishing
          content:
            application/json:
              schema:
                type: object
                properties:
                  artifacts:
                    type: array
                    items:
                      $ref: '#/components/schemas/ArtifactBundle'
        '403':
          description: Caller has no access to this room
      tags:
      - Rooms
    servers:
    - url: https://meet.confcall.app
      description: Production
components:
  schemas:
    AiAgentStatus:
      type: object
      properties:
        roomId:
          type: string
        agentPresent:
          type: boolean
        available:
          type: boolean
    AiAgentRemoveResult:
      type: object
      properties:
        message:
          type: string
        roomId:
          type: string
    ArtifactTurn:
      type: object
      properties:
        role:
          type: string
          enum:
          - user
          - agent
        content:
          type: string
        language:
          type:
          - string
          - 'null'
        intent:
          type:
          - string
          - 'null'
        timestamp:
          type: string
          format: date-time
    RoomInfo:
      type: object
      properties:
        roomId:
          type: string
        roomName:
          type:
          - string
          - 'null'
        shareableLink:
          type: string
        createdAt:
          type: string
          format: date-time
        lastActivityAt:
          type:
          - string
          - 'null'
          format: date-time
        isOwner:
          type: boolean
        isCoOrganizer:
          type: boolean
        isPublic:
          type: boolean
        requiresAuth:
          type: boolean
        coOrganizers:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CoOrganizer'
    AiAgentInviteResult:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        roomId:
          type: string
        mode:
          type: string
          example: Generic
        sessionId:
          type:
          - string
          - 'null'
        configId:
          type:
          - string
          - 'null'
          format: uuid
    ArtifactBundle:
      type: object
      properties:
        conferenceSessionId:
          type: string
        roomId:
          type: string
        accountId:
          type:
          - string
          - 'null'
        source:
          type: string
        startedAt:
          type: string
          format: date-time
        endedAt:
          type:
          - string
          - 'null'
          format: date-time
        turns:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactTurn'
        summaryText:
          type:
          - string
          - 'null'
        actionItems:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ArtifactActionItem'
        outcome:
          type:
          - string
          - 'null'
        decisions:
          type:
          - array
          - 'null'
          items:
            type: string
        followUps:
          type:
          - array
          - 'null'
          items:
            type: string
        structuredOutput:
          description: Free-form structured output, when the session produced one
        createdAt:
          type: string
          format: date-time
        provenance:
          type: object
          description: Which parts of the bundle are AI-generated (EU AI Act Art. 50(2)); computed on read
          properties:
            aiGenerated:
              type: array
              items:
                type: string
            aiAssisted:
              type: array
              items:
                type: string
            generator:
              type: string
            notice:
              type: string
              description: Ready-to-embed attribution for exported text; empty when nothing is AI-generated
    CoOrganizer:
      type: object
      properties:
        userId:
          type: string
        userEmail:
          type:
          - string
          - 'null'
        userName:
          type:
          - string
          - 'null'
        addedAt:
          type: string
          format: date-time
    ArtifactActionItem:
      type: object
      properties:
        description:
          type: string
        assignee:
          type:
          - string
          - 'null'
        dueDate:
          type:
          - string
          - 'null'
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: A confcall secret (sk_live_/sk_test_) API key. Publishable (pk_) keys are rejected on every route documented here.
    OAuth2ClientCredentials:
      type: oauth2
      description: 'OAuth 2.0 client-credentials grant. Exchange a client id/secret at the token URL for a short-lived bearer JWT and send it as `Authorization: Bearer <token>`. Operations with x-auth jwtOrApiKey accept either this or ApiKeyAuth; x-auth jwt operations need a user-context token.'
      flows:
        clientCredentials:
          tokenUrl: https://auth.confcall.app/oauth/token
          scopes:
            confcall:rooms: Manage rooms and invite/remove the AI agent
            confcall:history: Read meeting artifacts (transcripts, summaries, action items)
x-refined-from:
- confcall-control-plane.json
- confcall-app-openapi.yml