@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
@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}
@errors {403}

@endgroup

@group users
@endpoint GET /users/{id}
@required {id: int}
@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}
@errors {403, 404}

@endpoint PUT /users/{id}
@required {id: int}
@optional {name: str, time_zone: str, week_start_day: int, beta_user: bool, base_currency_code: str, always_show_base_currency: bool}
@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}
@errors {403, 404, 422}

@endgroup

@group institutions
@endpoint GET /institutions/{id}
@required {id: int}
@returns(200) {currency_code: str, title: str, updated_at: str, created_at: str, id: int}
@errors {403, 404}

@endpoint PUT /institutions/{id}
@required {id: int}
@optional {title: str, currency_code: str}
@returns(200) {currency_code: str, title: str, updated_at: str, created_at: str, id: int}
@errors {403, 404, 422}

@endpoint DELETE /institutions/{id}
@required {id: int}
@optional {merge_into_institution_id: int}
@returns(204)
@errors {403, 404, 422}

@endgroup

@group users
@endpoint GET /users/{id}/institutions
@required {id: int}
@returns(200)
@errors {403, 404}

@endpoint POST /users/{id}/institutions
@required {id: int, title: str, currency_code: str}
@returns(201) {currency_code: str, title: str, updated_at: str, created_at: str, id: int}
@errors {403, 404, 422}

@endgroup

@group accounts
@endpoint GET /accounts/{id}
@required {id: int}
@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}
@errors {403, 404}

@endpoint PUT /accounts/{id}
@required {id: int}
@optional {title: str, currency_code: str, type: str(bank/credits/cash/loans/mortgage/stocks/vehicle/property/insurance/other_asset/other_liability), is_net_worth: bool}
@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}
@errors {403, 404, 422}

@endpoint DELETE /accounts/{id}
@required {id: int}
@returns(204)
@errors {403, 404, 422}

@endgroup

@group users
@endpoint GET /users/{id}/accounts
@required {id: int}
@returns(200)
@errors {403, 404}

@endpoint PUT /users/{id}/accounts
@required {id: int, 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}]}
@returns(200)
@errors {400, 403, 404}

@endpoint POST /users/{id}/accounts
@required {id: int, institution_id: int, title: str, currency_code: str, type: str(bank/credits/cash/loans/mortgage/stocks/vehicle/property/insurance/other_asset/other_liability)}
@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}
@errors {403, 404, 422}

@endgroup

@group institutions
@endpoint GET /institutions/{id}/accounts
@required {id: int}
@returns(200)
@errors {403, 404}

@endgroup

@group transaction_accounts
@endpoint GET /transaction_accounts/{id}
@required {id: int}
@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}
@errors {403, 404}

@endpoint PUT /transaction_accounts/{id}
@required {id: int}
@optional {institution_id: int, starting_balance: num, starting_balance_date: str}
@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}
@errors {403, 404, 422}

@endgroup

@group users
@endpoint GET /users/{id}/transaction_accounts
@required {id: int}
@returns(200)
@errors {403, 404}

@endgroup

@group transactions
@endpoint GET /transactions/{id}
@required {id: int}
@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}
@errors {403, 404}

@endpoint PUT /transactions/{id}
@required {id: int}
@optional {memo: str, cheque_number: str, payee: str, amount: num, date: str, is_transfer: bool, category_id: int, note: str, needs_review: bool, labels: str, splits: [map{amount!: num, payee: str, category_id: int, is_transfer: bool, date: str}]}
@returns(200)
@errors {403, 404, 422}

@endpoint DELETE /transactions/{id}
@required {id: int}
@returns(204)
@errors {403, 404}

@endgroup

@group users
@endpoint GET /users/{id}/transactions
@required {id: int}
@optional {start_date: str, end_date: str, updated_since: str, uncategorised: int, type: str(debit/credit), needs_review: int, search: str, page: int}
@returns(200)
@errors {400, 403, 404}

@endgroup

@group accounts
@endpoint GET /accounts/{id}/transactions
@required {id: int}
@optional {start_date: str, end_date: str, updated_since: str, uncategorised: int, type: str(debit/credit), needs_review: int, search: str, page: int}
@returns(200)
@errors {400, 403, 404}

@endgroup

@group categories
@endpoint GET /categories/{id}/transactions
@required {id: str}
@optional {start_date: str, end_date: str, updated_since: str, uncategorised: int, type: str(debit/credit), needs_review: int, search: str, page: int}
@returns(200)
@errors {400, 403, 404}

@endgroup

@group transaction_accounts
@endpoint GET /transaction_accounts/{id}/transactions
@required {id: int}
@optional {start_date: str, end_date: str, updated_since: str, uncategorised: int, type: str(debit/credit), needs_review: int, search: str, page: int}
@returns(200)
@errors {400, 403, 404}

@endpoint POST /transaction_accounts/{id}/transactions
@required {id: int, payee: str, amount: num, date: str}
@optional {is_transfer: bool, labels: str, category_id: int, note: str, memo: str, cheque_number: str, needs_review: bool}
@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}
@errors {403, 404, 422}

