Working with Sonta programmatically

Most CRMs treat programmatic access as an afterthought — a read-only API bolted to the side, good for exporting a list. Sonta is built the other way round: the same surface your team uses is available to code and to AI agents, so an agent is a participant in your operation rather than a spectator reading a copy of it. This guide covers what that surface can do, how you work with it, and how to keep it scoped.

A control surface, not a data feed

The distinction matters, so it is worth stating plainly. A connected agent does not just read your entries — it can shape and run the business. It can create a collection and add fields to it, read and write entries, set up the stages work moves through, build a pipeline, configure booking, wire an automation, and install a packaged setup. Everything you would otherwise do by hand in the interface is available programmatically. That is what makes it possible to say "set up a collection for work orders with these fields, and an automation that emails the customer when one is done" and have it actually happen, rather than receive instructions for doing it yourself.

Connecting, and where you are

A connection starts with authenticating, and from that point the agent works inside one business at a time. That framing matters more than it might sound: everything read or written belongs to the business currently in context, and switching businesses is a deliberate act. The isolation between businesses that keeps your data separate applies to agents exactly as it applies to people — an agent working one business cannot wander into another.

Tools for the common work

Rather than leaving everything to raw calls, the connection offers purpose-built tools for the work that comes up constantly — and they are the right first reach, because they carry validation and explain their errors instead of failing opaquely. There are tools to read a collection's schema, including the exact shape a field expects when you write to it; to search entries and get back a compact, workable list; to create and update entries with their input checked; to take a snapshot of your booking setup with a checklist of what is still missing; to look up what automations can be triggered by and made to do, pitfalls included; to inspect an automation run step by step when something did not behave; and to install a blueprint end to end. Using these rather than improvising is the difference between an agent that works reliably and one that guesses.

Recipes before improvisation

Many real tasks are multi-step, and the order is not always obvious — what must exist before what, which step quietly depends on another. For those, Sonta ships recipes: short step-by-step guides for common sequences like creating a collection, adding a field, setting up stages and pipelines, making something bookable, installing a blueprint, inviting a teammate, connecting a mailbox, or building a report. The working habit is simple: if a task takes more than one step, look for the recipe first. It encodes the sequence and the traps, which is faster than rediscovering both.

The long tail

The curated tools cover the common ground, not every corner. Behind them the wider surface of the product remains reachable — hundreds of operations covering the things a dedicated tool does not — so an unusual need is not a dead end. The practical approach is to prefer a tool where one exists, and reach past it only for the long tail.

An agent is scoped like a teammate

This is the part worth being deliberate about. An agent connects as something, and what it may do is decided by the role it holds — the same roles and permissions that govern people, described in how access works. An agent given a role that can only read and update a couple of collections can do exactly that and no more. Give an agent the access its job requires and no more, exactly as you would a new hire; broad access should be a decision, not a default.

Working practice

Three habits make programmatic work go smoothly, and they are the ones experienced use converges on. Consult the recipe before a multi-step task. Read the schema before writing, so you send what a field actually expects rather than what you assume. And when a response comes back too large, narrow it — ask for fewer records or fewer fields — rather than repeating the same request and hoping. None of these are ceremony; each one removes a class of failure.

Where to go deeper

Programmatic work assumes the concepts underneath: the data model for what you are acting on, collections and fields for shaping it, how access works for scoping an agent, agents and automations for AI acting from inside the product, and integrations for connecting an AI provider. The specifics — establishing a connection, the tools reference, how read and write shapes differ, and the machine-readable index of this documentation — have their own pages in this section.