Skip to main content
Every request to the Statisfy API carries an API key as a bearer token in the Authorization header:
Keys start with 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 sync or Nightly 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.
  1. Click Create key.
  2. Name the key after the integration that will use it, such as HubSpot sync.
  3. 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.
  4. Choose when the key Expires: never, or in 30 days, 90 days, or 1 year.
  5. 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.
Settings → API Keys lists every key that hasn’t been revoked, with its access, when it was created and last used, and when it expires. An expired key stays in the list, marked Expired, until you revoke it. It shows only the start of each key, never the whole key. To confirm the key works and see its scopes, call 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 403 with the code not_entitled. When your plan changes, your keys follow on their next call.
  • Every write verb includes read on the same object. A key with tasks:update can also list and get tasks.
  • Write verbs don’t include each other. A key with opportunities:update can’t create or delete opportunities.
  • Upserts need both create and update on the object, because an upsert can do either.
  • Account records carry each health pillar’s current label, and the overall reason (health_summary), with accounts:read. Each pillar’s reason, confidence, source, and history need health:read.
  • Product usage needs only a usage scope, but finding a product’s id and its dimension keys needs products:read.
  • reports:read reads 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 one reports:update, and deleting one reports:delete.
  • Each reports write scope includes reports: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:write can 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 account accounts:read, as well as templates:read, because the preview shows their field values. A contact’s own account renders with real values only when the key has accounts:read, and with sample values otherwise. A preview with sample values needs only templates:read.
  • Publishing a survey needs surveys:update, and it can’t be undone. A published survey can’t be changed or deleted. Duplicating it needs surveys:create.
  • surveys:read lists 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:publish doesn’t include campaigns:read or campaigns:write: grant those as well.
  • campaigns:write can 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:read lists 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 other digital_workers scopes: grant those as well.
  • digital_workers:update can stop or archive any worker, so a key that edits workers can always take one off the air.
  • digital_workers:evaluate tries 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 a PATCH needs.
  • digital_workers:update adds, 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 need digital_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:read reads 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:read reads every knowledge base and its documents, words included, whatever their account, and searches them as a worker would. It needs no other scope.
  • knowledge:write adds, 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:read reads 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:write alone creates and copies skills and changes ones no agent uses. skills:publish doesn’t include skills:read or skills: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:create adds 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:create and notification_rules:update choose 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:read reads parts of recordings. A clip’s video and its transcript_snippet hold the words spoken in it, so clips:read reads them without meetings:read or transcripts: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 include clips:read: grant that as well.
  • settings:update changes 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:read also reads your licenses and features. GET /v1/settings/licenses lists the Statisfy products your workspace has, with each one’s term, status, and seats. GET /v1/settings/licenses/{license_id}/users lists who holds a seat on a license. GET /v1/settings/features lists the app’s optional features and whether each is on. These are read only: settings:update doesn’t change them.
  • agent_studio:read reads Agent Studio’s agents and flows. GET /v1/agents and GET /v1/agents/{agent_id} return each agent with its instructions, toolkits, skills, and knowledge bases, Statisfy’s and your own. GET /v1/automations/flows and GET /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:read reads scheduled workflows: the questions Stella answers on a schedule, from the app’s Workflows page. It covers GET /v1/automations/workflows and GET /v1/automations/workflows/{workflow_id}. A key that acts for a person sees only that person’s workflows, and another person’s workflow returns 404. Any other key sees every workflow in the workspace.
  • approvals:read reads 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/approvals lists them as the app’s Approvals page does: list is its My Approvals / All Approvals selector, and status its tabs (pending, approved, rejected, history, or all; 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:write approves or rejects up to 100 approvals at once (POST /v1/approvals/decisions with approval_ids and approved), 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 gets 403. Approving resumes each run, which can send email to your customers. Each approval answers on its own: one someone already decided fails with conflict, and the others are still decided.
  • credits:read reads 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:update can 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:create posts 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, so comments:update and comments:delete reach only that person’s comments.
  • fields:delete deletes a custom field and its value on every record, and the delete can’t be undone. fields:create and fields:update don’t include it. In the app, only admins delete fields.
  • Writing custom field values needs the object’s scope, not a fields scope. Setting a value under fields on an account needs accounts:update. The fields scopes cover field definitions only.
  • audit_logs:read reads 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 covers GET /v1/audit-logs and POST /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, and request_id take eq, neq, in, and nin. action_happened_at (RFC 3339) takes gt, gte, lt, and lte. A search filter nests at most 3 levels deep and holds at most 20 conditions. Events come newest first, and limit is at most 200. See Search with AND and OR.
  • integrations:read reads every app your workspace can connect, not only SQL warehouses. It covers GET /v1/integrations and, 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:read never 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 either integrations scope only when that person is an admin.
  • integrations:read also 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:write saves a warehouse’s config, queries, and schedule, and starts runs. It also runs POST /v1/integrations/{key}/sql, which returns up to 1,000 rows, and POST /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 a 422 with the app’s text. Saving locks each mapped field.
  • integrations:write also returns raw Pendo data. POST /v1/integrations/pendo/preview runs a Pendo query and returns up to 100 rows, and POST /v1/integrations/pendo/surveys/preview returns 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/test checks the stored ones.
  • Send expected_version to save a warehouse config safely. Pass the config version you read when you change the config or a query. If the config changed since, Statisfy returns 409 with the code conflict and writes nothing: read it again. Left out, the change always lands.
  • /sql and /preview run against your warehouse, so they can fail there. Each workspace runs only a couple at once on each server. Past that, Statisfy returns 429 with rate_limited and Retry-After. SQL the warehouse refuses, and a result over 8 MB, return 422 with validation_failed. A warehouse that can’t be reached returns 502 with upstream_failed, and one with no usable connection 409 with conflict. The warehouse stops a query at 120 seconds, which returns 504 with query_timeout.
  • integrations:read also reads your file import feeds. It covers GET /v1/integrations/imports/feeds and each feed, shown one entry per mapped column with the place it goes, such as account.fields.tier__c or usage.12.active_seats. GET /v1/integrations/imports/targets lists 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/sample reads a sample’s columns and first rows, from CSV text you send or from a file Statisfy received.
  • integrations:write also sets up and runs your file import feeds. POST /v1/integrations/imports/feeds creates a feed, switched off; PATCH and DELETE on /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 a 422 that names each column and why. Saving locks each mapped field, so it is read-only in the app. POST /v1/integrations/imports/test is the app’s test of a feed on a sample, which writes nothing. POST /v1/integrations/imports/feeds/{name}/run imports 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/imports with the status held, 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_version to change a feed safely. Pass the feed’s version from GET /v1/integrations/imports/feeds/{name}. If the feed changed since, Statisfy returns 409 with the code conflict and writes nothing. A run on a file Statisfy already imported is a 409 too.
  • Each run counts what each query read and wrote. GET /v1/integrations/{key}/runs returns counts for every query that finished: read, then each row in exactly one of written, unmatched (no account or person), invalid (dropped by validators), skipped (nothing to write), or failed. counts is null while a run is going and when every query failed.
  • admin allows every operation. Avoid it unless an integration truly needs everything.
  • GET /v1/meta/whoami and GET /v1/meta/capabilities need no scope. Any valid key can call them.
A request the key’s scopes don’t allow returns 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

  1. Create a new key with the same access and a new name. Names must be unique among active keys.
  2. Switch your integration to the new key, and confirm it works with GET /v1/meta/whoami.
  3. 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 returns 401.

Keep keys safe

An API key can read and change your workspace’s data, so treat it like a password.
  • 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 read scopes.
  • 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-Id from its response instead. See Request IDs.