tribecode API Usage Guide

Learn how to use the TRIBE API to generate insights and integrate with your development workflow.

ℹ️

Beta Feature

The TRIBE API is currently in beta. While our insights dashboard is being perfected, you can use these API endpoints to generate custom insights.

📦

Sample Code Repository

Get complete working examples, integration templates, and ready-to-use code snippets from our official repository.

View on GitHub

Authentication

All TRIBE API requests require authentication via session cookies or API tokens. Make sure you're logged into the dashboard or have a valid API token.

Generate Insights

Basic Insight Generation

Generate a basic insight from your telemetry data:

Click to copy

curl -X POST "https://tribecode.ai/api/onboarding/generate-insight" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{}'

Custom Insight Parameters

You can customize insight generation with various parameters:

Click to copy

curl -X POST "https://tribecode.ai/api/onboarding/generate-insight" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "timeframe": "7d",
    "focus": "productivity",
    "include_recommendations": true,
    "format": "detailed"
  }'

Available Parameters

timeframe - Time period for analysis (1d, 7d, 30d)
focus - Analysis focus (productivity, patterns, optimization)
include_recommendations - Include actionable recommendations
format - Response format (summary, detailed, technical)

Retrieve Insights

List All Insights

Click to copy

curl -X GET "https://tribecode.ai/api/data/insights" \
  -H "Cookie: your-session-cookie"

Get Specific Insight

Click to copy

curl -X GET "https://tribecode.ai/api/data/insights/{insight_id}" \
  -H "Cookie: your-session-cookie"

JavaScript/TypeScript Integration

Using Fetch API

Click to copy

// Generate a new insight
async function generateInsight(params = {}) {
  const response = await fetch('/api/onboarding/generate-insight', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    credentials: 'include', // Include session cookies
    body: JSON.stringify(params),
  });

  if (!response.ok) {
    throw new Error('Failed to generate insight');
  }

  return response.json();
}

// Retrieve insights
async function getInsights() {
  const response = await fetch('/api/data/insights', {
    credentials: 'include',
  });

  if (!response.ok) {
    throw new Error('Failed to fetch insights');
  }

  return response.json();
}

// Example usage
try {
  const insight = await generateInsight({
    timeframe: '7d',
    focus: 'productivity',
    include_recommendations: true
  });
  console.log('Generated insight:', insight);
} catch (error) {
  console.error('Error:', error);
}

Response Formats

Insight Generation Response

Click to copy

{
  "success": true,
  "insight": {
    "id": "insight_123",
    "recommendation": "# Productivity Insight\n\nBased on your activity...",
    "provider": "kimi",
    "created_at": "2024-10-10T12:00:00Z",
    "source_metadata": {
      "topics": ["productivity", "code-quality"],
      "event_count": 1250,
      "scored_events": 95
    }
  },
  "redirectUrl": "/tribe/insights?highlight=insight_123"
}

Insights List Response

Click to copy

{
  "insights": [
    {
      "id": "insight_123",
      "user_id": "user_456",
      "recommendation": "# Your Weekly Coding Patterns\n\n...",
      "source_metadata": "{\"topics\": [...], \"event_count\": 1250}",
      "provider": "kimi",
      "created_at": "2024-10-10T12:00:00Z",
      "is_read": false
    }
  ],
  "hasTable": true,
  "unreadCount": 3
}

Error Handling

Common Error Responses

NO_EVENTS_FOUND - Insufficient telemetry data for insight generation
RATE_LIMITED - Too many requests, please wait before retrying
UNAUTHORIZED - Authentication required
INSIGHT_GENERATION_FAILED - AI provider error

Click to copy

{
  "success": false,
  "error": "NO_EVENTS_FOUND",
  "message": "No events found for insight generation. Please use Claude Code for a few days to build up telemetry data.",
  "code": "NO_EVENTS_FOUND"
}

Integration Examples

React Hook

Click to copy

import { useState, useCallback } from 'react';

