Connection
- Authentication: API key (Refiner API key).
In Refiner: Settings → Global Settings → API Keys → create a key (give it a name such as “Atako”) and copy it. A key belongs to one environment (the default one is named “Environment #1”): create it in the environment your agents should work in. Reading and writing use the same key, so grant only the read tools if the agent must not change contacts. API access depends on your Refiner plan: see refiner.io/pricing.See Refiner’s documentation.
Read actions (9)
| Action | Description |
|---|---|
get_account | Get the Refiner account: the subscription usage (plan, contacts, events, pageviews and survey responses counted, with their limits) and the list of environments { uuid, name, … }. No arguments. |
get_contact | Get everything Refiner holds on one contact: uuid, remote_id, e-mail, display name, first and last seen, attributes, segments and account. Give at least one of: id (string, your own user ID); email (string, e-mail address, the first match when several contacts share it); uuid (string, the Refiner contact UUID from list_contacts or identify_contact). |
get_reporting | Get an aggregated report, like the reporting dashboards. Arguments: type (string, required, one of nps (score, promoters, passives, detractors), csat (score and distribution), ratings (average and distribution), distribution (count per answer value), count (views and responses)); all others optional: form_uuids (array of UUID strings from list_forms); segment_uuids (array of UUID strings from list_segments); question_identifiers (array of strings, only these questions); date_range_start and date_range_end (strings, ISO 8601, default: the last 7 days up to the end of today); response_data (object { question identifier: answer }); contact_data (object { trait slug: value }); account_data (object { account trait slug: value }). |
list_contacts | List contacts with their attributes, segments and account: { items, pagination }. All arguments optional: search (string, matches e-mail, user ID or name); form_uuid (string, UUID from list_forms, only contacts linked to this survey); segment_uuid (string, UUID from list_segments); order_by (string, one of display_name, email, first_seen_at (default), last_seen_at, last_form_submission_at); page (integer >= 1); page_length (integer 1 to 1000, default 100); page_cursor (string, pagination.next_page_cursor of the previous page). |
list_form_history | List the previous versions of a form (survey), newest first: { items, pagination }, each version holding a snapshot of its name, configuration and questions. Arguments: form_uuid (string, UUID from list_forms, required); page (integer >= 1); page_length (integer 1 to 1000, default 100). |
list_forms | List the forms (surveys) ordered by name: { items, pagination }. Each item has uuid and name. All arguments optional: list (string, one of all, published, drafts, archived, all_with_archived; default all); page (integer >= 1); page_length (integer 1 to 1000, default 100); include_info (boolean, true adds channels, publication and creation dates, response and view counts, folder and survey page URL); include_config (boolean, true adds the survey configuration and each question under elements: large). The uuid is the form_uuid of list_responses, get_reporting, list_contacts and list_form_history. |
list_responses | List survey responses (and optionally views), newest first: { items, pagination }. Each item has the form, the answers under data (question identifier → answer) and the contact. All arguments optional: form_uuid (string, UUID from list_forms); form_uuids (array of UUID strings, several surveys); segment_uuid (string, UUID from list_segments); segment_uuids (array of UUID strings); date_range_start and date_range_end (strings, ISO 8601, YYYY-MM-DD or YYYY-MM-DD hh:mm:ss); include (string, one of completed (default), partials, all (also dismissed views)); search (string, matches the contact user ID, UUID, e-mail or name); response_data (object { question identifier: answer }, e.g. { “nps”: 9 }); contact_data (object { trait slug: value }); account_data (object { account trait slug: value }), the three filters need every key to match; with_attributes (boolean, true adds all contact attributes); page (integer >= 1); page_length (integer 1 to 1000, default 100); page_cursor (string, pagination.next_page_cursor of the previous page, recommended above 10,000 items). The response uuid is what tag_response takes. |
list_segments | List the segments ordered by name: { items, pagination }, each with uuid, name and is_manual (true = contacts are added by hand or through add_contact_to_segment). All arguments optional: page (integer >= 1); page_length (integer 1 to 1000, default 100). |
verify_key | Check the API key and return the environment it belongs to: { project_uuid, project_name, message }. No arguments. |
Write actions (5)
| Action | Description |
|---|---|
add_contact_to_segment | Add a contact to a MANUAL segment (a contact that does not exist yet is created). Returns { message, contact_uuid, segment_uuid }. Arguments: segment_uuid (string, UUID of a segment with is_manual true, from list_segments, required); id (string, your own user ID) and/or email (string): at least one is required. |
identify_contact | Create a contact or update its traits (like identify in the Refiner JavaScript client; the user ID or e-mail is the key, so the same ID updates the same contact). Returns { message, contact_uuid }. Refiner applies it with a delay: the contact and its traits can take about 10 minutes to show in get_contact or the Refiner app. Arguments: id (string, your own user ID) and/or email (string): at least one is required; traits (object { slug: value } with string (up to 4 KB), number or boolean values; a slug ending in _at is parsed as a date, e.g. created_at: “2026-10-23”; “name” sets the display name; any slug is created on the fly); account (object { id (string, required), name (string), traits (object { slug: value }, account traits, same value types) } to group the contact under a company). Traits you do not send are left unchanged. |
remove_contact_from_segment | Remove a contact from a MANUAL segment (the contact and its responses are kept). Arguments: segment_uuid (string, UUID of a segment with is_manual true, from list_segments, required); id (string, your own user ID) and/or email (string): at least one is required. |
tag_response | Add tags to an existing survey response. Arguments: uuid (string, the response UUID from list_responses, required); tags (array of strings, 1 to 20 tag names, required). Returns { message }. |
track_event | Record an event for a contact (a contact that does not exist yet is created). Returns { message }. Refiner shows the event after a delay of about 10 minutes. Arguments: event (string, the event name, required); id (string, your own user ID) and/or email (string): at least one is required. |
Permissions
Every action above must be explicitly granted to an agent before it can be used. See Permissions for the grant model and Security for how credentials are protected.Last reviewed against the provider API: October 2026.