openapi: 3.1.0
info:
  title: Matter Management API
  description: |
    API for managing matters in a workspace.

    The API described in the [matters.yaml](https://developers.hivelight.com/schemas/matters.yaml) file is designed to manage matters within a workspace. This typically involves creating, reading, updating, and deleting (CRUD) operations on matters or projects within a workspace environment. 

    The API provides endpoints to interact with these matters programmatically, allowing our customers to efficiently manage and organize their workspace contents.
    
  version: 1.0.0
  contact:
    name: Support
    url: https://docs.hivelight.com
    email: support@hivelight.com
servers:
  - url: https://api.hivelight.com
    description: Global endpoint
  - url: https://au.api.hivelight.com
    description: Australian endpoint
paths:
  /matters:
    get:
      summary: Get matters
      description: Get all matters the current user has access to in a workspace
      parameters:
        - name: from
          in: query
          description: Starting index for pagination.
          required: false
          schema:
            type: integer
        - name: size
          in: query
          description: Number of items to return.
          required: false
          schema:
            type: integer
        - name: archived
          in: query
          description: Filter matters by archived status.
          required: false
          schema:
            type: boolean
        - name: userIds
          in: query
          description: Comma-separated user IDs to filter matters by participants.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: List of matters
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/MatterBasic"
                  meta:
                    type: object
                    properties:
                      total:
                        description: Total number of matters
                        type: integer
                        example: 100
                      showing:
                        description: Total number of matters returned
                        type: integer
                        example: 10
                      from:
                        description: Current starting index for pagination
                        type: integer
                        example: 0
    post:
      summary: Create matter
      description: |
        This endpoint allows you to create a matter and apply associated workflows to it.
        ### Applying workflows
        When specifying workflows to apply, you can also set the start date for each workflow.

        Omitting start dates will apply the workflows sequentially from the current date.
        ### Specifying matter types
        Only matter types that are available in the workspace can be applied to a matter. If a matter type is not available, the API will return an error.

        Check out the [workspace API](/api/workspace/) to get a list of available matter types in the workspace.

      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  $ref: "#/components/schemas/MatterBasic"
                meta:
                  type: object
                  properties:
                    workflows:
                      type: array
                      description: A list of workflow to be applied to this matter
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            required: true
                            description: The Workflow ID
                          startDate:
                            type: integer
                            format: int64
                            description: An integer representing milliseconds since the Unix epoch
      responses:
        "201":
          description: Matter created
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/MatterWithMilestoneRelationship"
                  included:
                    type: array
                    items:
                      $ref: "#/components/schemas/Milestone"

  /matters/{matterId}:
    get:
      summary: Get a matter
      parameters:
        - name: matterId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Details of the matter
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/MatterWithMilestoneRelationship"
                  included:
                    type: array
                    items:
                      $ref: "#/components/schemas/Milestone"
    post:
      summary: Update matter details
      parameters:
        - name: matterId
          description: The ID of the matter to apply the update to
          in: path
          required: true
          schema:
            type: string

      description: |
        This endpoint allows you to update matter details.

      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      value: matters
                    id:
                      type: string
                    attributes:
                      type: object
                      properties:
                        name:
                          description: |
                            The name of the matter. This is a required field.
                          type: string
                        description:
                          description: |
                            The description of the matter. This is an optional field.
                          type: string
                        external-reference:
                          description: |
                            An external reference for the matter, such as a case number or external ID.
                            This is an optional field.
                          type: object
                          properties:
                            id:
                              type: string
                              required: true
                              description: The external reference ID
                            source:
                              type: string
                              required: true
                              description: The source of the external reference

      responses:
        "200":
          description: Matter roles updated
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/MatterWithMilestoneRelationship"
                  included:
                    type: array
                    items:
                      $ref: "#/components/schemas/Milestone"

    delete:
      summary: Delete a matter
      description: |
        This operation will delete the matter and all its associated data. This operation is irreversible.
        Only archived matters can be deleted
      parameters:
        - name: matterId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Matter deleted
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Matter deleted
  /matters/{matterId}/apply/{workflowId}:
    post:
      summary: Apply a workflow to a matter
      parameters:
        - name: matterId
          description: The ID of the matter to apply the workflow to
          in: path
          required: true
          schema:
            type: string
        - name: workflowId
          description: The ID of the workflow to apply
          in: path
          required: true
          schema:
            type: string
        - name: startDate
          description: The start date of the workflow
          in: query
          schema:
            type: integer
            format: int64
            description: An integer representing milliseconds since the Unix epoch
        - name: milestoneId
          description: The ID of the milestone to apply a task list to (optional, defaults to the general tasks)
          in: query
          required: false
          schema:
            type: string

      responses:
        "200":
          description: Matter archived
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/MatterWithMilestoneRelationship"
                  included:
                    type: array
                    items:
                      $ref: "#/components/schemas/Milestone"

  /matters/{matterId}/roles:
    post:
      summary: Update matter roles
      parameters:
        - name: matterId
          description: The ID of the matter to apply the new roles to
          in: path
          required: true
          schema:
            type: string

      description: |
        This endpoint allows you to update matter roles.

        Note that this action replaces the existing roles with the new ones provided in the request body.

      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      value: matters
                    id:
                      type: string
                    attributes:
                      type: object
                      properties:
                        roles:
                          description: |
                            A list of roles and users associated with the matter

                            If no OWNER is specified, the current user will be set as the matter owner
                          type: object
                          properties:
                            OWNER:
                              description: Matter owner (limited to one user)
                              type: array
                              items:
                                type: string
                                description: User ID or email of the user
                            LEAD:
                              description: Matter lead (limited to one user)
                              type: array
                              items:
                                type: string
                                description: User ID or email of the user
                            BUSINESS_1:
                              description: Business Administrators of the matter
                              type: array
                              items:
                                type: string
                                description: User ID or email of the user
                            ADVOCATE_1:
                              description: Advocates (or Barristers) of the matter
                              type: array
                              items:
                                type: string
                                description: User ID or email of the user
                            CONSULTANT_1:
                              description: Consultants of the matter
                              type: array
                              items:
                                type: string
                                description: User ID or email of the user
                            LEGAL_1:
                              description: Senior Lawyers of the matter
                              type: array
                              items:
                                type: string
                                description: User ID or email of the user
                            LEGAL_2:
                              description: Junior Lawyers of the matter
                              type: array
                              items:
                                type: string
                                description: User ID or email of the user
                            LEGAL_3:
                              description: Law Clerks or Paralegals of the matter
                              type: array
                              items:
                                type: string
                                description: User ID or email of the user
                            ADMINISTRATIVE_1:
                              description: Senior Legal Assistants of the matter
                              type: array
                              items:
                                type: string
                                description: User ID or email of the user
                            ADMINISTRATIVE_2:
                              description: Junior Legal Assistants of the matter
                              type: array
                              items:
                                type: string
                                description: User ID or email of the user

      responses:
        "200":
          description: Matter roles updated
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/MatterWithMilestoneRelationship"
                  included:
                    type: array
                    items:
                      $ref: "#/components/schemas/Milestone"

  /matters/{matterId}/archive:
    post:
      summary: Archive a matter
      parameters:
        - name: matterId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Matter archived
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/MatterBasic"
    delete:
      summary: Un-archive a matter
      parameters:
        - name: matterId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Matter un-archived
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/MatterBasic"

  /matters/{matterId}/notes:
    post:
      summary: Create a matter note
      parameters:
        - name: matterId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      value: notes
                    id:
                      type: string
                    attributes:
                      $ref: "#/components/schemas/NoteAttributes"

      responses:
        "200":
          description: Note created
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        value: notes
                      id:
                        type: string
                      attributes:
                        $ref: "#/components/schemas/NoteAttributes"

  /matters/{matterId}/tasks/{taskId}/notes:
    post:
      summary: Create a task note
      parameters:
        - name: matterId
          in: path
          required: true
          schema:
            type: string
        - name: taskId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      value: notes
                    id:
                      type: string
                    attributes:
                      $ref: "#/components/schemas/NoteAttributes"
      responses:
        "200":
          description: Note created
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      type:
                        type: string
                        value: notes
                      id:
                        type: string
                      attributes:
                        $ref: "#/components/schemas/NoteAttributes"

components:
  schemas:
    MatterBasic:
      type: object
      properties:
        type:
          type: string
          value: matters
        id:
          type: string
        attributes:
          $ref: "#/components/schemas/MatterAttributes"
    Milestone:
      type: object
      properties:
        type:
          type: string
          value: milestones
        id:
          type: string
        attributes:
          $ref: "#/components/schemas/MilestoneAttributes"
    MilestoneAttributes:
      type: object
      properties:
        name:
          type: string
          description: Name of the milestone
        description:
          type: string
          description: Description of the milestone
        status:
          type: string
          description: Status of the milestone
          enum:
            - NOTSTARTED
            - INPROGRESS
            - DONE
        "created-date":
          type: integer
          format: int64
          description: An integer representing milliseconds since the Unix epoch
        "due-date":
          type: integer
          format: int64
          description: An integer representing milliseconds since the Unix epoch
        "target-date":
          type: integer
          format: int64
          description: An integer representing milliseconds since the Unix epoch
        "total-tasks":
          type: integer
          description: Total number of tasks in the milestone
        "completed-tasks":
          type: integer
          description: Number of completed tasks in the milestone
        "pending-tasks":
          type: integer
          description: Number of pending tasks in the milestone
    MatterWithMilestoneRelationship:
      type: object
      properties:
        type:
          type: string
          value: matters
        id:
          type: string
        attributes:
          $ref: "#/components/schemas/MatterAttributes"
        relationships:
          type: object
          properties:
            milestones:
              type: object
              properties:
                data:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        value: milestones
                      id:
                        type: string
    MatterAttributes:
      type: object
      properties:
        name:
          type: string
          description: Name of the matter
        description:
          type: string
          description: Description of the matter
        external-reference:
          type: object
          properties:
            id:
              type: string
              description: External reference for the matter
            source:
              type: string
              description: Source of the external reference
        tags:
          type: array
          optional: true
          description: A list of label/value tags associated with the matter as an array of object .
          items:
            type: object
            properties:
              label:
                type: string
                description: The label of the tag (e.g., "priority", "status", "type", "value")
              value:
                type: string
                optional: true
                description: An optional value to the label of the tag (e.g., "high", "open", "ACC", "$3,000")
        types:
          type: array
          description: A list of matter type identifiers for this matter
          items:
            type: string
        jurisdictions:
          description: |
            A list of Jurisdictions this matter is associated with 
            Australia: https://en.wikipedia.org/wiki/ISO_3166-2:AU
            Canada: https://en.wikipedia.org/wiki/ISO_3166-2:CA
            Great Britain: https://en.wikipedia.org/wiki/ISO_3166-2:GB
            New Zealand: https://en.wikipedia.org/wiki/ISO_3166-2:NZ
            United States od America: https://en.wikipedia.org/wiki/ISO_3166-2:US

          type: array
          items:
            type: string
        roles:
          description: |
            A list of roles and users associated with the matter

            If no OWNER is specified, the current user will be set as the matter owner
          type: object
          properties:
            OWNER:
              description: Matter owner (limited to one user)
              type: array
              items:
                type: string
                description: User ID or email of the user
            LEAD:
              description: Matter lead (limited to one user)
              type: array
              items:
                type: string
                description: User ID or email of the user
            BUSINESS_1:
              description: Business Administrators of the matter
              type: array
              items:
                type: string
                description: User ID or email of the user
            ADVOCATE_1:
              description: Advocates (or Barristers) of the matter
              type: array
              items:
                type: string
                description: User ID or email of the user
            CONSULTANT_1:
              description: Consultants of the matter
              type: array
              items:
                type: string
                description: User ID or email of the user
            LEGAL_1:
              description: Senior Lawyers of the matter
              type: array
              items:
                type: string
                description: User ID or email of the user
            LEGAL_2:
              description: Junior Lawyers of the matter
              type: array
              items:
                type: string
                description: User ID or email of the user
            LEGAL_3:
              description: Law Clerks or Paralegals of the matter
              type: array
              items:
                type: string
                description: User ID or email of the user
            ADMINISTRATIVE_1:
              description: Senior Legal Assistants of the matter
              type: array
              items:
                type: string
                description: User ID or email of the user
            ADMINISTRATIVE_2:
              description: Junior Legal Assistants of the matter
              type: array
              items:
                type: string
                description: User ID or email of the user
    NoteAttributes:
      type: object
      properties:
        content:
          type: string
          description: Content of the note in text or HTML format