Qualiteam API reference (1.0.0)

Read projects, conversations, evaluation results and settings from your own integration. All endpoints are read-only.

Base URL: https://qualiteam.ai/api/v1

Authentication

Create an API key in Company → API Access. Send it in the Authorization header:

export QUALITEAM_API_KEY='your-key-from-api-access'
curl --fail-with-body 'https://qualiteam.ai/api/v1/projects' \
  -H "Authorization: Bearer $QUALITEAM_API_KEY"

Keep keys in a server-side secret manager, out of browser code, URLs and logs. API keys allow reading data only; they cannot manage integrations or change permissions. Keys do not expire automatically. Administrators can revoke a key or rotate the integration's key, retiring all older keys within 24 hours. Revocation takes effect on the next request.

Resources and permissions

GET /projects lists granted projects. GET /projects/{project_id} returns metadata, including reporting timezone and current score display direction. Any project grant allows this metadata; its shared instructions (description) require rules.read or criteria.read, otherwise the field is null.

Each resource has list and detail endpoints:

GET /projects/{project_id}/{resource}
GET /projects/{project_id}/{resource}/{resource_id}

Resource	Required permission
`managers`	`managers.read`
`conversations`	`conversations.read`
`messages`	`messages.read` and `conversations.read`
`evaluations`, `reviews`, `attribute-results`	`evaluations.read`
`appeals`	`appeals.read`
`alerts`, `alert-definitions`	`alerts.read`
`criteria`	`criteria.read`
`attributes`	`attributes.read`
`evaluation-tags`	`evaluation_tags.read`
`flows`	`flows.read`
`rules`	`rules.read`
`knowledge-base`	`knowledge_base.read`
`notification-rules`, `notification-recipients`	`notifications.read`
`notifications`	`notification_events.read`

Each permission covers the whole selected project, including unpublished evaluations, pending alerts and conversation history from disabled or disconnected sources. Resource access matches a company administrator's. Notification events additionally require that their saved content remains accessible to the original recipient. V1 excludes writes, billing, user management, playground and benchmarks.

Resource permissions include provider IDs (such as agent and chat IDs) and stored text. Email and Telegram handles require contacts.read; otherwise they are null. Personal data inside messages, names, comments and instructions remains readable without this permission. PII redaction follows project settings at import time; the API does no further redaction.

Conversation detail includes evaluation, alert and tag IDs only with the relevant permission (otherwise null). Alerts include their saved condition and matched-value snapshots; full evaluations require their own permission.

Project rules, criteria instructions and extracted knowledge-base text require their respective permissions. The API excludes credentials, access hashes, internal system prompts, usage/billing details and internal job payloads.

Pagination and filters

Lists return:

{
  "data": [{ "id": "example-resource-id" }],
  "next_cursor": "opaque-continuation-token"
}

limit defaults to 50, with a maximum of 100. Lists have no automatic total count. Pass the returned next_cursor as cursor, keeping the same project, resource and filters, until it is null. You can change the page size. Cursors are signed, belong to one integration and do not freeze the data.

With manager_ids, the API resolves agents for legacy or unevaluated conversations in batches. Pages can have fewer than limit results, even zero, while still returning a next_cursor. Continue until the cursor is null.

Results sort by resource ID ascending. Messages sort by conversation ID, timestamp, then message ID, with missing legacy timestamps first. Repeat array parameters as ids=id1&ids=id2, up to 100 values. Unknown parameters and unsupported filter/resource combinations are rejected.

Filter	Where supported
`ids`	Database resources and projects
`conversation_ids`	Conversations and their child resources
`manager_ids`	Managers; message authors; card attribution for evaluations, reviews and appeals; conversation attribution for conversations, attribute results and alerts
`evaluation_id`	Reviews, appeals
`attribute_id`	Attribute results, alert definitions
`alert_id`	Alerts
`source_id`	Managers, conversations, messages
`status`	Evaluations (`result_status`), appeals, alerts
`state`	Conversations
`published`	Evaluations
`approved`	Evaluations, reviews
`created_from`, `created_to`	Resources with `created_at`
`updated_from`, `updated_to`	Resources with `updated_at`
`evaluated_from`, `evaluated_to`	Evaluations
`published_from`, `published_to`	Evaluations
`triggered_from`, `triggered_to`	Alerts

