openapi3.yaml

openapi: 3.0.0
info:
  title: Pagecall Public API - OpenAPI 3.0
  description: |-
    This is a official Pagecall API Documents written in OpenAPI 3.0.
    Responses from the Pagecall API may contain more information, but what is not stated in this document may change at any time without any notice.
  termsOfService: https://pplink.notion.site/774e4131813b47f8b06e3da4524604e8
  contact:
    email: support@pagecall.com
  version: 1.0.0
servers:
  - url: https://api.pagecall.com/v1
tags:
  - name: room
    description: Operations about room resources
paths:
  /rooms:
    get:
      security:
        - ApiKeyAuth: []
      tags: [room]
      summary: List Rooms
      description: List all accessible rooms
      operationId: listRooms
      parameters:
        - in: query
          name: offset
          schema:
            type: integer
          description: The number of items to skip before starting to collect the result set
        - in: query
          name: limit
          schema:
            type: integer
          description: The numbers of items to return
        - in: query
          name: name
          schema:
            type: string
          description: Exact name of the room to search.
        - in: query
          name: layout
          schema:
            type: string
          description: Layout name to search.
        - in: query
          name: is_terminated
          schema:
            type: boolean
          description: Filter rooms by their termination status
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  rooms:
                    type: array
                    items:
                      $ref: "#/components/schemas/Room"
                    example:
                      - id: "000585f36eed9e8fb6b655b4"
                        type: "private"
                        name: "Monthly Meeting Room with Design Class"
                      - id: "000235f36efd9e8db6bc55b4"
                        type: "public"
                        name: "Daily Meet"
                      - id: "000935fc6efd9f8db61c35b4"
                        type: "open"
                        name: "Free Disgn Class"
                  paging:
                    $ref: "#/components/schemas/Paging"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
    post:
      security:
        - ApiKeyAuth: []
      tags: [room]
      summary: Create Room
      description: Create a new room
      operationId: createRoom
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRoomRequest"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  room:
                    $ref: "#/components/schemas/Room"
                  paging:
                    $ref: "#/components/schemas/Paging"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
  /rooms/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: room id
        example: 000585f36eed9e8fb6b655b4
    get:
      security:
        - ApiKeyAuth: []
      tags: [room]
      summary: Get Room
      description: Get a single room info
      operationId: getRoom
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  room:
                    $ref: "#/components/schemas/Room"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
    put:
      security:
        - ApiKeyAuth: []
      tags: [room]
      summary: Update Room
      description: Update some of room settings
      operationId: updateRoom
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRoomRequest"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  room:
                    $ref: "#/components/schemas/Room"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
    delete:
      security:
        - ApiKeyAuth: []
      tags: [room]
      summary: Delete Room
      description: Delete room
      operationId: deleteRoom
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  room:
                    $ref: "#/components/schemas/Room"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
  /rooms/{room_id}/sessions:
    parameters:
      - in: path
        name: room_id
        required: true
        schema:
          type: string
        example: 000585f36eed9e8fb6b655b4
    get:
      security:
        - ApiKeyAuth: []
      tags: [room]
      summary: Get Sessions in a Room
      description: Get a list of sessions in a meeting room
      operationId: GetRoomSessions
      parameters:
        - in: query
          name: user_id
          description: (Optional) Filter by user_id
          schema:
            type: string
        - in: query
          name: is_connecting
          description: (Optional) Filter by their online status
          schema:
            type: boolean
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessions:
                    type: array
                    items:
                      $ref: "#/components/schemas/Session"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
  /rooms/{room_id}/pages/create_many:
    parameters:
      - in: path
        name: room_id
        required: true
        schema:
          type: string
        description: room id
        example: 000585f36eed9e8fb6b655b4
    post:
      security:
        - ApiKeyAuth: []
      tags: [room]
      summary: Create Pages For Room
      description: Create new pages in a meeting room (Bulk API)
      operationId: CreateRoomsPage
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: "#/components/schemas/Page"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  pages:
                    type: array
                    description: Created pages
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        entities:
                          $ref: "#/components/schemas/Entity"
                    example:
                      - id: "000585f36eed9e8fb6b655b4"
                        entities:
                          - type: Image
                            src: "https://picsum.photos/id/237/536/354"
                      - id: "000585f36eed9e8fb6b655b5"
                        entities:
                          - type: Image
                            src: "https://picsum.photos/id/237/536/354"
                          - type: Image
                            src: "https://picsum.photos/id/237/536/354"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
  /rooms/{room_id}/members:
    parameters:
      - in: path
        name: room_id
        required: true
        schema:
          type: string
        description: room id
        example: 000585f36eed9e8fb6b655b4
    get:
      security:
        - ApiKeyAuth: []
      tags: [member]
      summary: List Members
      description: List Joined in the Room
      operationId: ListMembers
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    example:
                      - id: "000585f36eed9e8fb6b655b4"
                        user_id: external_user_20312
                        room_id: 000585f36eed9e8fb6b655b4
                        type: "host"
                      - id: "000585f36eed9e8fb6b655b4"
                        user_id: external_user_102932
                        room_id: 000585f36eed9e8fb6b655b4
                        type: "guest"
                    items:
                      $ref: "#/components/schemas/Member"
                  paging:
                    $ref: "#/components/schemas/Paging"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
    post:
      security:
        - ApiKeyAuth: []
      tags: [member]
      summary: Create Members
      description: Add Member to the Room
      operationId: CreateMember
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateMemberRequest"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - member
                properties:
                  member:
                    $ref: "#/components/schemas/Member"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
  /rooms/{room_id}/members/{member_id}:
    parameters:
      - in: path
        name: room_id
        required: true
        schema:
          type: string
        description: room id
        example: 000585f36eed9e8fb6b655b4
      - in: path
        name: member_id
        required: true
        schema:
          type: string
        description: member id
        example: external_user_102932
    get:
      security:
        - ApiKeyAuth: []
      tags: [member]
      summary: Get Member
      description: Get Member
      operationId: GetMember
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - member
                properties:
                  member:
                    $ref: "#/components/schemas/Member"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
    put:
      security:
        - ApiKeyAuth: []
      tags: [member]
      summary: Update Member
      description: Update Member
      operationId: UpdateMember
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateMemberRequest"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - member
                properties:
                  member:
                    $ref: "#/components/schemas/Member"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
  /rooms/{room_id}/message:
    parameters:
      - in: path
        name: room_id
        required: true
        schema:
          type: string
        description: room id
        example: 000585f36eed9e8fb6b655b4
    post:
      security:
        - ApiKeyAuth: []
      tags: [user]
      summary: Send a message to a room
      description: Send a message to live sessions in a room
      operationId: roomsSendMessage
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
  /users:
    get:
      security:
        - ApiKeyAuth: []
      tags: [user]
      summary: List Users
      description: List users within workspace
      operationId: ListUsers
      parameters:
        - in: query
          name: email_search_query
          schema:
            type: string
          description: Filter users by their email
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - users
                properties:
                  users:
                    type: array
                    items:
                      $ref: "#/components/schemas/User"
                    example:
                      - user_id: "user-1"
                        name: "John"
                        default_member_type: "guest"
                        access_token: "lw11gv95db-QcA3bDvuBQVomEmkAq1G-"
                        id: "642cdbef85fd90a348d9da1a"
                      - user_id: "user-2"
                        name: "Mike"
                        default_member_type: "guest"
                        access_token: "db32gv15d9-QcA3bDvuBQVomEmkAq1G-"
                        id: "642cdbef85fd90a348d9da1a"
                  paging:
                    $ref: "#/components/schemas/Paging"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
    post:
      security:
        - ApiKeyAuth: []
      tags: [user]
      summary: Create User
      description: Create user within workspace
      operationId: createUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: "#/components/schemas/User"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
  /users/{user_id}:
    parameters:
      - in: path
        name: user_id
        required: true
        schema:
          type: string
        description: "`user_id` of the user"
        example: external_user_102932
    get:
      security:
        - ApiKeyAuth: []
      tags: [user]
      summary: Get User
      description: Get user with user id
      operationId: GetUser
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - users
                properties:
                  user:
                    $ref: "#/components/schemas/User"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
    put:
      security:
        - ApiKeyAuth: []
      tags: [user]
      summary: Update User
      description: Update user with user id
      operationId: UpdateUser
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - users
                properties:
                  user:
                    $ref: "#/components/schemas/User"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
    delete:
      security:
        - ApiKeyAuth: []
      tags: [user]
      summary: Delete User
      description: Delete user with user id
      operationId: DeleteUser
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                required:
                  - users
                properties:
                  user:
                    $ref: "#/components/schemas/User"
        "400":
          description: Invalid Parameters Supplied or Unauthenticated or Unauthorized
        "500":
          description: Validation exception
