# Ender Turing > Conversation analytics for contact centers. This address serves the web app and its API. This file is the API guide for AI agents. It covers reading conversations, scores and summaries, writing filters, asking Ender chat, and uploading conversations. The full reference is `GET /api/v1/openapi.json`. It is large, so load it only when you need an operation that is not described here. It needs a token whose account may also create conversations; other accounts get `400`. ## Basics - Send every request to the address you were given. All paths start with `/api/v1`. - Every API call needs a token. Send it in a header: `Authorization: Bearer `. Ask the user for a token if you have none. - Send a `User-Agent` header that starts with `EnderTuringSDK/` and names your tool, for example `EnderTuringSDK/my-agent/1.0`. Without it, Ender Turing cloud may answer with a firewall page instead of JSON. - Answers are JSON. - You get only what the token's account may see. An account limited to one team, or to its own conversations, gets only those. - Do not create, change or delete data unless the user asked for exactly that. ## Vocabulary | In the product | In the API | | --- | --- | | Conversation (call, chat, email) | `sessions` | | Topic | `categories` | | Team | `agent-groups` | | Keyword | `tags` | | Quality score | `scores` | | Ender chat | `ender-chat` | ## Read conversations `GET /api/v1/sessions` lists conversations. | Parameter | Meaning | | --- | --- | | `filters` | Which conversations to return. See "Filters". | | `skip`, `limit` | Paging. `limit` is 100 by default and 1000 at most. | | `order_by` | `newest`, `oldest`, `longest`, `average_score_asc` or `average_score_desc`. | | `detailed_scores=true` | Adds every quality score to each conversation. Slower. | | `include_additional_info=true` | Adds `additional_info`: the data that came with each conversation from other systems, such as `call_recording_system_id`. Slower. | The answer is `{"items": [...], "total": N}`. Useful fields of an item: | Field | Meaning | | --- | --- | | `id` | Use it in the calls below. | | `type` | `call`, `chat`, `email`, `web` or `loan`. | | `start_dt`, `duration` | Start time, and length in seconds. | | `direction` | `in`, `out` or `internal`. | | `agent_id`, `agent_name`, `group_id` | The agent and the team. | | `categories` | Topics found in the conversation. Each item has the topic's `id`. | | `average_score`, `scores_count` | Quality scores. | | `summaries_count` | How many summaries exist. | Limits: - `skip` plus `limit` cannot go past 10,000, and the list's `total` stops counting at 10,000. For more, ask for one day or one week at a time with a `date_range` filter. - To count conversations, call `GET /api/v1/sessions/filter/statistics` with the same `filters`. Its `total` is exact, and `duration` is their total length in seconds. A first request, with `curl`: ``` curl -G "
/api/v1/sessions" \ -H "Authorization: Bearer " \ -H "User-Agent: EnderTuringSDK/my-agent/1.0" \ --data-urlencode "filters=date_range,|last_week|" \ --data-urlencode "limit=10" ``` More about one conversation: - `GET /api/v1/sessions/{session_id}` returns one conversation's details, the same kind of fields as the list. For what was said in it, read its summaries or ask Ender chat. - `GET /api/v1/sessions/{session_id}/summary` returns its summaries. Each has `text` and `prompt_name`. The answer is empty when there is none. - `GET /api/v1/sessions/{session_id}/scores` returns its quality scores. Each has `scorecard_id`, `reviewer_id` and `point_scores`. ## Filters `filters` is one text value. - One filter is `name,value`. - Join filters with `±` (U+00B1). A conversation must match all of them. - Put `-` before the name to exclude what the filter matches. - Pass the value as a query parameter and let your HTTP client encode it. Do not build the URL by hand. Each line below is a complete, working value. `filters=` is the parameter name. By date. Both days are included: ``` filters=date_range,2026-11-01,2026-11-15|| filters=date_range,2026-11-01,2026-11-15||09:00,17:00 filters=date_range,|last_week| filters=date_range,|yesterday| filters=datetime_range,2026-11-01T08:00:00,2026-11-01T18:00:00 ``` A date range has three parts split by `|`: the two dates, a named period, and a time of day. Leave the parts you do not use empty, but keep both `|`. Named periods: `today`, `yesterday`, `current_week`, `last_week`, `current_month`, `last_month`, `1w`, `2w`, `1m`, `3m`, `6m`, `1y`. By agent, direction, type and length: ``` filters=agent_ids,12,15 filters=-agent_ids,12 filters=direction,in filters=types,call,chat filters=duration,60-180 filters=duration,>300 ``` Agent ids come from `agents` in `GET /api/v1/sessions/filter/choices`. Direction is `in`, `out` or `internal`. An unknown direction is not refused; it matches nothing. Length is in seconds. By quality score, summary, topic and text: ``` filters=is_scored,true filters=is_scored,automated filters=is_summarized,true filters=categories,5,6 filters=-categories,5 filters=search_query,cancel my subscription ``` `is_scored` takes `true`, `false`, `manual` or `automated`. Topic ids come from `topics` in `GET /api/v1/sessions/filter/choices`; several ids mean "any of these". By an ID from another system, such as a call ID from the phone system: ``` filters=search_query,0x1a2b3c4d5e6f7a8b ``` `search_query` also finds a conversation by an ID that came with it from another system. It still matches what was said and phone numbers too, so other conversations can come back. Add `include_additional_info=true` and keep only the conversations whose `additional_info` has a value equal to the ID, including upper and lower case. One call can still give several conversations, for example when it was recorded in parts. Several filters together, and "either of these": ``` filters=date_range,|last_week|±direction,in±is_scored,true filters=complex,||[direction,inºtypes,chat] ``` Inside a `complex` group the filters are split by `º` (U+00BA). `||[...]` means any of them, `&&[...]` means all of them. Other filters, such as keywords and scorecards, have longer forms. Ask the user to set the filter on the Conversations page in the web interface and to copy the `filters` value from the address bar. Decode it once before you use it. A filter that cannot be read gets a `422` answer like `{"id": "invalid_filter_configuration", "detail": "Invalid filter 'duration': ..."}`. ## Names for ids Answers carry ids. `GET /api/v1/sessions/filter/choices` gives most names in one call, with no paging: `agents`, `groups` (teams), `topics`, `users` (each with `is_reviewer`), queues, campaigns and languages. Any account that can read conversations may call it. Fetch it once and keep it. Other lists, for more detail: - `GET /api/v1/scorecards` for scorecards. It returns 100 at a time; page with `skip` and `limit`. - `GET /api/v1/tags` for keywords. - `GET /api/v1/categories` for topic details. It returns 50 at a time (page with `skip` and `limit`) and needs the right to manage analytics settings. - `GET /api/v1/agents` and `GET /api/v1/agent-groups` for agent and team details. They need the right to view agents or teams. Some accounts may not read these lists; see "Errors". ## Ask Ender chat For a question about many conversations, such as "why do customers cancel?", ask Ender chat. Do not read conversations one by one. 1. Call `POST /api/v1/ender-chat` with `{"question": "...", "filters": "..."}`. `filters` is optional and uses the form above. The answer has the chat's `id`. 2. Call `GET /api/v1/ender-chat/{chat_id}` every few seconds until `workflow_state` is `waiting_for_user`. This can take minutes. 3. Read the last item of `messages` whose `message_type` is `ai_response`. The text is in `content`. If `error_message` is set, the question failed. 4. To ask more in the same chat, call `POST /api/v1/ender-chat/{chat_id}` with `{"question": "..."}` and wait again. A question sent before `workflow_state` is `waiting_for_user` gets a `400`. ## Upload conversations Only when the user asks for it. The account needs the right to create conversations. - A call: `POST /api/v1/recognizer/audio-file` with a multipart form. Put the recording in the field `file`. The file name must end in `.mp3`, `.wav`, `.opus` or `.m4a`, and the part's content type must start with `audio/`; anything else gets `415`. ``` curl "
/api/v1/recognizer/audio-file" \ -H "Authorization: Bearer " \ -H "User-Agent: EnderTuringSDK/my-agent/1.0" \ -F "file=@call.mp3;type=audio/mpeg" ``` - A chat, an email thread or a ticket: `POST /api/v1/sessions/chats` with JSON. `participants` needs one `customer` and at least one `agent` or `bot`, each with `role` and `phone`. Each message needs `msg_from` (the sender's `phone`), `dt` and `text`. A minimal body: ```json { "language_code": "en", "participants": [ {"role": "customer", "phone": "380441112233", "full_name": "Customer"}, {"role": "agent", "phone": "1001", "full_name": "Agent Name"} ], "messages": [ {"msg_from": "380441112233", "dt": "2026-11-16T09:00:00Z", "text": "Hello, my card is blocked."}, {"msg_from": "1001", "dt": "2026-11-16T09:01:00Z", "text": "I can help with that."} ] } ``` Both answer with `session_id`. Analysis runs after the answer. Until it finishes, reading the conversation can return `404` or miss summaries and scores, so read it again later. ## Change or delete data Ender Turing keeps earlier versions of only a few settings, and most deletes cannot be undone. So: - Before you change or delete an item, read it with `GET` and keep the whole answer. Save it to a file and tell the user where it is, or show it to the user if you cannot save files. - Start from what you read and change only what the user asked for. A list you send, such as a keyword's `phrases`, replaces the whole list. - If the item can be archived, offer that instead of deleting it. Archiving can be undone. A delete cannot: an item made again from your copy gets a new `id`. ## Errors | Answer | Meaning | What to do | | --- | --- | --- | | `401` | The token is missing or no longer valid. | Ask the user for a new token. | | `400` with "The user doesn't have enough privileges" | The account's role does not allow this call. | Tell the user which call was refused. An administrator can give the account a role with that right. | | `404` | Not found, not visible to this account, or a new conversation that is not ready yet. | For a new conversation, try again later. | | `422` | A parameter or a filter is wrong. | Read `detail` and correct the request. | | An HTML page | On Ender Turing cloud a firewall stopped the request. | Check the `User-Agent` (see "Basics"). If it is right, do not retry; give the user the Ray ID shown on the page. | Send requests one after another, not in parallel. ## Which call for what For the request body of a call not described above, look it up in the full reference before you send it. If your account cannot open the reference, ask the user instead of guessing. | To do this | Call | | --- | --- | | Find conversations | `GET /api/v1/sessions` | | Find a conversation by an ID from another system, such as a call ID | `GET /api/v1/sessions` with `filters=search_query,`, then check the IDs (see "Filters") | | Count conversations for a filter, or check that a filter works | `GET /api/v1/sessions/filter/statistics` with `filters`. The answer has `total` and `duration` in seconds. | | Allowed filter values: agents, teams, topics, queues, campaigns, languages | `GET /api/v1/sessions/filter/choices` | | Read one conversation, its summaries, its quality scores | `GET /api/v1/sessions/{session_id}`, `GET /api/v1/sessions/{session_id}/summary`, `GET /api/v1/sessions/{session_id}/scores` | | Answer a question about many conversations | `POST /api/v1/ender-chat` | | Ask the same question every day, week or month | `POST /api/v1/ender-chat/scheduled-chats` | | Upload a call or a chat | `POST /api/v1/recognizer/audio-file`, `POST /api/v1/sessions/chats` | | Add your own data to a conversation | `PUT /api/v1/sessions/{session_id}/metadata` | | Topics | `GET /api/v1/categories`, `POST /api/v1/categories` | | Keywords | `GET /api/v1/tags`, `POST /api/v1/tags` | | Scorecards | `GET /api/v1/scorecards`, `GET /api/v1/scorecards/{pk}` | | See which summaries are set up | `GET /api/v1/prompts/categories/{category}` with `summarisation` | | Automations (Enders): rules that act on new conversations, scores or summaries, webhooks included | `GET /api/v1/automation`, `POST /api/v1/automation` | | Connected apps (integrations) | `GET /api/v1/marketplace/installations` | | Dashboard numbers | No simple call yet. Count with the statistics call above, or ask Ender chat. |