Internal Endpoints and Operations #

This document provides a comprehensive reference for all internal endpoints and operations available in the backend. These endpoints are primarily used for administrative tasks, debugging, and manual triggering of background processes.

Table of Contents #

• Tick Endpoints
• Runner Operations
• Reprocessing Operations
• PubSub Operations
• Needle Mover Operations
• Prediction Operations
• Other Internal Operations

Tick Endpoints #

Tick endpoints manually trigger background processes that normally run on a schedule. These are useful for testing, debugging, or forcing immediate processing.

General Tick #

Endpoint: POST /api/tick
Permission: permissionWorkspacesWrite

Triggers all workspace-level tick operations for the current workspace, including:

• Workspace connections tick
• General workspace tick (config updates, core tick operations)

fetch("/api/tick", { method: "POST" });

Tick Conversations #

Endpoint: POST /api/tick/conversations
Permission: permissionWorkspacesWrite

Manually triggers conversation processing for the current workspace.

fetch("/api/tick/conversations", { method: "POST" });

Tick Runners #

Endpoint: POST /api/tick/runners
Permission: permissionWorkspacesWrite

Manually triggers all runners for the current workspace. Returns a map of runner IDs to boolean values indicating which runners were triggered.

Response:

{
  "calendar_events": true,
  "chat_summary_notes": false,
  "conversation_note_analysis_processor": true,
  ...
}

Note: If a runner is already running in the background, it may respond with a 500 status code.

fetch("/api/tick/runners", { method: "POST" });

Tick Tasks #

Endpoint: POST /api/tick/tasks
Permission: permissionWorkspacesWrite

Manually triggers task processing for the current workspace.

fetch("/api/tick/tasks", { method: "POST" });

Tick AI Workflows #

Endpoint: POST /api/tick/ai/workflows
Permission: permissionWorkspacesWrite

Manually triggers AI workflow processing for the current workspace.

fetch("/api/tick/ai/workflows", { method: "POST" });

Tick Notes #

Endpoint: POST /api/notes/tick
Permission: permissionWorkspacesWrite

Manually triggers note processing for the current workspace.

fetch("/api/notes/tick", { method: "POST" });

Tick Report Runs #

Endpoint: POST /api/reports/runs/tick
Permission: permissionWorkspacesWrite

Manually triggers report run processing for the current workspace.

fetch("/api/reports/runs/tick", { method: "POST" });

Enable Tick #

Endpoint: POST /api/tick/enable
Permission: permissionWorkspacesWrite

Enables tick operations for a workspace (sets config.tick.disable = false).

fetch("/api/tick/enable", { method: "POST" });

Runner Operations #

Runners are background processes that handle various asynchronous tasks. You can trigger individual runners or all runners at once.

Run Individual Runner #

Endpoint: POST /api/internal/runner/{runner_id}/run
Permission: permissionWorkspacesWrite

Runs a specific runner with optional configuration.

Request Body:

{
  "options": {
    "messages_to_process": 100
  }
}

The options field is optional. If omitted, the runner will use default settings (typically processes 100 messages).

Available Runner IDs:

• calendar_events - Checks calendar events (mainly for meeting summaries)
• chat_summary_notes - Creates note summary from Slack messages
• conversation_note_analysis_processor - Analyzes conversations/notes for labels (action_items, task_issue_bug, etc.)
• needle_mover - Processes needle mover conversations/notes
• needle_mover_scheduler - Looks for conversations and notes to be processed for needle mover
• scheduled_meetings - Creates the meeting summary
• slack_message_delivery - Sends the meeting summary over Slack

Example:

fetch("/api/internal/runner/needle_mover/run", {
  method: "POST",
  body: JSON.stringify({
    options: {
      messages_to_process: 100,
    },
  }),
});

Reprocessing Operations #

These endpoints allow you to reprocess existing data, such as conversations, notes, and needle movers.

Reprocess Conversations and Notes (Reanalysis) #

Endpoint: POST /api/internal/labels/reanalysis
Permission: permissionWorkspacesWrite

Reprocesses conversations and/or notes within a time range for label analysis.

Query Parameters:

• from (int64, optional): Unix timestamp for the start of the time range. Defaults to 30 days ago.
• until (int64, optional): Unix timestamp for the end of the time range. Defaults to current time.
• type (string, optional): Type of entity to reprocess. Valid values: conversations, notes. If omitted, both are processed.

Response:

{
  "conversations_processed": 150,
  "notes_processed": 42
}

Example:

