openapi: 3.0.3
info:
  title: MyCase Open API
  version: "1.0"
  description: |
    Partial, profile-only OpenAPI description of the publicly documented MyCase
    Open API surface, hand-assembled from the Stoplight reference at
    https://mycaseapi.stoplight.io/ and the MyCase Open API support article at
    https://supportcenter.mycase.com/en/articles/9370198-open-api.

    Only resources whose existence is confirmed from MyCase's public
    documentation are represented here: the authorized firm, cases (per client),
    case stages, companies, client relationships on a case, calendar events,
    tasks, documents and document folders, and time zones. Request and response
    schemas are intentionally minimal — full schemas are gated behind the
    Stoplight reference, which requires sign-in to view request/response bodies
    in detail. Authentication is documented by MyCase as a per-firm credential
    flow obtained through MyCase support; the security scheme below uses HTTP
    bearer as a placeholder for the issued access token.

    This document is part of the api-evangelist/mycase profile and is intended
    for catalog and tooling purposes, not for client code generation.
  contact:
    name: MyCase Support
    url: https://supportcenter.mycase.com/
  license:
    name: MyCase Terms of Service
    url: https://www.mycase.com/terms-of-service/
servers:
  - url: https://api.mycase.com
    description: MyCase Open API (production). The exact base URL is documented inside the authenticated Stoplight reference; this value is a placeholder consistent with MyCase's public hostnames.
security:
  - bearerAuth: []
tags:
  - name: Firm
    description: The authorized firm of the current API user.
  - name: Cases
    description: Cases (matters) for the firm, and case-scoped sub-resources.
  - name: Case Stages
    description: Configured case stages for the firm.
  - name: Contacts
    description: People and client relationships associated with cases.
  - name: Companies
    description: Companies visible to the authorized user.
  - name: Events
    description: Calendar events on the firm calendar.
  - name: Tasks
    description: Tasks visible to the authorized user.
  - name: Documents
    description: Documents and document folders associated with a case.
  - name: Time Zones
    description: Supported time zone identifiers.