Projects support ids, limit, cursor; flows support limit, cursor. Most lists are compact. Detail endpoints add criteria instructions, knowledge text, appeal comments and per-criterion results. Message lists include text for batch transcript reads; notification lists include the full notification content.

Date filters use ISO 8601 timestamps with Z or a timezone offset. Date-only values and timestamps without a timezone return 422. Each filter applies to its named timestamp, including the lower bound and excluding the upper bound.

Message lists require 1 to 100 conversation_ids, including on later pages. IDs outside the granted project return no data. in_evaluation_window marks timestamps inside loaded_from/loaded_to; is_internal_note is independent. Reply and forward snapshots provide context and do not count as messages or evaluation activity.

curl --get 'https://qualiteam.ai/api/v1/projects/PROJECT_ID/messages' \
  -H "Authorization: Bearer $QUALITEAM_API_KEY" \
  --data-urlencode 'conversation_ids=CONVERSATION_ID' \
  --data-urlencode 'limit=100'

Evaluation and history semantics

Scores and dates

score and total_score are the effective reviewed values; each criterion's model_score keeps the original model value. Use the card's scoring mode, min/max and the project's current addition_score_direction to interpret scores. Direction affects display only.
attribute-results belong to conversations and include effective and original numeric/time values and category sets. Numeric/time edits follow the application's QC rules. Original model category sets are immutable; deleted categories remain readable in history.
Approval and publication are separate. evaluated_at records evaluation, published_at records publication, and loaded_from/loaded_to define conversation coverage. As in reporting, reporting_date uses the last in-window message (or window end) and project timezone.

Agents and deleted cards

A conversation can have several cards with different agents. Each card has attributed_manager_ids; the conversation combines these, with fallback attribution for unevaluated or legacy data. Manager filters follow the same rules.
Reviews and appeals use their own card's agents. Without a card, their attribution is unknown: manager_ids filters exclude them, but unfiltered lists include them.
IDs stay stable until deletion. A replacement card gets a new ID. Reviews and appeals can survive with evaluation_id: null as conversation history; API reads never attach them to a replacement.
An approved review without a card can keep the evaluation card's approved true if the conversation has exactly one card and no card-linked review. Ownership remains unknown, so review_id, approved_at and reviewer references stay null. With multiple cards, it approves none.

Alerts and notifications

Alerts belong to conversations and identify neither a responsible agent nor a card. All states (active, pending_approval, read), historical hits and soft-deleted definitions remain readable. triggered_at records the original hit; activation/read changes use updated_at.
Notification rules list alert/appeal subscriptions, recipients and manager IDs. They do not describe reporting lines or publication-to-team-lead routing.
Saved recipients may be ineligible for built-in delivery. Before sending project data, verify recipient access and channel ownership. The saved telegram_handle may have changed owners and does not verify a Telegram destination.

app_url opens the relevant application screen and requires a user login with project access.

Notification feed

Use GET https://qualiteam.ai/api/v1/projects/{project_id}/notifications to read notifications that Qualiteam has already prepared for recipients. Each item includes the recipient, managers, conversations, title, text, links and event data, ready to send through your messenger. No per-notification request is needed. GET https://qualiteam.ai/api/v1/projects/{project_id}/notifications/{id} returns the same content when you need a single notification.

Field	Meaning
`recipient`	Who this notification was prepared for.
`managers`	The related support agents (`manager` means agent in this API), with their agent tags.
`conversations`	All related conversations, their chat tags and `manager_ids` referencing `managers[].id`. Present for every event type.
`data`	Event-specific facts, such as fired alerts or appeal outcomes. Use the top-level `conversations` for the common conversation references.
`title`, `text`, `links`	Prepared message content for your messenger.

There are three separate kinds of tags. Chat tags and agent tags are string lists. Evaluation tags have IDs in evaluation_tag_ids, with definitions from evaluation-tags and their own evaluation_tags.read permission.

In notifications, conversations[].chat_tags and managers[].tags are saved at creation. Changing source tags does not rewrite them. In contrast, GET https://qualiteam.ai/api/v1/projects/{project_id}/conversations (and its detail endpoint) returns current chat_tags, and managers[].name in notifications is the current agent name. Telegram, TimelinesAI and Helpshift chat tags are supported; Intercom, Zendesk and missing chat metadata return [].

