openapi: 3.0.1
info:
  title: Modern Treasury AccountCapability LedgerAccountCategory API
  version: v1
  contact:
    name: Modern Treasury Engineering Team
    url: https://moderntreasury.com
  description: The Modern Treasury REST API. Please see https://docs.moderntreasury.com for more details.
servers:
- url: http://localhost:3000
- url: https://app.moderntreasury.com
tags:
- name: LedgerAccountCategory
paths:
  /api/ledger_account_categories:
    get:
      summary: list ledger_account_categories
      tags:
      - LedgerAccountCategory
      operationId: listLedgerAccountCategories
      description: Get a list of ledger account categories.
      security:
      - basic_auth: []
      parameters:
      - name: after_cursor
        in: query
        schema:
          type: string
          nullable: true
        required: false
      - name: per_page
        in: query
        schema:
          type: integer
        required: false
      - $ref: '#/components/parameters/metadata_query'
      - $ref: '#/components/parameters/bulk_id'
      - name: name
        in: query
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/bulk_name'
      - name: ledger_id
        in: query
        schema:
          type: string
        required: false
      - name: currency
        in: query
        required: false
        schema:
          type: string
      - name: external_id
        in: query
        schema:
          type: string
        required: false
      - name: parent_ledger_account_category_id
        in: query
        schema:
          type: string
        required: false
        description: Query categories that are nested underneath a parent category
      - name: ledger_account_id
        in: query
        schema:
          type: string
        required: false
        description: Query categories which contain a ledger account directly or through child categories.
      - name: balances
        in: query
        schema:
          type: object
          properties:
            effective_at:
              type: string
              format: date-time
          additionalProperties: false
        style: deepObject
        required: false
        description: For example, if you want the balances as of a particular time (ISO8601), the encoded query string would be `balances%5Beffective_at%5D=2000-12-31T12:00:00Z`. The balances as of a time are inclusive of entries with that exact time, but with respect to the ledger accounts that are currently present in the category.
        explode: true
      responses:
        '200':
          description: successful
          headers:
            X-After-Cursor:
              schema:
                type: string
                nullable: true
              required: false
              description: The cursor for the next page. Including this in a call as `after_cursor` will return the next page.
            X-Per-Page:
              schema:
                type: integer
                nullable: true
              description: The current `per_page`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ledger_account_category'
    post:
      summary: create ledger_account_category
      tags:
      - LedgerAccountCategory
      operationId: createLedgerAccountCategory
      description: Create a ledger account category.
      security:
      - basic_auth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: This key should be something unique, preferably something like an UUID.
        schema:
          type: string
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ledger_account_category'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ledger_account_category_create_request'
  /api/ledger_account_categories/{id}:
    parameters:
    - name: id
      in: path
      schema:
        type: string
      description: id
      required: true
    get:
      summary: get ledger_account_category
      tags:
      - LedgerAccountCategory
      operationId: getLedgerAccountCategory
      description: Get the details on a single ledger account category.
      security:
      - basic_auth: []
      parameters:
      - name: balances
        in: query
        schema:
          type: object
          properties:
            as_of_date:
              type: string
              format: date
            effective_at:
              type: string
              format: date-time
          additionalProperties: false
        style: deepObject
        required: false
        description: For example, if you want the balances as of a particular time (ISO8601), the encoded query string would be `balances%5Beffective_at%5D=2000-12-31T12:00:00Z`. The balances as of a time are inclusive of entries with that exact time, but with respect to the ledger accounts that are currently present in the category.
        explode: true
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ledger_account_category'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    patch:
      summary: update ledger_account_category
      tags:
      - LedgerAccountCategory
      operationId: updateLedgerAccountCategory
      description: Update the details of a ledger account category.
      security:
      - basic_auth: []
      parameters: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ledger_account_category'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '409':
          description: conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ledger_account_category_update_request'
    delete:
      summary: delete ledger_account_category
      tags:
      - LedgerAccountCategory
      operationId: deleteLedgerAccountCategory
      description: Delete a ledger account category.
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ledger_account_category'
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
  /api/ledger_account_categories/{id}/ledger_accounts/{ledger_account_id}:
    parameters:
    - name: id
      in: path
      schema:
        type: string
      description: id
      required: true
    - name: ledger_account_id
      in: path
      schema:
        type: string
      description: ledger_account_id
      required: true
    put:
      summary: add ledger_account to ledger_account_category
      tags:
      - LedgerAccountCategory
      operationId: addLedgerAccountToLedgerAccountCategory
      description: Add a ledger account to a ledger account category.
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    delete:
      summary: remove ledger_account from ledger_account_category
      tags:
      - LedgerAccountCategory
      operationId: removeLedgerAccountFromLedgerAccountCategory
      description: Remove a ledger account from a ledger account category.
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
  /api/ledger_account_categories/{id}/ledger_account_categories/{sub_category_id}:
    parameters:
    - name: id
      in: path
      schema:
        type: string
      description: id
      required: true
    - name: sub_category_id
      in: path
      schema:
        type: string
      description: sub_category_id
      required: true
    put:
      summary: add ledger_account_category to ledger_account_category
      tags:
      - LedgerAccountCategory
      operationId: addLedgerAccountCategoryToLedgerAccountCategory
      description: Add a ledger account category to a ledger account category.
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
    delete:
      summary: delete ledger_account_category from ledger_account_category
      tags:
      - LedgerAccountCategory
      operationId: deleteLedgerAccountCategoryFromLedgerAccountCategory
      description: Delete a ledger account category from a ledger account category.
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
        '403':
          description: forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