components:
  schemas:
    Paging:
      description: Details of pagination used for current responses.
      type: object
      required:
        - limit
        - offset
        - total
      properties:
        limit:
          type: number
          default: 30
        offset:
          type: number
          default: 0
        total:
          type: number
          example: 0
    Room:
      description: Information about room
      required:
        - id
        - type
        - name
      properties:
        id:
          type: string
          example: 000585f36eed9e8fb6b655b4
          description: ID of the room
        application_id:
          type: string
          example: 000585f36eed9e8fb6b655b4
          description: ID of the workspace
        type:
          $ref: "#/components/schemas/RoomType"
        created_user_id:
          type: string
          example: "#DEPRECATED#"
          description: "*[Deprecated]* ID of the user who create this room"
        name:
          type: string
          example: "Weekly Meet"
          description: Human readable name of the room
        thumbnail_url:
          type: string
          example: https://example.url/thumbnail.png
          description: Generated thumbnail for this room
        last_thumbnail_updated_at:
          type: string
          example: "#DEPRECATED#"
          description: "*[Deprecated]* Last update time of generated thumbnail"
          format: date-time
        room_template_id:
          type: string
          example: "#DEPRECATED#"
          description: "*[Deprecated]* **Use `layout` instead.** ID of the room template used by this room"
        layout:
          type: string
          example: "SixAll"
          description: "How the room looks"
        record:
          type: boolean
          description: Whether this room is recorded or not.
        meeting_time:
          type: integer
          example: 200000
          description: Total meeting time in seconds
        is_terminated:
          type: boolean
          example: "#DEPRECATED#"
          description: "*[Deprecated]* **Use `terminated_at` instead.** Whether this room is terminated or not. If true, not available to join the room"
        is_ephemeral:
          type: boolean
          example: "#DEPRECATED#"
          description: "*[Deprecated]* Whether this room is for temporary or not. If true and all the members of this room leave, the room will be closed"
        is_recurring:
          type: boolean
          example: "#DEPRECATED#"
          description: "*[Deprecated]* Whether this meeting occurs regularly or not. If true, it will be reopened according to a predefined schedule."
        started_at:
          example: "2023-01-01T01:00:00.000Z"
          type: string
          description: The meeting is started at specified time format
          format: date-time
        terminated_at:
          example: "2023-01-01T01:00:00.000Z"
          type: string
          description: The room is terminated at specified time format
          format: date-time
        updated_at:
          example: "2023-01-01T01:00:00.000Z"
          type: string
          description: The room settings are changed at specified time format
          format: date-time
        created_at:
          example: "2023-01-01T01:00:00.000Z"
          type: string
          description: The room is created at specified time format
          format: date-time
    MemberType:
      type: string
      description: |
        Type of user in this room
        - guest: The user is guest.
        - host: The user is host. This user has administrator privileges.
        - monitor: The user is observer. Can watch the meeting, but can not join.
      enum:
        - guest
        - host
        - monitor
      example: guest
      default: guest
    RoomMember:
      type: object
      description: Information about the member joined the room
      required:
        - user_id
        - type
      properties:
        user_id:
          type: string
          description: "`user_id` of the user in application (workspace) scope"
          example: 000585f36eed9e8fb6b655b4
        type:
          $ref: "#/components/schemas/MemberType"
        name:
          type: string
          description: Display name of the user in the meeting room
          example: user-1
    RoomType:
      type: string
      description: |
        Room can have three different type

        * `open`    - anyone who obtain this room url can join and replay the meet.
        * `public`  - any member who haved joined in same worksapce can join and replay the meet.
        * `private` - only invited workspace user can join and replay the meet.
      enum:
        - open
        - public
        - private
      example: public
    UpdateRoomRequest:
      type: object
      description: Request format to update setting of exisiting room
      required:
        - application_id
      properties:
        name:
          type: string
          description: Set this to chagne current room name
          example: "Monthly Meetting - 2"
        is_terminated:
          type: boolean
          description: Set true to close this room
          default: false
    CreateRoomRequest:
      type: object
      description: Request format to create a new room
      required:
        - name
        - type
      properties:
        name:
          type: string
          description: Human-readable name of the room
          example: "Meeting Room - 1"
        type:
          $ref: "#/components/schemas/RoomType"
        record:
          type: boolean
          description: All meeting will be recorded
          default: true
        max_meeting_seconds:
          type: integer
          description:
            Determines the maximum meeting time in seconds. Once this time has elapsed, the meeting room will be automatically terminated.
            The 'meeting time' refers to the duration during which two or more participants are connected. If a `max_meeting_seconds` is set, the timer UI will display the remaining meeting time, rather than the elapsed time.
        members:
          type: array
          description: Specify inviting user_id and type
          items:
            $ref: "#/components/schemas/RoomMember"
        webhook:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              description: an URL to which the Pagecall server will send the webhook
            headers:
              type: object
              description: Headers to include when sending the webhook, which can be useful when authentication is required.

    # @scotty: UpdateUserRequest ⊂ CreateUserRequest ⊂ User,
    # However, we can not use "allOf" feature in openapi as mintlify dose not recognize "allOf" properties properly
    User:
      type: object
      properties:
        user_id:
          type: string
          description: "ID of the user. Will override exisiting user if the specified ID already being used. Please note that `id` field is only used internally."
          example: external_user_102932
        name:
          type: string
          description: Name of the user.
          example: scotty
        profile_url:
          type: string
          example: https://www.gravatar.com/avatar/00000000000000000000000000000000?d=mp&f=y
          description: Profile image of the user
        default_member_type:
          description: Default type of member when invited to room
          default: "guest"
          $ref: "#/components/schemas/MemberType"
        access_token:
          type: string
          description: Access token to authenticate as the user.
          example: "TfowtRYBs0E_trzoTaCmAXKzB1JxDDhi"
        created_at:
          type: string
          example: "2023-01-01T01:00:00.000Z"
          description: Creation time of the user
          format: date-time
        updated_at:
          type: string
          example: "2023-01-01T01:00:00.000Z"
          description: Last modified time of the user
          format: date-time
    CreateUserRequest:
      type: object
      required:
        - user_id
      properties:
        user_id:
          type: string
          description: "ID of the user. Will override exisiting user if the specified ID already being used. Please note that `id` field is only used internally."
          example: "external_user_102932"
        name:
          type: string
          description: Name of the user.
          example: scotty
        profile_url:
          type: string
          example: https://www.gravatar.com/avatar/00000000000000000000000000000000?d=mp&f=y
          description: Profile image of the user
        default_member_type:
          description: Default type of member when invited to room
          default: "guest"
          $ref: "#/components/schemas/MemberType"
    UpdateUserRequest:
      type: object
      properties:
        name:
          type: string
          description: Name of the user.
          example: scotty
        profile_url:
          type: string
          example: https://www.gravatar.com/avatar/00000000000000000000000000000000?d=mp&f=y
          description: Profile image of the user
        default_member_type:
          description: Default type of member when invited to room
          default: "guest"
          $ref: "#/components/schemas/MemberType"
    Member:
      type: object
      required:
        - id
        - user_id
        - room_id
        - type
      properties:
        id:
          type: string
          description: generated member id
          example: 642d103ce95bc9dc22ef789f
        user_id:
          type: string
          description: "`user_id` of the user."
          example: "external_user_102932"
        room_id:
          type: string
          example: 000585f36eed9e8fb6b655b4
          description: ID of the room
        type:
          $ref: "#/components/schemas/MemberType"
    CreateMemberRequest:
      type: object
      required:
        - user_id
      properties:
        user_id:
          type: string
          description: "`user_id` of the user."
          example: "external_user_102932"
        type:
          $ref: "#/components/schemas/MemberType"
    UpdateMemberRequest:
      type: object
      properties:
        name:
          type: string
          description: Change display name in meeting room
        type:
          $ref: "#/components/schemas/MemberType"
        is_blocked:
          type: boolean
          description: Kick the user from the room immediately, Works only on private type meeting room.
    EntityType:
      type: string
      description: |
        Type of entity in a page. Currently, manipulation through the API is only allowed for Image entities.
        - Image: Image
      enum:
        - Image
      example: Image
    Entity:
      type: object
      required:
        - type
      properties:
        type:
          $ref: "#/components/schemas/EntityType"
        src:
          type: string
          description: Source url (required for Image)
          example: "https://picsum.photos/id/237/536/354"
        fixed:
          type: boolean
          description: If true, entity is created in a locked state
    Page:
      type: object
      properties:
        entities:
          type: array
          items:
            $ref: "#/components/schemas/Entity"
        size:
          type: object
          description: Size of a page
          required:
            - width
            - height
          properties:
            width:
              type: integer
            height:
              type: integer
          default:
            width: 4000
            height: 3000
        index:
          type: integer
    Session:
      type: object
      required:
        - id
        - member_id
      properties:
        id:
          type: string
          description: ID of the session
          example: 000585f36eed9e8fb6b655b4
        member_id:
          type: string
          description: ID for the member associated with the session
          example: 000585f36eed9e8fb6b655b4
        user_id:
          type: string
          description: ID for the user associated with the session. It can be empty if the session represents an anonymous user.
          example: 000585f36eed9e8fb6b655b4
        connected_at:
          type: string
          description: Datetime when the session was established
          example: "2023-01-01T01:00:00.000Z"
        disconnected_at:
          type: string
          description: Datetime when the session was ended. It can be empty if the session is online.
          example: "2023-01-01T01:30:00.000Z"

  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: token