Both notification tag fields require only notification_events.read; no additional managers.read or conversations.read is needed. Chat tags hidden from a linked recipient are omitted at creation and hidden again if access is later revoked. Tags omitted at creation do not appear later when access is restored. Manual recipients follow their administrator-configured access. Old notifications still include related conversation and agent IDs, but their tag arrays are []. Tag fields are never null; an empty array can mean no tags, unavailable tags, hidden tags or a pre-feature notification.

Ask an administrator to grant notification_events.read in Company → API Access. Existing keys do not gain this permission automatically. notifications.read still covers settings only. Contact fields also require contacts.read.

The feed follows existing alert/appeal rules and agent-publication settings. One notification is shared across its delivery channels. Successful email/Telegram delivery does not remove it from the feed. Your integration handles delivery to your messenger; the API has no delivery acknowledgement endpoint.

At first connection, choose and persist created_from, for example 2026-10-21T09:00:00Z. Read the list with this date; optionally add event_type or recipient_id.
Process the complete notifications in data, using notification IDs to prevent duplicates.
Follow next_cursor until it is null, including through empty pages. Save your checkpoint only after processing its page or storing its notifications in your durable delivery queue.
Save the final resume_cursor; use it as cursor on the next poll and after restarts, with the same filters and the original created_from.

created_from includes its boundary; created_to excludes it. Both filter created_at and require an ISO 8601 timestamp with a timezone. Equivalent offsets are normalized to UTC. Invalid dates return 422, a reversed range returns 400, and equal boundaries return an empty page. Changing filters with a cursor returns 400.

For continuous polling, omit created_to. For a bounded export, supply both dates, for example created_from=2026-10-21T00:00:00Z and created_to=2026-10-22T00:00:00Z. Without dates, reading starts at the oldest retained feed position. Existing consumers can keep using their date-less cursors. To add date filters, restart without a cursor and deduplicate against saved notification IDs.

The order remains feed_sequence ASC: the order notifications appear in the feed. A late-committing notification may have an earlier created_at; it still arrives after your saved cursor if it matches your fixed date range. Do not replace the cursor with the last notification's timestamp or move created_from forward on each poll.

A page with one notification looks like this (IDs and cursor are illustrative):

{
  "data": [{
    "id": "notification-123",
    "project_id": "project-123",
    "event_type": "alert_fired",
    "created_at": "2026-10-21T09:00:00Z",
    "recipient": {
      "id": "recipient-123", "kind": "recipient", "name": "Team lead",
      "user_id": null, "email": null, "telegram_handle": null
    },
    "managers": [{"id": "manager-123", "name": "Alex", "tags": ["affiliate"]}],
    "conversations": [{
      "conversation_id": "conversation-123",
      "manager_ids": ["manager-123"],
      "chat_tags": ["weekly_review", "priority"]
    }],
    "title": "Notifications from Support",
    "text": "Support chat: Low score. View conversation (https://qualiteam.ai/conversation/conversation-123)",
    "links": [{
      "label": "View conversation",
      "url": "https://qualiteam.ai/conversation/conversation-123"
    }],
    "data": {
      "type": "alert_fired",
      "conversations": [{
        "conversation_id": "conversation-123", "topic": "Payment question",
        "chat_name": "Support chat", "manager_names": ["Alex"],
        "alerts": [{"id": "alert-123", "name": "Low score"}]
      }]
    }
  }],
  "next_cursor": null,
  "resume_cursor": "opaque-resume-token"
}

Committed notifications normally appear within a few seconds. They remain available for 90 days after entering the feed; pre-upgrade queued notifications are not added. HTTP 410 means the cursor is too old: restart without it using the same filters and deduplicate against saved IDs. An expired history window cannot be recovered through the API.

Access is rechecked when reading. Deleted sources or recipients, or lost membership can make an older notification unavailable (404 on detail). Contact edits and Telegram connection state do not erase API history. Publication notifications still require publication access and enabled agent-publication settings. Recipient contact fields describe the saved notification. Content is a saved snapshot; dates and links in the message describe that notification.

For publication notifications, recipient IDs are platform user IDs (kind: agent); other events use notification-recipient IDs (kind: recipient). Alerts identify conversations, not a responsible agent. The managers list identifies the permitted related agents. conversations[].manager_ids uses the saved attribution of permitted evaluation cards and can be empty, including for detached appeals; it does not identify an agent responsible for an alert. Publication references include all conversations, even when the message text shows only a preview. If an agent profile has no name, notifications return agent_name: "" in their event data.