paths:
  /firm:
    get:
      tags: [Firm]
      summary: Get the Firm of the Current Authorized User
      operationId: getFirm
      description: Return the firm record for the current authorized API user. Documented at https://mycaseapi.stoplight.io/docs/mycase-api-documentation/0acc0620bdd9e-get-the-firm-of-the-current-authorized-user.
      responses:
        "200":
          description: Firm record.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Firm"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /case_stages:
    get:
      tags: [Case Stages]
      summary: Get Case Stages
      operationId: getCaseStages
      description: Get all firm case stages viewable by the authorized user. Documented at https://mycaseapi.stoplight.io/docs/mycase-api-documentation/592cc136089e9-get-case-stages.
      responses:
        "200":
          description: A list of case stages.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/CaseStage"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /companies:
    get:
      tags: [Companies]
      summary: Get Companies
      operationId: getCompanies
      description: Get all firm companies viewable by the authorized user. Documented at https://mycaseapi.stoplight.io/docs/mycase-api-documentation/eddd20d8e1045-get-companies.
      responses:
        "200":
          description: A list of companies.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Company"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /clients/{clientId}/cases:
    parameters:
      - $ref: "#/components/parameters/ClientId"
    get:
      tags: [Cases]
      summary: Get All Cases for a Client
      operationId: getCasesForClient
      description: Return all cases associated with the given client. Documented at https://mycaseapi.stoplight.io/docs/mycase-api-documentation/999662f9e0762-get-all-cases-for-a-client.
      responses:
        "200":
          description: Cases associated with the client.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Case"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /cases/{caseId}/client_relationships:
    parameters:
      - $ref: "#/components/parameters/CaseId"
    post:
      tags: [Contacts]
      summary: Create a Client Relationship for a Case
      operationId: createClientRelationshipForCase
      description: Create a client relationship on the specified case. Documented at https://mycaseapi.stoplight.io/docs/mycase-api-documentation/2231b17f9f2e9-create-a-client-relationship-for-a-case.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClientRelationshipInput"
      responses:
        "201":
          description: Client relationship created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClientRelationship"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /cases/{caseId}/documents:
    parameters:
      - $ref: "#/components/parameters/CaseId"
    post:
      tags: [Documents]
      summary: Create a Document for a Case
      operationId: createDocumentForCase
      description: Upload a document to the specified case. Documented at https://mycaseapi.stoplight.io/docs/mycase-api-documentation/5f9d31af2e726-create-a-document-for-a-case.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/DocumentInput"
      responses:
        "201":
          description: Document created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Document"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"

  /cases/{caseId}/documents_folder:
    parameters:
      - $ref: "#/components/parameters/CaseId"
    get:
      tags: [Documents]
      summary: Get Case Documents Folder
      operationId: getCaseDocumentsFolder
      description: Return the documents folder for the case, including subfolders and document references. Documented at https://mycaseapi.stoplight.io/docs/mycase-api-documentation/1b7dc53b16e9d-get-case-documents-folder.
      responses:
        "200":
          description: The case documents folder.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentsFolder"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /events/{eventId}:
    parameters:
      - name: eventId
        in: path
        required: true
        schema:
          type: string
    patch:
      tags: [Events]
      summary: Update an Individual Event
      operationId: updateEvent
      description: Update an existing calendar event subject to user/firm privileges. Documented at https://mycaseapi.stoplight.io/docs/mycase-api-documentation/4f98681f0927b-update-an-individual-event.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EventInput"
      responses:
        "200":
          description: Updated event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Event"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token issued through the MyCase Open API onboarding flow. The exact authorization endpoint is documented inside the authenticated Stoplight reference.
  parameters:
    ClientId:
      name: clientId
      in: path
      required: true
      description: The unique identifier for a client (contact) in MyCase.
      schema:
        type: string
    CaseId:
      name: caseId
      in: path
      required: true
      description: The unique identifier for a case in MyCase.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UnprocessableEntity:
      description: Request body failed validation.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    Firm:
      type: object
      description: The firm record for the authorized user. Fields are gated behind the authenticated Stoplight reference; this shape is illustrative.
      properties:
        id:
          type: string
        name:
          type: string
        time_zone:
          type: string
          description: IANA time zone identifier used for the firm calendar.
    Case:
      type: object
      description: A case (matter) in MyCase.
      properties:
        id:
          type: string
        name:
          type: string
        case_number:
          type: string
        stage_id:
          type: string
        client_id:
          type: string
        opened_at:
          type: string
          format: date
        closed_at:
          type: string
          format: date
    CaseStage:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        practice_area:
          type: string
    Company:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        primary_email:
          type: string
          format: email
        primary_phone:
          type: string
    ClientRelationship:
      type: object
      properties:
        id:
          type: string
        case_id:
          type: string
        client_id:
          type: string
        role:
          type: string
    ClientRelationshipInput:
      type: object
      required: [client_id]
      properties:
        client_id:
          type: string
        role:
          type: string
    Document:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        case_id:
          type: string
        folder_id:
          type: string
        content_type:
          type: string
        size:
          type: integer
        created_at:
          type: string
          format: date-time
    DocumentInput:
      type: object
      required: [file]
      properties:
        file:
          type: string
          format: binary
        name:
          type: string
        folder_id:
          type: string
    DocumentsFolder:
      type: object
      properties:
        id:
          type: string
        case_id:
          type: string
        name:
          type: string
        subfolders:
          type: array
          items:
            $ref: "#/components/schemas/DocumentsFolder"
        documents:
          type: array
          items:
            $ref: "#/components/schemas/Document"
    Event:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        all_day:
          type: boolean
        case_id:
          type: string
        location:
          type: string
    EventInput:
      type: object
      properties:
        title:
          type: string
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
        all_day:
          type: boolean
        case_id:
          type: string
        location:
          type: string
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string