Developer & API

WorthSync has a small, stable public API for automating your own ledger: read your accounts and snapshots, create accounts, and write balances from a script, a spreadsheet job, or another tool you already use.

It exists because your data should not be trapped in a product. Everything the API can do, you can also do by hand in the app — and everything you put in, you can get back out.

Scope of the API

This is a personal automation API, not a platform API. There is no OAuth, no third-party app model, and no way to act on behalf of another user. A token acts as you, sees exactly what you see in the app, and is subject to the same database-level access rules as your session.

What it covers today:

• Your identity and the household the token resolves to
• Categories
• Accounts — list, read, create, update
• Snapshots — list, read, create/update, delete, and bulk write
• Outgoing webhooks for snapshot writes

Create a token

1. In the app, go to Settings → Developer.
2. Under API tokens, give the token a name and choose Create token.
3. Copy the token immediately — it is shown once and never again. WorthSync stores only a hash of it plus a short prefix so you can identify it later.

Tokens look like wsk_…. The list shows each token’s prefix and when it was last used, and Revoke disables one immediately.

Authenticate

Send the token as a bearer token on every request:

curl https://app.worthsync.com/api/public/v1/me \
  -H "Authorization: Bearer wsk_..."

The base URL is https://app.worthsync.com.

Scopes

Every endpoint requires one of three scopes:

Tokens are currently issued with all three scopes — there is no per-token scope picker in the app yet. The scope a request needs is listed with each endpoint in the API Reference, so a future narrower token stays predictable.

What a token can reach

• Access is resolved live from your account, not frozen at the moment the token was made. If you leave a household, tokens you created stop seeing that household’s shared accounts straight away.
• The account endpoints cover standard accounts only. Tangible-asset vault items are not exposed through the public API.
• The API itself needs the Household plan. Creating tokens or webhooks returns 402 on Solo (Free), and every request is checked against your household’s current plan — a token stops working if the plan lapses. Tokens you already created stay listed and revocable on any plan.
• Individual plan limits still apply on top of that. Creating or updating an account with a shared visibility requires a plan that includes sharing, and returns 402 otherwise.

Errors

Errors are JSON with an error message, sometimes with a machine-readable code or a detail payload:

{ "error": "Validation failed", "detail": [{ "path": "snapshot_date", "message": "..." }] }

Machine-readable spec

An OpenAPI 3.1 document describing the current endpoints is served from the app itself:

https://app.worthsync.com/api/public/v1/openapi.json

It requires no token to fetch and is generated from the live deployment, so it is the authoritative shape reference if this documentation and the app ever disagree.

Versioning

The path carries the version: /api/public/v1/…. Additive changes — new endpoints, new optional fields in a response — can land within v1. Write your client so unknown response fields are ignored.