Sessions API

Real-time streaming scans with live results as each tool completes.

Watch Results Stream In Live

The Sessions API is our new streaming experience. Instead of waiting 2-5 minutes for all 150 modules to finish, you see each tool's results the moment it completes.

❌ Old Way (Scans API)
  • • Start scan, wait 2-5 minutes
  • • Get all results at once
  • • No visibility into progress
✓ New Way (Sessions API)
  • • Results appear immediately as tools finish
  • • Real-time progress (23/150 modules done)
  • • Automatic credit refunds for failed tools

🎯 Not a Developer? Start Here

Copy these prompts into Claude, ChatGPT, Cursor, or any AI assistant. Your AI will build what you need.

Step 1: Copy a prompt below
Step 2: Paste into your AI assistant
Step 3: AI builds it for you

Quick Start Prompts

Common real-time scanning tasks you can accomplish with a single prompt.

📊 Build a Live Scan Dashboard

Watch results stream in real-time with a beautiful progress UI.

Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions

Build a live scan progress dashboard:

1. Start session: POST /api/sessions with target
2. Show session status and live progress bar
3. Poll /api/sessions/{sessionId}?progress=true every 2 seconds
4. Display: "23/150 tools complete (32%)"
5. As tools complete, add their results to a live list:
   - Tool name, duration, issue count
   - Color-code by severity (red=critical, orange=high, etc.)
6. When status is "completed", show final summary
7. If any tools failed, show refund credits received

Use smooth animations for new results appearing.
My stack: [YOUR_STACK]
👩‍💻 Technical Details (for developers)

Polling Flow

// 1. Start session
const response = await fetch('/api/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    target: { url: 'https://myapp.com' },
    categories: ['security', 'code-quality']
  })
});
const { sessionId } = await response.json();

// 2. Poll for progress (lightweight)
const poll = async () => {
  const res = await fetch(`/api/sessions/${sessionId}?progress=true`);
  const { status, progress } = await res.json();

  console.log(`${progress.completed}/${progress.total} (${progress.percentage}%)`);

  if (status !== 'completed') {
    setTimeout(poll, 2000);
  }
};
poll();

🔄 Get Only New Results (Efficient Polling)

Only fetch results that came in since your last poll - minimal bandwidth.

Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions

Build an efficient real-time results feed:

1. Start session: POST /api/sessions
2. Store the current timestamp
3. Every 2 seconds, call GET /api/sessions/{sessionId}?since={timestamp}
4. This returns ONLY tool reports added since that timestamp
5. Append new reports to your results list
6. Update timestamp to now for next poll
7. Stop polling when status is "completed"

This is much more efficient than fetching the full report each time.
My stack: [YOUR_STACK]
👩‍💻 Technical Details (for developers)

Incremental Polling

let lastPoll = new Date().toISOString();
const allReports = [];

const pollForNewReports = async (sessionId) => {
  const res = await fetch(
    `/api/sessions/${sessionId}?since=${encodeURIComponent(lastPoll)}`
  );
  const { newReports, status } = await res.json();

  // Add new reports to our list
  allReports.push(...newReports);
  lastPoll = new Date().toISOString();

  // Show new reports
  newReports.forEach(report => {
    console.log(`✓ ${report.toolName}: ${report.findingsCount} findings`);
  });

  if (status !== 'completed') {
    setTimeout(() => pollForNewReports(sessionId), 2000);
  }
};

🚀 CI/CD with Live Console Output

Show scan progress in your CI/CD logs as each tool completes.

Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions

Create a CI/CD script with live console output:

1. Start session: POST /api/sessions
2. Print "[SCAN] Starting security scan..."
3. Poll every 5 seconds
4. As each tool completes, print:
   "[45/150] ✓ eslint-security: 3 findings (0.8s)"
   "[45/150] ✓ semgrep: 1 critical, 2 high (2.3s)"
5. If a tool fails, print warning but continue
6. When done, print summary table:
   - Total findings by severity
   - Credits refunded for failed tools
7. Exit code 1 if critical > 0 or high > 5

Use ANSI colors for pretty console output.
My stack: [YOUR_STACK]

⚛️ React Hook for Live Sessions

A custom React hook that manages the whole polling lifecycle.

Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions

Create a useSessionPolling React hook:

const { session, progress, isComplete, error, startSession } = useSessionPolling();

