EuGasto API

Versioned HTTP API. The web app and API keys call the shared domain services. Send a session cookie, or Authorization: Bearer with a personal API key. Amounts are integer minor units. Every workspace route is limited to a workspace the caller belongs to. Version 0.1.0.

Authentication

Send the session cookie from /api/auth, or a personal API key as Authorization: Bearer ldl_…. Keys are created in Settings and shown once. A key is limited to one workspace and to the scopes stamped on it (read, write). Managing keys requires a signed-in session.

The machine-readable document is /api/v1/openapi.json. Amounts are integer minor units. Each workspace is single-currency until conversion ships, and every route is scoped to a workspace the caller belongs to.

System

GET /api/v1/health

Service health

GET /api/v1/hints

Sign-up suggestions

Account

GET /api/v1/me

Current user and workspaces

DELETE /api/v1/me

Delete my account and owned spaces

Workspaces

POST /api/v1/workspaces

Create a workspace

PATCH /api/v1/workspaces/{workspaceId}

Update workspace settings

Accounts

GET /api/v1/workspaces/{workspaceId}/accounts

List payment accounts

  • q
  • from
  • to
  • categoryId
  • tagId
  • accountId
  • payee
  • sellerVat
  • minMinor
  • maxMinor
  • sort
  • direction
  • page
  • pageSize
  • includeArchived
  • asOf
  • groupBy
POST /api/v1/workspaces/{workspaceId}/accounts

Create a payment account

PATCH /api/v1/workspaces/{workspaceId}/accounts/{accountId}

Update a payment account

Categories

GET /api/v1/workspaces/{workspaceId}/categories

List categories

  • q
  • from
  • to
  • categoryId
  • tagId
  • accountId
  • payee
  • sellerVat
  • minMinor
  • maxMinor
  • sort
  • direction
  • page
  • pageSize
  • includeArchived
  • asOf
  • groupBy
POST /api/v1/workspaces/{workspaceId}/categories

Create a category

PATCH /api/v1/workspaces/{workspaceId}/categories/{categoryId}

Update or archive a category

Tags

GET /api/v1/workspaces/{workspaceId}/tags

List tags

POST /api/v1/workspaces/{workspaceId}/tags

Create a tag

PATCH /api/v1/workspaces/{workspaceId}/tags/{tagId}

Rename a tag

DELETE /api/v1/workspaces/{workspaceId}/tags/{tagId}

Delete a tag

Expenses

GET /api/v1/workspaces/{workspaceId}/expenses

Search expenses

  • q
  • from
  • to
  • categoryId
  • tagId
  • accountId
  • payee
  • sellerVat
  • minMinor
  • maxMinor
  • sort
  • direction
  • page
  • pageSize
  • includeArchived
  • asOf
  • groupBy
POST /api/v1/workspaces/{workspaceId}/expenses

Record an expense

GET /api/v1/workspaces/{workspaceId}/expenses/{expenseId}

Get an expense

PATCH /api/v1/workspaces/{workspaceId}/expenses/{expenseId}

Update an expense

DELETE /api/v1/workspaces/{workspaceId}/expenses/{expenseId}

Delete an expense

POST /api/v1/workspaces/{workspaceId}/invoice-qr/preview

Preview a Portuguese invoice QR code

POST /api/v1/workspaces/{workspaceId}/expenses/{expenseId}/receipts

Upload a receipt

GET /api/v1/workspaces/{workspaceId}/expenses/{expenseId}/receipts/{receiptId}

Download a receipt

DELETE /api/v1/workspaces/{workspaceId}/expenses/{expenseId}/receipts/{receiptId}

Delete a receipt

Reports

GET /api/v1/workspaces/{workspaceId}/reports/dashboard

Dashboard figures

  • q
  • from
  • to
  • categoryId
  • tagId
  • accountId
  • payee
  • sellerVat
  • minMinor
  • maxMinor
  • sort
  • direction
  • page
  • pageSize
  • includeArchived
  • asOf
  • groupBy
GET /api/v1/workspaces/{workspaceId}/reports/summary

Spending report

  • q
  • from
  • to
  • categoryId
  • tagId
  • accountId
  • payee
  • sellerVat
  • minMinor
  • maxMinor
  • sort
  • direction
  • page
  • pageSize
  • includeArchived
  • asOf
  • groupBy
GET /api/v1/workspaces/{workspaceId}/exports/expenses.csv

Export expenses as CSV

  • q
  • from
  • to
  • categoryId
  • tagId
  • accountId
  • payee
  • sellerVat
  • minMinor
  • maxMinor
  • sort
  • direction
  • page
  • pageSize
  • includeArchived
  • asOf
  • groupBy
GET /api/v1/workspaces/{workspaceId}/exports/report.pdf

Download a PDF report

  • q
  • from
  • to
  • categoryId
  • tagId
  • accountId
  • payee
  • sellerVat
  • minMinor
  • maxMinor
  • sort
  • direction
  • page
  • pageSize
  • includeArchived
  • asOf
  • groupBy

Imports

POST /api/v1/workspaces/{workspaceId}/imports/preview

Preview a CSV import

POST /api/v1/workspaces/{workspaceId}/imports

Import a CSV

GET /api/v1/workspaces/{workspaceId}/imports

List imports

POST /api/v1/workspaces/{workspaceId}/imports/{importId}/undo

Undo an import

GET /api/v1/workspaces/{workspaceId}/import-mappings

List saved CSV mappings

POST /api/v1/workspaces/{workspaceId}/import-mappings

Save a CSV mapping

DELETE /api/v1/workspaces/{workspaceId}/import-mappings/{mappingId}

Delete a saved mapping

API keys

GET /api/v1/workspaces/{workspaceId}/api-keys

List API keys

POST /api/v1/workspaces/{workspaceId}/api-keys

Create an API key

POST /api/v1/workspaces/{workspaceId}/api-keys/{keyId}/revoke

Revoke an API key

Budgets

GET /api/v1/workspaces/{workspaceId}/budgets

List budgets