export function useInsights() {
  const [loading, setLoading] = useState(false);
  const [insights, setInsights] = useState([]);

  const generateInsight = useCallback(async (params = {}) => {
    setLoading(true);
    try {
      const response = await fetch('/api/onboarding/generate-insight', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        credentials: 'include',
        body: JSON.stringify(params),
      });

      const data = await response.json();

      if (response.ok) {
        // Refresh insights list
        await fetchInsights();
        return data.insight;
      } else {
        throw new Error(data.message || 'Generation failed');
      }
    } finally {
      setLoading(false);
    }
  }, []);

  const fetchInsights = useCallback(async () => {
    const response = await fetch('/api/data/insights', {
      credentials: 'include',
    });

    if (response.ok) {
      const data = await response.json();
      setInsights(data.insights || []);
    }
  }, []);

  return {
    insights,
    loading,
    generateInsight,
    fetchInsights,
  };
}

CLI Integration

You can also integrate insight generation into your CLI workflows:

Click to copy

#!/bin/bash
# generate-weekly-insight.sh

COOKIE_FILE="~/.tribe-session"
API_BASE="https://tribecode.ai"

# Generate insight
curl -X POST "$API_BASE/api/onboarding/generate-insight" \
  -H "Content-Type: application/json" \
  -b "$COOKIE_FILE" \
  -d '{
    "timeframe": "7d",
    "focus": "productivity",
    "format": "summary"
  }' | jq '.insight.recommendation' -r

echo "Insight generated! View at: $API_BASE/tribe/insights"

Best Practices

Rate Limiting: Don't generate insights more than once per hour to avoid rate limits
Error Handling: Always handle NO_EVENTS_FOUND errors gracefully
Caching: Cache insights locally to reduce API calls
Authentication: Keep session cookies secure and refresh them regularly
Monitoring: Monitor API response times and success rates

Support

If you encounter issues with the TRIBE API or need additional endpoints, please reach out through our support channels. The API is actively being developed and new features are added regularly.

💡

Tip

The insights generated through the API are also visible in the dashboard. Use the API for automation and the dashboard for interactive exploration.

tribecode API Usage Guide

Learn how to use the TRIBE API to generate insights and integrate with your development workflow.

ℹ️

Beta Feature

The TRIBE API is currently in beta. While our insights dashboard is being perfected, you can use these API endpoints to generate custom insights.

📦

Sample Code Repository

Get complete working examples, integration templates, and ready-to-use code snippets from our official repository.

View on GitHub

Authentication

All TRIBE API requests require authentication via session cookies or API tokens. Make sure you're logged into the dashboard or have a valid API token.

Generate Insights

Basic Insight Generation

Generate a basic insight from your telemetry data:

Click to copy

curl -X POST "https://tribecode.ai/api/onboarding/generate-insight" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{}'

Custom Insight Parameters

You can customize insight generation with various parameters:

Click to copy

curl -X POST "https://tribecode.ai/api/onboarding/generate-insight" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "timeframe": "7d",
    "focus": "productivity",
    "include_recommendations": true,
    "format": "detailed"
  }'

Available Parameters

timeframe - Time period for analysis (1d, 7d, 30d)
focus - Analysis focus (productivity, patterns, optimization)
include_recommendations - Include actionable recommendations
format - Response format (summary, detailed, technical)

Retrieve Insights

List All Insights

Click to copy

curl -X GET "https://tribecode.ai/api/data/insights" \
  -H "Cookie: your-session-cookie"

Get Specific Insight

Click to copy

curl -X GET "https://tribecode.ai/api/data/insights/{insight_id}" \
  -H "Cookie: your-session-cookie"

JavaScript/TypeScript Integration

Using Fetch API

Click to copy

// Generate a new insight
async function generateInsight(params = {}) {
  const response = await fetch('/api/onboarding/generate-insight', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    credentials: 'include', // Include session cookies
    body: JSON.stringify(params),
  });

  if (!response.ok) {
    throw new Error('Failed to generate insight');
  }

  return response.json();
}