@endgroup

@group categories
@endpoint GET /categories/{id}
@required {id: int}
@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)}
@errors {403, 404}

@endpoint PUT /categories/{id}
@required {id: int}
@optional {title: str, colour: str, parent_id: int, is_transfer: bool, is_bill: bool, roll_up: bool, refund_behaviour: str(debits_are_deductions/credits_are_refunds)}
@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)}
@errors {403, 404, 422}

@endpoint DELETE /categories/{id}
@required {id: int}
@returns(204)
@errors {403, 404}

@endgroup

@group users
@endpoint GET /users/{id}/categories
@required {id: int}
@returns(200)
@errors {403, 404}

@endpoint POST /users/{id}/categories
@required {id: int, title: str}
@optional {colour: str, parent_id: int, is_transfer: bool, is_bill: bool, roll_up: bool, refund_behaviour: str(debits_are_deductions/credits_are_refunds)}
@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)}
@errors {403, 404, 422}

@endpoint GET /users/{id}/category_rules
@required {id: int}
@returns(200)
@errors {403, 404}

@endgroup

@group categories
@endpoint POST /categories/{id}/category_rules
@required {id: int, payee_matches: str}
@optional {apply_to_uncategorised: bool, apply_to_all: bool}
@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)}
@errors {403, 404, 422}

@endgroup

@group users
@endpoint GET /users/{id}/budget
@required {id: int}
@optional {roll_up: bool}
@returns(200)

@endpoint GET /users/{id}/budget_summary
@required {id: int, period: str(weeks/months/years/event), interval: int, start_date: str, end_date: str}
@returns(200)
@errors {400, 403, 404}

@endpoint GET /users/{id}/trend_analysis
@required {id: int, period: str(weeks/months/years/event), interval: int, start_date: str, end_date: str, categories: str, scenarios: str}
@returns(200)
@errors {400, 403, 404, 422}

@endpoint DELETE /users/{id}/forecast_cache
@required {id: int}
@returns(204)
@errors {403, 404}

@endgroup

@group events
@endpoint GET /events/{id}
@required {id: str}
@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}
@errors {403, 404}

@endpoint PUT /events/{id}
@required {id: str, behaviour: str(one/forward/all)}
@optional {amount: num, repeat_type: str(once/daily/weekly/fortnightly/monthly/yearly/each weekday), repeat_interval: int, note: str}
@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}
@errors {400, 403, 404, 409, 422}

@endpoint DELETE /events/{id}
@required {id: str, behaviour: str(one/forward/all)}
@returns(204)
@errors {400, 403, 404, 409}

@endgroup

@group users
@endpoint GET /users/{id}/events
@required {id: int, start_date: str, end_date: str}
@returns(200)
@errors {403, 404}

@endgroup

@group scenarios
@endpoint GET /scenarios/{id}/events
@required {id: int, start_date: str, end_date: str}
@returns(200)
@errors {403, 404}

@endpoint POST /scenarios/{id}/events
@required {id: int, category_id: int, date: str, amount: num, repeat_type: str(once/daily/weekly/fortnightly/monthly/yearly/each weekday)}
@optional {repeat_interval: int=1, note: str}
@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}
@errors {403, 404, 409, 422}

@endgroup

@group attachments
@endpoint GET /attachments/{id}
@required {id: int}
@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)}
@errors {403, 404}

@endpoint PUT /attachments/{id}
@required {id: int}
@optional {title: str}
@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)}
@errors {403, 404, 422}

@endpoint DELETE /attachments/{id}
@required {id: int}
@returns(204)
@errors {403, 404}

@endgroup

@group users
@endpoint GET /users/{id}/attachments
@required {id: int}
@optional {unassigned: int}
@returns(200)
@errors {403, 404}

@endpoint POST /users/{id}/attachments
@required {id: int}
@optional {title: str, file_name: str, file_data: str(base64)}
@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)}
@errors {403, 404, 422}

@endgroup

@group transactions
@endpoint GET /transactions/{id}/attachments
@required {id: int}
@returns(200)
@errors {403, 404}

@endpoint POST /transactions/{id}/attachments
@required {id: int}
@optional {attachment_id: int}
@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)}
@errors {403, 404}

@endpoint DELETE /transactions/{transaction_id}/attachments/{attachment_id}
@required {transaction_id: int, attachment_id: int}
@returns(204)
@errors {403, 404}

@endgroup

@group users
@endpoint GET /users/{id}/labels
@required {id: int}
@returns(200)
@errors {403, 404}

@endpoint GET /users/{id}/saved_searches
@required {id: int}
@returns(200)
@errors {403, 404}

@endgroup

@group currencies
@endpoint GET /currencies
@returns(200)

@endpoint GET /currencies/{id}
@required {id: str}
@returns(200) {id: str, name: str, minor_unit: int, separators: map{major: str, minor: str}, symbol: str}
@errors {404}

@endgroup

@group time_zones
@endpoint GET /time_zones
@returns(200)

@endgroup

@end