Pulse Server API Guide

Overview

This guide explains how to use the exposed API endpoints in the Pulse Server. The server provides REST endpoints for repository analysis, issue summarization, and AI-powered insights powered by OpenRouter.

Base URL

http://localhost:3000

Authentication

Currently, authentication is handled via GitHub token in the backend environment (.env.local). No client-side authentication is required for API calls.

Endpoints

1. Health Check

Check if the server is running and healthy.

Endpoint: GET /health

Response:

{
  "status": "ok",
  "timestamp": "2025-11-06T12:34:56.789Z"
}

Example:

curl http://localhost:3000/health

2. Root/Welcome

Get server information and welcome message.

Endpoint: GET /

Response:

{
  "message": "Welcome to Pulse Server",
  "version": "1.0.0",
  "endpoints": {
    "health": "/health",
    "api": "/api",
    "enrichment": "/api/enrichment"
  }
}

3. API Information

Get list of all available API routes.

Endpoint: GET /api

Response:

{
  "message": "Pulse Server API",
  "availableRoutes": [
    "/ai/llm - AI Chat endpoint",
    "/ai/models - Get available AI models",
    "/enrichment - Repository enrichment (analyze, summarize issues)",
    "/github - GitHub data endpoints"
  ]
}

4. Repository Enrichment (Primary Endpoint)

Analyze repositories or summarize issues using AI. This is the main endpoint for the frontend.

Endpoint: POST /api/enrichment

Required Parameters:

Field	Type	Description
`owner`	string	GitHub repository owner username
`name`	string	GitHub repository name
`scope`	string	Scope of analysis (currently only `"repo"` supported)
`task`	string	Task to perform: `"analyze"` or `"summarize-issues"`
`question`	string	(Optional) Custom question for analyze task. If not provided, uses default analysis

Task: `analyze`

Fetch GitHub repository data and provide AI analysis with insights.

Request Example:

curl -X POST http://localhost:3000/api/enrichment \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "octocat",
    "name": "Hello-World",
    "scope": "repo",
    "task": "analyze",
    "question": "What is the code quality of this repository?"
  }'

Response:

{
  "success": true,
  "data": {
    "repository": {
      "name": "Hello-World",
      "owner": "octocat",
      "url": "https://github.com/octocat/Hello-World",
      "stars": 2023,
      "language": "Python"
    },
    "analysis": "Based on the repository data...",
    "metadata": {
      "totalIssues": 42,
      "lastUpdated": "2025-11-06T10:00:00Z"
    }
  }
}

What Happens:

Fetches repository details from GitHub (stars, forks, language, description, etc.)
Fetches recent issues for context
Sends combined data to OpenRouter AI for analysis
Returns AI-generated insights

Task: `summarize-issues`

Fetch and summarize repository issues with AI analysis.

Request Example:

curl -X POST http://localhost:3000/api/enrichment \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "octocat",
    "name": "Hello-World",
    "scope": "repo",
    "task": "summarize-issues"
  }'

Response:

{
  "success": true,
  "data": {
    "repository": "octocat/Hello-World",
    "totalIssues": 156,
    "analyzedIssues": 10,
    "summary": "The repository has various issues across categories...",
    "issues": [
      {
        "number": 123,
        "title": "Bug: Login fails on Safari",
        "state": "OPEN",
        "author": "developer1",
        "labels": ["bug", "priority-high"]
      },
      ...
    ]
  }
}

What Happens:

Fetches up to 10 most recent issues from the repository
Sends issues to OpenRouter AI for analysis
AI identifies themes, patterns, and priority areas
Returns summary with individual issue details

5. AI Chat Endpoint

Direct access to AI chat completions.

Endpoint: POST /api/ai/llm

Parameters:

Field	Type	Description
`message`	string	Your message to the AI
`model`	string	(Optional) AI model to use. Defaults to `deepseek/deepseek-chat-v3.1:free`

Request Example:

curl -X POST http://localhost:3000/api/ai/llm \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explain what DevOps is in simple terms"
  }'

Response:

{
  "success": true,
  "data": {
    "role": "assistant",
    "content": "DevOps is a set of practices that combines software development..."
  },
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

6. Available AI Models

Get list of available AI models from OpenRouter.

Endpoint: GET /api/ai/models

Response:

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "anthropic/claude-3-haiku",
        "name": "Claude 3 Haiku",
        "pricing": {...}
      },
      {
        "id": "deepseek/deepseek-chat-v3.1:free",
        "name": "DeepSeek Chat v3.1 (Free)",
        "pricing": {...}
      },
      ...
    ]
  }
}

7. GitHub Data Endpoints

Access raw GitHub data without AI enrichment.

Endpoint: POST /api/github/repository

Get repository details.

Request:

curl -X POST http://localhost:3000/api/github/repository \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "octocat",
    "name": "Hello-World"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "description": "Example repository",
    "url": "https://github.com/octocat/Hello-World",
    "stargazerCount": 2023,
    "forkCount": 523,
    "createdAt": "2011-01-26T19:01:12Z",
    "updatedAt": "2025-11-06T10:00:00Z",
    "primaryLanguage": {
      "name": "Python",
      "color": "#3572A5"
    }
  }
}

