@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api PocketSmith
@base https://api.pocketsmith.com/v2
@version 2.0
@auth ApiKey X-Developer-Key in header | OAuth2
@endpoints 56
@hint download_for_search
@toc me(1), users(21), institutions(4), accounts(4), transaction_accounts(4), transactions(6), categories(5), events(3), scenarios(2), attachments(3), currencies(2), time_zones(1)

@group me
@endpoint GET /me
@desc Get the authorised user
@returns(200) {id: int, login: str, name: str, email: str, avatar_url: str, beta_user: bool, time_zone: str, week_start_day: int, is_reviewing_transactions: bool, base_currency_code: str, always_show_base_currency: bool, using_multiple_currencies: bool, available_accounts: int, available_budgets: int, forecast_last_updated_at: str, forecast_last_accessed_at: str, forecast_start_date: str, forecast_end_date: str, forecast_defer_recalculate: bool, forecast_needs_recalculate: bool, last_logged_in_at: str, last_activity_at: str, created_at: str, updated_at: str} # Success
@errors {403: Not Allowed}

@endgroup

@group users
@endpoint GET /users/{id}
@desc Get user
@required {id: int # The unique identifier of the user.}
@returns(200) {id: int, login: str, name: str, email: str, avatar_url: str, beta_user: bool, time_zone: str, week_start_day: int, is_reviewing_transactions: bool, base_currency_code: str, always_show_base_currency: bool, using_multiple_currencies: bool, available_accounts: int, available_budgets: int, forecast_last_updated_at: str, forecast_last_accessed_at: str, forecast_start_date: str, forecast_end_date: str, forecast_defer_recalculate: bool, forecast_needs_recalculate: bool, last_logged_in_at: str, last_activity_at: str, created_at: str, updated_at: str} # Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint PUT /users/{id}
@desc Update user
@required {id: int # The unique identifier of the user.}
@optional {name: str # A new name for the user., time_zone: str # A new time zone for the user., week_start_day: int # The day of the week the user wishes their calendars to start on. A number between 0 and 6, where 0 is Sunday and 6 is Saturday., beta_user: bool # Whether the user is a beta user, and wishes to try out new features., base_currency_code: str # A new base currency code for the user., always_show_base_currency: bool # Whether the user wishes to have all monetary values converted to their base currency.}
@returns(200) {id: int, login: str, name: str, email: str, avatar_url: str, beta_user: bool, time_zone: str, week_start_day: int, is_reviewing_transactions: bool, base_currency_code: str, always_show_base_currency: bool, using_multiple_currencies: bool, available_accounts: int, available_budgets: int, forecast_last_updated_at: str, forecast_last_accessed_at: str, forecast_start_date: str, forecast_end_date: str, forecast_defer_recalculate: bool, forecast_needs_recalculate: bool, last_logged_in_at: str, last_activity_at: str, created_at: str, updated_at: str} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endgroup

@group institutions
@endpoint GET /institutions/{id}
@desc Get institution
@required {id: int # The unique identifier of the institution.}
@returns(200) {currency_code: str, title: str, updated_at: str, created_at: str, id: int} # Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint PUT /institutions/{id}
@desc Update institution
@required {id: int # The unique identifier of the institution.}
@optional {title: str # A new title for the institution., currency_code: str # A new currency code for the institution.}
@returns(200) {currency_code: str, title: str, updated_at: str, created_at: str, id: int} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endpoint DELETE /institutions/{id}
@desc Delete institution
@required {id: int # The unique identifier of the institution.}
@optional {merge_into_institution_id: int # The unique identifier of the institution to merge into.}
@returns(204) Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endgroup

@group users
@endpoint GET /users/{id}/institutions
@desc List institutions in user
@required {id: int # The unique identifier of the user}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint POST /users/{id}/institutions
@desc Create institution in user
@required {id: int # The unique identifier of the user, title: str # A title for the institution., currency_code: str # A currency code for the institution.}
@returns(201) {currency_code: str, title: str, updated_at: str, created_at: str, id: int} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endgroup

@group accounts
@endpoint GET /accounts/{id}
@desc Get account
@required {id: int # The unique identifier of the account.}
@returns(200) {id: int, title: str, currency_code: str, type: str, is_net_worth: bool, primary_transaction_account: map{id: int, name: str, number: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, starting_balance: num, starting_balance_date: str, created_at: str, updated_at: str, institution: map{currency_code: str, title: str, updated_at: str, created_at: str, id: int}, currency_code: str, type: str}, primary_scenario: map{id: int, title: str, description: str, interest_rate: num, interest_rate_repeat_id: int, type: str, minimum-value: num, maximum-value: num, achieve_date: str, starting_balance: num, starting_balance_date: str, closing_balance: num, closing_balance_date: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, created_at: str, updated_at: str}, transaction_accounts: [map], scenarios: [map], created_at: str, updated_at: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num} # Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint PUT /accounts/{id}
@desc Update account
@required {id: int # The unique identifier of the account.}
@optional {title: str # A new title for the account., currency_code: str # A new currency code for the account., type: str(bank/credits/cash/loans/mortgage/stocks/vehicle/property/insurance/other_asset/other_liability) # The type of the account., is_net_worth: bool # Whether the account is a net worth account.}
@returns(200) {id: int, title: str, currency_code: str, type: str, is_net_worth: bool, primary_transaction_account: map{id: int, name: str, number: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, starting_balance: num, starting_balance_date: str, created_at: str, updated_at: str, institution: map{currency_code: str, title: str, updated_at: str, created_at: str, id: int}, currency_code: str, type: str}, primary_scenario: map{id: int, title: str, description: str, interest_rate: num, interest_rate_repeat_id: int, type: str, minimum-value: num, maximum-value: num, achieve_date: str, starting_balance: num, starting_balance_date: str, closing_balance: num, closing_balance_date: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, created_at: str, updated_at: str}, transaction_accounts: [map], scenarios: [map], created_at: str, updated_at: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endpoint DELETE /accounts/{id}
@desc Delete account
@required {id: int # The unique identifier of the account.}
@returns(204) Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endgroup

@group users
@endpoint GET /users/{id}/accounts
@desc List accounts in user
@required {id: int # The unique identifier of the user.}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint PUT /users/{id}/accounts
@desc Update the display order of accounts in user
@required {id: int # The unique identifier of the user., accounts: [map{id: int, title: str, currency_code: str, type: str, is_net_worth: bool, primary_transaction_account: map, primary_scenario: map, transaction_accounts: [map], scenarios: [map], created_at: str, updated_at: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num}] # List the account objects in their new display order.}
@returns(200) Success
@errors {400: Bad Request, 403: Not Allowed, 404: Not Found}

@endpoint POST /users/{id}/accounts
@desc Create an account in user
@required {id: int # The unique identifier of the user., institution_id: int # The ID of the institution to create this account in., title: str # A title for the account., currency_code: str # A currency code for the account., type: str(bank/credits/cash/loans/mortgage/stocks/vehicle/property/insurance/other_asset/other_liability) # The type of the account.}
@returns(201) {id: int, title: str, currency_code: str, type: str, is_net_worth: bool, primary_transaction_account: map{id: int, name: str, number: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, starting_balance: num, starting_balance_date: str, created_at: str, updated_at: str, institution: map{currency_code: str, title: str, updated_at: str, created_at: str, id: int}, currency_code: str, type: str}, primary_scenario: map{id: int, title: str, description: str, interest_rate: num, interest_rate_repeat_id: int, type: str, minimum-value: num, maximum-value: num, achieve_date: str, starting_balance: num, starting_balance_date: str, closing_balance: num, closing_balance_date: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, created_at: str, updated_at: str}, transaction_accounts: [map], scenarios: [map], created_at: str, updated_at: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endgroup

@group institutions
@endpoint GET /institutions/{id}/accounts
@desc List accounts in institution
@required {id: int # The unique identifier of the institution.}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endgroup

@group transaction_accounts
@endpoint GET /transaction_accounts/{id}
@desc Get transaction account
@required {id: int # The unique identifier of the transaction account.}
@returns(200) {id: int, name: str, number: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, starting_balance: num, starting_balance_date: str, created_at: str, updated_at: str, institution: map{currency_code: str, title: str, updated_at: str, created_at: str, id: int}, currency_code: str, type: str} # Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint PUT /transaction_accounts/{id}
@desc Update transaction account
@required {id: int # The unique identifier of the transaction account.}
@optional {institution_id: int # The unique identifier of a new institution for the transaction account., starting_balance: num # The starting balance amount of the transaction account., starting_balance_date: str # The starting balance date of the transaction account.}
@returns(200) {id: int, name: str, number: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, starting_balance: num, starting_balance_date: str, created_at: str, updated_at: str, institution: map{currency_code: str, title: str, updated_at: str, created_at: str, id: int}, currency_code: str, type: str} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endgroup

@group users
@endpoint GET /users/{id}/transaction_accounts
@desc List transaction accounts in user
@required {id: int # The unique identifier of the user.}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endgroup

@group transactions
@endpoint GET /transactions/{id}
@desc Get a transaction
@required {id: int # The unique identifier of the transaction.}
@returns(200) {cheque_number: str, type: str, memo: str, payee: str, amount: num, amount_in_base_currency: num, date: str, is_transfer: bool, category: map{id: int, title: str, colour: str(CSS-style hex triplet), children: [map], parent_id: int, is_transfer: bool, is_bill: bool, roll_up: bool, refund_behaviour: str?, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)}, note: str, labels: [str], id: int, original_payee: str, upload_source: str, closing_balance: num, transaction_account: map{id: int, name: str, number: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, starting_balance: num, starting_balance_date: str, created_at: str, updated_at: str, institution: map{currency_code: str, title: str, updated_at: str, created_at: str, id: int}, currency_code: str, type: str}, status: str, needs_review: bool, created_at: str, updated_at: str} # Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint PUT /transactions/{id}
@desc Update a transaction
@required {id: int # The unique identifier of the transaction.}
@optional {memo: str # A new memo for the transaction., cheque_number: str # A new cheque number for the transaction., payee: str # A new payee for the transaction., amount: num # The amount of the transaction (signed). A positive amount is a credit, and a negative amount is a debit., date: str # A new date for the transaction., is_transfer: bool # Whether the transaction is a transfer or not., category_id: int # The unique identifier of a new category for the transaction. Sending an empty string will uncategorize the transaction., note: str # A new note for the transaction., needs_review: bool # Whether the transaction needs to be reviewed or not., labels: str # A new comma-separated set of labels for the transaction., splits: [map{amount!: num, payee: str, category_id: int, is_transfer: bool, date: str}] # Split this transaction into multiple transactions. The correctly calculated remainder amount parameter must be provided, which is equal to the amount - sum(split_amounts). Splitting is atomic: all splits are validated before the original transaction and any splits are saved.}
@returns(200) Success. When splits are provided, the response includes both the updated transaction and the newly created split transactions.
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endpoint DELETE /transactions/{id}
@desc Delete transaction
@required {id: int # The unique identifier of the transaction.}
@returns(204) Success
@errors {403: Not Allowed, 404: Not Found}

@endgroup

@group users
@endpoint GET /users/{id}/transactions
@desc List transactions in user
@required {id: int # The unique identifier of the user.}
@optional {start_date: str # Limit to transactions on or after this date. Required if end_date is provided. If not provided, defaults to the furtherest date allowed by the user's subscription., end_date: str # Limit to transactions on or before this date. Required if start_date is provided. If not provided, defaults to today's date., updated_since: str # Limit to transactions updated since an ISO 8601 timestamp., uncategorised: int # Limit to uncategorised transactions., type: str(debit/credit) # Limit to transactions of this type., needs_review: int # Limit to transactions that need to be reviewed., search: str # Limit to transactions matching a keyword search string. The provided string is matched against the transaction amount, account name, payee, category title, note, labels, and the date in ISO 8601 format., page: int # Choose a particular page of the results.}
@returns(200) Success
@errors {400: Bad Request, 403: Not Allowed, 404: Not Found}

@endgroup

@group accounts
@endpoint GET /accounts/{id}/transactions
@desc List transactions in account
@required {id: int # The unique identifier of the account.}
@optional {start_date: str # Limit to transactions on or after this date. Required if end_date is provided. If not provided, defaults to the furtherest date allowed by the user's subscription., end_date: str # Limit to transactions on or before this date. Required if start_date is provided. If not provided, defaults to today's date., updated_since: str # Limit to transactions updated since an ISO 8601 timestamp., uncategorised: int # Limit to uncategorised transactions., type: str(debit/credit) # Limit to transactions of this type., needs_review: int # Limit to transactions that need to be reviewed., search: str # Limit to transactions matching a keyword search string. The provided string is matched against the transaction amount, account name, payee, category title, note, labels, and the date in ISO 8601 format., page: int # Choose a particular page of the results.}
@returns(200) Success
@errors {400: Bad Request, 403: Not Allowed, 404: Not Found}

@endgroup

@group categories
@endpoint GET /categories/{id}/transactions
@desc List transactions in categories
@required {id: str # A comma-separated list of category IDs.}
@optional {start_date: str # Limit to transactions on or after this date. Required if end_date is provided. If not provided, defaults to the furtherest date allowed by the user's subscription., end_date: str # Limit to transactions on or before this date. Required if start_date is provided. If not provided, defaults to today's date., updated_since: str # Limit to transactions updated since an ISO 8601 timestamp., uncategorised: int # Limit to uncategorised transactions., type: str(debit/credit) # Limit to transactions of this type., needs_review: int # Limit to transactions that need to be reviewed., search: str # Limit to transactions matching a keyword search string. The provided string is matched against the transaction amount, account name, payee, category title, note, labels, and the date in ISO 8601 format., page: int # Choose a particular page of the results.}
@returns(200) Success
@errors {400: Bad Request, 403: Not Allowed, 404: Not Found}

@endgroup

@group transaction_accounts
@endpoint GET /transaction_accounts/{id}/transactions
@desc List transactions in transaction account
@required {id: int # The unique identifier of the transaction account.}
@optional {start_date: str # Limit to transactions on or after this date. Required if end_date is provided. If not provided, defaults to the furtherest date allowed by the user's subscription., end_date: str # Limit to transactions on or before this date. Required if start_date is provided. If not provided, defaults to today's date., updated_since: str # Limit to transactions updated since an ISO 8601 timestamp., uncategorised: int # Limit to uncategorised transactions., type: str(debit/credit) # Limit to transactions of this type., needs_review: int # Limit to transactions that need to be reviewed., search: str # Limit to transactions matching a keyword search string. The provided string is matched against the transaction amount, account name, payee, category title, note, labels, and the date in ISO 8601 format., page: int # Choose a particular page of the results.}
@returns(200) Success
@errors {400: Bad Request, 403: Not Allowed, 404: Not Found}

@endpoint POST /transaction_accounts/{id}/transactions
@desc Create a transaction in transaction account
@required {id: int # The unique identifier of the transaction account., payee: str # The payee/merchant of the transaction., amount: num # The amount of the transaction (signed). A positive amount is a credit, and a negative amount is a debit., date: str # The date when the transaction occurred.}
@optional {is_transfer: bool # Whether the transaction should be indicated as a transfer., labels: str # A set of comma-separated labels for the transaction., category_id: int # The unique identifier of a category for the transaction., note: str # A note for the transaction., memo: str # A memo for the transaction., cheque_number: str # A cheque number for the transaction., needs_review: bool # Whether the transaction needs to be reviewed or not.}
@returns(201) {cheque_number: str, type: str, memo: str, payee: str, amount: num, amount_in_base_currency: num, date: str, is_transfer: bool, category: map{id: int, title: str, colour: str(CSS-style hex triplet), children: [map], parent_id: int, is_transfer: bool, is_bill: bool, roll_up: bool, refund_behaviour: str?, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)}, note: str, labels: [str], id: int, original_payee: str, upload_source: str, closing_balance: num, transaction_account: map{id: int, name: str, number: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, starting_balance: num, starting_balance_date: str, created_at: str, updated_at: str, institution: map{currency_code: str, title: str, updated_at: str, created_at: str, id: int}, currency_code: str, type: str}, status: str, needs_review: bool, created_at: str, updated_at: str} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endgroup

@group categories
@endpoint GET /categories/{id}
@desc Get category
@required {id: int # The unique identifier of the category.}
@returns(200) {id: int, title: str, colour: str(CSS-style hex triplet), children: [map], parent_id: int, is_transfer: bool, is_bill: bool, roll_up: bool, refund_behaviour: str?, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)} # Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint PUT /categories/{id}
@desc Update category
@required {id: int # The unique identifier of the category.}
@optional {title: str # A new title for the category., colour: str # A new CSS-style hex colour for the category., parent_id: int # The unique identifier of a parent category for the category, making this category a child of that category., is_transfer: bool # Set the category as a transfer category., is_bill: bool # Set the category as a bill category., roll_up: bool # Set the category to be rolled up into its parent category., refund_behaviour: str(debits_are_deductions/credits_are_refunds) # Set the refund behaviour of the category.}
@returns(200) {id: int, title: str, colour: str(CSS-style hex triplet), children: [map], parent_id: int, is_transfer: bool, is_bill: bool, roll_up: bool, refund_behaviour: str?, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endpoint DELETE /categories/{id}
@desc Delete category
@required {id: int # The unique identifier of the category.}
@returns(204) Success
@errors {403: Not Allowed, 404: Not Found}

@endgroup

@group users
@endpoint GET /users/{id}/categories
@desc List categories in user
@required {id: int # The unique identifier of the user.}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint POST /users/{id}/categories
@desc Create category in user
@required {id: int # The unique identifier of the user., title: str # A title for the category.}
@optional {colour: str # A CSS-style hex colour for the category., parent_id: int # The unique identifier of a category to be the parent of this category., is_transfer: bool # Set the category as a transfer category., is_bill: bool # Set the category as a bill category., roll_up: bool # Set the category to be rolled up into its parent category., refund_behaviour: str(debits_are_deductions/credits_are_refunds) # Set the refund behaviour of the category.}
@returns(201) {id: int, title: str, colour: str(CSS-style hex triplet), children: [map], parent_id: int, is_transfer: bool, is_bill: bool, roll_up: bool, refund_behaviour: str?, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endpoint GET /users/{id}/category_rules
@desc List category rules in user
@required {id: int # The unique identifier of the user.}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endgroup

@group categories
@endpoint POST /categories/{id}/category_rules
@desc Create category rule in category
@required {id: int # The unique identifier of the category., payee_matches: str # The keyword/s to match the transaction payees.}
@optional {apply_to_uncategorised: bool # Apply the created category rule to all uncategorised transactions., apply_to_all: bool # Apply the created category rule to all transactions.}
@returns(200) {category: map{id: int, title: str, colour: str(CSS-style hex triplet), children: [map], parent_id: int, is_transfer: bool, is_bill: bool, roll_up: bool, refund_behaviour: str?, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)}, id: int, payee_matches: str, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endgroup

@group users
@endpoint GET /users/{id}/budget
@desc List budget for user
@required {id: int # The unique identifier of the account.}
@optional {roll_up: bool # Whether parent categories should have their children rolled up into them. When used, the children will still appear in the collection on their own, but their actual and forecast figures will be rolled up to the root parent.}
@returns(200) Success

@endpoint GET /users/{id}/budget_summary
@desc Get budget summary for user
@required {id: int # The unique identifier of the user., period: str(weeks/months/years/event) # The period to analyse in, one of `weeks`, `months` or `years`. Also supported is `event`, although event period analysis is only possible when the budget events gathered align, so in this case where all categories are analysed together, it's highly unlikely that event period analysis will be possible., interval: int # The period interval, e.g. if the interval is 2 and the period is weeks, the budget will be analysed fortnightly., start_date: str # The date to start analysing the budget from. This will be bumped out to make full periods as necessary., end_date: str # The date to stop analysing the budget from. This will be bumped out to make full periods as necessary.}
@returns(200) Success
@errors {400: Bad Request, 403: Not Allowed, 404: Not Found}

@endpoint GET /users/{id}/trend_analysis
@desc Get trend analysis for user
@required {id: int # The unique identifier of the user., period: str(weeks/months/years/event) # The period to analyse in, one of `weeks`, `months` or `years`. Also supported is `event`, although event period analysis is only possible when the budget events gathered align, so in this case where all categories are analysed together, it's highly unlikely that event period analysis will be possible., interval: int # The period interval, e.g. if the interval is 2 and the period is weeks, the budget will be analysed fortnightly., start_date: str # The date to start analysing the budget from. This will be bumped out to make full periods as necessary., end_date: str # The date to stop analysing the budget from. This will be bumped out to make full periods as necessary., categories: str # A comma-separated list of category IDs to analyse., scenarios: str # A comma-separated list of scenario IDs to analyse. You're likely going to want to include all a user's scenarios here, unless you have reason to only analyse for a subset of scenarios. Regardless of what scenarios are analysed, all actuals (transactions) across all accounts will be included.}
@returns(200) Success
@errors {400: Bad Request, 403: Not Allowed, 404: Not Found, 422: Validation Error}

@endpoint DELETE /users/{id}/forecast_cache
@desc Delete forecast cache for user
@required {id: int # The unique identifier of the user.}
@returns(204) Success
@errors {403: Not Allowed, 404: Not Found}

@endgroup

@group events
@endpoint GET /events/{id}
@desc Get event
@required {id: str # The unique identifier of the event.}
@returns(200) {id: str, category: map{id: int, title: str, colour: str(CSS-style hex triplet), children: [map], parent_id: int, is_transfer: bool, is_bill: bool, roll_up: bool, refund_behaviour: str?, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)}, scenario: map{id: int, title: str, description: str, interest_rate: num, interest_rate_repeat_id: int, type: str, minimum-value: num, maximum-value: num, achieve_date: str, starting_balance: num, starting_balance_date: str, closing_balance: num, closing_balance_date: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, created_at: str, updated_at: str}, amount: num, amount_in_base_currency: num, currency_code: str, date: str, colour: str, note: str, repeat_type: str, repeat_interval: int, series_id: int, series_start_id: str, infinite_series: bool} # Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint PUT /events/{id}
@desc Update event
@required {id: str # The unique identifier of the event., behaviour: str(one/forward/all) # Whether the update applies only to this event, to all events within the series from this event or to all events within the series.}
@optional {amount: num # The amount of the event. A positive amount is a credit, and a negative amount is a debit., repeat_type: str(once/daily/weekly/fortnightly/monthly/yearly/each weekday) # The repeat type of the event., repeat_interval: int # The repeat interval of the event., note: str # A note for the event.}
@returns(200) {id: str, category: map{id: int, title: str, colour: str(CSS-style hex triplet), children: [map], parent_id: int, is_transfer: bool, is_bill: bool, roll_up: bool, refund_behaviour: str?, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)}, scenario: map{id: int, title: str, description: str, interest_rate: num, interest_rate_repeat_id: int, type: str, minimum-value: num, maximum-value: num, achieve_date: str, starting_balance: num, starting_balance_date: str, closing_balance: num, closing_balance_date: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, created_at: str, updated_at: str}, amount: num, amount_in_base_currency: num, currency_code: str, date: str, colour: str, note: str, repeat_type: str, repeat_interval: int, series_id: int, series_start_id: str, infinite_series: bool} # Success
@errors {400: Bad Request, 403: Not Allowed, 404: Not Found, 409: Conflict, 422: Validation Error}

@endpoint DELETE /events/{id}
@desc Delete event
@required {id: str # The unique identifier of the event., behaviour: str(one/forward/all) # Whether the delete applies only to this event, to all events within the series from this event or to all events within the series.}
@returns(204) Success
@errors {400: Bad Request, 403: Not Allowed, 404: Not Found, 409: Conflict}

@endgroup

@group users
@endpoint GET /users/{id}/events
@desc List events in user.
@required {id: int # The unique identifier of the user., start_date: str # Return the events from and including this date., end_date: str # Return the events until and including this date.}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endgroup

@group scenarios
@endpoint GET /scenarios/{id}/events
@desc List events in scenario.
@required {id: int # The unique identifier of the scenario., start_date: str # Return the events from and including this date., end_date: str # Return the events until and including this date.}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint POST /scenarios/{id}/events
@desc Create event in scenario
@required {id: int # The unique identifier of the scenario., category_id: int # The unique identifier of the category for the event., date: str # The starting date of the event., amount: num # The amount of the event. A positive amount is a credit, and a negative amount is a debit., repeat_type: str(once/daily/weekly/fortnightly/monthly/yearly/each weekday) # The repeat type of the event.}
@optional {repeat_interval: int=1 # The repeat interval of the event., note: str # A note for the event.}
@returns(201) {id: str, category: map{id: int, title: str, colour: str(CSS-style hex triplet), children: [map], parent_id: int, is_transfer: bool, is_bill: bool, roll_up: bool, refund_behaviour: str?, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)}, scenario: map{id: int, title: str, description: str, interest_rate: num, interest_rate_repeat_id: int, type: str, minimum-value: num, maximum-value: num, achieve_date: str, starting_balance: num, starting_balance_date: str, closing_balance: num, closing_balance_date: str, current_balance: num, current_balance_date: str, current_balance_in_base_currency: num, current_balance_exchange_rate: num, safe_balance: num, safe_balance_in_base_currency: num, created_at: str, updated_at: str}, amount: num, amount_in_base_currency: num, currency_code: str, date: str, colour: str, note: str, repeat_type: str, repeat_interval: int, series_id: int, series_start_id: str, infinite_series: bool} # Success
@errors {403: Not Allowed, 404: Not Found, 409: Conflict, 422: Validation Error}

@endgroup

@group attachments
@endpoint GET /attachments/{id}
@desc Get attachment
@required {id: int # The unique identifier of the attachment.}
@returns(200) {id: int, title: str, file_name: str, type: str, content_type: str, content_type_meta: map{title: str, description: str, extension: str}, original_url: str, variants: map{large_url: str, thumb_url: str}, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)} # Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint PUT /attachments/{id}
@desc Update attachment
@required {id: int # The unique identifier of the attachment.}
@optional {title: str # The new title of the attachment. If the title is blank or not provided, the server will derive a title from the file name.}
@returns(200) {id: int, title: str, file_name: str, type: str, content_type: str, content_type_meta: map{title: str, description: str, extension: str}, original_url: str, variants: map{large_url: str, thumb_url: str}, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endpoint DELETE /attachments/{id}
@desc Delete attachment
@required {id: int # The unique identifier of the attachment.}
@returns(204) Success
@errors {403: Not Allowed, 404: Not Found}

@endgroup

@group users
@endpoint GET /users/{id}/attachments
@desc Lists attachments in user
@required {id: int # The unique identifier of the user.}
@optional {unassigned: int # If set, returns unassigned attachments, that are available for assigning to a transaction.}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint POST /users/{id}/attachments
@desc Create attachment in user
@required {id: int # The unique identifier of the user.}
@optional {title: str # The title of the attachment. If the title is blank or not provided, the title will derived from the file name., file_name: str # The file name of the attachment., file_data: str(base64) # The base64-encoded contents of the source file. The supported file types are png, jpg, pdf, xls, xlsx, doc, docx.}
@returns(200) {id: int, title: str, file_name: str, type: str, content_type: str, content_type_meta: map{title: str, description: str, extension: str}, original_url: str, variants: map{large_url: str, thumb_url: str}, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)} # Success
@errors {403: Not Allowed, 404: Not Found, 422: Validation Error}

@endgroup

@group transactions
@endpoint GET /transactions/{id}/attachments
@desc List attachments in transaction
@required {id: int # The unique identifier of the transaction.}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint POST /transactions/{id}/attachments
@desc Assigns attachment to transaction
@required {id: int # The unique identifier of the transaction.}
@optional {attachment_id: int # The unique identifier of the attachment.}
@returns(201) {id: int, title: str, file_name: str, type: str, content_type: str, content_type_meta: map{title: str, description: str, extension: str}, original_url: str, variants: map{large_url: str, thumb_url: str}, created_at: str(ISO 8601 timestamp), updated_at: str(ISO 8601 timestamp)} # Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint DELETE /transactions/{transaction_id}/attachments/{attachment_id}
@desc Unassigns attachment in transaction
@required {transaction_id: int # The unique identifier of the transaction., attachment_id: int # The unique identifier of the attachment.}
@returns(204) Success
@errors {403: Not Allowed, 404: Not Found}

@endgroup

@group users
@endpoint GET /users/{id}/labels
@desc List labels in user
@required {id: int # The unique identifier of the user.}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endpoint GET /users/{id}/saved_searches
@desc List saved searches in user
@required {id: int # The unique identifier of the user.}
@returns(200) Success
@errors {403: Not Allowed, 404: Not Found}

@endgroup

@group currencies
@endpoint GET /currencies
@desc List currencies
@returns(200) Success

@endpoint GET /currencies/{id}
@desc Get currency
@required {id: str # The unique identifier of the currency.}
@returns(200) {id: str, name: str, minor_unit: int, separators: map{major: str, minor: str}, symbol: str} # Success
@errors {404: Not Found}

@endgroup

@group time_zones
@endpoint GET /time_zones
@desc List time zones
@returns(200) Success

@endgroup

@end