// Reprocess all conversations and notes from the last 7 days
const from = Math.floor(Date.now() / 1000) - 7 * 24 * 60 * 60;
fetch(`/api/internal/labels/reanalysis?from=${from}`, {
  method: "POST",
});

// Reprocess only conversations from a specific time range
const from = 1609459200; // Jan 1, 2021
const until = 1640995200; // Jan 1, 2022
fetch(
  `/api/internal/labels/reanalysis?from=${from}&until=${until}&type=conversations`,
  {
    method: "POST",
  }
);

Note: After calling this endpoint, you typically need to tick runners to process the queued items:

// Run this multiple times until all items are processed
fetch("/api/tick/runners", { method: "POST" });

Reprocess Needle Movers #

Endpoint: POST /api/v2/needle_movers/reprocess
Permission: permissionTasksWrite

Reprocesses needle movers based on content labels within a time range. This endpoint streams events using Server-Sent Events (SSE).

Query Parameters:

• from (int64, required): Unix timestamp for the start of the time range.
• until (int64, required): Unix timestamp for the end of the time range.

Example:

const from = Math.floor(Date.now() / 1000) - 30 * 24 * 60 * 60; // 30 days ago
const until = Math.floor(Date.now() / 1000); // now

const response = await fetch(
  `/api/v2/needle_movers/reprocess?from=${from}&until=${until}`,
  { method: "POST" }
);

// Handle SSE stream
const reader = response.body.getReader();
// ... process stream events

PubSub Operations #

PubSub is used for asynchronous message processing. You can manually publish messages to trigger various background processes.

Publish PubSub Message #

Endpoint: POST /api/internal/pubsub/publish
Permission: permissionWorkspacesWrite

Publishes a message to a PubSub topic, which will be processed by background workers.

Request Body:

{
  "topic": "conversation_note_analysis",
  "key": {
    "conversation_fs_id": "conv_123",
    "note_id": "note_456",
    "note_version": "v1"
  },
  "data": {},
  "deliver_after": "2024-01-01T00:00:00Z" // optional
}

Response:

{
  "id": "msg_789",
  "published": "2024-01-01T12:00:00Z"
}

Common Topics:

• conversation_note_analysis - Triggers analysis of conversations/notes for labels

Example:

// Publish a message to trigger conversation analysis
fetch("/api/internal/pubsub/publish", {
  method: "POST",
  body: JSON.stringify({
    topic: "conversation_note_analysis",
    key: {
      conversation_fs_id: "conv_abc123",
    },
    data: {},
  }),
});

Needle Mover Operations #

Refresh Needle Mover #

Endpoint: POST /api/v2/needle_movers/{id}/refresh
Permission: permissionWorkspacesWrite

Refreshes a specific needle mover, updating its impact and summaries.

Query Parameters:

• impact (bool, optional): Whether to refresh impact calculations. Default: false
• summaries (bool, optional): Whether to refresh summaries. Default: false

Example:

fetch("/api/v2/needle_movers/nm_123/refresh?impact=true&summaries=true", {
  method: "POST",
});

Purge Needle Movers #

Endpoint: POST /api/v2/needle_movers/purge
Permission: permissionWorkspacesWrite

Deletes needle movers within an optional time range.

Query Parameters:

• from (int64, optional): Unix timestamp. Only delete needle movers created after this time.
• until (int64, optional): Unix timestamp. Only delete needle movers created before this time.

Example:

// Delete all needle movers
fetch("/api/v2/needle_movers/purge", { method: "POST" });

// Delete needle movers created before a specific date
const until = 1609459200; // Jan 1, 2021
fetch(`/api/v2/needle_movers/purge?until=${until}`, { method: "POST" });

// Delete needle movers within a date range
const from = 1609459200;
const until = 1640995200;
fetch(`/api/v2/needle_movers/purge?from=${from}&until=${until}`, {
  method: "POST",
});

Process Needle Mover Actions #

Endpoint: POST /api/v2/needle_movers/{id}/actions/process
Permission: permissionTasksWrite

Processes actions for a specific needle mover.

Response:

{
  "action_ids": ["action_1", "action_2", "action_3"]
}

Example:

fetch("/api/v2/needle_movers/nm_123/actions/process", {
  method: "POST",
});

Match Needle Mover #

Endpoint: POST /api/internal/needle_movers/match
Permission: permissionWorkspacesWrite

Matches content to needle movers.

Example:

fetch("/api/internal/needle_movers/match", {
  method: "POST",
  body: JSON.stringify({
    // ... match parameters
  }),
});

Prediction Operations #

Train Prediction Model #

Endpoint: POST /api/internal/prediction/models/{model_type}/train
Permission: permissionWorkspacesWrite

