NQD API getting started

The developer credential flow authenticates your account; it does not create a profile, workspace, or bypass their limits.

Read the financial sources guide before importing bank movements. It explains when to create an Invoice, Income, Expense, Payout, or Asset, and when to record a cash Transaction against an existing source.

Set the origins once for your shell. The local launcher uses port 1335; production uses the origins configured for your deployment.

export AUTH="http://auth.nqd.localhost:1335"
export API="http://api.nqd.localhost:1335"
export DASH="http://dash.nqd.localhost:1335"
export DOCS="http://docs.nqd.localhost:1335"
export MCP="http://mcp.nqd.localhost:1335"
export CLI="http://cli.nqd.localhost:1335"

Local origins

The canonical production origins are HTTPS subdomains configured by your deployment. Local development uses the shared HTTP origin configured by the launcher. The default registered origins are auth, api, dash, web, docs, mcp, and cli under nqd.localhost:1335. Resolve branch or fixture origins from the launcher instead of copying these defaults into a client. Use the CLI guide for the installed command and the MCP guide for remote tool clients.

1. Request and verify a code

Use your own email and the received code. These fictional examples never execute from Docs.

curl "$AUTH/v1/email/challenges" \
  --json '{"email":"developer@example.test"}'

curl "$AUTH/v1/email/verifications" \
  --json '{"email":"developer@example.test","code":"123456"}'

Verification returns access_token, token_type: "bearer", and the provider’s expires_at Unix seconds. Store the token securely as $TOKEN. No refresh token or Dash cookie is returned. Obtain a new OTP credential when it expires.

2. Discover workspaces

curl "$API/v1/workspaces" -H "Authorization: Bearer $TOKEN"

Choose an ID from data. Store it as $WORKSPACE. Workspace discovery is identity-scoped and accepts no Workspace-Id header.

3. Read the catalog and payable settings

curl "$API/v1/currencies?limit=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Workspace-Id: $WORKSPACE"

curl "$API/v1/entries?limit=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Workspace-Id: $WORKSPACE"

curl "$API/v1/modifiers?limit=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Workspace-Id: $WORKSPACE"

curl "$API/v1/settings/payables" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Workspace-Id: $WORKSPACE"

The catalog responses return records in data and page metadata, including an opaque page.nextCursor when more records are available. Payable settings identify the workspace’s current payable modifier. Use IDs returned by these resources when you create a financial record. Do not invent related records or put a Workspace ID in a Client field.

Workspace-scoped bodies do not repeat workspaceId; the Workspace-Id header supplies that scope. Collection responses place arrays in data; single-resource responses place one object there.

4. Create a draft

For a fictional Workspace with 15% VAT, save the following as invoice.json. Replace the Currency, Entry, and Modifier IDs with records from your Workspace. The Entry price is 100 net, and the applied modifier supplies the VAT. Preserve decimal strings. The IDs below are illustrative; use the IDs returned by the catalog resources.

[
  {
    "name": "Fictional consulting draft",
    "description": "Fictional example",
    "clientId": null,
    "projectId": null,
    "contactId": null,
    "bankAccountId": null,
    "currencyId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "entries": [
      {
        "id": "01ARZ3NDEKTSV4RRFFQ69G5FA7",
        "name": "Consulting",
        "description": "Fictional example",
        "quantity": "1",
        "unit": "hour",
        "pricePerUnit": "100"
      }
    ],
    "modifiers": [
      {
        "id": "01ARZ3NDEKTSV4RRFFQ69G5FA9",
        "name": "VAT",
        "value": "15.00%"
      }
    ],
    "tags": []
  }
]

Each POST body is an array of writable records. currencyId, entries, and modifiers are fields on each record. The response returns the created records in data; the request uses relationship IDs so the server can validate them against the workspace catalog. The example uses the standard hour catalog unit; use a unit returned by the units resource in your workspace. A modifier’s value uses a trailing % for a percentage and a leading - for a decrease. Core applies the workspace’s configured payable modifier as the tax rule when calculating totals.

curl "$API/v1/invoices" -H "Authorization: Bearer $TOKEN" \
  -H "Workspace-Id: $WORKSPACE" \
  -H 'Content-Type: application/json' --data-binary @invoice.json

A successful create returns 201 and a data array because this resource create accepts a batch envelope. Follow the returned record ID with the same bearer and workspace headers. Read the invoice reference before updating the invoice or posting payments. If a write’s response is lost, reconcile the current source and transaction summary before retrying.