Polling notifications

Call this function on each poll with your persisted created_from and saved cursor, or None for the cursor on the first run. Keep the same date after restarts. Supply enqueue_once(id, notification) to store the full notification in your durable delivery queue, deduplicated by ID, and save_cursor(cursor) to persist the checkpoint. Send queued messages through your messenger separately. If storing a page fails, its checkpoint is not advanced and the next poll can retry it.

import os
import requests


def poll_notifications(project_id, created_from, cursor, enqueue_once, save_cursor):
    base = "https://qualiteam.ai/api/v1"
    params = {"limit": 100, "created_from": created_from}
    if cursor is not None:
        params["cursor"] = cursor

    with requests.Session() as session:
        session.headers["Authorization"] = f"Bearer {os.environ['QUALITEAM_API_KEY']}"
        while True:
            response = session.get(
                f"{base}/projects/{project_id}/notifications",
                params=params, timeout=30,
            )
            response.raise_for_status()
            page = response.json()
            for notification in page["data"]:
                enqueue_once(notification["id"], notification)

            cursor = page["next_cursor"] or page["resume_cursor"]
            save_cursor(cursor)
            if page["next_cursor"] is None:
                return cursor
            params["cursor"] = cursor

Match conversations to agents

Use IDs to associate each conversation with its agents and their tags. No further API calls are needed:

def conversations_with_agents(notification):
    agents = {agent["id"]: agent for agent in notification["managers"]}
    for conversation in notification["conversations"]:
        yield conversation, [agents[agent_id] for agent_id in conversation["manager_ids"]]

Polling evaluations

Read currently published evaluations within an evaluation-time range from your server. Your integration handles message composition and delivery.

import os
import requests

base = "https://qualiteam.ai/api/v1"
project_id = "PROJECT_ID"
params = {
    "published": "true",
    "evaluated_from": "2026-10-01T00:00:00Z",
    "evaluated_to": "2026-10-08T00:00:00Z",
    "limit": 100,
}
headers = {"Authorization": f"Bearer {os.environ['QUALITEAM_API_KEY']}"}

with requests.Session() as session:
    while True:
        response = session.get(
            f"{base}/projects/{project_id}/evaluations",
            headers=headers, params=params, timeout=30,
        )
        response.raise_for_status()
        page = response.json()
        for evaluation in page["data"]:
            print(evaluation["id"], evaluation["total_score"], evaluation["app_url"])
        if page["next_cursor"] is None:
            break
        params["cursor"] = page["next_cursor"]

The API returns current state, so pages can change during a scan. When polling, re-read the relevant period and deduplicate by resource ID. Child changes may leave the parent's timestamp unchanged. Polling can miss deletions, unpublish/republish cycles and intermediate states. These resource endpoints have no change log or deletion markers; ID order cannot identify new items since the last poll. The notification feed has its own resumable cursor and 90-day history. Webhooks are not available.

Limits and errors

Limits default to 60 requests/minute per integration and 300/minute per company, shared across keys and workers. Counters reset in fixed minute windows; quota rejections also count toward the company limit. Administrators cannot change these server limits.

For 429, wait the Retry-After seconds before retrying. For 503 or temporary network errors, use bounded backoff. Authentication and permission errors require fixing the key or grants.

HTTP status	Meaning
400	Invalid cursor, unsupported filters or missing message conversation IDs
401	Missing, invalid, expired or revoked API key
403	Project is granted, but a required scope is missing
404	Resource/project is absent or outside the grant
405	Unsupported write operation
409	Legacy flow storage has an ambiguous project prefix; contact support
410	Notification cursor expired; restart without a cursor to read retained history
422	Invalid parameter type, range or unknown parameter
429	Integration or company rate limit
503	Database busy; retry shortly

Errors use {"error":{"code":403,"message":"Missing required API scope"}}. Data and key-creation responses use Cache-Control: no-store. OpenAPI is public, with no customer data. The reference shows examples without sending API requests.

Versioning

/api/v1 preserves existing fields, types and meanings. Ignore unfamiliar fields from compatible optional additions. Breaking changes use /api/v2. V1 remains supported for at least 180 days after a migration announcement, with migration instructions and a retirement date. Internal frontend endpoints follow a separate lifecycle outside this contract.

