Developer Shell

Interactive API terminal built into every page of SpeyBooks. Test any endpoint, explore routes with tab autocomplete, and inspect JSON responses - all without leaving the browser.

The shell consumes the same API endpoints as external integrations. There are no special internal routes. Anything you test in the shell works identically with curl or your HTTP client.

What it looks like

The shell is a dark terminal panel docked to the bottom of the content area. It sits within the main content column and never overlaps the sidebar navigation.

When collapsed, it appears as a slim bar with a $ prompt, a text input, and a Shell label on the right. You can type directly into the collapsed bar - pressing Enter expands the panel and executes the command. When expanded, you get a full output area above the input, a resize handle along the top edge, and minimise/close buttons in the header.

The panel is hidden on mobile viewports.

A typical exploration

The fastest way to understand the shell is to use it. Open the shell with Ctrl+J and try this sequence:

1. GET /contacts - lists your contacts with their prefixed IDs
2. Click cont_17 in the response - the shell populates GET /contacts/cont_17 and fetches the full contact
3. GET /invoices?contactId=cont_17&status=sent - filter that contact's outstanding invoices

Each response is syntax-highlighted (keys in blue, strings in green, numbers in amber) with a colour-coded status badge and response time. Every prefixed ID in the output is an underlined, clickable link.

Opening the shell

Press Ctrl+J (Windows/Linux) or Cmd+J (macOS) from any page to toggle the shell. The panel persists as you navigate between pages - your output and command history are preserved until you explicitly close.

Making requests

Type an HTTP method and path, then press Enter. Paths are relative to /api/v1/ - the shell prepends this prefix automatically.

Methods are colour-coded as you type: GET in green, POST in blue, PUT and PATCH in amber, DELETE in red. The status badge on each response follows the same scheme: 2xx green, 4xx amber, 5xx red.

Sending a body

For POST, PUT, and PATCH requests, add a JSON object after the path. The shell validates the JSON before sending - if the syntax is invalid, it shows an error immediately without making a request.

PATCH /categorisation-rules/rule_3 \
  {"field": "description", "operator": "contains", "value": "AWS"}

Error responses

Errors are displayed the same way as successful responses - full JSON body with syntax highlighting and a colour-coded status badge. The 4xx statuses appear in amber, 5xx in red.

This means you can inspect the error.code, error.message, and error.field values directly in the shell, which is useful for debugging validation rules or testing error handling in your integration. See the Error Handling guide for the full list of error codes.

Clickable IDs

Every prefixed ID in a response is underlined with a dotted line and turns teal on hover. Click any ID and the shell auto-populates a GET request for that resource, then executes it. This makes it easy to navigate relationships without typing paths manually.

Recognised ID prefixes

The shell recognises 25 ID prefixes across all resources:

Tab autocomplete

The shell knows every route in the API. Press Tab to complete partial paths, methods, and built-in commands. When multiple matches exist, repeated Tab presses cycle through them and the shell lists all options in the output area.

Type a partial path to narrow suggestions. /inv + Tab shows all invoice routes. /dir + Tab shows directors, director-loans, and dividends. /rep + Tab shows all report endpoints.

Ghost text appears in dark grey ahead of your cursor as you type, suggesting completions from your history and common commands. Press the right arrow key to accept.

Route discovery

The routes command lists all 197 endpoints grouped by category: Core, Accounting, Banking, Company, Import & Migration, Integration, Platform, and Admin. Each route shows its method (colour-coded), path, and a short description.

Add a filter to narrow the list. routes dividend shows the 12 dividend-related endpoints. routes GET shows all read-only endpoints. routes bank shows banking routes including imports and categorisation rules. The filter matches against the path, method, and description.

Exporting to curl

After making a request, type curl to export it as a copy-pasteable curl command. The export uses the external API URL (https://api.speybooks.com/v1/...) with an sk_live_YOUR_KEY placeholder, ready to share with colleagues or paste into scripts.

For POST requests with a body, the export includes the -d flag with your JSON payload.

Built-in commands

Keyboard shortcuts

Response viewer

Hover over any response block to reveal a copy button in the top-right corner, which copies the raw JSON to your clipboard. This is useful for pasting responses into bug reports or comparing output between requests.

Resizing

Drag the top edge of the expanded panel to resize it. The minimum height is 200px; the maximum extends to the full viewport minus 120px. Your preferred height is saved in localStorage.

History

Command history is stored in localStorage and persists across page reloads and browser restarts. The shell keeps the last 100 commands, automatically deduplicating repeated entries.

Press up and down to cycle through previous commands. Type history to see the last 20 with line numbers.

Authentication

The shell uses your active browser session (JWT token). No API key is needed - if you are logged in to SpeyBooks, the shell is authenticated. Run env to confirm your session is active.

If env shows Not authenticated, refresh the page or log in again.