Analysis API

Use the Analysis API to query the same production data available in Voxmith: Intents, Violations, Conversations, and Events. It is useful for internal tools, scheduled reports, and investigations driven by an AI agent.

Before you begin

Create an API key in Voxmith, then set it as an environment variable using your runtime, deployment platform, or preferred .env loader:

VOXMITH_API_KEY=your_api_key

Every request uses:

• Base URL: https://api.voxmith.com
• Header: x-api-key: $VOXMITH_API_KEY
• Content type: application/json for request bodies

Most endpoints accept time_range. Supported values are 5min, 1h, 1d, 1w, 1m, all, and custom durations such as custom:2h30m. Most endpoints default to 30d when the value is omitted or invalid.

Recommended workflow

Use exact intent or violation titles returned by the list and stats endpoints. Do not invent normalized tags. Intents and violations are classified proactively, so there is no manual classification step.

Intents

POST /dashboard/api/sentiment-stats

Lists top intent clusters and counts in a time window. Best for: Ranking the intents that matter across recent conversations.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sentiment-stats" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"time_range":"1w"}'

POST /dashboard/api/sentiment-messages

Returns paginated user messages that matched one intent cluster. Best for: Inspecting evidence after selecting an exact intent title from sentiment-stats or sentiments.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sentiment-messages" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag":"Draft an email","time_range":"1w","page":1,"limit":25}'

POST /dashboard/api/sentiment-timeline

Returns a bucketed count timeline for one intent cluster. Best for: Seeing whether one intent is rising, falling, or spiking over time.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sentiment-timeline" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag":"Draft an email","time_range":"1w"}'

POST /dashboard/api/sentiment-timelines

Returns bucketed timelines for multiple intent clusters in one call. Best for: Comparing several known intents over the same time window.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sentiment-timelines" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags":["Draft an email","Schedule a meeting"],"time_range":"1w"}'

POST /dashboard/api/summarize-intent-distribution

Summarizes why one intent cluster is appearing in the selected time window. Best for: Producing a short explanation after reviewing sentiment-stats or sentiment-messages.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/summarize-intent-distribution" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag":"Draft an email","time_range":"1w"}'

GET /dashboard/api/sentiments

Lists active and suggested intent definitions. Best for: Finding an existing intent before querying or creating one.

Request:

Response schema:

Output format: object[] at the JSON response root. Decode directly as an array/list, not as { "sentiments": [...] }.

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sentiments" \
  -H "x-api-key: $VOXMITH_API_KEY"

POST /dashboard/api/sentiments

Creates a new intent definition for future proactive classification. Best for: Creating an intent only when no existing definition covers the need.

Request:

Response schema:

Created response:

Duplicate skip response:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sentiments" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Draft an email","description":"User wants the agent to draft, edit, or send an email.","active":true}'

PUT /dashboard/api/sentiments/{id}

Updates an existing intent definition or lifecycle status. Best for: Correcting, enabling, or disabling an existing intent. Use active, not status.

Request:

Response schema:

Call:

curl -sS -X PUT "https://api.voxmith.com/dashboard/api/sentiments/$INTENT_ID" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"User wants the agent to draft, edit, or send an email.","active":true}'

Violations

POST /dashboard/api/sop-stats

Lists the most common violations and their counts in a time window. Best for: Ranking the agent rules violated most often.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sop-stats" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"time_range":"1w"}'

POST /dashboard/api/sop-messages

Returns paginated assistant messages that violated one rule. Best for: Inspecting evidence after selecting an exact violation title. Violations match assistant output, while intents match user input.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sop-messages" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag":"Confirm scheduling conflicts proactively","time_range":"1w","page":1,"limit":25}'

POST /dashboard/api/sop-violations

Returns a paginated feed of violation events across all rules. Best for: Exploring violations before choosing a single rule to investigate.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sop-violations" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"time_range":"1w","page":1,"limit":20}'

POST /dashboard/api/sop-timeline

Returns a bucketed count timeline for one violation rule. Best for: Seeing whether one violation is rising, falling, or spiking over time.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sop-timeline" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag":"Confirm scheduling conflicts proactively","time_range":"1w"}'

POST /dashboard/api/sop-timelines

Returns bucketed timelines for multiple violation rule clusters in one call. Best for: Comparing several known violations over the same time window.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sop-timelines" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags":["Confirm scheduling conflicts proactively","No unsupported guarantees"],"time_range":"1w"}'

POST /dashboard/api/summarize-sop-distribution

Summarizes why one violation rule is being violated in the selected time window. Best for: Producing a short explanation after reviewing sop-stats or sop-messages.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/summarize-sop-distribution" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag":"Confirm scheduling conflicts proactively","time_range":"1w"}'

GET /dashboard/api/sops

Lists active and suggested violation rule definitions. Best for: Finding an existing violation rule before querying or creating one.

Request:

Response schema:

Output format: object[] at the JSON response root. Decode directly as an array/list, not as { "sops": [...] }.

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sops" \
  -H "x-api-key: $VOXMITH_API_KEY"

POST /dashboard/api/sops

Creates a new violation rule definition for proactive violation detection. Best for: Creating a rule only when no existing violation definition covers it. Send active:true to classify future messages and asynchronously backfill up to 1,000 recent conversations.

Request:

Response schema:

Created response:

