Developers / API Reference

REST API Reference

Five endpoints. JSON in, JSON out. Your tech due diligence infrastructure, automated.

Base URL: https://badcop.tech/api/v1/

Quick Start

One cURL command to get your first insights.

curl -H "Authorization: Bearer bc_ak_..." https://badcop.tech/api/v1/sessions/

Authentication

All API endpoints require an API key passed via the Authorization header.

Authorization: Bearer bc_ak_your_api_key_here

⚠️ Keep your API keys secure

Never expose API keys in client-side code or public repositories. Use environment variables.

→ Sign up to get API keys

Rate Limiting

Each API key has a configurable daily rate limit (default: 100 requests/day).

When the limit is exceeded, the API returns:

429 Too Many Requests

Permissions (Scopes)

Scope	Access
`read`	List sessions, get insights, get reports
`write`	Submit transcripts for AI analysis
`mcp`	Grants access to the hosted MCP endpoint at `https://badcop.tech/mcp/`

Endpoints

GET /api/v1/sessions/

List all interview sessions for the authenticated user.

Query Parameters

Param	Type	Default	Description
`page`	int	1	Page number
`per_page`	int	20	Results per page (max 100)

Example Response

{
  "sessions": [
    {
      "id": 42,
      "conversation_id": "conv_abc123",
      "status": "completed",
      "role": "Founder",
      "started_at": "2025-03-15T10:30:00Z",
      "ended_at": "2025-03-15T10:52:00Z",
      "has_insights": true,
      "has_report": false
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 3,
    "total_pages": 1
  }
}

GET /api/v1/sessions/{id}/

Get details for a single session.

Example Response

{
  "id": 42,
  "conversation_id": "conv_abc123",
  "status": "completed",
  "role": "Founder",
  "started_at": "2025-03-15T10:30:00Z",
  "ended_at": "2025-03-15T10:52:00Z",
  "has_insights": true,
  "has_report": false,
  "insights_generated_at": "2025-03-15T10:53:00Z"
}

GET /api/v1/sessions/{id}/insights/

Get AI-generated insights and executive summary for a session.

Example Response

{
  "session_id": 42,
  "insights": [
    {
      "title": "Bus Factor Risk: Critical Level",
      "description": "Your CTO holds all architectural knowledge...",
      "category": "risk",
      "icon": "⚠️",
      "risk_score": 8
    }
  ],
  "summary": {
    "headline": "Scaling Fast, But At What Cost?",
    "verdict": "CAUTION",
    "summary": "Your engineering organization shows signs of..."
  },
  "generated_at": "2025-03-15T10:53:00Z"
}

GET /api/v1/sessions/{id}/report/

Get the full audit report in Markdown format. Requires a purchased or coupon-unlocked session.

Example Response

{
  "session_id": 42,
  "report_markdown": "# Executive Summary\n\n## The Verdict: PROCEED WITH CAUTION\n...",
  "generated_at": "2025-03-15T11:00:00Z"
}

POST /api/v1/analyze/ write scope required

Submit a transcript for AI-powered technical due diligence analysis. Returns structured insights and an executive summary.

Request Body

{
  "transcript": "Interviewer: Tell me about your tech stack.\nCTO: We use a monolithic Django app with PostgreSQL..."
}

Example Response (201 Created)

{
  "session_id": 43,
  "conversation_id": "api_a1b2c3d4e5f6",
  "insights": [...],
  "summary": {
    "headline": "Strong Foundation, But Scaling Risks Loom",
    "verdict": "CAUTION",
    "summary": "..."
  },
  "generated_at": "2025-03-15T11:05:00Z"
}

Error Codes

Code	Meaning
`400`	Bad Request — invalid JSON or missing fields
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — key revoked or missing permission scope
`404`	Not Found — session or resource doesn't exist
`429`	Too Many Requests — daily rate limit exceeded

Ready to Build?

Generate your API key and start pulling insights in under 60 seconds.

Create Free Account Prefer AI? Try MCP →