firefly-iii-2.1.0-v2.yaml

openapi: 3.0.0
servers:
  - description: Firefly III demo site
    url: https://demo.firefly-iii.org/api
info:
  title: Firefly III API v2.1.0
  description: |
    This is the documentation of the Firefly III API. You can find accompanying documentation on the website of Firefly III itself (see below). Please report any bugs or issues. You may use the "Authorize" button to try the API below. This file was last generated on 2024-09-10T05:07:57+00:00

    Please keep in mind that the demo site does not accept requests from curl, colly, wget, etc. You must use a browser or a tool like Postman to make requests. Too many script kiddies out there, sorry about that.
  version: "2.1.0"
  contact:
    name: James Cole
    email: james@firefly-iii.org
    url: https://firefly-iii.org
  license:
    name: AGPLv3
    url: 'https://www.gnu.org/licenses/agpl-3.0.en.html'
tags:
- name: accounts
  description: Endpoints that deliver all of the user's asset, expense and other accounts
    (and the metadata) together with related transactions, piggy banks and other objects.
    Also delivers endpoints for CRUD operations for accounts.
- name: budgets
  description: Endpoints to manage a user's budgets and get info on the related objects,
    like limits.
- name: charts
  description: The "charts" endpoints deliver optimised data for charts and graphs.
- name: net-worth
  description: Shows you the net worth of the current user.
- name: preferences
  description: These endpoints can be used to manage the user's preferences, including
    some hidden ones.
- name: transactions-sum
  description: Endpoints to sum transactions based on various properties.

paths:
  /v2/autocomplete/accounts:
    get:
      tags:
        - autocomplete
      operationId: getAccountsAC
      parameters:
        - name: X-Trace-Id
          in: header
          description: Unique identifier associated with this request.
          required: false
          schema:
            type: string
            format: uuid
        - name: filter
          in: query
          description: Filter the autocomplete thing.
          required: false
          schema:
            $ref: '#/components/schemas/AutocompleteFilter'
  
      summary: Returns all accounts of the user returned in a basic auto-complete array.
      responses:
        "401":
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
  
        "404":
          description: Page not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
  
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
  
        "500":
          description: Internal exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalExceptionResponse'
  
        "200":
          description: A list of accounts with basic account information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteObject'
  /v2/autocomplete/categories:
    get:
      tags:
        - autocomplete
      operationId: getCategoriesAC
      parameters:
        - name: X-Trace-Id
          in: header
          description: Unique identifier associated with this request.
          required: false
          schema:
            type: string
            format: uuid
        - name: filter
          in: query
          description: Filter the autocomplete thing.
          required: false
          schema:
            $ref: '#/components/schemas/AutocompleteFilter'
  
      summary: Returns all categories of the user returned in a basic auto-complete array.
      responses:
        "401":
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
  
        "404":
          description: Page not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
  
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
  
        "500":
          description: Internal exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalExceptionResponse'
  
        "200":
          description: A list of categories with basic category information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteObject'
  /v2/autocomplete/tags:
    get:
      tags:
        - autocomplete
      operationId: getTagsAC
      parameters:
        - name: X-Trace-Id
          in: header
          description: Unique identifier associated with this request.
          required: false
          schema:
            type: string
            format: uuid
        - name: filter
          in: query
          description: Filter the autocomplete thing.
          required: false
          schema:
            $ref: '#/components/schemas/AutocompleteFilter'
  
      summary: Returns all tags of the user returned in a basic auto-complete array.
      responses:
        "401":
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
  
        "404":
          description: Page not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
  
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
  
        "500":
          description: Internal exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalExceptionResponse'
  
        "200":
          description: A list of tags with basic tag information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteObject'
  /v2/autocomplete/transaction-descriptions:
    get:
      tags:
        - autocomplete
      operationId: getTransactionsAC
      parameters:
        - name: X-Trace-Id
          in: header
          description: Unique identifier associated with this request.
          required: false
          schema:
            type: string
            format: uuid
        - name: filter
          in: query
          description: Filter the autocomplete thing.
          required: false
          schema:
            $ref: '#/components/schemas/AutocompleteFilter'
  
      summary: Returns all transactions of the user returned in a basic auto-complete array (descriptions only).
      responses:
        "401":
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
  
        "404":
          description: Page not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
  
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
  
        "500":
          description: Internal exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalExceptionResponse'
  
        "200":
          description: A list of transactions with the description and some basic information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutocompleteObject'
