# 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](/openapi.json), 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](/docs/apps/oauth-apps) when your product acts for other people's workspaces. [Authentication](/docs/getting-started/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](/docs/sdk/node#pagination). 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" }
```

| Status | Meaning                                                                                  |
| ------ | ---------------------------------------------------------------------------------------- |
| `400`  | The request is invalid: a missing field, a bad date, or a journal that does not balance. |
| `401`  | The API key or access token is missing, expired or revoked.                              |
| `403`  | The user cannot reach that workspace or entity.                                          |
| `404`  | The record does not exist, or is not visible to this user.                               |
| `500`  | Something 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](/docs/sdk/node#errors).

## For AI tools

Every page of this reference is also published as Markdown: add `.md` to its URL. [`/docs/api/llms-full.txt`](/docs/api/llms-full.txt) holds the whole reference in one file, and the [developer MCP server](/docs/ai/build-with-ai) 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](/docs/ledger/chart-of-accounts) for required write choices, permissions and conflict recovery.

## Resources

- [User](https://developer.prosaic.works/docs/api/user.md): The user an API key or access token acts as, and the workspaces they belong to.
  - Get current user information: `GET /api/public/v1/me`, `prosaic.me.retrieve()`
- [Entities](https://developer.prosaic.works/docs/api/entities.md): The businesses whose books you keep. Each entity carries its own tax rates and bank accounts.
  - List entities: `GET /api/public/v1/entities`, `prosaic.entities.list(params)`
  - Create an entity: `POST /api/public/v1/entities`, `prosaic.entities.create(params)`
- [Chart of accounts](https://developer.prosaic.works/docs/api/chart-of-accounts.md): Chart of accounts templates, each entity's own accounts, and the global account library templates are built from.
  - List all chart of accounts templates: `GET /api/public/v1/charts`, `prosaic.charts.list()`
  - Get chart of accounts template accounts: `GET /api/public/v1/charts/{chartId}`, `prosaic.charts.listAccounts(chartId, params)`
  - List approved Xero report-code mappings: `GET /api/public/v1/xero-report-mappings`, `prosaic.charts.listXeroReportMappings()`
  - Create a chart of accounts template: `POST /api/public/v1/charts`, `prosaic.charts.create(params)`
  - Add a single account to a chart of accounts template: `POST /api/public/v1/charts/{chartId}/accounts`, `prosaic.charts.createAccount(chartId, params)`
  - Update a chart of accounts template: `POST /api/public/v1/charts/{chartId}/update`, `prosaic.charts.update(chartId, params)`
  - Update a single account in a chart of accounts template: `POST /api/public/v1/charts/{chartId}/accounts/{accountId}/update`, `prosaic.charts.updateAccount(chartId, accountId, params)`
  - Delete a chart of accounts template: `POST /api/public/v1/charts/{chartId}/delete`, `prosaic.charts.del(chartId)`
  - Delete a single account from a chart of accounts template: `POST /api/public/v1/charts/{chartId}/accounts/{accountId}/delete`, `prosaic.charts.deleteAccount(chartId, accountId, params)`
  - List chart of accounts for an entity: `GET /api/public/v1/entities/{entityId}/charts`, `prosaic.entityAccounts.list(entityId, params)`
  - Create a child account in the chart of accounts: `POST /api/public/v1/entities/{entityId}/charts`, `prosaic.entityAccounts.create(entityId, params)`
  - Update an entity account: `POST /api/public/v1/entities/{entityId}/charts/{accountId}/update`, `prosaic.entityAccounts.update(entityId, accountId, params)`
  - Restore a hidden/excluded template account: `POST /api/public/v1/entities/{entityId}/charts/excluded/{templateAccountId}/restore`, `prosaic.entityAccounts.restore(entityId, templateAccountId)`
  - Reset an entity account to template defaults: `POST /api/public/v1/entities/{entityId}/charts/{accountId}/reset`, `prosaic.entityAccounts.reset(entityId, accountId)`
  - Delete or hide an entity account: `POST /api/public/v1/entities/{entityId}/charts/{accountId}/delete`, `prosaic.entityAccounts.del(entityId, accountId)`
  - List report groups and categories for the authorised workspace: `GET /api/public/v1/report-categories`, `prosaic.reportCategories.listForWorkspace()`
  - List report groups and categories for an entity: `GET /api/public/v1/entities/{entityId}/report-categories`, `prosaic.reportCategories.list(entityId)`
  - List all global accounts: `GET /api/public/v1/global-accounts`, `prosaic.globalAccounts.list()`
- [Journals](https://developer.prosaic.works/docs/api/journals.md): Manual journals: post or draft them, list them, attach files and void them.
  - List manual journals: `GET /api/public/v1/entities/{entityId}/journals`, `prosaic.journals.list(entityId, params)`
  - Create a manual journal: `POST /api/public/v1/entities/{entityId}/journals`, `prosaic.journals.create(entityId, params)`
  - Create several manual journals at once: `POST /api/public/v1/entities/{entityId}/journals/bulk`, `prosaic.journals.createBulk(entityId, params)`
  - Attach files to an existing journal: `POST /api/public/v1/entities/{entityId}/journals/{journalId}/attachments`, `prosaic.journals.attachFiles(entityId, journalId, params)`
  - Void a journal: `PATCH /api/public/v1/entities/{entityId}/journals/{journalId}/void`, `prosaic.journals.void(entityId, journalId)`
- [Transactions](https://developer.prosaic.works/docs/api/transactions.md): Bank transactions: list them, reconcile them one at a time or in bulk, and reverse a reconciliation.
  - List bank transactions: `GET /api/public/v1/entities/{entityId}/transactions`, `prosaic.transactions.list(entityId, params)`
  - Reconcile bank transactions (bulk or single): `POST /api/public/v1/transactions/reconcile`, `prosaic.transactions.reconcileBulk(params)`
  - Reconcile a bank transaction: `POST /api/public/v1/entities/{entityId}/transactions/{transactionId}/reconcile`, `prosaic.transactions.reconcile(entityId, transactionId, params)`
  - Reverse a bank transaction reconciliation: `POST /api/public/v1/entities/{entityId}/transactions/{transactionId}/reverse`, `prosaic.transactions.reverse(entityId, transactionId, params)`
- [Bank accounts](https://developer.prosaic.works/docs/api/bank-accounts.md): Link a client's bank accounts to an entity, or create CSV accounts and fill them with transactions from your own systems.
  - Create a CSV bank account and import transactions into it: `POST /api/public/v1/entities/{entityId}/bank-accounts/import`, `prosaic.bankAccounts.createWithTransactions(entityId, params)`
  - Link bank accounts to an entity: `POST /api/public/v1/entities/{entityId}/bank-accounts`, `prosaic.bankAccounts.link(entityId, params)`
  - Import transactions into a CSV bank account: `POST /api/public/v1/entities/{entityId}/bank-accounts/{bankAccountId}/import`, `prosaic.bankAccounts.importTransactions(entityId, bankAccountId, params)`
- [Reports](https://developer.prosaic.works/docs/api/reports.md): Trial balance, profit and loss, balance sheet, current accounts, depreciation schedule and the general ledger.
  - Get general ledger grouped by account: `GET /api/public/v1/entities/{entityId}/general-ledger/account`, `prosaic.generalLedger.byAccount(entityId, params)`
  - Get general ledger as flat entry list: `GET /api/public/v1/entities/{entityId}/general-ledger/transaction`, `prosaic.generalLedger.byTransaction(entityId, params)`
  - Get ledger entries: `GET /api/public/v1/entities/{entityId}/ledger`, `prosaic.ledger.list(entityId, params)`
  - Get trial balance report: `GET /api/public/v1/entities/{entityId}/trial-balance`, `prosaic.reports.trialBalance(entityId, params)`
  - Get profit & loss report: `GET /api/public/v1/entities/{entityId}/reports/profit-loss`, `prosaic.reports.profitLoss(entityId, params)`
  - Get balance sheet report: `GET /api/public/v1/entities/{entityId}/reports/balance-sheet`, `prosaic.reports.balanceSheet(entityId, params)`
  - Get current accounts report: `GET /api/public/v1/entities/{entityId}/reports/current-accounts`, `prosaic.reports.currentAccounts(entityId, params)`
  - Get depreciation schedule report: `GET /api/public/v1/entities/{entityId}/reports/depreciation-schedule`, `prosaic.reports.depreciationSchedule(entityId, params)`
- [GST returns](https://developer.prosaic.works/docs/api/gst-returns.md): GST returns and their IRD box amounts, for one entity or across the workspace.
  - List GST returns across the workspace: `GET /api/public/v1/gst-returns`, `prosaic.gstReturns.list(params)`
  - List GST returns for an entity: `GET /api/public/v1/entities/{entityId}/gst-returns`, `prosaic.gstReturns.listForEntity(entityId, params)`
  - Get a single GST return with its IRD box amounts: `GET /api/public/v1/entities/{entityId}/gst-returns/{gstReturnId}`, `prosaic.gstReturns.retrieve(entityId, gstReturnId)`
- [Contacts](https://developer.prosaic.works/docs/api/contacts.md): Customers and suppliers: create, update, archive, restore and delete them.
  - List contacts: `GET /api/public/v1/contacts`, `prosaic.contacts.list(params)`
  - Get a contact: `GET /api/public/v1/entities/{entityId}/contacts/{contactId}`, `prosaic.contacts.retrieve(entityId, contactId)`
  - Create a contact: `POST /api/public/v1/entities/{entityId}/contacts`, `prosaic.contacts.create(entityId, params)`
  - Update a contact: `PATCH /api/public/v1/entities/{entityId}/contacts/{contactId}`, `prosaic.contacts.update(entityId, contactId, params)`
  - Restore a contact: `POST /api/public/v1/entities/{entityId}/contacts/{contactId}/restore`, `prosaic.contacts.restore(entityId, contactId, params)`
  - Delete a contact: `DELETE /api/public/v1/entities/{entityId}/contacts/{contactId}`, `prosaic.contacts.del(entityId, contactId)`
  - Archive a contact: `POST /api/public/v1/entities/{entityId}/contacts/{contactId}/archive`, `prosaic.contacts.archive(entityId, contactId, params)`
- [Invoices](https://developer.prosaic.works/docs/api/invoices.md): Finalised invoices: create, read and list them.
  - List invoices: `GET /api/public/v1/invoices`, `prosaic.invoices.list(params)`
  - Get an invoice by ID for an entity: `GET /api/public/v1/entities/{entityId}/invoices/{invoiceId}`, `prosaic.invoices.retrieve(entityId, invoiceId)`
  - Create a finalised invoice: `POST /api/public/v1/entities/{entityId}/invoices`, `prosaic.invoices.create(entityId, params)`
- [Fixed assets](https://developer.prosaic.works/docs/api/fixed-assets.md): Fixed assets and their types, for depreciation.
  - List fixed asset types (categories) for an entity: `GET /api/public/v1/entities/{entityId}/fixed-asset-types`, `prosaic.fixedAssetTypes.list(entityId)`
  - Create a new fixed asset type (category): `POST /api/public/v1/entities/{entityId}/fixed-asset-types`, `prosaic.fixedAssetTypes.create(entityId, params)`
  - List fixed assets for an entity: `GET /api/public/v1/entities/{entityId}/fixed-assets`, `prosaic.fixedAssets.list(entityId, params)`
  - Get a single fixed asset by ID: `GET /api/public/v1/entities/{entityId}/fixed-assets/{assetId}`, `prosaic.fixedAssets.retrieve(entityId, assetId)`
  - Create a new fixed asset: `POST /api/public/v1/entities/{entityId}/fixed-assets`, `prosaic.fixedAssets.create(entityId, params)`
  - Update a draft fixed asset: `PATCH /api/public/v1/entities/{entityId}/fixed-assets/{assetId}`, `prosaic.fixedAssets.update(entityId, assetId, params)`
- [Files](https://developer.prosaic.works/docs/api/files.md): Upload files and list them, to attach to journals.
  - List files: `GET /api/public/v1/entities/{entityId}/files`, `prosaic.files.list(entityId, params)`
  - Upload a file: `POST /api/public/v1/entities/{entityId}/files/upload`, `prosaic.files.upload(entityId, file)`
- [Dimensions](https://developer.prosaic.works/docs/api/dimensions.md): Tracking categories, such as Property or Department, whose options tag journal lines.
  - List dimensions: `GET /api/public/v1/entities/{entityId}/dimensions`, `prosaic.dimensions.list(entityId)`
- [Clients](https://developer.prosaic.works/docs/api/clients.md): An accounting practice's clients, their bank accounts and transactions, and onboarding links.
  - List clients: `GET /api/public/v1/clients`, `prosaic.clients.list(params)`
  - List client's bank transactions: `GET /api/public/v1/clients/{clientId}/transactions`, `prosaic.clients.listTransactions(clientId, params)`
  - List client's bank accounts: `GET /api/public/v1/clients/{clientId}/bank-accounts`, `prosaic.clients.listBankAccounts(clientId)`
  - Create a client: `POST /api/public/v1/clients`, `prosaic.clients.create(params)`
  - Create onboarding link: `POST /api/public/v1/clients/{clientId}/onboarding`, `prosaic.clients.createOnboardingLink(clientId, params)`
- [Rules](https://developer.prosaic.works/docs/api/rules.md): Rules that act on bank transactions when their conditions match.
  - List rules: `GET /api/public/v1/rules`, `prosaic.rules.list(params)`
  - Get a rule by ID: `GET /api/public/v1/rules/{ruleId}`, `prosaic.rules.retrieve(ruleId)`
  - Create a rule: `POST /api/public/v1/rules`, `prosaic.rules.create(params)`
  - Update a rule: `PATCH /api/public/v1/rules/{ruleId}`, `prosaic.rules.update(ruleId, params)`
  - Soft-delete a rule: `DELETE /api/public/v1/rules/{ruleId}`, `prosaic.rules.del(ruleId)`
- [Scheduled tasks](https://developer.prosaic.works/docs/api/scheduled-tasks.md): Prosaic AI tasks that run a prompt unattended on a schedule, and running one now.
  - List scheduled tasks: `GET /api/public/v1/scheduled-tasks`, `prosaic.scheduledTasks.list()`
  - Get a scheduled task: `GET /api/public/v1/scheduled-tasks/{id}`, `prosaic.scheduledTasks.retrieve(id)`
  - Create a scheduled task: `POST /api/public/v1/scheduled-tasks`, `prosaic.scheduledTasks.create(params)`
  - Update a scheduled task: `PATCH /api/public/v1/scheduled-tasks/{id}`, `prosaic.scheduledTasks.update(id, params)`
  - Run a scheduled task now: `POST /api/public/v1/scheduled-tasks/{id}/run`, `prosaic.scheduledTasks.run(id)`
  - Delete a scheduled task: `DELETE /api/public/v1/scheduled-tasks/{id}`, `prosaic.scheduledTasks.del(id)`
- [Extensions](https://developer.prosaic.works/docs/api/extensions.md): Outbound requests made through an extension's connections, with the credential attached server-side.
  - Make an outbound request through an extension connection: `POST /api/public/v1/extensions/{extensionId}/http`, `prosaic.extensions.request(extensionId, params)`
- [Change sets](https://developer.prosaic.works/docs/api/change-sets.md): Proposed journals and reconciliations that an admin approves before they reach the ledger.
  - Submit a change-set (proposed financial writes) for an entity: `POST /api/public/v1/entities/{entityId}/change-sets`, `prosaic.changeSets.create(entityId, params)`
- [Version](https://developer.prosaic.works/docs/api/version.md): The API version.
  - API version information: `GET /api/public/v1`, `prosaic.version.retrieve()`