Duplicate skip response:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/sops" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Confirm scheduling conflicts proactively","description":"Assistant must identify scheduling conflicts and ask for confirmation before booking or sending calendar changes.","active":true}'

PUT /dashboard/api/sops/{id}

Updates an existing violation rule definition or lifecycle status. Best for: Correcting, enabling, or disabling a violation rule. Activating a rule or changing its active description asynchronously backfills up to 1,000 recent conversations.

Request:

Response schema:

Call:

curl -sS -X PUT "https://api.voxmith.com/dashboard/api/sops/$VIOLATION_ID" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Assistant must surface conflicts and get explicit confirmation before taking scheduling action.","active":true}'

Conversations and events

POST /dashboard/api/user-stories

Lists conversations with event rows, metadata, intent matches, and violations. It can also page conversation- or user-metadata groups, then page users within one selected group. Best for: Building a paginated group → user → conversation inventory. Use event-io or raw-logs for exact input and output.

Request:

Response schema:

With group_by and group_level:"groups" (the grouped default), the response contains groups instead of conversations. Each group includes value, user_count, conversation_count, message_count, intent and violation counts/labels, last_active, and cost_metadata. The legacy message_count field counts distinct captured events, including tool events, and equals the sum shown for its child conversations. With group_level:"users", the response contains users with the same metrics plus an opaque key, user_id, label, and representative_conversation_id. Send that key as group_user_key with group_level:"conversations" to retrieve the user's conversations through the exact same group membership logic. Metadata arrays can place one conversation in more than one group.

Each cost_metadata entry is either an explicit USD cost bucket or a model/provider token bucket. Token buckets combine requests that share the same input-token count, expose that count as tokens.request_input, and use tokens.aggregated:"true"; clients should select any request-level pricing tier from tokens.request_input, then apply it to the aggregated token totals. pricing.invalid:"true" marks malformed numeric metadata. If an event has neither a valid explicit cost nor enough valid model/token data to price it, a computed total is incomplete.

Call:

curl -sS "https://api.voxmith.com/dashboard/api/user-stories" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"time_range":"1w","page":1,"page_size":15,"exclude_io":true}'

Grouped metadata call:

curl -sS "https://api.voxmith.com/dashboard/api/user-stories" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"time_range":"1w","page":1,"page_size":15,"group_by":{"source":"user_metadata","key":"organization_id"},"group_level":"groups"}'

POST /dashboard/api/conversation-detail

Fetches one conversation's metadata, transcript messages, and full span tree. Best for: Loading messages and trace spans when you already have a conversation_id.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/conversation-detail" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"'$CONVERSATION_ID'","load_io":true}'

POST /dashboard/api/conversation-messages

Returns the user-facing transcript for one conversation. Best for: Replaying the user-visible message flow without internal tool or model spans.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/conversation-messages" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"'$CONVERSATION_ID'","load_io":true}'

POST /dashboard/api/conversation-spans

Returns the event/span hierarchy for one conversation, including child spans. Best for: Debugging tool calls, model execution, latency, errors, and parent-child spans.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/conversation-spans" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"'$CONVERSATION_ID'","event_id":"'$EVENT_ID'"}'

POST /dashboard/api/event-io

Fetches only the readable input and output for an exact event id. Best for: Fetching readable input and output when you already have an event_id.

Request:

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/event-io" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_id":"'$EVENT_ID'"}'

POST /dashboard/api/raw-logs

Fetches raw event rows with optional metadata, agent, connection, success, and IO filters. Best for: Paginating raw events with metadata, status, latency, and optional input and output.

Request:

Filter guidance:

• Use dedicated fields for exclude_io, agent_name, and success; metadata_filters cannot express those event columns or output-shaping options.
• connection_type is equivalent to metadata_filters[{source:"conversation_metadata", key:"transport_type"}]; prefer connection_type for this common filter.
• client_config is equivalent to metadata_filters[{source:"conversation_metadata", key:"client_config"}]; prefer client_config for this common filter.
• Use metadata_filters for arbitrary event/conversation/user metadata keys and user_id.
• If dedicated filters and metadata_filters are both sent, the backend applies all of them with AND semantics.

Response schema:

Call:

curl -sS "https://api.voxmith.com/dashboard/api/raw-logs" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"time_range":"all","page":1,"page_size":1,"exclude_io":false}'

Ask Voxmith

POST /dashboard/api/run-spotlight-query

Runs an open-ended investigation from a natural-language question. Best for: Questions that the deterministic intent, violation, conversation, and event endpoints cannot answer. Keep limit as small as possible.

Request:

Response schema:

Output transport: text/event-stream. Decode SSE events. The final answer is sent in a chunk event as {"text": string}; completion metadata is sent in a done event. By default text is prose. With response_format: "json", text contains one compact JSON object synthesized from the template after Spotlight chooses and runs its read-only MCP tools.

SSE event payloads:

Call:

curl -N -sS "https://api.voxmith.com/dashboard/api/run-spotlight-query" \
  -H "x-api-key: $VOXMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Find users who were frustrated because email drafting failed","time_range":"1w","limit":25}'

Metadata filters

{
  "metadata_filters": [
    {
      "source": "event_metadata | conversation_metadata | user_metadata | user_id",
      "key": "metadata_key_optional_for_user_id",
      "values": ["value-a", "value-b"]
    }
  ]
}

Next steps

• Authentication: create and use a Voxmith API key.
• Intents: understand the intent data returned by these APIs.
• Violations: review the violation model and workflow.