Recoup API Integration

Relevant source files

The following files were used as context for generating this wiki page:

• lib/recoup/fetchAccountTaskRuns.ts
• lib/recoup/fetchAdminSandboxOrgs.ts
• lib/recoup/fetchCodingPrStatus.ts
• lib/recoup/fetchContentSlackTags.ts
• lib/recoup/fetchSlackTags.ts
• hooks/useIsAdmin.ts
• types/coding-agent.ts

The Recoup API Integration module serves as the communication layer between the Recoup Admin dashboard and the backend services. It facilitates administrative operations including monitoring agent usage (Coding and Content agents), tracking sandbox organization activity, and managing background task runs. All communication is secured via Bearer authentication using Privy access tokens.

This integration is primarily used to populate administrative views with real-time data regarding user interactions on Slack, GitHub Pull Request statuses, and internal system tasks.
Sources: README.md:1-20, hooks/useIsAdmin.ts:10-25, lib/recoup/fetchSlackTags.ts:1-15

Authentication Architecture

The system utilizes a centralized authentication check to ensure only authorized administrators can access backend data. Authentication is handled via the usePrivy hook, which provides an access token that is subsequently passed into the Authorization header of every API request.

Admin Verification Flow

Before accessing protected administrative routes, the system verifies the user's role through a dedicated endpoint.

Agent Analytics Integrations

The dashboard integrates with specific endpoints to monitor the performance and usage of Recoup Agents. These integrations provide insights into Slack tags, associated Pull Requests, and content generation.

Coding Agent Slack Integration

This integration retrieves analytics regarding mentions of the Coding Agent on Slack. It supports filtering by time periods (daily, weekly, monthly, or all).

Endpoint	Method	Parameters	Description
/api/admins/coding/slack	GET	period	Fetches Slack tagging analytics including user prompts and channel info.
/api/admins/coding/pr	GET	pull_requests	Checks the status (open/closed/merged) for specific GitHub PR URLs.

Sources: lib/recoup/fetchSlackTags.ts:15-25, lib/recoup/fetchCodingPrStatus.ts:16-30, types/coding-agent.ts:1-25

Content Agent Integration

Similar to the Coding Agent, the Content Agent integration tracks Slack tags but focuses on video links generated by the agent.

System Monitoring & Task Management

The integration provides granular visibility into the background processes and organizational health of the platform.

Task Run Monitoring

Admin users can fetch specific task runs associated with an account ID. This is heavily used for monitoring "Pulse" email tasks.

• Endpoint: /api/tasks/runs
• Filter: account_id
• Polling: The dashboard implements a 10-second refetch interval to provide near real-time updates.

Sources: hooks/useAccountTaskRuns.ts:10-23, lib/recoup/fetchAccountTaskRuns.ts:12-25

Sandbox Organization Statistics

This integration tracks commit activity across organization sub-modules. The data is typically ordered by total commits in descending order.

// Example of the fetching logic for Sandbox Orgs
export async function fetchAdminSandboxOrgs(accessToken: string): Promise<OrgRepoRow[]> {
  const res = await fetch(`${API_BASE_URL}/api/admins/sandboxes/orgs`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  // ... error handling ...
  const data = await res.json();
  return data.repos ?? [];
}

Sources: lib/recoup/fetchAdminSandboxOrgs.ts:11-26, components/SandboxOrgs/SandboxOrgsPage.tsx:10-20

Data Models

The following table describes the primary data structures returned by the Recoup API for agent monitoring:

Field	Type	Description
user_name	string	Name of the user who tagged the agent on Slack.
prompt	string	The specific text prompt sent to the agent.
pull_requests	string[]	Array of GitHub URLs associated with a specific Slack tag.
status	string	Current state of a PR (open, closed, merged).
timestamp	string	ISO string of when the event occurred.

Sources: types/coding-agent.ts:1-32

Summary

The Recoup API Integration provides a unified interface for the Admin dashboard to interact with backend services. By leveraging Privy-based authentication and standardized fetch utilities across several domains—Agents, Sandboxes, and Tasks—the system ensures that administrators have accurate, authenticated, and filtered access to the platform's operational data.