All API resources
Docs

API reference

Every endpoint of the Prosaic REST API, with its parameters, request and response fields, and the matching Node SDK call.

The Prosaic API is a REST API over HTTPS. It takes and returns JSON, and every path sits under one base URL:

text
https://app.prosaic.works/api/public/v1

Each operation on these pages shows its HTTP route and the prosaic-node method that calls it. The method names are the operation IDs in the OpenAPI document, so code, docs and AI tools all use the same names.

Authentication

Send an API key or an OAuth access token as a bearer token on every request:

bash
curl https://app.prosaic.works/api/public/v1/me \
  -H "Authorization: Bearer $PROSAIC_API_KEY"

API keys start with prsk_ and act as the user who created them. Use an OAuth app when your product acts for other people's workspaces. Authentication covers both, and how to choose a workspace with the x-workspace-id header when a user belongs to more than one.

With the Node SDK, create one client and reuse it:

ts
import Prosaic from 'prosaic-node';

const prosaic = new Prosaic(process.env.PROSAIC_API_KEY!);

Requests

  • Dates are calendar dates in YYYY-MM-DD form, such as 2026-04-01. Regional formats such as 01-04-2026 are rejected with a 400.
  • Amounts are accepted as strings or numbers. Send decimal strings, such as "1150.00", so nothing is lost to floating-point rounding.
  • IDs in paths, such as entityId, come from the list endpoints: GET /entities for entities and their tax rates, and GET /entities/{entityId}/charts for account codes.

Responses

Most endpoints wrap their result in data, with a meta.count where a count helps:

json
{ "data": { "id": "…" } }

Paginated lists add a pagination object instead:

json
{
  "data": [],
  "pagination": {
    "currentPage": 1,
    "pageSize": 20,
    "totalCount": 0,
    "totalPages": 0,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

Ask for a page with the page (from 1) and pageSize query parameters. The SDK's list methods can page for you; see pagination in the Node SDK. Creating a journal, running a report and uploading a file return the object itself, with no data wrapper.

Errors

Errors use standard HTTP status codes, with a JSON body that says what went wrong:

json
{ "error": "Access denied to the specified entity" }
StatusMeaning
400The request is invalid: a missing field, a bad date, or a journal that does not balance.
401The API key or access token is missing, expired or revoked.
403The user cannot reach that workspace or entity.
404The record does not exist, or is not visible to this user.
500Something went wrong on Prosaic's side. Retry later, and tell us if it persists.

The Node SDK turns each status into an error class, such as ValidationError and NotFoundError; see errors in the Node SDK.

For AI tools

Every page of this reference is also published as Markdown: add .md to its URL. /docs/api/llms-full.txt holds the whole reference in one file, and the developer MCP server looks operations up by name, method or path.

Chart reporting assignments

Discover workspace choices with GET /api/public/v1/report-categories, or entity choices with GET /api/public/v1/entities/{entityId}/report-categories. The saved reporting group/category pair is authoritative in activated workspaces. Stored subtype remains compatibility data, not a promise that reports derive from it. Trial-balance groupBy=subtype remains available pending its separate retirement. See Chart of accounts for required write choices, permissions and conflict recovery.

Resources

User

The user an API key or access token acts as, and the workspaces they belong to.

  • GETGet current user information

Entities

The businesses whose books you keep. Each entity carries its own tax rates and bank accounts.

  • GETList entities
  • POSTCreate an entity

Chart of accounts

Chart of accounts templates, each entity's own accounts, and the global account library templates are built from.

  • GETList all chart of accounts templates
  • GETGet chart of accounts template accounts
  • GETList approved Xero report-code mappings
  • POSTCreate a chart of accounts template
  • and 14 more

Journals

Manual journals: post or draft them, list them, attach files and void them.

  • GETList manual journals
  • POSTCreate a manual journal
  • POSTCreate several manual journals at once
  • POSTAttach files to an existing journal
  • and 1 more

Transactions

Bank transactions: list them, reconcile them one at a time or in bulk, and reverse a reconciliation.

  • GETList bank transactions
  • POSTReconcile bank transactions (bulk or single)
  • POSTReconcile a bank transaction
  • POSTReverse a bank transaction reconciliation

Bank accounts

Link a client's bank accounts to an entity, or create CSV accounts and fill them with transactions from your own systems.

  • POSTCreate a CSV bank account and import transactions into it
  • POSTLink bank accounts to an entity
  • POSTImport transactions into a CSV bank account

Reports

Trial balance, profit and loss, balance sheet, current accounts, depreciation schedule and the general ledger.

  • GETGet general ledger grouped by account
  • GETGet general ledger as flat entry list
  • GETGet ledger entries
  • GETGet trial balance report
  • and 4 more

GST returns

GST returns and their IRD box amounts, for one entity or across the workspace.

  • GETList GST returns across the workspace
  • GETList GST returns for an entity
  • GETGet a single GST return with its IRD box amounts

Contacts

Customers and suppliers: create, update, archive, restore and delete them.

  • GETList contacts
  • GETGet a contact
  • POSTCreate a contact
  • PATCHUpdate a contact
  • and 3 more

Invoices

Finalised invoices: create, read and list them.

  • GETList invoices
  • GETGet an invoice by ID for an entity
  • POSTCreate a finalised invoice

Fixed assets

Fixed assets and their types, for depreciation.

  • GETList fixed asset types (categories) for an entity
  • POSTCreate a new fixed asset type (category)
  • GETList fixed assets for an entity
  • GETGet a single fixed asset by ID
  • and 2 more

Files

Upload files and list them, to attach to journals.

  • GETList files
  • POSTUpload a file

Dimensions

Tracking categories, such as Property or Department, whose options tag journal lines.

  • GETList dimensions

Clients

An accounting practice's clients, their bank accounts and transactions, and onboarding links.

  • GETList clients
  • GETList client's bank transactions
  • GETList client's bank accounts
  • POSTCreate a client
  • and 1 more

Rules

Rules that act on bank transactions when their conditions match.

  • GETList rules
  • GETGet a rule by ID
  • POSTCreate a rule
  • PATCHUpdate a rule
  • and 1 more

Scheduled tasks

Prosaic AI tasks that run a prompt unattended on a schedule, and running one now.

  • GETList scheduled tasks
  • GETGet a scheduled task
  • POSTCreate a scheduled task
  • PATCHUpdate a scheduled task
  • and 2 more

Extensions

Outbound requests made through an extension's connections, with the credential attached server-side.

  • POSTMake an outbound request through an extension connection

Change sets

Proposed journals and reconciliations that an admin approves before they reach the ledger.

  • POSTSubmit a change-set (proposed financial writes) for an entity

Version

The API version.

  • GETAPI version information