openapi: 3.0.3
info:
    title: api
    description: The API service is the secure public gateway to our platform, letting people access features without touching our private internal APIs. It authenticates clients with its own internal tokens and then routes their requests to the right internal services behind the scenes.
    version: 1.0.0
servers:
    - url: https://api.arb.inc
paths:
    /cases/create:
        post:
            summary: Create a case
            description: >
                Creates a new arbitration case for the authenticated user's organization.
                All fields are optional — calling with an empty body creates a case with
                default settings (14-day response period, default ruleset).
            operationId: createCase
            security:
                - bearerAuth: []
            requestBody:
                required: false
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                ruleset:
                                    type: string
                                    description: >
                                        Identifier for the arbitration ruleset to apply to this case.
                                        Must be between 1 and 50 characters.
                                    default: "default"
                                    example: "default"
                                responseDeadlineDays:
                                    type: integer
                                    description: >
                                        The number of calendar days the respondent is given to
                                        respond to the case before it may proceed without them
                                        (ex parte). See [Arbitration.Inc Rules](https://arbitration.inc/rules) Article 5.
                                    enum: [14, 21, 30]
                                    default: 14
                                    example: 14
                                claimantCoversRespondentFees:
                                    type: boolean
                                    description: >
                                        When true, the claimant absorbs all respondent filing fees,
                                        so the respondent is not charged to participate.
                                    default: false
                                    example: false
            responses:
                '200':
                    description: Case successfully created.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    caseID:
                                        type: string
                                        description: Unique ID of the new case.
                                        example: "2025-08-00292"
                                    title:
                                        type: string
                                        description: Short title for the case.
                                        example: "Case 2025-08-00292"
                '400':
                    description: >
                        Invalid request. Possible reasons: user is not part of an organization,
                        invalid responseDeadlineDays value, invalid ruleset, or user has a
                        restricted role (arbitrator or case manager).
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "responseDeadlineDays must be 14, 21, or 30"
                '402':
                    description: Insufficient credits to create a case.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    error:
                                        type: string
                                        example: "insufficient_credits"
                                    message:
                                        type: string
                                        example: "Insufficient credits to file a case. Please purchase more credits."
                                    required:
                                        type: number
                                        description: Number of credits required.
                                        example: 1
                '403':
                    description: User has reached the maximum number of active cases.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "too many active cases"
            tags:
                - cases
    /cases/list:
        post:
            summary: List active cases for the signed-in user
            description: Returns the user's active cases with simple pagination via a cursor.
            operationId: listCases
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                cursor:
                                    type: string
                                    format: date-time
                                    nullable: true
                                    description: Return cases created after this timestamp.
                                    example: "2025-07-15T10:20:30Z"
                        examples:
                            default:
                                summary: Start from a timestamp
                                value:
                                    cursor: "2025-07-15T10:20:30Z"
            responses:
                '200':
                    description: Cases successfully listed.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    cases:
                                        type: array
                                        description: List of active cases for the user.
                                        items:
                                            type: object
                                            properties:
                                                overview:
                                                    type: object
                                                    description: Summary information about the case.
                                                    properties:
                                                        id:
                                                            type: string
                                                            description: Unique identifier for the case.
                                                            example: "2025-08-00125"
                                                        created:
                                                            type: string
                                                            format: date-time
                                                            description: When the case was created.
                                                            example: "2025-07-01T09:12:45Z"
                                                        updated:
                                                            type: string
                                                            format: date-time
                                                            description: When the case was last updated.
                                                            example: "2025-07-20T14:03:11Z"
                                                        createdByUserID:
                                                            type: string
                                                            description: ID of the user who created the case.
                                                            example: "2720f109-0caf-4c62-af22-5d08c853711c"
                                                        createdByOrgID:
                                                            type: string
                                                            nullable: true
                                                            description: Organization ID that created the case, if any.
                                                            example: "cfb40d07-6160-4cbc-899e-5541dec01394"
                                                        phaseID:
                                                            type: string
                                                            description: Current phase identifier.
                                                            example: "caseInitiation"
                                                        title:
                                                            type: string
                                                            description: Human-readable title for the case.
                                                            example: "Case 2025-08-00125"
                                                participants:
                                                    type: array
                                                    description: People or entities involved in the case.
                                                    items:
                                                        type: object
                                                        properties:
                                                            created:
                                                                type: string
                                                                format: date-time
                                                                description: When the participant was added.
                                                                example: "2025-07-02T10:00:00Z"
                                                            userID:
                                                                type: string
                                                                description: ID of the participant user.
                                                                example: "2b7bd450-342a-47c8-8759-9276e5119be4"
                                                            organizationID:
                                                                type: string
                                                                nullable: true
                                                                description: Organization ID tied to the participant.
                                                                example: "4190c6ca-647d-4d99-b8b3-991b30ebb378"
                                                            partyID:
                                                                type: string
                                                                description: Participant party role.
                                                                example: "claimant"
                                                            isPrimary:
                                                                type: boolean
                                                                description: Whether this participant is the primary representative.
                                                                example: true
                                                            isObserver:
                                                                type: boolean
                                                                description: Whether this participant is an observer.
                                                                example: false
                                                partyID:
                                                    type: string
                                                    description: Users party in the case.
                                                    example: "claimant"
                                    cursor:
                                        type: string
                                        format: date-time
                                        nullable: true
                                        description: Cursor for fetching the next page (created time of the last case).
                                        example: "2025-07-20T14:03:11Z"
                                    moreCases:
                                        type: boolean
                                        description: Indicates if more cases are available to fetch.
                                        example: true
                            examples:
                                default:
                                    summary: Example response
                                    value:
                                        cases:
                                            - overview:
                                                id: "2025-08-00125"
                                                created: "2025-07-01T09:12:45Z"
                                                updated: "2025-07-20T14:03:11Z"
                                                createdByUserID: "2720f109-0caf-4c62-af22-5d08c853711c"
                                                createdByOrgID: "cfb40d07-6160-4cbc-899e-5541dec01394"
                                                phaseID: "caseInitiation"
                                                title: "Case 2025-08-00125"
                                              participants:
                                                - created: "2025-07-02T10:00:00Z"
                                                  userID: "2b7bd450-342a-47c8-8759-9276e5119be4"
                                                  organizationID: "4190c6ca-647d-4d99-b8b3-991b30ebb378"
                                                  partyID: "claimant"
                                                  isPrimary: true
                                                  isObserver: false
                                                - created: "2025-07-02T10:05:00Z"
                                                  userID: "65edccfa-93f6-4dd5-9421-2b3e1ffe856c"
                                                  organizationID: null
                                                  partyID: "caseAdministrator"
                                                  isPrimary: false
                                                  isObserver: false
                                              partyID: claimant
                                        cursor: "2025-07-20T14:03:11Z"
                                        moreCases: true
            tags:
                - cases
    /cases/view:
        post:
            summary: View a case
            description: Returns a simple snapshot of a case the user can access.
            operationId: postCasesView
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                            properties:
                                caseID:
                                    type: string
                                    description: The identifier of the case to view.
                                    example: "2025-08-00139"
            responses:
                '200':
                    description: Case overview, participants, and timetable.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    overview:
                                        type: object
                                        properties:
                                            id:
                                                type: string
                                                description: Unique identifier for the case.
                                                example: "2025-08-00139"
                                            created:
                                                type: string
                                                format: date-time
                                                description: When the case was created.
                                                example: "2025-08-23T02:47:42Z"
                                            updated:
                                                type: string
                                                format: date-time
                                                description: When the case was last updated.
                                                example: "2025-08-23T02:47:42Z"
                                            createdByUserID:
                                                type: string
                                                description: ID of the user who created the case.
                                                example: "00c573fd-18d9-4fbe-921e-6926d2c4869e"
                                            createdByOrgID:
                                                type: string
                                                nullable: true
                                                description: ID of the organization that created the case, if any.
                                                example:
                                            phaseID:
                                                type: string
                                                description: Current phase identifier.
                                                example: "caseInitiation"
                                            title:
                                                type: string
                                                description: Human-friendly title for the case.
                                                example: "Case 2025-08-00139"
                                            canSubmitEvidence:
                                                type: boolean
                                                description: Whether parties can currently submit evidence.
                                                example: true
                                    participants:
                                        type: array
                                        description: List of case participants.
                                        items:
                                            type: object
                                            properties:
                                                created:
                                                    type: string
                                                    format: date-time
                                                    description: When the participant was added.
                                                    example: "2025-08-23T02:47:42Z"
                                                userID:
                                                    type: string
                                                    description: ID of the participant user.
                                                    example: "00c573fd-18d9-4fbe-921e-6926d2c4869e"
                                                organizationID:
                                                    type: string
                                                    nullable: true
                                                    description: Organization ID of the participant, if any.
                                                    example:
                                                partyID:
                                                    type: string
                                                    description: Role of the participant.
                                                    example: "claimant"
                                                isPrimary:
                                                    type: boolean
                                                    description: Whether the participant is the primary representative.
                                                    example: true
                                                isObserver:
                                                    type: boolean
                                                    description: Whether the participant is an observer.
                                                    example: false
                                    partyID:
                                        type: string
                                        description: Users party in the case.
                                        example: "claimant"
                                    timetable:
                                        type: object
                                        description: Case timetable details.
                                        properties:
                                            phases:
                                                type: array
                                                items:
                                                    type: object
                                                    properties:
                                                        id:
                                                            type: string
                                                            description: Phase identifier.
                                                            example: "caseInitiation"
                                                        scheduledStart:
                                                            type: string
                                                            format: date-time
                                                            description: Scheduled start of the phase.
                                                            example: "2025-08-23T02:47:42.123816Z"
                                                        scheduledEnd:
                                                            type: string
                                                            format: date-time
                                                            nullable: true
                                                            description: Scheduled end of the phase, if set.
                                                            example:
                                                        filingDeadline:
                                                            type: string
                                                            format: date-time
                                                            description: Deadline for required filings in this phase.
                                                            example: "2025-09-23T02:47:42.123816Z"
                                                        documents:
                                                            type: array
                                                            description: Documents relevant to this phase.
                                                            items:
                                                                type: object
                                                                properties:
                                                                    id:
                                                                        type: string
                                                                        description: Document identifier.
                                                                        example: "statementOfClaim"
                                                                    filedBy:
                                                                        type: string
                                                                        nullable: true
                                                                        description: Party who files the document.
                                                                        example: "claimant"
                                                                    approvedBy:
                                                                        type: string
                                                                        nullable: true
                                                                        description: Party who approves the document, if any.
                                                                        example: "caseAdministrator"
                                                                    maxAllowed:
                                                                        type: integer
                                                                        description: Maximum number of documents allowed.
                                                                        example: 1
                                                                    required:
                                                                        type: boolean
                                                                        description: Whether the document is required.
                                                                        example: true
                                example:
                                    overview:
                                        id: "2025-08-00139"
                                        created: "2025-08-23T02:47:42Z"
                                        updated: "2025-08-23T02:47:42Z"
                                        createdByUserID: "00c573fd-18d9-4fbe-921e-6926d2c4869e"
                                        createdByOrgID: null
                                        phaseID: "caseInitiation"
                                        title: "Case 2025-08-00139"
                                        canSubmitEvidence: true
                                    participants:
                                        - created: "2025-08-23T02:47:42Z"
                                          userID: "00c573fd-18d9-4fbe-921e-6926d2c4869e"
                                          organizationID: null
                                          partyID: "claimant"
                                          isPrimary: true
                                          isObserver: false
                                        - created: "2025-08-23T02:48:01Z"
                                          userID: "df25d20f-8042-44e2-97af-3609659c56a3"
                                          organizationID: null
                                          partyID: "caseAdministrator"
                                          isPrimary: true
                                          isObserver: false
                                    partyID: claimant
                                    timetable:
                                        phases:
                                            - id: "caseInitiation"
                                              scheduledStart: "2025-08-23T02:47:42.123816Z"
                                              scheduledEnd: null
                                              filingDeadline: "2025-09-23T02:47:42.123816Z"
                                              documents:
                                                - id: "statementOfClaim"
                                                  filedBy: "claimant"
                                                  approvedBy: "caseAdministrator"
                                                  maxAllowed: 1
                                                  required: true
                                                - id: "noticeOfArbitration"
                                                  filedBy: "caseAdministrator"
                                                  approvedBy: null
                                                  maxAllowed: 1
                                                  required: true
                '404':
                    description: The case was not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "case not found"
                '410':
                    description: The user is not a participant in the case.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "user is not a participant"
            tags:
                - cases
    /evidence/uploads/create:
        post:
            summary: Upload evidence to a case
            description: Upload one file to a case with a short description.
            operationId: postEvidenceUploadsCreate
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    multipart/form-data:
                        schema:
                            type: object
                            required:
                                - caseID
                                - description
                                - file
                            properties:
                                caseID:
                                    type: string
                                    description: ID of the case to attach the evidence to. Must be sent before the file part.
                                    example: "2025-08-00123"
                                description:
                                    type: string
                                    description: Short description of the evidence. Must be sent before the file part.
                                    example: "Photo from the incident on May 5, 2025"
                                file:
                                    type: string
                                    format: binary
                                    description: The evidence file to upload (single file only).
                                    example: (binary file contents)
                        encoding:
                            caseID:
                                contentType: text/plain
                            description:
                                contentType: text/plain
                            file:
                                contentType: application/pdf
            responses:
                '200':
                    description: Evidence successfully uploaded.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    uploadID:
                                        type: string
                                        description: ID of the created evidence upload.
                                        example: "12"
                '403':
                    description: User is not allowed to upload in this case.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "you cannot upload evidence in this case"
                '404':
                    description: Case not found or user not a participant.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "case not found"
                '410':
                    description: Evidence submission window is closed for the case.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "evidence submission is currently closed"
                '411':
                    description: The party has reached the maximum number of evidence uploads.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "maximum number of evidence uploads reached"
                '412':
                    description: The uploaded file is too large.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "uploaded file size is too large"
                '413':
                    description: File not supported.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "file not supported"
            tags:
                - evidence
    /evidence/uploads/delete:
        post:
            summary: Delete an uploaded evidence file
            description: Removes a specific upload from a case if you have access.
            operationId: deleteEvidenceUpload
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                                - uploadID
                            properties:
                                caseID:
                                    type: string
                                    description: The case identifier.
                                    maxLength: 36
                                    example: "2025-08-00123"
                                uploadID:
                                    type: string
                                    description: The upload identifier to delete.
                                    maxLength: 36
                                    example: "32"
            responses:
                '200':
                    description: Upload deleted.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "upload successfully deleted"
                '404':
                    description: Case or upload not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "upload not found"
                '410':
                    description: Evidence submission is closed for this case.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "evidence submission is currently closed"
                '411':
                    description: User is an observer and cannot delete uploads.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "you are registered as an observer and cannot delete uploads in this case"
                '412':
                    description: User is not a participant in the case.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "you are not a participant in the case"
            tags:
                - evidence
    /evidence/uploads/download:
        post:
            summary: Get a download link for an uploaded file
            description: Returns a short-lived URL so you can download the upload.
            operationId: getEvidenceUploadDownloadUrl
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                                - uploadID
                            properties:
                                caseID:
                                    type: string
                                    description: The case identifier.
                                    maxLength: 36
                                    example: "2025-08-00123"
                                uploadID:
                                    type: string
                                    description: The upload identifier for which to generate a download URL.
                                    maxLength: 36
                                    example: "3"
            responses:
                '200':
                    description: Signed download URL generated.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    url:
                                        type: string
                                        format: uri
                                        description: Time-limited URL for downloading the file.
                                        example: "https://secure-storage.arb.inc/uploads/2025-08-00123/22"
                                    validForSeconds:
                                        type: integer
                                        description: How long the URL is valid, in seconds.
                                        example: 600
                '404':
                    description: Case, participant, or upload not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "Upload could not be found"
            tags:
                - evidence
    /evidence/uploads/list:
        post:
            summary: List evidence uploads for a case
            description: Returns the uploads the user is allowed to access for a given case.
            operationId: listEvidenceUploads
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                            properties:
                                caseID:
                                    type: string
                                    description: The case identifier to look up uploads for.
                                    minLength: 1
                                    maxLength: 36
                                    example: "2025-08-00123"
            responses:
                '200':
                    description: Successfully returned uploads the user is allowed to access.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    uploads:
                                        type: array
                                        description: List of evidence uploads visible to the user.
                                        items:
                                            type: object
                                            properties:
                                                created:
                                                    type: string
                                                    format: date-time
                                                    description: When the evidence was submitted (RFC 3339).
                                                    example: "2025-08-29T16:27:16Z"
                                                uploadID:
                                                    type: string
                                                    description: Unique identifier for the upload.
                                                    example: "4"
                                                categoryID:
                                                    type: string
                                                    description: Evidence category classification.
                                                    example: "document"
                                                phaseID:
                                                    type: string
                                                    description: Case phase at submission.
                                                    example: "caseInitiation"
                                                partyID:
                                                    type: string
                                                    description: Party linked to the evidence.
                                                    example: "claimant"
                                                userID:
                                                    type: string
                                                    description: User who submitted the evidence.
                                                    example: "00c573fd-18d9-4fbe-921e-6926d2c4869e"
                                                organizationID:
                                                    type: string
                                                    nullable: true
                                                    description: Organization the user belongs to, if any.
                                                    example: "8a922e11-1821-4923-a860-58683cbda9a2"
                                                description:
                                                    type: string
                                                    description: Text description of the evidence.
                                                    example: "This is my description"
                                                contentType:
                                                    type: string
                                                    description: MIME type of the uploaded file.
                                                    example: "application/pdf"
                            examples:
                                sample:
                                    summary: Example response
                                    value:
                                        uploads:
                                            - created: "2025-08-29T15:41:19Z"
                                              uploadID: "1"
                                              categoryID: "image"
                                              phaseID: "caseInitiation"
                                              partyID: "claimant"
                                              userID: "00c573fd-18d9-4fbe-921e-6926d2c4869e"
                                              organizationID: "8a922e11-1821-4923-a860-58683cbda9a2"
                                              description: "Photo of the building"
                                              contentType: "application/png"
                                            - created: "2025-08-29T15:45:09Z"
                                              uploadID: "2"
                                              categoryID: "document"
                                              phaseID: "caseInitiation"
                                              partyID: "claimant"
                                              userID: "00c573fd-18d9-4fbe-921e-6926d2c4869e"
                                              organizationID: "8a922e11-1821-4923-a860-58683cbda9a2"
                                              description: "Terms of service"
                                              contentType: "application/pdf"
                '404':
                    description: The case was not found or the user is not a participant.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "case not found"
            tags:
                - evidence
    /filings/documents/create:
        post:
            summary: Create a document
            description: Creates a new document for a case using a document template.
            operationId: postFilingsDocumentsCreate
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                                - documentID
                            properties:
                                caseID:
                                    type: string
                                    description: ID of the case to file into.
                                    example: "2025-08-00125"
                                documentID:
                                    type: string
                                    description: Identifier of the document type/template.
                                    example: "statementOfClaim"
                                fields:
                                    type: object
                                    additionalProperties:
                                        type: string
                                    description: Key-value field inputs for the document.
                                    example:
                                        respondentName: "Mike Smith"
                                        respondentAddress: "123 Main Street"
            responses:
                '200':
                    description: Document successfully filed.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    filingID:
                                        type: string
                                        description: ID of the created filing.
                                        example: "3"
                '404':
                    description: Case not found or user not a participant.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "case not found"
                '409':
                    description: User is an observer and cannot file.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "you are registered as an observer and cannot file documents in this case"
                '410':
                    description: The document cannot be filed at this phase.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "document not allowed in this phase"
                '411':
                    description: Filing deadline has passed.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "filing deadline for this document has closed"
                '412':
                    description: Filing limit reached for this document type.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "filing limit for this document type reached"
                '422':
                    description: Validation errors for submitted fields.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    validationErrors:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                field:
                                                    type: string
                                                    description: Field or section with an error.
                                                    example: "respondentName"
                                                message:
                                                    type: string
                                                    description: Human-readable error.
                                                    example: "must be at least 20 characters."
            tags:
                - filings
    /filings/documents/delete:
        post:
            summary: Delete a filed document
            description: Removes a document from a case if it’s still eligible for deletion.
            operationId: deleteFiledDocument
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                                - filingID
                            properties:
                                caseID:
                                    type: string
                                    description: The case identifier.
                                    maxLength: 36
                                    example: "2025-08-00251"
                                filingID:
                                    type: string
                                    description: The filing/document identifier.
                                    maxLength: 36
                                    example: "3"
            responses:
                '200':
                    description: Document was deleted.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "Document successfully deleted"
                '404':
                    description: Case participant or document not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "document not found"
                '409':
                    description: Document can’t be deleted because it is already docketed.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "document cannot be deleted because it's already added to the docket"
                '410':
                    description: Document is currently submitted for approval and cannot be deleted.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "document cannot be deleted because it's currently submitted for approval"
                '411':
                    description: User is an observer in the case and cannot delete documents.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "you are registered as an observer and cannot delete documents in this case"
            tags:
                - filings
    /filings/documents/list:
        post:
            summary: List filed documents for a case
            description: Returns filed documents for a specific case that the signed-in user participates in.
            operationId: listFiledDocuments
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                            properties:
                                caseID:
                                    type: string
                                    description: The case ID to list filed documents for.
                                    example: "4f9b1d9e-0e7a-4b4d-9f0e-5f5f2b7d8a33"
            responses:
                '200':
                    description: Filed documents successfully retrieved.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    documents:
                                        type: array
                                        description: List of filed documents for the case.
                                        items:
                                            type: object
                                            properties:
                                                created:
                                                    type: string
                                                    format: date-time
                                                    description: Timestamp when the filing was created.
                                                    example: "2025-06-12T14:23:45Z"
                                                updated:
                                                    type: string
                                                    format: date-time
                                                    description: Timestamp when the filing was last updated.
                                                    example: "2025-06-18T09:11:02Z"
                                                filingID:
                                                    type: string
                                                    description: Unique identifier for the filing record.
                                                    example: "4"
                                                phaseID:
                                                    type: string
                                                    description: Identifier of the phase this document was filed in.
                                                    example: "caseInitiation"
                                                documentType:
                                                    type: string
                                                    description: Identifier of the type of document that was filed.
                                                    example: "statementOfClaim"
                                                userID:
                                                    type: string
                                                    description: Identifier of the user who filed the document.
                                                    example: "d7f2a1b3-4c5d-6e7f-8a90-b1c2d3e4f5a6"
                                                organizationID:
                                                    type: string
                                                    nullable: true
                                                    description: Identifier of the organization the user belongs to (null if a personal account).
                                                    example: "f3e9c5b7-8a1d-4c2e-9f0b-1a2b3c4d5e6f"
                                                isSubmitted:
                                                    type: boolean
                                                    description: Indicates whether the filing has been submitted for review.
                                                    example: true
                                                approved:
                                                    type: string
                                                    format: date-time
                                                    nullable: true
                                                    description: Timestamp when the filing was approved (null if not approved).
                                                    example: "2025-06-20T16:45:00Z"
                                                approvedBy:
                                                    type: string
                                                    nullable: true
                                                    description: Identifier of the user who approved the filing (null if not approved).
                                                    example: "9a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d"
                                                docketId:
                                                    type: string
                                                    nullable: true
                                                    description: Identifier linking the filing to a docket entry (null if not docketed).
                                                    example: "8"
                            examples:
                                success:
                                    summary: Example successful response
                                    value:
                                        documents:
                                            - created: "2025-06-12T14:23:45Z"
                                              updated: "2025-06-18T09:11:02Z"
                                              filingID: "b1f6d3f2-0a5b-48fb-8b13-2a8c9b0f6e77"
                                              phaseID: "2c9f1c1e-7e2a-4f6c-9a54-3e8d2f4c6a11"
                                              documentType: "statementOfClaim"
                                              userID: "d7f2a1b3-4c5d-6e7f-8a90-b1c2d3e4f5a6"
                                              organizationID: "f3e9c5b7-8a1d-4c2e-9f0b-1a2b3c4d5e6f"
                                              isSubmitted: true
                                              approved: "2025-06-20T16:45:00Z"
                                              approvedBy: "9a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d"
                                              docketId: "8"
                                            - created: "2025-06-10T10:05:12Z"
                                              updated: "2025-06-10T10:05:12Z"
                                              filingID: "3b7a9d5e-2c4f-4a6b-9d8e-0f1a2b3c4d5e"
                                              phaseID: "a1b2c3d4-e5f6-7890-abcd-ef0123456789"
                                              documentType: "statementOfCase"
                                              userID: "11111111-2222-3333-4444-555555555555"
                                              organizationID: null
                                              isSubmitted: false
                                              approved: null
                                              approvedBy: null
                                              docketId: null
                '404':
                    description: Case not found or user is not a participant in the case.
                    content:
                        text/plain:
                            schema:
                                type: string
                            examples:
                                caseMissing:
                                    summary: Case missing
                                    value: "case not found"
                                notParticipant:
                                    summary: Not a participant
                                    value: "not a participant in the case"
            tags:
                - filings
    /filings/documents/pdf:
        post:
            summary: Get a temporary PDF URL for a filed document
            description: Returns a short-lived URL to download the PDF of a filed document in a case.
            operationId: postFilingsDocumentsPDF
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                                - filingID
                            properties:
                                caseID:
                                    type: string
                                    description: Unique identifier of the case that contains the filed document.
                                    maxLength: 36
                                    example: "2025-08-00123"
                                filingID:
                                    type: string
                                    description: Unique identifier of the filed document whose PDF URL is requested.
                                    maxLength: 36
                                    example: "2"
            responses:
                '200':
                    description: Signed URL generated successfully.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    url:
                                        type: string
                                        format: uri
                                        description: Temporary URL to download the PDF.
                                        example: "https://secure-storage.arb.inc/filings/2025-08-00123/22"
                                    validForSeconds:
                                        type: integer
                                        description: Number of seconds the URL remains valid.
                                        example: 3600
                '404':
                    description: The requested document could not be found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: The specified document could not be found.
                '410':
                    description: The requested case could not be found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: The specified case could not be found.
                '411':
                    description: Permission denied.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: You do not have permission to view this document.
                '412':
                    description: The document is only available from the docket.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: The specified document is only accessible from the docket.
            tags:
                - filings
    /filings/documents/submit:
        post:
            summary: Submit a filed document
            description: Sends a filed document for approval in a case.
            operationId: submitFiledDocument
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                                - filingID
                            properties:
                                caseID:
                                    type: string
                                    description: The case ID.
                                    maxLength: 36
                                    example: "2025-08-00125"
                                filingID:
                                    type: string
                                    description: The filing ID.
                                    maxLength: 36
                                    example: "8"
            responses:
                '200':
                    description: Document submitted.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Document successfully submitted
                '404':
                    description: Document not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: document not found
                '409':
                    description: Document is already docketed and cannot be submitted.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: document cannot be submitted because it's already been added to the docket
                '410':
                    description: Document has already been submitted for approval.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: document is already submitted for approval
                '411':
                    description: User is an observer and cannot file in this case.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: You are registered as an observer and cannot file documents in this case
                '412':
                    description: Document type is not allowed right now.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: document not allowed in this phase
            tags:
                - filings
    /filings/documents/update:
        post:
            summary: Update a filed document
            description: Updates a document in a case with new field values.
            operationId: updateFiledDocument
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                                - filingID
                                - fields
                            properties:
                                caseID:
                                    type: string
                                    description: The case ID the document belongs to.
                                    example: "2025-08-00125"
                                filingID:
                                    type: string
                                    description: The filing ID of the document to update.
                                    example: "14"
                                fields:
                                    type: object
                                    additionalProperties:
                                        type: string
                                    description: Key-value fields to update on the document.
                                    example:
                                        title: "Amended Motion to Dismiss"
                                        description: "Updated summary after review"
                                        docketNumber: "2025-00123"
            responses:
                '200':
                    description: Document successfully updated.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "Document successfully updated"
                '404':
                    description: The document or participant was not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "document not found"
                '409':
                    description: The document is docketed and cannot be changed.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "document cannot be updated because it's already been added to the docket"
                '410':
                    description: The document is currently submitted for approval.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "document cannot be updated because it's currently submitted for approval"
                '411':
                    description: The user is an observer and cannot file documents.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "You are registered as an observer and cannot file documents in this case"
                '422':
                    description: One or more fields failed validation.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    validationErrors:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                field:
                                                    type: string
                                                    description: The field or section that failed validation.
                                                    example: "title"
                                                message:
                                                    type: string
                                                    description: What went wrong with the value.
                                                    example: "title is required"
                            examples:
                                sampleValidationErrors:
                                    value:
                                        validationErrors:
                                            - field: "title"
                                              message: "title is required"
                                            - field: "docketNumber"
                                              message: "docketNumber must be numeric"
            tags:
                - filings
    /filings/documents/view:
        post:
            summary: View a filed document
            description: Returns the details of a filed document for a given case and filing.
            operationId: postFilingsDocumentsView
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                                - filingID
                            properties:
                                caseID:
                                    type: string
                                    description: The case identifier.
                                    example: "2025-08-00225"
                                filingID:
                                    type: string
                                    description: The filing identifier.
                                    example: "15"
            responses:
                '200':
                    description: Filed document returned.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    document:
                                        type: object
                                        properties:
                                            created:
                                                type: string
                                                format: date-time
                                                description: When the filing was created.
                                                example: "2025-06-01T14:23:45Z"
                                            updated:
                                                type: string
                                                format: date-time
                                                description: When the filing was last updated.
                                                example: "2025-06-10T09:15:00Z"
                                            caseID:
                                                type: string
                                                description: Case ID the filing belongs to.
                                                example: "2025-08-00225"
                                            filingID:
                                                type: string
                                                description: Unique filing record ID.
                                                example: "15"
                                            phaseID:
                                                type: string
                                                description: Phase in which the document was filed.
                                                example: "caseInitiation"
                                            documentId:
                                                type: string
                                                description: Type identifier of the filed document.
                                                example: "statementOfClaim"
                                            partyID:
                                                type: string
                                                description: Party on whose behalf the document was filed.
                                                example: "claimant"
                                            userID:
                                                type: string
                                                description: User who filed the document.
                                                example: "74e7a465-6865-42b9-a1cf-a241bd8896d4"
                                            organizationID:
                                                type: string
                                                nullable: true
                                                description: Organization ID of the user, if any.
                                                example: "16d1224b-8f19-44c7-bfb0-47a6a272ff33"
                                            isSubmitted:
                                                type: boolean
                                                description: Whether the filing was submitted for review.
                                                example: true
                                            fields:
                                                type: object
                                                additionalProperties:
                                                    type: string
                                                description: Map of field IDs to their text content.
                                                example:
                                                    claimantName: "Mike Smith"
                                                    claimantAddress: "123 Main Street"
                                            approved:
                                                type: string
                                                format: date-time
                                                nullable: true
                                                description: When the filing was approved, if approved.
                                                example: "2025-06-12T17:00:00Z"
                                            approvedBy:
                                                type: string
                                                nullable: true
                                                description: User ID of the approver, if approved.
                                                example: "107b5300-6f89-4934-b188-b99594cf3c55"
                                            docketId:
                                                type: string
                                                nullable: true
                                                description: Docket entry ID, if docketed.
                                                example: "42"
                '404':
                    description: The document or participant was not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: Document not found
            tags:
                - filings
    /filings/documents/withdraw:
        post:
            summary: Withdraw a filed document
            description: Removes a filed document from a case if it hasn’t been docketed.
            operationId: withdrawFiledDocument
            security:
                - bearerAuth: []
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - caseID
                                - filingID
                            properties:
                                caseID:
                                    type: string
                                    description: The case identifier.
                                    example: "2025-08-00124"
                                filingID:
                                    type: string
                                    description: The filed document identifier.
                                    example: "15"
            responses:
                '200':
                    description: Document successfully withdrawn.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "Document successfully withdrawn"
                '404':
                    description: Document not found.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "document not found"
                '409':
                    description: Document already docketed and cannot be withdrawn.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "document cannot be withdrawn because it's already been added to the docket"
                '410':
                    description: Document was already withdrawn.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "document is already withdrawn"
                '411':
                    description: User is an observer and cannot file or withdraw documents in the case.
                    content:
                        text/plain:
                            schema:
                                type: string
                                example: "You are registered as an observer and cannot file documents in this case"
            tags:
                - filings
    /schemas/list:
        post:
            summary: List schemas
            description: Retrieves all available schemas for case phases and documents.
            operationId: listSchemas
            security:
                - bearerAuth: []
            responses:
                '200':
                    description: Schemas successfully retrieved.
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    parties:
                                        type: array
                                        description: All available parties.
                                        items:
                                            type: object
                                            properties:
                                                id:
                                                    type: string
                                                    description: Unique party identifier.
                                                    example: "caseAdministrator"
                                                displayName:
                                                    type: string
                                                    description: Human-readable party name.
                                                    example: "Case Administrator"
                                                description:
                                                    type: string
                                                    description: Brief explanation of the party.
                                                    example: "Responsible for handling the administrative aspects of the case."
                                    phases:
                                        type: array
                                        description: All available case phases.
                                        items:
                                            type: object
                                            properties:
                                                id:
                                                    type: string
                                                    description: Unique phase identifier.
                                                    example: "caseInitiation"
                                                displayName:
                                                    type: string
                                                    description: Human-readable phase name.
                                                    example: "Case Initiation"
                                                description:
                                                    type: string
                                                    description: Brief explanation of the phase.
                                                    example: "The initial phase of the case."
                                    documents:
                                        type: array
                                        description: All available document schemas.
                                        items:
                                            type: object
                                            properties:
                                                id:
                                                    type: string
                                                    description: Unique document identifier.
                                                    example: "statementOfClaim"
                                                displayName:
                                                    type: string
                                                    description: Human-readable document name.
                                                    example: "Statement of Claim"
                                                description:
                                                    type: string
                                                    description: Brief explanation of the document.
                                                    example: "A formal statement outlining the details of the claim."
                                                sections:
                                                    type: array
                                                    description: Sections belonging to this document.
                                                    items:
                                                        type: object
                                                        properties:
                                                            displayName:
                                                                type: string
                                                                description: Human-readable section name.
                                                                example: "Claim Details"
                                                            description:
                                                                type: string
                                                                description: Brief explanation of the section.
                                                                example: "This section captures the details of the claim."
                                                            sortOrder:
                                                                type: integer
                                                                description: Numeric order of this section within its parent document.
                                                                example: 1
                                                            fields:
                                                                type: array
                                                                description: Fillable fields in the section.
                                                                items:
                                                                    type: object
                                                                    properties:
                                                                        id:
                                                                            type: string
                                                                            description: Unique field identifier.
                                                                            example: "claimDetails"
                                                                        displayName:
                                                                            type: string
                                                                            description: Human-readable field name.
                                                                            example: "Claim Details"
                                                                        required:
                                                                            type: boolean
                                                                            description: Whether this field is mandatory.
                                                                            example: true
                                                                        minLength:
                                                                            type: integer
                                                                            description: Minimum required content length.
                                                                            example: 10
                                                                        maxLength:
                                                                            type: integer
                                                                            description: Maximum allowed content length.
                                                                            example: 500
                                                                        sortOrder:
                                                                            type: integer
                                                                            description: Numeric order of this field within its parent section.
                                                                            example: 1
                                    evidence:
                                        type: array
                                        description: All supported evidence types and their allowed MIME content types.
                                        items:
                                            type: object
                                            properties:
                                                id:
                                                    type: string
                                                    description: Unique evidence type identifier.
                                                    example: "audio"
                                                displayName:
                                                    type: string
                                                    description: Human-readable evidence type name.
                                                    example: "Audio"
                                                contentTypes:
                                                    type: array
                                                    description: Allowed MIME content types for this evidence type.
                                                    items:
                                                        type: string
                                                    example:
                                                        - "audio/mpeg"
                                                        - "audio/wav"
                                                        - "audio/flac"
                                                        - "audio/mp4"
                                                        - "audio/ogg"
            tags:
                - schemas
components:
    securitySchemes:
        bearerAuth:
            type: http
            description: access token
            scheme: bearer
            bearerFormat: JWT
tags:
    - name: cases
    - name: evidence
    - name: filings
    - name: schemas