Notifications

Ready notifications for your own delivery integration. One record per recipient, shared across email and Telegram. History lasts 90 days after appearing in the feed. Existing notification rules and publication settings determine which events are created. Each list item includes the full text, recipient, managers, conversations, links and event data, ready for your messenger without per-notification requests. Detail returns the same content for a single notification. Read all pages with next_cursor, then save resume_cursor for the next poll after processing the page or storing it in your durable delivery queue. Save created_from at first connection and keep it unchanged with each cursor, including after restarts. created_from is inclusive and created_to exclusive, both on created_at with a required timezone. Omit created_to for continuous polling; use both dates for a bounded export. Feed order is feed_sequence ASC (appearance order), not creation time: late commits can have an older created_at and still appear after your cursor if they match the date range. On 410, restart without a cursor using the same filters and deduplicate saved IDs. Recipient access is rechecked on every read. Channel delivery does not consume the feed. managers[].tags and conversations[].chat_tags are saved tag snapshots; conversations[].manager_ids links conversations to managers[].id without matching names or making extra requests. Older notifications keep their conversation/agent references with empty tag arrays. Only notification_events.read is needed for both tag types; hidden recipient chat tags remain hidden.

List notifications

GET https://qualiteam.ai/api/v1/projects/{project_id}/notifications

Required permissions: notification_events.read.

Pagination and filters.

Required permissions: notification_events.read.

Parameters

Name	Location	Required	Schema and description
`project_id`	path	Yes	`string` ID of a project granted to this integration. Get it from `GET /projects`.
`cursor`	query	No	Any of: (`string`; `null`) anyOf variant: `string` maxLength: `4096` anyOf variant: `null` Use next_cursor for another page, or resume_cursor to poll for new notifications. Keep filters unchanged. A page may be empty when saved content is no longer authorized. An expired cursor returns 410.
`limit`	query	No	`integer` default: `50` minimum: `1` maximum: `100` Maximum page size: 1–100, default 50. No total count is calculated.
`event_type`	query	No	Any of: (NotificationEventType; `null`) anyOf variant: `null` Filter by alert_fired, appeal_created, appeal_resolved or agent_conversations_published.
`recipient_id`	query	No	Any of: (`string`; `null`) anyOf variant: `string` anyOf variant: `null` Recipient ID from a notification. Publication notifications use the recipient's platform user ID.
`created_from`	query	No	Any of: (`string` · format: `date-time`; `null`) anyOf variant: `string` · format: `date-time` anyOf variant: `null` Inclusive lower bound on created_at. ISO 8601 with Z or an offset. `"2026-10-01T00:00:00Z"`
`created_to`	query	No	Any of: (`string` · format: `date-time`; `null`) anyOf variant: `string` · format: `date-time` anyOf variant: `null` Exclusive upper bound on created_at. ISO 8601 with Z or an offset. `"2026-10-01T00:00:00Z"`

curl example

curl --fail-with-body --get 'https://qualiteam.ai/api/v1/projects/PROJECT_ID/notifications' \
  -H "Authorization: Bearer $QUALITEAM_API_KEY"

Python example

import os
import requests

response = requests.get(
    "https://qualiteam.ai/api/v1/projects/PROJECT_ID/notifications",
    headers={"Authorization": f"Bearer {os.environ['QUALITEAM_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Responses

200

Successful Response

application/json

NotificationFeedPage

400

Invalid cursor, unsupported filter or missing message conversation IDs.

application/json

Qualiteam API reference (1.0.0)

Authentication

Resources and permissions

Pagination and filters

Evaluation and history semantics

Scores and dates

Agents and deleted cards

Alerts and notifications

Notification feed

Polling notifications

Match conversations to agents

Polling evaluations

Limits and errors

Versioning

Notifications

List notifications

Parameters

curl example

Python example

Responses

200

400

401

403

404

405

409

410

422

429

Response headers

500

503

Get notification

Parameters

curl example

Python example

Responses

200

400

401

403

404

405

409

422

429

Response headers

500

503

Projects

List projects

Parameters

curl example

Python example

Responses

200

400

401

403

404

405

409

422

429

Response headers

500

503

Get project

Parameters

curl example

Python example

Responses

200

400

401

403

404

405

409