openapi: 3.0.3
info:
  title: SimpleLegal Cost Codes Matters API
  description: The SimpleLegal API is organized around REST. The API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. It uses built-in HTTP features like HTTP authentication and HTTP verbs. JSON is returned by all API responses, including errors. The API supports PATCH methods throughout; POST can be used instead of PATCH for systems that cannot use PATCH. Pagination defaults to 25 items per page and can be configured with the page_size query parameter.
  version: '1.0'
  contact:
    name: SimpleLegal Support
    url: https://support.simplelegal.com/
  termsOfService: https://www.simplelegal.com/terms-of-service
servers:
- url: https://app.simplelegal.com/api/v1
  description: SimpleLegal Production API
security:
- basicAuth: []
tags:
- name: Matters
paths:
  /matters:
    get:
      operationId: list-matters
      summary: List Matters
      description: Retrieve a paginated list of legal matters.
      tags:
      - Matters
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
        description: Page number for pagination.
      - name: page_size
        in: query
        schema:
          type: integer
          default: 25
          maximum: 100
        description: Number of results per page (max 100).
      - name: status
        in: query
        schema:
          type: string
          enum:
          - open
          - closed
          - pending
          - on_hold
        description: Filter matters by status.
      - name: practice_area
        in: query
        schema:
          type: string
        description: Filter matters by practice area.
      responses:
        '200':
          description: Paginated list of matters.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Matter'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: create-matter
      summary: Create Matter
      description: Create a new legal matter.
      tags:
      - Matters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Matter'
      responses:
        '201':
          description: Matter created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Matter'
        '400':
          description: Invalid request data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /matters/{id}:
    get:
      operationId: get-matter
      summary: Get Matter
      description: Retrieve a specific legal matter by ID.
      tags:
      - Matters
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Matter ID.
      responses:
        '200':
          description: Matter details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Matter'
        '404':
          description: Matter not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: update-matter
      summary: Update Matter
      description: Update fields on an existing legal matter.
      tags:
      - Matters
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Matter ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Matter'
      responses:
        '200':
          description: Updated matter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Matter'
components:
  schemas:
    Matter:
      type: object
      description: A legal matter representing a case, project, or legal engagement.
      properties:
        id:
          type: string
          description: Unique matter identifier.
        name:
          type: string
          description: Matter name or title.
        matter_number:
          type: string
          description: Internal matter reference number.
        status:
          type: string
          description: Current matter status.
          enum:
          - open
          - closed
          - pending
          - on_hold
        practice_area:
          type: string
          description: Legal practice area for the matter.
        description:
          type: string
          description: Detailed description of the matter.
        client:
          type: string
          description: Internal client or business unit for the matter.
        lead_attorney:
          type: string
          description: Primary attorney responsible for the matter.
        outside_counsel:
          type: string
          description: Outside law firm handling the matter.
        budget:
          type: number
          format: float
          description: Total budget allocated for the matter.
        actual_spend:
          type: number
          format: float
          description: Total actual spend on the matter to date.
        accruals:
          type: number
          format: float
          description: Accrued but unpaid costs for the matter.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the matter was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the matter was last updated.
        custom_fields:
          type: object
          description: Custom field values specific to the organization.
          additionalProperties: true
      required:
      - name
    PaginatedResponse:
      type: object
      properties:
        count:
          type: integer
          description: Total number of items matching the query.
        next:
          type: string
          nullable: true
          description: URL for the next page of results.
        previous:
          type: string
          nullable: true
          description: URL for the previous page of results.
        results:
          type: array
          description: The paginated list of results.
          items: {}
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error description.
        code:
          type: string
          description: Machine-readable error code.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using your SimpleLegal API credentials.