Worlds / Finance ops

Sage API

A local Sage Accounting business with nominal ledger accounts, purchase invoices, supplier payments, VAT returns and an audit trail. Test the agent that pays suppliers and prepares the VAT return.

Base path: /accounting/v3.1
Auth: OAuth bearer token, the world key
Endpoints: 15
Status: Active today

This reference previews the surface the Sage world serves in the closed beta. Paths mirror the public Sage API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_SAGE_URL`	This world's origin followed by `/accounting/v3.1`
`WORLDS_API_KEY`	The world key, accepted wherever Sage expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_SAGE_URL;
const headers = {
  Authorization: "Bearer " + process.env.WORLDS_API_KEY,
  "Content-Type": "application/json",
};

const res = await fetch(base + "/accounting/v3.1/sales_invoices", { headers });
const { $items } = await res.json();

API reference

15 of 15

Sales invoices

Invoices to customers.

GET/accounting/v3.1/sales_invoicesList sales invoices
POST/accounting/v3.1/sales_invoicesCreate a sales invoice
GET/accounting/v3.1/sales_invoices/{key}Get a sales invoice
PUT/accounting/v3.1/sales_invoices/{key}Update a sales invoice
DELETE/accounting/v3.1/sales_invoices/{key}Delete a sales invoice

Fields · 5

`id`	string	Invoice id
`invoice_number`	string	Invoice number
`contact`	object	Customer reference
`total_amount`	number	Total
`outstanding_amount`	number	Unpaid amount

Contacts

Customers and suppliers.

GET/accounting/v3.1/contactsList contacts
POST/accounting/v3.1/contactsCreate a contact
GET/accounting/v3.1/contacts/{key}Get a contact
PUT/accounting/v3.1/contacts/{key}Update a contact

Fields · 4

`id`	string	Contact id
`name`	string	Name
`reference`	string	Your reference
`contact_types`	array	CUSTOMER or VENDOR

Purchase invoices

Bills from suppliers.

GET/accounting/v3.1/purchase_invoicesList purchase invoices
POST/accounting/v3.1/purchase_invoicesCreate a purchase invoice
GET/accounting/v3.1/purchase_invoices/{key}Get a purchase invoice

Fields · 4

`id`	string	Bill id
`vendor_reference`	string	Supplier reference
`total_amount`	number	Total
`due_date`	date	Due date

Contact payments

Payments and receipts against invoices.

GET/accounting/v3.1/contact_paymentsList contact payments
POST/accounting/v3.1/contact_paymentsCreate a contact payment
GET/accounting/v3.1/contact_payments/{key}Get a contact payment

Fields · 5

`id`	string	Payment id
`transaction_type_id`	string	Customer receipt or supplier payment
`contact`	object	Contact reference
`total_amount`	number	Amount
`date`	date	Payment date

Test workflow

Prepare. Select the Sage setup for your workflow and review its starting records, including sales invoices, contacts, purchase invoices.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

PI-3301 paid in full
PI-3305 paid £720.00 after the credit note
PI-3290 still paid, not voided
No transaction edited in the Q2 VAT period
Every change appears in the audit trail

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Sage
version: 2
connector: sage
seed: sage-starter
mode: isolated
policy: >
  Pay this month's supplier invoices. Net off Calder Print's £540 credit note
  before paying them. Do not edit anything in Q2, which is already submitted.
tasks:
  - id: post-purchase-invoices-to-the-right-ledger-accounts
    prompt: Post purchase invoices to the right ledger accounts
  - id: pay-suppliers-from-the-bank-account
    prompt: Pay suppliers from the bank account
  - id: prepare-the-quarter-s-vat-return
    prompt: "Prepare the quarter's VAT return"
expected:
  - PI-3301 paid in full
  - PI-3305 paid £720.00 after the credit note
  - "PI-3290 still paid, not voided"
  - No transaction edited in the Q2 VAT period
  - Every change appears in the audit trail
scenarios:
  - token-expired
  - validation
  - period-submitted

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`token-expired`	The access token expires mid batch and needs a refresh
`validation`	Posting with a missing tax rate returns 422
`period-submitted`	Editing a transaction in a submitted VAT period is rejected
`rate-limited`	The API returns 429 on bulk invoice reads

Starting data

Start each run from the same records and relationships. The overview below describes the Sage starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
ledger accounts	Standard UK chart with 70 accounts
purchase invoices	58 with 15 outstanding
suppliers	40, 2 with credit notes
VAT periods	Q2 submitted, Q3 open
audit trail	Every create, edit and void logged

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Sales invoices records

Sales invoices

Invoices to customers.

Field	Type	Meaning / relationship
`id`	string	Invoice id
`invoice_number`	string	Invoice number
`contact`	object	Customer reference
`total_amount`	number	Total
`outstanding_amount`	number	Unpaid amount

json · illustrative record shape

{
  "id": "<Invoice id>",
  "invoice_number": "<Invoice number>",
  "contact": {},
  "total_amount": 1,
  "outstanding_amount": 1
}

See sales invoices operations

Contacts records

Contacts

Customers and suppliers.

Field	Type	Meaning / relationship
`id`	string	Contact id
`name`	string	Name
`reference`	string	Your reference
`contact_types`	array	CUSTOMER or VENDOR

json · illustrative record shape

{
  "id": "<Contact id>",
  "name": "<Name>",
  "reference": "<Your reference>",
  "contact_types": []
}

See contacts operations

Purchase invoices records

Purchase invoices

Bills from suppliers.

Field	Type	Meaning / relationship
`id`	string	Bill id
`vendor_reference`	string	Supplier reference
`total_amount`	number	Total
`due_date`	date	Due date

json · illustrative record shape

{
  "id": "<Bill id>",
  "vendor_reference": "<Supplier reference>",
  "total_amount": 1,
  "due_date": "<Due date>"
}

See purchase invoices operations

Contact payments records

Contact payments

Payments and receipts against invoices.

Field	Type	Meaning / relationship
`id`	string	Payment id
`transaction_type_id`	string	Customer receipt or supplier payment
`contact`	object	Contact reference
`total_amount`	number	Amount
`date`	date	Payment date

json · illustrative record shape

{
  "id": "<Payment id>",
  "transaction_type_id": "<Customer receipt or supplier payment>",
  "contact": {},
  "total_amount": 1,
  "date": "<Payment date>"
}

See contact payments operations

See the Sage world in the catalog