API Reference

Last Updated: January 2026

The Gamut Agent API is built on a Defense-in-Depth architecture that protects you from wasted API calls and costs. Unlike standard AI APIs that charge for every request (even when they return hallucinations or process invalid data), Gamut's circuit breakers block bad requests before expensive inference occurs.

Base URL

https://api.gamutagent.ai

Quick Start: One-Call Autonomous Mode

You don't need to chain multiple API calls to see value. The autonomous mode endpoint handles the entire discovery-to-analysis pipeline in a single request.

Example: Find Series A AI Startups

                curl -X POST https://api.gamutagent.ai/v1/run \
  -H "Authorization: Bearer sk_gamut_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "autonomous",
    "thesis": "Find Series A AI startups in San Francisco",
    "constraints": {
      "location": "San Francisco, CA",
      "min_employees": 10,
      "funding_stage": "Series A",
      "must_have_tech": ["Python", "PyTorch"]
    },
    "webhook_url": "https://your-app.com/webhooks/gamut"
  }'
            

Response: Returns immediately with a job_id. Results are delivered via webhook when complete (typically 30-60 seconds for discovery missions).

Response Codes & Circuit Breakers

This is your cost protection layer. Most APIs charge you even when they return errors or process invalid data. Gamut's Defense-in-Depth architecture blocks bad requests before expensive LLM inference occurs.

HTTP Code	Status	Meaning (The "Sales Pitch")	Chargeable?
`200`	`OK`	Analysis complete. Evidence found and verified.	Yes
`422`	`FIREWALL_BLOCK`	Domain blocked by Hallucination Firewall™ (DNS/HTTP check failed). Dead link or parking page detected.	NO
`424`	`INSUFFICIENT_EVIDENCE`	Zero-Evidence Circuit Breaker triggered. Data payload below minimum threshold. No inference cost incurred.	NO
`409`	`CONSTRAINT_VIOLATION`	Target rejected based on Thesis Constraints (e.g., Location mismatch, employee count). Analysis ran but verdict is NO_FIT.	Yes
`400`	`BAD_REQUEST`	Invalid request parameters. No processing occurred.	NO
`401`	`UNAUTHORIZED`	Invalid or expired authentication token.	NO
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests. Rate limit headers indicate when to retry.	NO

💡 Why This Matters

If you send 100 invalid URLs to a standard AI API, you pay for 100 LLM calls. With Gamut, the Hallucination Firewall blocks dead links before inference, and the Zero-Evidence Circuit Breaker prevents charges for empty data. You only pay when we deliver verified, evidence-backed results.

Authentication

All API requests require authentication using Firebase Authentication tokens. Include the token in the Authorization header:

Authorization: Bearer <firebase_id_token>

To obtain a token, authenticate through the web application or use Firebase SDK authentication methods. Tokens expire after 1 hour and must be refreshed.

The Scorecard: Structured Output

Unlike chatbots that return text blobs, Gamut returns structured, parseable JSON with verification evidence. Every response includes a scorecard object:

Scorecard Schema

                {
  "verdict": "FIT" | "NO_FIT" | "NEEDS_REVIEW",
  "evidence_strength": 0-100,  // Confidence score
  "match_score": 0.0-1.0,      // Overall match to thesis
  "sources": [                  // Verified citations
    "PDL",                      // People Data Labs
    "Scrape",                   // Website scrape
    "LinkedIn"                  // LinkedIn profile
  ],
  "red_flags": [                // Specific violations
    "Location mismatch: Listed as 'Remote' but constraint requires 'San Francisco'",
    "Employee count below threshold: 8 employees (minimum: 10)"
  ],
  "green_flags": [              // Positive signals
    "Tech stack matches: Python, PyTorch confirmed",
    "Funding stage verified: Series A closed Q3 2025"
  ],
  "verification_evidence": [
    {
      "field": "employee_count",
      "value": 45,
      "source": "PDL",
      "confidence": 0.95,
      "timestamp": "2026-01-16T12:00:00Z"
    }
  ],
  "reasoning": "Company matches Series A criteria with verified employee count and tech stack. Location constraint satisfied.",
  "circuit_breaker_status": {
    "firewall_passed": true,
    "evidence_threshold_met": true,
    "constraints_satisfied": true
  }
}
            

Endpoints

Autonomous Mode: Run

POST /v1/run

The one-call solution for complete deal flow discovery. Handles search, verification, filtering, and analysis in a single request. Returns immediately with a job_id; results delivered via webhook.

Request Body

Parameter	Type	Required	Description
`mode`	string	Yes	Must be `"autonomous"`
`thesis`	string	Yes	Investment thesis (e.g., "Series A AI startups in San Francisco")
`constraints`	object	No	Strict constraints: `location`, `min_employees`, `max_employees`, `funding_stage`, `must_have_tech`, `exclude_domains`
`webhook_url`	string	No	Recommended: URL to receive results when job completes (avoids long polling)
`max_results`	integer	No	Maximum companies to discover (default: 50, max: 500)

Response (Immediate)

                {
  "job_id": "job_abc123",
  "status": "queued",
  "estimated_completion": "2026-01-16T12:05:00Z",
  "webhook_registered": true
}
            

Webhook Payload (When Complete)

                {
  "job_id": "job_abc123",
  "status": "completed",
  "mission_id": "mission_xyz789",
  "companies_found": 15,
  "companies_verified": 12,
  "companies_saved": 8,
  "summary": "Found 8 qualified companies matching your criteria",
  "companies": [
    {
      "company_name": "Example Corp",
      "website": "https://example.com",
      "scorecard": { ... },
      "status": "identified"
    }
  ],
  "circuit_breaker_stats": {
    "firewall_blocks": 3,
    "insufficient_evidence_rejects": 4,
    "constraint_violations": 0,
    "total_cost_saved": "$0.12"  // Money saved by blocking bad requests
  }
}
            

Discovery: Search

POST /api/discovery/search

Initiates a deal flow discovery mission. Searches for companies matching your investment thesis, verifies them through the Hallucination Firewall, and saves qualified leads to your pipeline.

Request Body

Parameter	Type	Required	Description
`query`	string	Yes	Investment thesis (e.g., "Series A AI startups in San Francisco with >20 engineers")
`constraints`	object	No	Additional constraints (location, funding stage, employee count, etc.)
`ignore_domains`	array	No	List of domains to exclude from results

Response

                {
  "mission_id": "mission_abc123",
  "status": "completed",
  "companies_found": 15,
  "companies_verified": 12,
  "companies_saved": 8,
  "summary": "Found 8 qualified companies matching your criteria",
  "circuit_breaker_stats": {
    "firewall_blocks": 3,
    "insufficient_evidence_rejects": 4
  }
}
            

Analysis: Deep Dive (Single Domain)

POST /api/analyze/domain

Analyzes a single company by URL. Returns a complete scorecard with verification evidence. Use webhooks for long-running analysis jobs.

Request Body

Parameter	Type	Required	Description
`website_url`	string	Yes	Company website URL to analyze
`thesis`	string	No	Investment thesis to evaluate against
`webhook_url`	string	No	Recommended: Webhook URL for async results (analysis can take 30-60 seconds)

Response (Synchronous - if no webhook)

                {
  "job_id": "job_xyz789",
  "status": "processing",
  "estimated_completion": "2026-01-16T12:02:00Z"
}
            

Response (Asynchronous - via webhook)

                {
  "job_id": "job_xyz789",
  "status": "completed",
  "company_name": "Example Corp",
  "website": "https://example.com",
  "scorecard": {
    "verdict": "FIT",
    "evidence_strength": 87,
    "match_score": 0.92,
    "sources": ["PDL", "Scrape", "LinkedIn"],
    "red_flags": [],
    "green_flags": [
      "Tech stack matches: Python, PyTorch confirmed",
      "Funding stage verified: Series A closed Q3 2025"
    ],
    "verification_evidence": [ ... ],
    "reasoning": "Strong fit for Series A AI thesis..."
  }
}
            

Analysis: Poll Job Status

GET /api/analyze/{job_id}

Poll the status of an analysis job. Note: Using webhooks is recommended to avoid polling.

Response

                {
  "job_id": "job_xyz789",
  "status": "completed" | "processing" | "failed",
  "progress": 0.85,  // 0-1
  "result": { ... }   // Only present when status is "completed"
}
            

Pipeline: Query

GET /api/pipeline/query

Retrieves companies from your deal flow pipeline with optional filtering and pagination.

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `new_lead`, `identified`, `enriched`, `deep_dived`, `discarded`
`mission_id`	string	No	Filter by discovery mission ID
`limit`	integer	No	Maximum number of results (default: 50, max: 500)
`offset`	integer	No	Pagination offset (default: 0)

Memory Bank: Query Constraints

GET /api/knowledge/constraints

Retrieves learned constraints from your institutional memory. Shows what the AI has learned to avoid based on your past rejections and feedback.

Response

                {
  "learned_constraints": [
    {
      "type": "domain_pattern",
      "pattern": "*consulting*",
      "reason": "User rejected 5 consulting firms",
      "learned_at": "2026-01-10T10:00:00Z"
    },
    {
      "type": "entity_type",
      "entity": "service_agency",
      "reason": "User marked as 'wrong_entity_type'",
      "learned_at": "2026-01-12T14:30:00Z"
    }
  ],
  "rejection_patterns": [
    {
      "pattern": "Location: Remote",
      "count": 12,
      "last_rejected": "2026-01-15T09:00:00Z"
    }
  ]
}
            

Technical Best Practices

1. Use Webhooks for Long-Running Jobs

Deep dive analysis can take 30-60 seconds (scraping + multi-source verification + LLM analysis). Instead of holding a connection open, use the webhook_url parameter:

                {
  "website_url": "https://example.com",
  "webhook_url": "https://your-app.com/webhooks/gamut",
  "webhook_secret": "your_webhook_secret"  // For signature verification
}
            

Your webhook endpoint will receive a POST request with the complete analysis when ready.

2. Leverage the Cache (Memory Bank)

If you request the same company twice within 24 hours, Gamut returns the cached result from the Memory Bank instantly (and at a lower cost). This reinforces the "Compounding Intelligence" value proposition—your past analysis makes future queries faster and cheaper.

                💡 Cache Benefits
                Instant Results: Cached responses return in <100ms
Lower Cost: No inference cost for cached data
Consistent Results: Same company, same analysis (unless you provide corrections)

            

3. Batch Processing

For analyzing multiple companies, use the autonomous mode with a list of URLs or domains. The system processes them in parallel and delivers results via webhook.

4. Error Handling

Always check the circuit_breaker_stats in responses to understand cost savings. Handle FIREWALL_BLOCK and INSUFFICIENT_EVIDENCE errors gracefully—they indicate the system protected you from charges.

Rate Limits

API requests are rate-limited to prevent abuse:

Standard Tier: 100 requests per minute per team
Enterprise Tier: 500 requests per minute per team

Rate limit headers are included in all responses:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Unix timestamp when the limit resets

SDKs and Libraries

Official SDKs are available for:

Python: pip install gamut-agent
JavaScript/TypeScript: npm install @gamutagent/sdk

Documentation and examples for SDKs are available in our Developer Documentation.

Support

For API support, questions, or to report issues:

Email: api@gamutagent.ai
Documentation: docs.gamutagent.ai