// Retrieve insights
async function getInsights() {
  const response = await fetch('/api/data/insights', {
    credentials: 'include',
  });

  if (!response.ok) {
    throw new Error('Failed to fetch insights');
  }

  return response.json();
}

// Example usage
try {
  const insight = await generateInsight({
    timeframe: '7d',
    focus: 'productivity',
    include_recommendations: true
  });
  console.log('Generated insight:', insight);
} catch (error) {
  console.error('Error:', error);
}

Response Formats

Insight Generation Response

Click to copy

{
  "success": true,
  "insight": {
    "id": "insight_123",
    "recommendation": "# Productivity Insight\n\nBased on your activity...",
    "provider": "kimi",
    "created_at": "2024-10-10T12:00:00Z",
    "source_metadata": {
      "topics": ["productivity", "code-quality"],
      "event_count": 1250,
      "scored_events": 95
    }
  },
  "redirectUrl": "/tribe/insights?highlight=insight_123"
}

Insights List Response

Click to copy

{
  "insights": [
    {
      "id": "insight_123",
      "user_id": "user_456",
      "recommendation": "# Your Weekly Coding Patterns\n\n...",
      "source_metadata": "{\"topics\": [...], \"event_count\": 1250}",
      "provider": "kimi",
      "created_at": "2024-10-10T12:00:00Z",
      "is_read": false
    }
  ],
  "hasTable": true,
  "unreadCount": 3
}

Error Handling

Common Error Responses

NO_EVENTS_FOUND - Insufficient telemetry data for insight generation
RATE_LIMITED - Too many requests, please wait before retrying
UNAUTHORIZED - Authentication required
INSIGHT_GENERATION_FAILED - AI provider error

Click to copy

{
  "success": false,
  "error": "NO_EVENTS_FOUND",
  "message": "No events found for insight generation. Please use Claude Code for a few days to build up telemetry data.",
  "code": "NO_EVENTS_FOUND"
}

Integration Examples

React Hook

Click to copy

import { useState, useCallback } from 'react';

export function useInsights() {
  const [loading, setLoading] = useState(false);
  const [insights, setInsights] = useState([]);

  const generateInsight = useCallback(async (params = {}) => {
    setLoading(true);
    try {
      const response = await fetch('/api/onboarding/generate-insight', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        credentials: 'include',
        body: JSON.stringify(params),
      });

      const data = await response.json();

      if (response.ok) {
        // Refresh insights list
        await fetchInsights();
        return data.insight;
      } else {
        throw new Error(data.message || 'Generation failed');
      }
    } finally {
      setLoading(false);
    }
  }, []);

  const fetchInsights = useCallback(async () => {
    const response = await fetch('/api/data/insights', {
      credentials: 'include',
    });

    if (response.ok) {
      const data = await response.json();
      setInsights(data.insights || []);
    }
  }, []);

  return {
    insights,
    loading,
    generateInsight,
    fetchInsights,
  };
}

CLI Integration

You can also integrate insight generation into your CLI workflows:

Click to copy

#!/bin/bash
# generate-weekly-insight.sh

COOKIE_FILE="~/.tribe-session"
API_BASE="https://tribecode.ai"

# Generate insight
curl -X POST "$API_BASE/api/onboarding/generate-insight" \
  -H "Content-Type: application/json" \
  -b "$COOKIE_FILE" \
  -d '{
    "timeframe": "7d",
    "focus": "productivity",
    "format": "summary"
  }' | jq '.insight.recommendation' -r

echo "Insight generated! View at: $API_BASE/tribe/insights"

Best Practices

Rate Limiting: Don't generate insights more than once per hour to avoid rate limits
Error Handling: Always handle NO_EVENTS_FOUND errors gracefully
Caching: Cache insights locally to reduce API calls
Authentication: Keep session cookies secure and refresh them regularly
Monitoring: Monitor API response times and success rates

Support

If you encounter issues with the TRIBE API or need additional endpoints, please reach out through our support channels. The API is actively being developed and new features are added regularly.

💡

Tip

The insights generated through the API are also visible in the dashboard. Use the API for automation and the dashboard for interactive exploration.