Features:
1. startSession(target) - starts a new session
2. Automatically polls for progress every 2 seconds
3. Stops polling when complete
4. Returns:
   - session: full session data
   - progress: { completed, total, percentage }
   - isComplete: boolean
   - error: any error that occurred
5. Cleanup: stops polling when component unmounts

Use React Query or SWR for caching.
My stack: React with TypeScript
👩‍💻 Technical Details (for developers)

Example Implementation

import { useState, useEffect, useCallback } from 'react';

export function useSessionPolling(options = {}) {
  const { pollInterval = 2000, autoStart = false } = options;

  const [sessionId, setSessionId] = useState(null);
  const [session, setSession] = useState(null);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState(null);

  const startSession = useCallback(async (target) => {
    setIsLoading(true);
    try {
      const res = await fetch('/api/sessions', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ target })
      });
      const data = await res.json();
      setSessionId(data.sessionId);
    } catch (err) {
      setError(err);
    }
  }, []);

  useEffect(() => {
    if (!sessionId) return;

    const poll = async () => {
      const res = await fetch(`/api/sessions/${sessionId}`);
      const data = await res.json();
      setSession(data);
      setIsLoading(false);

      if (data.status !== 'completed') {
        setTimeout(poll, pollInterval);
      }
    };
    poll();
  }, [sessionId, pollInterval]);

  return {
    session,
    progress: session?.progress,
    isComplete: session?.status === 'completed',
    isLoading,
    error,
    startSession
  };
}

Start a Session

Start a Streaming Audit

Begin a new scan session. Results stream in as each tool completes.

Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions

Add a streaming scan to my app:

1. POST to /api/sessions with:
   - target: { url: "https://myapp.com" } or { directory: "/path/to/code" }
   - categories: ['security', 'code-quality'] (optional)
   - enableIntelligence: true (for AI-powered analysis)
2. Returns sessionId immediately
3. Poll /api/sessions/{sessionId} for live results
4. Show results as they come in

Handle 402 error for insufficient credits.
My stack: [YOUR_STACK]
👩‍💻 Technical Reference
POST/api/sessions

Start a new streaming audit session. Returns immediately with session ID and polling URLs.

Request Body

FieldTypeRequiredDescription
targetobjectYesWhat to scan (see below)
target.urlstring*Live URL to scan
target.urlsstring[]*Multiple URLs to scan
target.directorystring*Local directory path
categoriesstring[]Nosecurity, code-quality, accessibility, performance
toolsstring[]NoSpecific tools to run (overrides categories)
excludeToolsstring[]NoTools to skip
enableIntelligencebooleanNoGenerate AI analysis (default: true)
timeoutnumberNoMax ms per tool (default: 300000)
maxConcurrentnumberNoParallel tools (default: 5)

* One of url, urls, or directory is required

Example Request

curl -X POST https://bugrit.com/api/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": {
      "url": "https://myapp.com"
    },
    "categories": ["security", "code-quality"],
    "enableIntelligence": true
  }'

Response (202 Accepted)

{
  "sessionId": "sess-abc123xyz",
  "scanId": "scan-1705834200-a1b2c3",
  "status": "started",
  "message": "Audit session started. Poll /api/sessions/{sessionId} for real-time updates.",
  "pollUrls": {
    "full": "/api/sessions/sess-abc123xyz",
    "progress": "/api/sessions/sess-abc123xyz?progress=true",
    "newReports": "/api/sessions/sess-abc123xyz?since={timestamp}"
  }
}

Poll Session

Get Real-Time Results

Poll for live updates. Three modes: full report, progress only, or incremental.

Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions

Build a polling system with three modes:

1. Progress only (lightweight):
   GET /api/sessions/{id}?progress=true
   → Returns just { status, progress: { completed, total, percentage } }
   → Use for progress bars, minimal bandwidth

2. Incremental updates:
   GET /api/sessions/{id}?since={ISO_timestamp}
   → Returns only NEW tool reports since that time
   → Most efficient for live feeds

3. Full report:
   GET /api/sessions/{id}
   → Returns everything including all tool reports
   → Use when you need the complete picture

Start with progress-only, switch to incremental for results.
My stack: [YOUR_STACK]
👩‍💻 Technical Details (for developers)
GET/api/sessions/:sessionId

Query Parameters

ParameterTypeDescription
progressbooleanIf true, returns only status and progress counts
sinceISO timestampReturns only reports added after this time

Full Response

