API and keys

Avitly has a machine-facing surface. You can connect your organisation to an AI client over MCP, or script against the same data over REST. Both use the same personal API key, and both can read and, if you allow it, write.

You manage keys under Settings, Integrations.

Before you start

API access uses the same gates as the in-app AI assistant. Three things must be true: your organisation has Platform Pro, an owner has enabled the AI assistant in Settings, Preferences, and your own role allows the data you are asking for. A key can never do more than the person who created it can do.

Creating a key

Choose New key and name it after where it will live, so you know what to revoke later. Then set access per feature: none, read, or write.

Access is granted per feature, not per table and not per tool. Projects, Tasks, Customers, Catalogue, Suppliers, Labour rates and Stock sit under Platform; Quotes, Offers, Orders, Invoices and Purchase orders under Sales; Floor plans, Rack plans and Wiring plans under Design; Tickets, RMAs, Installed devices and Maintenance plans under Service; Crew planning and Time tracking under Planning. Expanding a feature lists the tables it covers and, where writing is limited, why.

Tickets and RMAs are separate grants even though they live in one table. A key granted RMAs never sees a support ticket, and the other way round.

Design is read only at every level. Plans are drawn in the editor, where coordinates mean something against a plan version and its calibration, so there is no honest way to write them a row at a time.

The full key is shown exactly once, at creation. Copy it then. If you lose it, revoke it and create a new one. Only a short prefix is stored in readable form; the key itself is stored hashed. Treat it like a password: never put it in a public repository, a screenshot, or a support ticket.

You can change a key's access afterwards without reconnecting anything. Narrowing takes effect on the key's next call. Keys are revoked rather than deleted, so the audit trail stays intact, and a revoked key cannot be edited.

Reading

Two shapes of read tool. Named tools answer whole questions in one call, joined and summarised: a project with its plans, quotes, and tasks, or a quote with its lines and totals. list_records covers everything else by reading any table your key was granted, with exact-match filters, ordering, and paging, up to 200 rows a call.

Between them, every feature you can grant is a feature you can actually read: invoices, orders, purchase orders, stock on hand, crew bookings, logged hours, maintenance balances, racks, wiring, and the rest.

Writing

Writing is always two calls. A propose_ call validates what you asked for, resolves references such as a project named in plain language to a record it has verified, and returns a draft. Nothing has changed at that point. A second commit_change call applies the draft through the same code the in-app approval card uses.

That gives you three paths:

• propose_record creates, updates, or deletes a single row in any table your key was granted with write.
• Named propose_ tools cover the things people ask for most, with a curated set of columns each.
• propose_conversion makes the documents that are never inserted by hand: an order from a quote, an invoice from a quote or an order, a deposit invoice for a percentage of an order, and a credit note from a finalised invoice. These call the app's own creators, so numbering, line copying, and tax treatment are exactly what the buttons in the app produce.

What a key can never write

	Why
Device credentials	Encrypted secrets. Not readable, not writable, not listed, at any grant level. A key lives in a config file; a vault should not.
Floor, rack and wiring plans	Read only as a whole. Geometry belongs to a plan version, and versions deep copy their children. Drawn in the editor.
Orders and invoices, directly	Their numbering is legal and gapless and their lines are copied from the source. Created through propose_conversion instead.
Stock movements, after the fact	The ledger is append only. On hand is the sum of the movements, so a correction is another movement, never an edit. Exactly what the stock page does.
Stock reservations	Written together with purchase orders by the reservation logic. A stray reservation silently hides stock from every other project.
Deleting a project	Refused at any grant. The quotes, plans, tickets, and hours go with it, and no approval step makes that reviewable.
Members, roles, and invitations	Writing these is privilege escalation by another name.

Some columns are refused inside tables you can otherwise write: document numbers, acceptance records, share tokens, received quantities, and every ownership and audit column. Your organisation is read from the key, never from an argument, so a key cannot be pointed at another organisation.

Limits

• Rate limit. 120 requests per minute per key. An agent loop can outrun a person by orders of magnitude.
• Audit. Every call is one row: the key, the organisation, the action, the result, and how long it took. The last used date shows on the keys list. Argument contents are not stored unless your organisation turns that on.
• No secrets. No tool returns device credentials, API keys, or bank details.
• No email or other side effects. No tool sends anything out. Documents are created, not delivered.
• No webhooks. Avitly does not call your systems. You poll.
• No human in the loop on this path. In the app, a write waits on an approval card. Over the API there is nobody looking. If that matters for your organisation, grant read and keep writes in the app, which is the default.