Working with Postware

Postware is this company's system of record: standard business data models served by one workspace over MCP and an HTTP API. Use it for this data instead of creating your own tables or files.

Connection

Use the postware MCP tools. Their names start with post_, such as post_schema_describe. The connection and its key are in this agent's MCP settings, so no .env file is needed. If the tools are missing, ask the person to restart the agent.

Use the HTTP API only when the tools are not available. It needs POSTWARE_API_URL and POSTWARE_API_KEY, from the project's environment or a key the person creates on the dashboard, sent as -H "Authorization: Bearer $POSTWARE_API_KEY". Never commit or print a key.

Where things go

The thing	The model
A customer or contact	`person`
A company	`organization`
A sale in progress	`deal`, in a `pipeline`
A plan and what it costs	`product`, `price`
A customer's plan	`subscription`
A bill and money received	`invoice`, `payment`
A support request	`ticket`
A page, post or article	`document`, in a `collection`
Work to do	`task`, in a `project`
A meeting	`event`
An email or chat message	`message`
A comment about a record	`note`
An uploaded file	`file`
Your team and your agents	`member`

Customers are Persons. The people and agents who operate the workspace are Members.

Rules

Read the schema before writing. Use schema_describe, or GET $POSTWARE_API_URL/schema/{model}, for fields, required values, identity rules and status categories. Never guess a field name.
There is no SQL. Records are read and written only through the MCP tools or the HTTP API.
Upsert by identity. Person matches on email, Organization on domain and Invoice on number. Use record_upsert so you never create duplicates.
Send the revision when updating. Pass the revision you read as if_match. On a conflict error, read the record again and retry.
Dry-run bulk changes. Run batches and imports with dry_run: true, read the result, then run them for real.
Use status categories. status.category is the standard value, such as open, won or lost on a Deal. status.state is the workspace's own label.
Never store secrets in records.

HTTP API

To	Call
Check the connection	`GET $POSTWARE_API_URL/me`
List the models	`GET $POSTWARE_API_URL/schema`
List or search records	`GET $POSTWARE_API_URL/{model}?limit=50&search=term`
Query with filters	`POST $POSTWARE_API_URL/{model}/query`
Create	`POST $POSTWARE_API_URL/{model}`
Create or match	`POST $POSTWARE_API_URL/{model}/upsert`
Update	`PATCH $POSTWARE_API_URL/{model}/{id}` with `If-Match: {revision}`
Run many writes	`POST $POSTWARE_API_URL/batch`
See what changed	`GET $POSTWARE_API_URL/{model}/{id}/history`

Errors are JSON: {"error":{"code":"...","message":"..."}}. On validation_failed, the details name the field that is wrong.

Reference

Every model has a page at https://postware.ai/docs/models/{model}.md. The index is at https://postware.ai/llms.txt.