{
  "sessionId": "sess-abc123xyz",
  "userId": "user-123",
  "status": "running",
  "progress": {
    "total": 150,
    "completed": 23,
    "failed": 1,
    "skipped": 2,
    "running": 5,
    "pending": 40,
    "percentage": 32
  },
  "toolReports": {
    "eslint-security": {
      "toolName": "eslint-security",
      "category": "security",
      "status": "completed",
      "duration": 1234,
      "findingsCount": 3,
      "result": { ... },
      "completedAt": "2026-01-22T10:30:15Z"
    },
    "semgrep": {
      "toolName": "semgrep",
      "category": "security",
      "status": "completed",
      "duration": 2567,
      "findingsCount": 5,
      "result": { ... },
      "completedAt": "2026-01-22T10:30:18Z"
    }
  },
  "summary": {
    "totalFindings": 8,
    "bySeverity": {
      "critical": 1,
      "high": 2,
      "medium": 3,
      "low": 2
    },
    "byCategory": {
      "security": 5,
      "code-quality": 3
    },
    "toolsRun": 23,
    "toolsSkipped": 2,
    "toolsFailed": 1
  },
  "lastUpdated": "2026-01-22T10:30:18Z"
}

Progress-Only Response

{
  "sessionId": "sess-abc123xyz",
  "status": "running",
  "progress": {
    "total": 150,
    "completed": 23,
    "failed": 1,
    "skipped": 2,
    "running": 5,
    "pending": 40,
    "percentage": 32
  },
  "lastUpdated": "2026-01-22T10:30:18Z"
}

Incremental Response

{
  "sessionId": "sess-abc123xyz",
  "status": "running",
  "progress": { ... },
  "newReports": [
    {
      "toolName": "trivy",
      "category": "security",
      "status": "completed",
      "duration": 1890,
      "findingsCount": 2,
      "result": { ... },
      "completedAt": "2026-01-22T10:30:20Z"
    }
  ],
  "lastUpdated": "2026-01-22T10:30:20Z"
}

List Sessions

View Session History

Get a list of your recent scan sessions.

Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions

Create a session history component:

1. Fetch GET /api/sessions?limit=20
2. Display as table:
   - Created date
   - Status badge (running=blue, completed=green, failed=red)
   - Progress (45/150 tools)
   - Issue summary (2 critical, 5 high)
3. Click row to view full session
4. Running sessions: show progress bar + live badge

My stack: [YOUR_STACK]
👩‍💻 Technical Details (for developers)
GET/api/sessions

Query Parameters

ParameterTypeDescription
limitintegerMax results (default: 20)

Response

{
  "sessions": [
    {
      "sessionId": "sess-abc123xyz",
      "status": "completed",
      "progress": { "total": 150, "completed": 150, "percentage": 100 },
      "createdAt": "2026-01-22T10:25:00Z",
      "completedAt": "2026-01-22T10:30:47Z"
    }
  ],
  "total": 1
}

Automatic Credit Refunds

💰 You Only Pay for Results

If a tool fails, times out, or gets skipped, you automatically get those credits back. Check the refund field in your completed session.

// In your completed session response:
{
  "status": "completed",
  "refund": {
    "refundedCredits": 150,
    "toolsRefunded": ["tool-that-failed", "tool-that-timed-out"],
    "newBalance": 4850
  }
}

Session Status Values

StatusDescription
initializingSession created, modules being prepared
runningModules actively running, results streaming in
completedAll modules finished successfully
partialCompleted with some modules failed/skipped
failedSession failed (check error field)

Tool Report Status Values

StatusDescription
pendingTool queued, waiting to run
runningTool currently executing
completedTool finished with results
failedTool encountered an error (credits refunded)
skippedTool skipped (circuit breaker open, etc.)

Migrating from Scans API

Upgrade Your Integration

Switch from the old Scans API to the new Sessions API.

Read the Bugrit Sessions API at https://bugrit.com/docs/api-reference/sessions

Migrate my existing scan integration to use Sessions:

Old code uses:
- POST /api/v1/scans to start
- GET /api/v1/scans/{id} to poll

Change to:
- POST /api/sessions to start (note: different request body)
- GET /api/sessions/{id}?progress=true for quick polls
- GET /api/sessions/{id}?since={timestamp} for incremental results

Key differences:
1. Request body uses "target" object instead of flat fields
2. Response has "sessionId" not "scanId"
3. Real-time progress available immediately
4. Automatic credit refunds for failures

Keep backward compatibility if needed.
My stack: [YOUR_STACK]