openapi: 3.0.3
info:
    title: roster
    description: The Roster service keeps a list of all available arbitrators and case administrators. Other parts of the system use it to pick the right people for new cases.
    version: 1.0.0
servers:
    - url: https://roster.platform.arb.inc
paths:
    /:
        get:
            summary: Get basic service information
            description: Returns a plain text welcome message with the service name and creation date.
            operationId: getRoot
            responses:
                '200':
                    description: Successfully retrieved welcome message.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Welcome to the roster service. Created on August 15, 2025 by Al Beebe
            tags:
                - /
    /arbitrators/confirm:
        post:
            summary: Confirm an arbitrator reservation
            description: Confirms a pending arbitrator reservation.
            operationId: confirmArbitratorReservation
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - reservationID
                            properties:
                                reservationID:
                                    type: string
                                    format: uuid
                                    description: The reservation ID to confirm.
                                    example: "c17c3433-81b3-4096-90e0-9fbb32c06204"
            responses:
                '200':
                    description: Reservation successfully confirmed.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "reservation successfully confirmed"
                '404':
                    description: The specified reservation could not be found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "reservation not found"
            tags:
                - arbitrators
    /arbitrators/release:
        post:
            summary: Release an arbitrator reservation
            description: Releases an active arbitrator reservation.
            operationId: releaseArbitratorReservation
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - reservationID
                            properties:
                                reservationID:
                                    type: string
                                    format: uuid
                                    description: The reservation ID to release.
                                    example: "c17c3433-81b3-4096-90e0-9fbb32c06204"
            responses:
                '200':
                    description: Reservation successfully released.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "reservation successfully released"
                '404':
                    description: The specified reservation could not be found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "reservation not found"
            tags:
                - arbitrators
    /arbitrators/reserve:
        post:
            summary: Reserve an arbitrator
            description: Reserves an available arbitrator for the provided case.
            operationId: reserveArbitrator
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                            properties:
                                caseID:
                                    type: string
                                    description: ID of the case to reserve an arbitrator for. Must be 1–36 characters.
                                    example: "2025-08-00091"
            responses:
                '200':
                    description: Reservation successfully created.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    reservationID:
                                        type: string
                                        format: uuid
                                        description: Unique ID of the reservation.
                                        example: "c17c3433-81b3-4096-90e0-9fbb32c06204"
                                    userID:
                                        type: string
                                        format: uuid
                                        description: UUID of the assigned arbitrator user.
                                        example: "9fe1c0e3-8b1d-42a5-9b0a-1d2f3a4b5c6d"
                                    organizationID:
                                        type: string
                                        format: uuid
                                        nullable: true
                                        description: UUID of the arbitrator's organization; null if none.
                                        example: "6a7b8c9d-0e1f-2345-6789-ab0c1d2e3f45"
                                    expires:
                                        type: string
                                        format: date-time
                                        description: ISO 8601 timestamp when the reservation will expire.
                                        example: "2025-08-15T14:30:00Z"
                '409':
                    description: An arbitrator is already assigned to this case.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "arbitrator already assigned to this case"
                '410':
                    description: No arbitrators are currently available.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "no arbitrators are available"
            tags:
                - arbitrators
    /case-administrators/confirm:
        post:
            summary: Confirm a case administrator reservation
            description: Confirms a pending case-administrator reservation.
            operationId: confirmCaseAdministratorReservation
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - reservationID
                            properties:
                                reservationID:
                                    type: string
                                    format: uuid
                                    description: The reservation ID to confirm.
                                    example: "c17c3433-81b3-4096-90e0-9fbb32c06204"
            responses:
                '200':
                    description: Reservation successfully confirmed.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "reservation successfully confirmed"
                '404':
                    description: The specified reservation could not be found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "reservation not found"
            tags:
                - case-administrators
    /case-administrators/release:
        post:
            summary: Release a case administrator reservation
            description: Releases an active case-administrator reservation.
            operationId: releaseCaseAdministratorReservation
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - reservationID
                            properties:
                                reservationID:
                                    type: string
                                    format: uuid
                                    description: The reservation ID to release.
                                    example: "c17c3433-81b3-4096-90e0-9fbb32c06204"
            responses:
                '200':
                    description: Reservation successfully released.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "reservation successfully released"
                '404':
                    description: The specified reservation could not be found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "reservation not found"
            tags:
                - case-administrators
    /case-administrators/reserve:
        post:
            summary: Reserve a case administrator
            description: Reserves an available case administrator for the provided case.
            operationId: reserveCaseAdministrator
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                            properties:
                                caseID:
                                    type: string
                                    description: ID of the case to reserve an administrator for. Must be 1–36 characters.
                                    example: "2025-08-00091"
            responses:
                '200':
                    description: Reservation successfully created.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    reservationID:
                                        type: string
                                        format: uuid
                                        description: Unique ID of the reservation.
                                        example: "c17c3433-81b3-4096-90e0-9fbb32c06204"
                                    userID:
                                        type: string
                                        format: uuid
                                        description: UUID of the assigned case administrator user.
                                        example: "9fe1c0e3-8b1d-42a5-9b0a-1d2f3a4b5c6d"
                                    organizationID:
                                        type: string
                                        format: uuid
                                        nullable: true
                                        description: UUID of the administrator's organization; null if none.
                                        example: "6a7b8c9d-0e1f-2345-6789-ab0c1d2e3f45"
                                    expires:
                                        type: string
                                        format: date-time
                                        description: ISO 8601 timestamp when the reservation will expire.
                                        example: "2025-08-15T14:30:00Z"
                '409':
                    description: A case administrator is already assigned to this case.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "case administrator already assigned to this case"
                '410':
                    description: No case administrators are currently available.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "no case administrators are available"
            tags:
                - case-administrators
components:
    securitySchemes:
        bearerAuth:
            type: http
            description: access token
            scheme: bearer
            bearerFormat: JWT
tags:
    - name: /
    - name: arbitrators
    - name: case-administrators