Authorization header:
stfy_live_. A request without a valid key returns 401 with the error code unauthorized.
What an API key is
- It belongs to your workspace, not to a person. A key isn’t tied to the admin who created it. It works across your whole workspace, limited only by its scopes.
- It has a name. The name identifies the integration that uses the key, such as
HubSpot syncorNightly renewal script. No two active keys in a workspace share a name. - It has scopes. A key can only call the operations its scopes allow. See Scopes.
- It’s shown once. Statisfy shows the full key only when it’s created and doesn’t keep a readable copy, so a lost key can’t be recovered. Create a new one and revoke the old one instead.
- It can expire. A key can have an expiry date, after which requests with it return
401. A key without one works until it’s revoked. - It can be revoked. Revocation takes effect immediately and can’t be undone.
Get an API key
Admins create keys in Statisfy, in Settings → API Keys.- Click Create key.
- Name the key after the integration that will use it, such as
HubSpot sync. - Under Access, choose what the key can do on each object: View, Create, Edit, or Delete, or, for objects that take one verb for every change (such as product usage, email templates, and activities), Write. Choosing anything other than View includes View. Access lists only the objects your workspace’s plan includes. Full access grants every scope your plan includes; avoid it unless an integration truly needs everything.
- Choose when the key Expires: never, or in 30 days, 90 days, or 1 year.
- Click Create key, then copy the key and store it somewhere safe, such as a secrets manager. This is the only time the full key is shown.
GET /v1/meta/whoami. See the quickstart.
Scopes
A scope has the form<object>:<verb>.
The two meeting scopes are separate.
transcripts:read gets a meeting’s transcript links and its participants (names and emails included) but doesn’t list meetings, and meetings:read doesn’t get transcripts. To find meetings and download their transcripts, grant both.
activity_content:read is separate from activities:read. activities:read lists the timeline and gets each activity’s AI summary and the facts of its kind (a ticket’s status, a survey’s score, a campaign). activity_content:read reads what was written in an activity: email, chat, ticket, and Chatter messages (bodies, senders, recipients, attachment names), notes, survey answers, and campaign emails. It covers every account, so grant it only to an integration that may read all of the workspace’s mail, chats, notes, and survey answers. Neither shows a meeting’s transcript: that is transcripts:read, for meetings Statisfy’s notetaker recorded.
activities:write pushes what another of your systems (a marketing platform, a sequencer) did with a person, such as an email thread, a LinkedIn conversation, a call, or a form, onto their account’s timeline. It writes and deletes only what was pushed through the API, never an activity Statisfy synced. Like every write scope, it also reads: a key with it can list the timeline as activities:read does. A key that acts for a person gets it only when that person is an admin.
conversations:read reads a conversation whole: its record, its thread’s messages (bodies, senders, recipients, attachment names), and its internal notes. It needs neither timeline scope, and covers every conversation the workspace’s plan includes, so grant it only to an integration that may read them all. AI drafts nobody has sent are never on the API.
What each verb allows:
How scopes combine:
- A key reaches only what your workspace’s plan includes, whatever its scopes, Full access included. A call to an object your plan doesn’t include returns
403with the codenot_entitled. When your plan changes, your keys follow on their next call. - Every write verb includes
readon the same object. A key withtasks:updatecan also list and get tasks. - Write verbs don’t include each other. A key with
opportunities:updatecan’t create or delete opportunities. - Upserts need both
createandupdateon the object, because an upsert can do either. - Account records carry each health pillar’s current label, and the overall reason (
health_summary), withaccounts:read. Each pillar’s reason, confidence, source, and history needhealth:read. - Product usage needs only a
usagescope, but finding a product’s id and its dimension keys needsproducts:read. reports:readreads everything your report views hold, whatever other scopes the key has: accounts and their fields, contacts, your team’s names and emails, opportunities, account owners, health, product usage, tasks, activities, projects, surveys, support tickets, custom objects, and Digital Worker conversations (subjects and participants) and actions. It also lists every report, private ones included, with its owner’s email. Grant it only to an integration that may read all of that.- A report’s widgets go by the same verbs as the report. Adding a widget needs
reports:create, changing onereports:update, and deleting onereports:delete. - Each
reportswrite scope includesreports:read, so it reads everything the report views hold too. It can also change or delete any report, private ones included, whoever owns it: the app’s rule that only a report’s owner or an admin changes it doesn’t apply to API keys. templates:writecan change or delete any email template except a survey’s, published ones included. Campaigns and Agent Studio flows read a template each time they send, draft or published, so a change goes out on their next send, as an edit in the app does.- Previewing a template with a real contact needs
contacts:read, and with a real accountaccounts:read, as well astemplates:read, because the preview shows their field values. A contact’s own account renders with real values only when the key hasaccounts:read, and with sample values otherwise. A preview with sample values needs onlytemplates:read. - Publishing a survey needs
surveys:update, and it can’t be undone. A published survey can’t be changed or deleted. Duplicating it needssurveys:create. surveys:readlists every response a survey collected, with the id of the contact who answered.- Publishing a campaign needs
campaigns:publish, and no other scope includes it. Publishing sends email to your customers, so grant it by name, only to an integration that may send. Changing a published campaign needs it too, because a change changes what is sent.campaigns:publishdoesn’t includecampaigns:readorcampaigns:write: grant those as well. campaigns:writecan unpublish any campaign, so a key that edits campaigns can always stop a send.- A test email goes only to a member of your workspace. The merge tags can be filled in from any existing contact.
campaigns:readlists the contacts a campaign was sent to, with their emails and delivery status.- Activating a digital worker needs
digital_workers:activate, and no other scope includes it. An active worker answers your customers, and where its replies don’t wait for a person it writes to them on its own, following its job, voice, and guardrails. Changing an active worker needs it too, because a change changes what the worker tells your customers. Grant it by name, only to an integration that may put a worker in front of your customers. It doesn’t include the otherdigital_workersscopes: grant those as well. digital_workers:updatecan stop or archive any worker, so a key that edits workers can always take one off the air.digital_workers:evaluatetries a worker without changing it. A preview of one message (POST /v1/digital_workers/{worker_id}/preview) and an evaluation run work on a copy of the worker: they send nothing and save nothing, so a key that may test a worker needn’t be one that may change it. Restoring a saved version is a change: it needs what aPATCHneeds.digital_workers:updateadds, changes, and deletes a worker’s proactive tasks: the work it does on its own, once, on a schedule, or until a goal is met. It doesn’t needdigital_workers:activate, even for a worker whose outreach is on, so a key with it can give a worker that writes to your customers new work. Adding or changing a task needs AI CSM; closing or deleting one doesn’t, so a key that edits workers can always stop a task. A digital worker’s own key reads tasks but never writes them.outreach:readreads every email your digital workers sent on their own initiative: its words, who it went to, and what became of it (the customer’s reply, its delivery, opens and clicks, an opt-out). It needs no other scope, so grant it only to an integration that may read all of that email.knowledge:readreads every knowledge base and its documents, words included, whatever their account, and searches them as a worker would. It needs no other scope.knowledge:writeadds, changes and deletes documents, and makes, changes and deletes knowledge bases. It writes into knowledge bases it made and ones that take uploads in the app; a connector’s are read-only, because its sync would overwrite them. Your digital workers answer your customers from what it writes, so grant it only to an integration that may decide what they say. A digital worker’s own key never writes knowledge.skills:readreads every skill your workspace can see, instructions and files included, Statisfy’s and your own. It needs no other scope.- Changing a skill an agent uses needs
skills:publish, and no other scope includes it. A skill is instructions your agents follow, and a change reaches every agent that uses it at once: Stella, the workbench agent, your digital workers, and Agent Studio agents. Grant it by name, only to an integration that may decide what your agents do.skills:writealone creates and copies skills and changes ones no agent uses.skills:publishdoesn’t includeskills:readorskills:write: grant those as well. A digital worker’s own key never writes skills. - The API writes a skill’s text files under
references/only. Scripts and other files are added in the app, and a skill with tools of its own can only be turned on or off through the API. sender_domains:createadds a domain and verifies it. Only a verified domain can be a campaign’s or a flow’s From address, so grant it only to an integration that may set up who your workspace sends email as. In the app, only admins manage sender domains.notification_rules:createandnotification_rules:updatechoose who gets meeting insights. A rule sends a processed meeting’s insights to its recipients. A new email must belong to a member of your workspace, so a rule never sends insights outside it. In the app, every member can manage notification rules.clips:readreads parts of recordings. A clip’s video and itstranscript_snippethold the words spoken in it, soclips:readreads them withoutmeetings:readortranscripts:read. It covers every clip in the workspace, whoever made it.- Sharing a clip needs
clips:share, and no other scope includes it. A share opens a public page: anyone with the link can watch the clip, with no login. Grant it by name, only to an integration that may make recordings public. It doesn’t includeclips:read: grant that as well. settings:updatechanges workspace-wide settings. For example, it can stop the NoteTaker for the whole workspace, change when AI tasks close, or change which senders count as automated. In the app, only people who manage settings change them. It can’t change company domains or Stella’s PII guardrail.settings:readalso reads your licenses and features.GET /v1/settings/licenseslists the Statisfy products your workspace has, with each one’s term, status, and seats.GET /v1/settings/licenses/{license_id}/userslists who holds a seat on a license.GET /v1/settings/featureslists the app’s optional features and whether each is on. These are read only:settings:updatedoesn’t change them.agent_studio:readreads Agent Studio’s agents and flows.GET /v1/agentsandGET /v1/agents/{agent_id}return each agent with its instructions, toolkits, skills, and knowledge bases, Statisfy’s and your own.GET /v1/automations/flowsandGET /v1/automations/flows/{flow_id}return each flow with its trigger and steps. It reads only: the API doesn’t create, change, or run agents or flows.workflows:readreads scheduled workflows: the questions Stella answers on a schedule, from the app’s Workflows page. It coversGET /v1/automations/workflowsandGET /v1/automations/workflows/{workflow_id}. A key that acts for a person sees only that person’s workflows, and another person’s workflow returns404. Any other key sees every workflow in the workspace.approvals:readreads the Approvals inbox: the flow runs waiting on an Agent Studio approval step, with what each would send (an email’s recipients, subject, and body).GET /v1/approvalslists them as the app’s Approvals page does:listis its My Approvals / All Approvals selector, andstatusits tabs (pending,approved,rejected,history, orall; pending by default).GET /v1/approvals/{approval_id}opens one. A key that acts for a person lists My Approvals, and All Approvals only when the person builds in Agent Studio. Any other key lists All Approvals.- Only a person decides an approval, with their own key.
approvals:writeapproves or rejects up to 100 approvals at once (POST /v1/approvals/decisionswithapproval_idsandapproved), as the app does for one or many, as the person who made the key, and only approvals assigned to them unless they build in Agent Studio. Any other key gets403. Approving resumes each run, which can send email to your customers. Each approval answers on its own: one someone already decided fails withconflict, and the others are still decided. credits:readreads your AI credit summary, usage by flow, and usage log. The log names the person who made a call by id only. It never shows a call’s prompt or answer.users:updatecan change any teammate’s name, role, department, manager, calendar link, and custom user fields. In the app, only an admin edits another user on the Team page. It can’t change a user’s access role or membership, or invite anyone.- A comment the API writes is by the person who created the key.
comments:createposts as that person: the people a task comment mentions are emailed, and so are the task’s followers. Only a comment’s author can edit or delete it, socomments:updateandcomments:deletereach only that person’s comments. fields:deletedeletes a custom field and its value on every record, and the delete can’t be undone.fields:createandfields:updatedon’t include it. In the app, only admins delete fields.- Writing custom field values needs the object’s scope, not a
fieldsscope. Setting a value underfieldson an account needsaccounts:update. Thefieldsscopes cover field definitions only. audit_logs:readreads your workspace’s audit trail, as Settings > Audit logs shows it: each call on each record, through the app, the API, MCP, an Agent Studio flow, or a file import, with who made it and the fields it stored. It coversGET /v1/audit-logsandPOST /v1/audit-logs/search, and needs no other scope. A key that acts for a person, such as one Claude uses, gets it only when that person is an admin. Reading the trail isn’t itself audited.- Audit events filter on a fixed set of fields.
source(app,rest,mcp,agent-studio,bulk-file),actor_type,actor_user_id,object_type,object_id,action,status, andrequest_idtakeeq,neq,in, andnin.action_happened_at(RFC 3339) takesgt,gte,lt, andlte. A search filter nests at most 3 levels deep and holds at most 20 conditions. Events come newest first, andlimitis at most 200. See Search with AND and OR. integrations:readreads every app your workspace can connect, not only SQL warehouses. It coversGET /v1/integrationsand, for each app, its status, connections, schedule, and runs. For Slack and Teams, it lists the channels Statisfy is in. It also lists file imports (GET /v1/integrations/imports): CSV and Excel files uploaded in the app or received by a file feed, with their row counts and up to 20 failed rows. For a SQL warehouse, it reads the config, saved queries, and the schemas, tables, and columns its catalog lists.integrations:readnever returns a credential, a token, or a row of warehouse data. For the SQL warehouses and the other apps it reads metadata only. For Pendo it also returns the query text of Pendo reports (filters can hold values, such as an account ID) and the NPS answer count of each guide, but no Pendo rows, emails, or comments. A key that acts for a person gets eitherintegrationsscope only when that person is an admin.integrations:readalso covers Pendo’s config, saved queries, and lookups. The lookups are Pendo’s reports, its catalog of pages, features, track types, and apps, the account fields, the NPS guides, the answer counts of the guides, and the check of a Sentiment survey ID. They make live calls to Pendo. The Pendo key stays in Statisfy’s app: the API never takes or returns it.integrations:writesaves a warehouse’s config, queries, and schedule, and starts runs. It also runsPOST /v1/integrations/{key}/sql, which returns up to 1,000 rows, andPOST /v1/integrations/{key}/preview, a dry run of a query on up to 1,000 rows that writes nothing. Those rows can be anything the warehouse login can read, so grant it only to an integration that may read all of that. For Pendo, the same scope also changes the config, the queries, the NPS survey settings, and the schedule, and starts Pendo runs, including the NPS survey job. A Pendo save runs the same checks as the app’s save, and a refusal comes back as a422with the app’s text. Saving locks each mapped field.integrations:writealso returns raw Pendo data.POST /v1/integrations/pendo/previewruns a Pendo query and returns up to 100 rows, andPOST /v1/integrations/pendo/surveys/previewreturns NPS responses, with the visitor’s email, rating, and comment. Grant it only to an integration that may read all of that.- Warehouse credentials never cross the API. You connect a warehouse in Statisfy’s app. The API can’t set its credentials and never returns them.
POST /v1/integrations/{key}/connection/testchecks the stored ones. - Send
expected_versionto save a warehouse config safely. Pass the configversionyou read when you change the config or a query. If the config changed since, Statisfy returns409with the codeconflictand writes nothing: read it again. Left out, the change always lands. /sqland/previewrun against your warehouse, so they can fail there. Each workspace runs only a couple at once on each server. Past that, Statisfy returns429withrate_limitedandRetry-After. SQL the warehouse refuses, and a result over 8 MB, return422withvalidation_failed. A warehouse that can’t be reached returns502withupstream_failed, and one with no usable connection409withconflict. The warehouse stops a query at 120 seconds, which returns504withquery_timeout.integrations:readalso reads your file import feeds. It coversGET /v1/integrations/imports/feedsand each feed, shown one entry per mapped column with the place it goes, such asaccount.fields.tier__corusage.12.active_seats.GET /v1/integrations/imports/targetslists every place a column can go, with whether a feed may write it and why not, and the date formats and identifier fields a feed takes.POST /v1/integrations/imports/samplereads a sample’s columns and first rows, from CSV text you send or from a file Statisfy received.integrations:writealso sets up and runs your file import feeds.POST /v1/integrations/imports/feedscreates a feed, switched off;PATCHandDELETEon/v1/integrations/imports/feeds/{name}change or delete one. A save runs the same checks as the app’s data import settings, and a refused column comes back as a422that names each column and why. Saving locks each mapped field, so it is read-only in the app.POST /v1/integrations/imports/testis the app’s test of a feed on a sample, which writes nothing.POST /v1/integrations/imports/feeds/{name}/runimports one file now: a file the feed received, CSV text you send, or an object in an S3 feed’s bucket.- An email feed that is off keeps the files it receives. Each one shows in
GET /v1/integrations/importswith the statusheld, and imports only when you run the feed on it. Switching the feed on imports the files that arrive afterwards. An S3 feed that is off isn’t polled: when you switch it on, it imports every file under its prefix that it hasn’t imported before. - Send
expected_versionto change a feed safely. Pass the feed’sversionfromGET /v1/integrations/imports/feeds/{name}. If the feed changed since, Statisfy returns409with the codeconflictand writes nothing. A run on a file Statisfy already imported is a409too. - Each run counts what each query read and wrote.
GET /v1/integrations/{key}/runsreturnscountsfor every query that finished:read, then each row in exactly one ofwritten,unmatched(no account or person),invalid(dropped by validators),skipped(nothing to write), orfailed.countsis null while a run is going and when every query failed. adminallows every operation. Avoid it unless an integration truly needs everything.GET /v1/meta/whoamiandGET /v1/meta/capabilitiesneed no scope. Any valid key can call them.
403 with the error code insufficient_scope, and the message names the scope it needs. Each operation’s required scopes are also listed in GET /v1/meta/capabilities.
Rotate a key
- Create a new key with the same access and a new name. Names must be unique among active keys.
- Switch your integration to the new key, and confirm it works with
GET /v1/meta/whoami. - Revoke the old key.
Revoke a key
In Settings → API Keys, click Revoke next to the key, then confirm. Revoke a key when the integration that uses it is retired, or right away if the key may have leaked. Revocation takes effect immediately: any request made with the key afterwards returns401.
Keep keys safe
- Store keys in a secrets manager or an environment variable. Never commit them to source control.
- Use keys only from servers and scripts. Never put a key in a browser app, a mobile app, or anything else you ship to end users.
- Give each integration its own key, so you can revoke one without breaking the others.
- Ask for the fewest scopes that work. A read-only reporting script needs only
readscopes. - Set an expiry date on keys for short-lived work, such as a one-off migration.
- Never paste a key into a support ticket, chat, or log. To trace a request, share the
X-Request-Idfrom its response instead. See Request IDs.