components:
  parameters:
    bulk_id:
      name: id[]
      in: query
      style: form
      explode: true
      allowReserved: true
      schema:
        type: array
        items:
          type: string
      required: false
      description: If you have specific IDs to retrieve in bulk, you can pass them as query parameters delimited with `id[]=`, for example `?id[]=123&id[]=abc`.
    bulk_name:
      name: name[]
      in: query
      style: form
      explode: true
      allowReserved: true
      schema:
        type: array
        items:
          type: string
      required: false
      description: If you have specific names to retrieve in bulk, you can pass them as query parameters delimited with `name[]=`, for example `?name[]=123&name[]=abc`.
    metadata_query:
      name: metadata
      in: query
      schema:
        type: object
        additionalProperties:
          type: string
      style: deepObject
      explode: true
      required: false
      description: For example, if you want to query for records with metadata key `Type` and value `Loan`, the query would be `metadata%5BType%5D=Loan`. This encodes the query parameters.
  schemas:
    ledger_account_category:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        discarded_at:
          type: string
          format: date-time
          nullable: true
        name:
          type: string
          description: The name of the ledger account category.
        description:
          type: string
          description: The description of the ledger account category.
          nullable: true
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
        ledger_id:
          type: string
          format: uuid
          description: The id of the ledger that this account category belongs to.
        normal_balance:
          type: string
          enum:
          - credit
          - debit
          description: The normal balance of the ledger account category.
          _x-stainless-modelDefPath: $shared.transaction_direction
        external_id:
          type: string
          nullable: true
          description: An optional user-defined 180 character unique identifier.
        balances:
          $ref: '#/components/schemas/ledger_balances'
          description: The pending, posted, and available balances for this ledger account category. The posted balance is the sum of all posted entries on the account. The pending balance is the sum of all pending and posted entries on the account. The available balance is the posted incoming entries minus the sum of the pending and posted outgoing amounts.
      additionalProperties: false
      minProperties: 13
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - discarded_at
      - name
      - description
      - metadata
      - ledger_id
      - normal_balance
      - external_id
      - balances
    error_message:
      type: object
      properties:
        errors:
          type: object
          properties:
            code:
              type: string
              enum:
              - parameter_invalid
              - parameter_missing
              - resource_not_found
              - not_found
              - forbidden
              - invalid_ip
              - invalid_key
              - header_invalid
              - expired_key
              - conflict
              - too_many_requests
            message:
              type: string
            parameter:
              type: string
      required:
      - errors
    ledger_balance:
      type: object
      properties:
        credits:
          type: integer
        debits:
          type: integer
        amount:
          type: integer
        currency:
          type: string
          description: The currency of the ledger account.
        currency_exponent:
          type: integer
          description: The currency exponent of the ledger account.
      additionalProperties: false
      minProperties: 5
      required:
      - credits
      - debits
      - amount
      - currency
      - currency_exponent
    ledger_account_category_update_request:
      type: object
      properties:
        name:
          type: string
          description: The name of the ledger account category.
        description:
          type: string
          description: The description of the ledger account category.
          nullable: true
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
        external_id:
          type: string
          description: An optional user-defined 180 character unique identifier.
          nullable: true
    ledger_account_category_create_request:
      type: object
      properties:
        name:
          type: string
          description: The name of the ledger account category.
        description:
          type: string
          description: The description of the ledger account category.
          nullable: true
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
        currency:
          type: string
          description: The currency of the ledger account category.
        currency_exponent:
          type: integer
          description: The currency exponent of the ledger account category.
          nullable: true
        ledger_id:
          type: string
          format: uuid
          description: The id of the ledger that this account category belongs to.
        normal_balance:
          type: string
          enum:
          - credit
          - debit
          description: The normal balance of the ledger account category.
          _x-stainless-modelDefPath: $shared.transaction_direction
        ledger_account_category_ids:
          type: array
          items:
            type: string
            format: uuid
          description: The array of ledger account category ids that this ledger account category should be a child of.
        external_id:
          type: string
          nullable: true
          description: An optional user-defined 180 character unique identifier.
      required:
      - name
      - normal_balance
      - currency
      - ledger_id
    ledger_balances:
      type: object
      properties:
        pending_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The pending_balance is the sum of all pending and posted entries.
        posted_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The posted_balance is the sum of all posted entries.
        available_balance:
          $ref: '#/components/schemas/ledger_balance'
          description: The available_balance is the sum of all posted inbound entries and pending outbound entries. For credit normal, available_amount = posted_credits - pending_debits; for debit normal, available_amount = posted_debits - pending_credits.
      additionalProperties: false
      minProperties: 3
      required:
      - pending_balance
      - posted_balance
      - available_balance
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic