API Documentation

API Reference

Integrate ContractorMargin data into your own tools with our REST API and MCP endpoint.

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

GET/api/v1/stats

Returns aggregated stats for the authenticated user.

Response

{
  "avg_margin": 38.4,
  "active_jobs": 3,
  "flagged_jobs": 1,
  "estimate_accuracy": 96.2
}

GET/api/v1/jobs

Returns all jobs with computed margins for the authenticated user.

Response

{
  "jobs": [
    {
      "id": "uuid",
      "name": "Residential AC Install - Johnson",
      "client_name": "Mike Johnson",
      "status": "completed",
      "estimated_revenue": 3200,
      "actual_revenue": 3100,
      "total_labor_cost": 650,
      "total_material_cost": 1300,
      "total_cost": 1950,
      "margin": 37.1,
      "margin_danger": false
    }
  ]
}

POST/api/v1/jobs

Create a new job.

Request Body

{
  "name": "Heat Pump Install - Smith",
  "client_name": "Bob Smith",
  "job_type": "residential",
  "estimated_revenue": 4500
}

POST/api/mcpMCP Protocol

Model Context Protocol endpoint. Use with Claude, Cursor, or any MCP-compatible AI assistant to query your job data via natural language.

Available Tools

get_stats

Get aggregated margin stats for your account

create_job

Create a new job with name, client, and revenue

add_labor

Log a labor entry to a job (tech, hours, rate)

add_material

Log a material cost to a job

Example Request (tools/call)

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "get_stats",
    "arguments": {}
  }
}

Rate Limits

Plan	Requests/min	MCP calls/day
Starter	30	100
Pro	120	1,000
Team	300	5,000