Usage Examples

JavaScript/Fetch

// Analyze a repository
async function analyzeRepository(owner, name, question) {
  const response = await fetch("http://localhost:3000/api/enrichment", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      owner,
      name,
      scope: "repo",
      task: "analyze",
      question,
    }),
  });

  const data = await response.json();
  return data;
}

// Usage
const result = await analyzeRepository(
  "octocat",
  "Hello-World",
  "What is the overall health of this repository?"
);
console.log(result.data.analysis);

// Summarize issues
async function summarizeIssues(owner, name) {
  const response = await fetch("http://localhost:3000/api/enrichment", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      owner,
      name,
      scope: "repo",
      task: "summarize-issues",
    }),
  });

  const data = await response.json();
  return data;
}

// Usage
const result = await summarizeIssues("octocat", "Hello-World");
console.log(result.data.summary);

PowerShell

# Analyze repository
$body = @{
  owner = "octocat"
  name = "Hello-World"
  scope = "repo"
  task = "analyze"
  question = "What programming language is this repository built with?"
} | ConvertTo-Json

$response = Invoke-WebRequest -Uri "http://localhost:3000/api/enrichment" `
  -Method POST `
  -Headers @{'Content-Type'='application/json'} `
  -Body $body

$response.Content | ConvertFrom-Json

Python

import requests

def analyze_repository(owner, name, question=None):
    payload = {
        "owner": owner,
        "name": name,
        "scope": "repo",
        "task": "analyze",
        "question": question
    }

    response = requests.post(
        'http://localhost:3000/api/enrichment',
        json=payload,
        headers={'Content-Type': 'application/json'}
    )

    return response.json()

# Usage
result = analyze_repository('octocat', 'Hello-World', 'Is this a well-maintained repository?')
print(result['data']['analysis'])

Error Handling

All endpoints return error responses in this format:

{
  "success": false,
  "error": "Description of the error"
}

Common Error Codes

Status	Error	Cause
400	Missing required fields	owner, name, scope, or task not provided
400	Unknown task	task value not recognized
400	Repository not found	GitHub repository doesn't exist
401	GitHub token not configured	GITHUB_API_TOKEN env var missing
500	AI analysis failed	OpenRouter API error
500	Internal server error	Server-side error

Logging

All API requests are logged with timestamps and request details. Enable debug logging by setting LOG_LEVEL=debug in .env.local:

LOG_LEVEL=debug

Check the server console for:

✅ [INFO] - Successful operations
⚠️ [WARN] - Warnings (e.g., issue fetch failed but continuing)
❌ [ERROR] - Errors with details
🔧 [DEBUG] - Detailed debugging info (dev mode only)

Environment Configuration

Ensure these are set in .env.local:

# Server
PORT=3000
NODE_ENV=development

# GitHub
GITHUB_API_TOKEN=your_github_token_here
GITHUB_GRAPHQL_API_BASE_URL=https://api.github.com/graphql

# OpenRouter AI
OPENROUTER_API_KEY=your_openrouter_key_here
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
DEFAULT_AI_MODEL=deepseek/deepseek-chat-v3.1:free

Rate Limiting

GitHub API: ~5000 requests/hour (handled by GitHub token)
OpenRouter AI: Depends on your plan
Server rate limiting: 100 requests per 15 minutes per IP

Tips & Best Practices

✅ DO:

Always provide owner, name, scope, and task
Use specific questions for better analyze results
Cache results to reduce API calls
Check success field before accessing data

❌ DON'T:

Make requests without proper error handling
Ignore the error field in responses
Send the same request multiple times immediately
Store sensitive data in response logs

Support

For issues or questions about the API:

Check the server logs for detailed error messages
Verify GitHub and OpenRouter credentials in .env.local
Test endpoints with curl or Postman first
Review this guide for correct payload structure

Version History

Version	Date	Changes
1.0.0	2025-11-06	Initial release with unified enrichment endpoint

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Pulse Server API Guide

Overview

Base URL

Authentication

Endpoints

1. Health Check

2. Root/Welcome

3. API Information

4. Repository Enrichment (Primary Endpoint)

Task: `analyze`

Task: `summarize-issues`

5. AI Chat Endpoint

6. Available AI Models

7. GitHub Data Endpoints

Usage Examples

JavaScript/Fetch

PowerShell

Python

Error Handling

Common Error Codes

Logging

Environment Configuration

Rate Limiting

Tips & Best Practices

Support

Version History

FilesExpand file tree

API_GUIDE.md

Latest commit

History

API_GUIDE.md

File metadata and controls

Pulse Server API Guide

Overview

Base URL

Authentication

Endpoints

1. Health Check

2. Root/Welcome

3. API Information

4. Repository Enrichment (Primary Endpoint)

Task: analyze

Task: summarize-issues

5. AI Chat Endpoint

6. Available AI Models

7. GitHub Data Endpoints

Usage Examples

JavaScript/Fetch

PowerShell

Python

Error Handling

Common Error Codes

Logging

Environment Configuration

Rate Limiting

Tips & Best Practices

Support

Version History

Task: `analyze`

Task: `summarize-issues`