v3.1.0 3 February 2026 Feature

Metadata, Categorisation, Scoped Keys & Developer Shell

Developer Shell

Interactive API testing terminal available on every page of the app. Stripe-inspired developer experience — no need to switch to Postman or curl.

  • Ctrl+J to toggle the slide-up terminal panel
  • Tab autocomplete for paths, methods, and built-in commands
  • Ghost text suggestions based on history and common commands (accept with →)
  • Clickable IDs in responses — click inv_29 or cont_1 to auto-populate a GET request
  • Copy button on hover for every response block
  • Persistent history across page reloads
  • Coloured input — method turns green/blue/amber/red as you type
  • curl export — replay any request outside the browser
  • Built-in commands: help, routes, curl, env, history, clear

Custom Metadata

Flat key-value metadata (JSONB) on invoices, contacts, transactions, and quotes. Stripe-style merge semantics — null values delete keys.

  • POST and PUT accept metadata on contacts, invoices, transactions, and quotes
  • Max 50 keys per entity, keys: 1–40 chars, values: max 500 chars, _sb_ prefix reserved
  • GIN-indexed for future query support

Categorisation Rules

Auto-categorisation engine for bank transactions. Rules match on description, contact name, amount, reference, or metadata fields.

  • CRUD endpoints at /api/v1/categorisation-rules
  • Test endpoint to preview matches before activating
  • Bulk reorder by priority
  • Max 100 rules per organisation

Scoped API Keys

API keys now support fine-grained permissions using resource:action scopes (e.g. invoices:read, contacts:write). Returns 403 INSUFFICIENT_SCOPE when denied.

Idempotency Keys

Idempotency-Key header supported on all POST, PUT, and PATCH requests via API key auth. Replaying the same key returns the cached response with Idempotent-Replayed: true. Body mismatch returns 422 IDEMPOTENCY_MISMATCH. Concurrent duplicates return 409 IDEMPOTENCY_CONFLICT. Keys expire after 24 hours. 5xx responses release the key for retry.

Documentation

API reference published at docs.speybooks.com for all v3.1.0 features. Full audit against source code resolved 10 discrepancies before publication.

  • New docs: categorisation-rules, quotes, organisation, webhooks, metadata, idempotency
  • Updated: authentication (4 new scopes), overview (perPage param, new resources)
  • Corrected categorisation rules API surface (field/operator/value, not pattern/matchType)
  • Corrected idempotency scope (POST/PUT/PATCH, not POST-only)
  • Corrected metadata deletion semantics (null, not empty string) and max keys (50)
  • Fixed sidebar position clashes and pagination type reference

Fixes

  • Prefixed ID consistency across categorisation rules
  • API key auth sets request.user for audit logging
  • Proper error codes on categorisation rule validation failures