# TableWealth Public API

Use this API to read organization-scoped TableWealth financial data: accounts, transactions, holdings, tags, and organization metadata.

Authentication:
- Send the API key in the X-API-Key header.
- Call GET /v1/api-key first. It returns the current key scopes, account access, rate limits, and available operations.

Important workflows:
- Discover capabilities: GET /v1/api-key
- List accounts: GET /v1/accounts?pageSize=50
- Fetch one account: GET /v1/accounts/{accountId}
- Fetch transactions for a date range: GET /v1/transactions?dateFrom=2026-01-01&dateTo=2026-01-31&pageSize=100
- Fetch transactions for one account: GET /v1/accounts/{accountId}/transactions
- Fetch holdings: GET /v1/holdings or GET /v1/accounts/{accountId}/holdings
- List tags: GET /v1/tags?type=transaction
- Create tags: POST /v1/tags with the tags:write scope
- Attach tags to transactions: POST /v1/tags/{tagId}/transactions with the tags:write scope

Pagination:
- List endpoints accept pageSize up to 100.
- If pagination.nextPageToken is present, pass it back as pageToken on the next request.

Errors:
- 401 unauthorized means the key is missing, malformed, expired, revoked, or unknown.
- 403 forbidden_scope means the key is valid but lacks the required scope.
- 404 on account detail can mean the account does not exist or is not accessible to the key.
- 429 rate_limited means wait for Retry-After before retrying.

Financial semantics:
- Dates use YYYY-MM-DD for date-only fields.
- Transaction amount is the stored source-normalized amount.
- Transaction displayAmount is user-facing and currently equals amount * -1.
- Empty lists can mean the API key has restricted account access, not necessarily that the organization has no data.
- API data is not investment advice.

Machine-readable contract:
- OpenAPI is available at /openapi.json.
- Stable operationIds are used for agent tooling.

Human-readable docs:
- Docs are available at /docs.