Trains a prediction model of the specified type.

Example:

fetch("/api/internal/prediction/models/account/train", {
  method: "POST",
});

Update Prediction Scores #

Endpoint: POST /api/internal/prediction/scores/accounts/update
Permission: permissionWorkspacesWrite

Manually triggers update of prediction scores for accounts.

fetch("/api/internal/prediction/scores/accounts/update", {
  method: "POST",
});

Endpoint: POST /api/internal/prediction/scores/users/update
Permission: permissionWorkspacesWrite

Manually triggers update of prediction scores for users.

fetch("/api/internal/prediction/scores/users/update", {
  method: "POST",
});

Get Prediction Models #

Endpoint: GET /api/internal/prediction/models
Permission: permissionWorkspacesWrite

Retrieves all prediction models.

Endpoint: GET /api/internal/prediction/models/{model_type}
Permission: permissionWorkspacesWrite

Retrieves a specific prediction model.

Prediction Recall #

Endpoint: POST /api/internal/prediction/recall
Permission: permissionWorkspacesWrite

Triggers prediction recall calculation.

fetch("/api/internal/prediction/recall", {
  method: "POST",
});

Get Prediction Data #

Endpoint: GET /api/internal/conversations/prediction_data
Permission: permissionWorkspacesWrite

Retrieves prediction data for conversations.

Other Internal Operations #

Run AI Agent Workflow #

Endpoint: POST /api/internal/ai/agent/workflow/run
Permission: permissionWorkspacesWrite

Manually triggers an AI agent workflow run.

Run Flow #

Endpoint: POST /api/internal/flows/run
Permission: permissionWorkspacesWrite

Manually runs a flow with a given configuration.

Request Body:

{
  "config": {
    /* flow graph configuration */
  },
  "input": {
    /* input data */
  }
}

Queue Content Labels #

Endpoint: POST /api/internal/content_labels/queue
Permission: permissionWorkspacesWrite

Queues content labels for processing.

Analyze Content Labels #

Endpoint: POST /api/internal/content_labels/analyze
Permission: permissionWorkspacesWrite

Triggers analysis of content labels.

Process Task Labels #

Endpoint: POST /api/internal/tasks/process_labels
Permission: permissionWorkspacesWrite

Note: Added for testing. Remove after 10 Oct 2025.

Processes labels for tasks.

Delete Suggested Tasks #

Endpoint: DELETE /api/internal/tasks/suggested
Permission: permissionWorkspacesWrite

Deletes suggested tasks.

Delete Agent Threads #

Endpoint: DELETE /api/internal/agents/{agent_id}/threads
Permission: permissionWorkspacesWrite

Deletes threads for a specific agent.

Delete Completions #

Endpoint: DELETE /api/internal/completions
Permission: permissionWorkspacesWrite

Deletes completion records.

Expire OAuth Token #

Endpoint: POST /api/internal/oauth/tokens/{token_id}/expire
Permission: permissionWorkspacesWrite

Manually expires an OAuth token.

Common Workflows #

Reprocessing Conversations/Notes in Bulk #

1. Trigger reanalysis:

const from = Math.floor(Date.now() / 1000) - 30 * 24 * 60 * 60;
fetch(`/api/internal/labels/reanalysis?from=${from}`, {
  method: "POST",
});

2. Process the queue by repeatedly ticking runners:

async function processQueue() {
  for (let i = 0; i < 100; i++) {
    const response = await fetch("/api/tick/runners", { method: "POST" });
    if (!response.ok) {
      console.log(`Call ${i} failed: ${response.status}`);
    }
    await new Promise((resolve) => setTimeout(resolve, 1000)); // Wait 1 second between calls
  }
}
processQueue();

Reprocessing a Single Conversation #

1. Publish PubSub message:

fetch("/api/internal/pubsub/publish", {
  method: "POST",
  body: JSON.stringify({
    topic: "conversation_note_analysis",
    key: {
      conversation_fs_id: "conv_abc123",
    },
    data: {},
  }),
});

2. Tick runners to process:

fetch("/api/tick/runners", { method: "POST" });

Triggering All Runners for a Workspace #

fetch("/api/tick/runners", { method: "POST" });

This will trigger all registered runners. Check the response to see which runners were actually executed.

Notes #

• Most internal endpoints require permissionWorkspacesWrite permission
• Some operations are asynchronous and may take time to complete
• For bulk operations, consider rate limiting and monitoring system resources
• Always check response status codes and handle errors appropriately
• Some endpoints return SSE streams that need special handling
• Timestamps are typically Unix timestamps (seconds since epoch)