components:
  schemas:
    AutocompleteAccountV2Array:
      type: array
      items:
        $ref: '#/components/schemas/AutocompleteAccountV2'
    AutocompleteAccountV2:
      type: object
      required:
        - id
        - name
        - name_with_balance
        - type
        - currency_id
        - currency_name
        - currency_code
        - currency_symbol
        - currency_decimal_places
      properties:
        id:
          type: string
          format: string
          example: "2"
        name:
          type: string
          format: string
          example: "Checking Account"
          description: Name of the account found by an auto-complete search.
        name_with_balance:
          type: string
          format: string
          example: "Checking Account ($123.45)"
          description: Asset accounts and liabilities have a second field with the given date's account balance.
        type:
          type: string
          format: string
          example: "Asset account"
          description: Account type of the account found by the auto-complete search.
        currency_id:
          type: string
          format: string
          example: "12"
          description: ID for the currency used by this account.
        currency_name:
          type: string
          format: string
          example: "Euro"
          description: Currency name for the currency used by this account.
        currency_code:
          type: string
          format: string
          example: "EUR"
          description: Currency code for the currency used by this account.
        currency_symbol:
          type: string
          format: string
          example: "$"
          description: Currency symbol for the currency used by this account.
        currency_decimal_places:
          type: integer
          format: int32
          example: 2
          description: Number of decimal places for the currency used by this account.
    AutocompleteFilter:
      type: object
      properties:
        query:
          type: array
          items:
            type: string
            format: string
            example: "autocomplete query here"
            description: The search query to filter the autocomplete on. Multiple words can be submitted, but this is not required. An autocomplete box generally only submits one query.
        account_types:
          type: array
          items:
            $ref: '#/components/schemas/AccountTypeFilter'
            type: string
            example: "Asset account"
            description: Used only in the 'accounts' autocomplete endpoint, this filters the results by account type.
    AutocompleteObject:
      type: object
      required:
        - id
        - title
        - meta
      properties:
        id:
          type: string
          format: string
          example: "2"
          readOnly: true
          description: The ID of the object as a string
        title:
          type: string
          format: string
          example: "Some object"
          description: The autocomplete value that your dropdown can use.
          readOnly: true
        value:
          type: string
          format: string
          nullable: true
          example: "2"
          readOnly: true
          description: Optional. The ID of the object as a string. This is only used in the tags autocomplete endpoint because the JS library I use doesn't support "id" as the value field.
        label:
          type: string
          format: string
          example: "Some object"
          description: The autocomplete value that your dropdown can use. This is only used in the tags autocomplete endpoint because the JS library I use doesn't support "title" as the value field.
          readOnly: true
        meta:
          type: object
          description: Array with optional meta-information. Fields will be different for each autocomplete entry.
          properties:
            type:
              type: string
              format: string
              example: "Asset account"
              readOnly: true
              description: Account type of the account found by the auto-complete search.
            transaction_group_id:
              type: string
              format: string
              nullable: true
              example: "2"
              readOnly: true
              description: The ID of the associated transaction. Only used in the transaction description autocomplete endpoint.
            currency_id:
              type: string
              format: string
              example: "12"
              readOnly: true
              description: ID for the currency used by this account. Only used in the account autocomplete endpoint.
            currency_name:
              type: string
              format: string
              example: "Euro"
              readOnly: true
              description: Currency name for the currency used by this account. Only used in the account autocomplete endpoint.
            currency_code:
              type: string
              format: string
              example: "EUR"
              readOnly: true
              description: Currency code for the currency used by this account. Only used in the account autocomplete endpoint.
            currency_symbol:
              type: string
              format: string
              example: "$"
              readOnly: true
              description: Currency symbol for the currency used by this account. Only used in the account autocomplete endpoint.
            currency_decimal_places:
              type: integer
              format: int32
              example: 2
              readOnly: true
              description: Number of decimal places for the currency used by this account. Only used in the account autocomplete endpoint.
            account_balances:
                type: array
                readOnly: true
                description: The latest account balance(s) of the account. Only used in the account autocomplete endpoint.
                items:
                    type: object
                    properties:
                      native_amount:
                        type: string
                        format: amount
                        example: "123.45"
                        description: The account balance in the user's default currency.
                      amount:
                        type: string
                        format: amount
                        example: "123.45"
                        description: The account balance.
                      currency_id:
                        type: string
                        format: string
                        example: "12"
                        readOnly: true
                        description: ID for the currency of the amount.
                      currency_name:
                        type: string
                        format: string
                        example: "Euro"
                        readOnly: true
                        description: Currency name for the currency of the amount.
                      currency_code:
                        type: string
                        format: string
                        example: "EUR"
                        readOnly: true
                        description: Currency code for the currency of the amount.
                      currency_symbol:
                        type: string
                        format: string
                        example: "$"
                        readOnly: true
                        description: Currency symbol for the currency of the amount.
                      currency_decimal_places:
                        type: integer
                        format: int32
                        example: 2
                        readOnly: true
                        description: Number of decimal places for the currency of the amount.
                      native_currency_id:
                        type: string
                        format: string
                        example: "12"
                        readOnly: true
                        description: ID for the native currency of the user, so the currency of the native amount field.
                      native_currency_name:
                        type: string
                        format: string
                        example: "Euro"
                        readOnly: true
                        description: Currency name for the native currency of the user, so the currency of the native amount field.
                      native_currency_code:
                        type: string
                        format: string
                        example: "EUR"
                        readOnly: true
                        description: Currency code for the native currency of the user, so the currency of the native amount field.
                      native_currency_symbol:
                        type: string
                        format: string
                        example: "$"
                        readOnly: true
                        description: Currency symbol for the native currency of the user, so the currency of the native amount field.
                      native_currency_decimal_places:
                        type: integer
                        format: int32
                        example: 2
                        readOnly: true
                        description: Number of decimal places for for the native currency of the user, so the currency of the native amount field.
    Meta:
      type: object
      properties:
        pagination:
          type: object
          properties:
            total:
              type: integer
              example: 3
            count:
              type: integer
              example: 20
            per_page:
              type: integer
              example: 100
            current_page:
              type: integer
              example: 1
            total_pages:
              type: integer
              example: 1
    BadRequestResponse:
      type: object
      properties:
        message:
          type: string
          format: string
          example: "Bad Request"
        exception:
          type: string
          format: string
          example: "BadRequestHttpException"
    InternalExceptionResponse:
      type: object
      properties:
        message:
          type: string
          format: string
          example: "Internal Exception"
        exception:
          type: string
          format: string
          example: "InternalException"
    NotFoundResponse:
      type: object
      properties:
        message:
          type: string
          format: string
          example: "Resource not found"
        exception:
          type: string
          format: string
          example: "NotFoundHttpException"
    UnauthenticatedResponse:
      type: object
      properties:
        message:
          type: string
          format: string
          example: "Unauthenticated"
        exception:
          type: string
          format: string
          example: "AuthenticationException"
    ValidationErrorResponse:
      type: object
      properties:
        message:
          type: string
          format: string
          example: "The given data was invalid."
        errors:
          type: object
          properties:
            email:
              type: array
              items:
                type: string
                format: string
            blocked:
              type: array
              items:
                type: string
                format: string
            role:
              type: array
              items:
                type: string
                format: string
            blocked_code:
              type: array
              items:
                type: string
                format: string
            name:
              type: array
              items:
                type: string
                format: string
            type:
              type: array
              items:
                type: string
                format: string
            iban:
              type: array
              items:
                type: string
                format: string
            start:
              type: array
              items:
                type: string
                format: string
            end:
              type: array
              items:
                  type: string
                  format: string
            date:
              type: array
              items:
                type: string
                format: string
    AccountRoleProperty:
      type: string
      format: string
      example: "defaultAsset"
      description: "Is only mandatory when the type is asset."
      nullable: true
      enum:
        - defaultAsset
        - sharedAsset
        - savingAsset
        - ccAsset
        - cashWalletAsset
        - null
    AccountTypeProperty:
      type: string
      format: string
      example: "Asset account"
      readOnly: true
      enum:
        - Default account
        - Cash account
        - Asset account
        - Expense account
        - Revenue account
        - Initial balance account
        - Beneficiary account
        - Import account
        - Reconciliation account
        - Loan
        - Debt
        - Mortgage
    CreditCardTypeProperty:
      type: string
      format: string
      example: monthlyFull
      description: "Mandatory when the account_role is ccAsset. Can only be monthlyFull or null."
      nullable: true
      enum:
        - monthlyFull
        - null
    InterestPeriodProperty:
      type: string
      format: string
      example: monthly
      description: "Mandatory when type is liability. Period over which the interest is calculated."
      nullable: true
      enum:
        - weekly
        - monthly
        - quarterly
        - half-year
        - yearly
        - null
    LiabilityDirectionProperty:
      type: string
      format: string
      example: credit
      description: "'credit' indicates somebody owes you the liability. 'debit' Indicates you owe this debt yourself. Works only for liabiltiies."
      nullable: true
      enum:
        - credit
        - debit
        - null
    LiabilityTypeProperty:
      type: string
      format: string
      example: "loan"
      description: "Mandatory when type is liability. Specifies the exact type."
      nullable: true
      enum:
        - loan
        - debt
        - mortgage
        - null
    ShortAccountTypeProperty:
      type: string
      format: string
      example: "asset"
      description: "Can only be one one these account types. import, initial-balance and reconciliation cannot be set manually."
      enum:
        - asset
        - expense
        - import
        - revenue
        - cash
        - liability
        - liabilities
        - "initial-balance"
        - reconciliation
    TransactionTypeProperty:
      type: string
      format: string
      example: "withdrawal"
      enum:
        - withdrawal
        - deposit
        - transfer
        - reconciliation
        - opening balance
    AccountTypeFilter:
      type: string
      enum:
        - all
        - asset
        - cash
        - expense
        - revenue
        - special
        - hidden
        - liability
        - liabilities
        - Default account
        - Cash account
        - Asset account
        - Expense account
        - Revenue account
        - Initial balance account
        - Beneficiary account
        - Import account
        - Reconciliation account
        - Loan
        - Debt
        - Mortgage
    TransactionTypeFilter:
      type: string
      enum:
        - all
        - withdrawal
        - withdrawals
        - expense
        - deposit
        - deposits
        - income
        - transfer
        - transfers
        - opening_balance
        - reconciliation
        - special
        - specials
        - default
  securitySchemes:
    firefly_iii_auth:
      type: oauth2
      description: Default OAuth2 flow
      flows:
        authorizationCode:
          authorizationUrl: https://demo.firefly-iii.org/oauth/authorize
          tokenUrl: https://demo.firefly-iii.org/oauth/token
          refreshUrl: https://demo.firefly-iii.org/oauth/token
          scopes: {}
    local_bearer_auth:
      description: Optional Bearer token flow
      type: http
      scheme: bearer
security:
  - firefly_iii_auth: []
  - local_bearer_auth: []