{
  "openapi": "3.1.0",
  "info": {
    "title": "Bytemine API",
    "version": "1.0.0",
    "summary": "B2B contact data, company enrichment, signals, web crawler, email verification, and MCP-ready endpoints.",
    "description": "Bytemine's REST API for B2B contact & company data, enrichment, intent signals, and email verification. Optimized for AI agents (MCP / OpenAI Function Calling / Anthropic Tool Use). 1 credit = 1 complete contact. Free tier: 500 credits/month for 12 months.\n\nDocs: https://www.bytemine.ai/developers\nMCP Server: https://www.bytemine.ai/mcp-server",
    "termsOfService": "https://www.bytemine.ai/terms",
    "contact": {
      "name": "Bytemine Support",
      "url": "https://www.bytemine.ai/contact",
      "email": "support@bytemine.ai"
    },
    "license": { "name": "Commercial", "url": "https://www.bytemine.ai/terms" }
  },
  "servers": [
    { "url": "https://api.bytemine.ai/v1", "description": "Production" }
  ],
  "externalDocs": {
    "description": "Bytemine API documentation",
    "url": "https://www.bytemine.ai/developers"
  },
  "security": [{ "ApiKeyAuth": [] }],
  "tags": [
    { "name": "Contacts", "description": "Find and enrich B2B contacts" },
    { "name": "Companies", "description": "Search, enrich, and find lookalikes" },
    { "name": "Email Verification", "description": "Verify deliverability in real-time" },
    { "name": "Signals", "description": "Intent and buying signals" },
    { "name": "ICP", "description": "Programmatic ICP builder" },
    { "name": "Web Crawler", "description": "On-demand web extraction & enrichment" },
    { "name": "LinkedIn Agent", "description": "Autonomous LinkedIn prospecting results" }
  ],
  "paths": {
    "/enrich/email": {
      "post": {
        "tags": ["Contacts"],
        "summary": "Enrich a contact by email",
        "operationId": "enrichByEmail",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailEnrichRequest" } } }
        },
        "responses": {
          "200": { "description": "Contact record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": { "$ref": "#/components/responses/InsufficientCredits" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/enrich/mobile": {
      "post": {
        "tags": ["Contacts"],
        "summary": "Find a verified mobile number for a contact",
        "operationId": "enrichMobile",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactIdentifier" } } } },
        "responses": { "200": { "description": "Contact with mobile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } } }
      }
    },
    "/enrich/linkedin": {
      "post": {
        "tags": ["Contacts"],
        "summary": "Enrich a contact by LinkedIn URL",
        "operationId": "enrichByLinkedin",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedinEnrichRequest" } } } },
        "responses": { "200": { "description": "Contact record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } } }
      }
    },
    "/enrich/company": {
      "post": {
        "tags": ["Companies"],
        "summary": "Enrich a company by domain or name",
        "operationId": "enrichCompany",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyEnrichRequest" } } } },
        "responses": { "200": { "description": "Company record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } } }
      }
    },
    "/company/search": {
      "post": {
        "tags": ["Companies"],
        "summary": "Search companies by firmographic filters",
        "operationId": "searchCompanies",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySearchRequest" } } } },
        "responses": { "200": { "description": "List of companies", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } } } }
      }
    },
    "/company/lookalikes": {
      "post": {
        "tags": ["Companies"],
        "summary": "Find companies similar to a seed set",
        "operationId": "companyLookalikes",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seed_domains": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "integer", "default": 25 } }, "required": ["seed_domains"] } } } },
        "responses": { "200": { "description": "Lookalike companies", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } } } }
      }
    },
    "/contact/search": {
      "post": {
        "tags": ["Contacts"],
        "summary": "Search contacts by title, seniority, company, location",
        "operationId": "searchContacts",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSearchRequest" } } } },
        "responses": { "200": { "description": "List of contacts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } } } }
      }
    },
    "/email/verify": {
      "post": {
        "tags": ["Email Verification"],
        "summary": "Verify an email address",
        "operationId": "verifyEmail",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": ["email"] } } } },
        "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationResult" } } } } }
      }
    },
    "/signals": {
      "post": {
        "tags": ["Signals"],
        "summary": "Get buying & intent signals for an account",
        "operationId": "getSignals",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" } }, "required": ["domain"] } } } },
        "responses": { "200": { "description": "Signals list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } } } } } }
      }
    },
    "/icp/build": {
      "post": {
        "tags": ["ICP"],
        "summary": "Build or refine an ICP from seed customers",
        "operationId": "buildIcp",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seed_domains": { "type": "array", "items": { "type": "string" } } }, "required": ["seed_domains"] } } } },
        "responses": { "200": { "description": "ICP definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IcpDefinition" } } } } }
      }
    },
    "/crawl": {
      "post": {
        "tags": ["Web Crawler"],
        "summary": "Crawl a URL and return structured extraction",
        "operationId": "crawlUrl",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "schema": { "type": "object", "description": "Optional JSON schema for extraction" } }, "required": ["url"] } } } },
        "responses": { "200": { "description": "Extraction result", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/linkedin/hot-leads": {
      "get": {
        "tags": ["LinkedIn Agent"],
        "summary": "Retrieve qualified leads from the LinkedIn Agent",
        "operationId": "getHotLeads",
        "parameters": [
          { "name": "qualification", "in": "query", "schema": { "type": "string", "enum": ["hot", "warm", "cold"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 500 } }
        ],
        "responses": { "200": { "description": "Hot leads", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HotLead" } } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }
    },
    "responses": {
      "Unauthorized": { "description": "Missing or invalid API key" },
      "InsufficientCredits": { "description": "Account is out of credits" },
      "NotFound": { "description": "Record not found" }
    },
    "schemas": {
      "EmailEnrichRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": ["email"] },
      "LinkedinEnrichRequest": { "type": "object", "properties": { "linkedin_url": { "type": "string", "format": "uri" } }, "required": ["linkedin_url"] },
      "ContactIdentifier": { "type": "object", "properties": { "email": { "type": "string" }, "linkedin_url": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company_domain": { "type": "string" } } },
      "CompanyEnrichRequest": { "type": "object", "properties": { "domain": { "type": "string" }, "name": { "type": "string" } } },
      "CompanySearchRequest": { "type": "object", "properties": { "industry": { "type": "array", "items": { "type": "string" } }, "headcount_min": { "type": "integer" }, "headcount_max": { "type": "integer" }, "country": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "integer", "default": 25 } } },
      "ContactSearchRequest": { "type": "object", "properties": { "title": { "type": "array", "items": { "type": "string" } }, "seniority": { "type": "array", "items": { "type": "string" } }, "company_domain": { "type": "array", "items": { "type": "string" } }, "country": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "integer", "default": 25 } } },
      "Contact": { "type": "object", "properties": { "id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "title": { "type": "string" }, "seniority": { "type": "string" }, "work_email": { "type": "string", "format": "email" }, "personal_email": { "type": "string", "format": "email" }, "direct_dial": { "type": "string" }, "mobile": { "type": "string" }, "linkedin_url": { "type": "string", "format": "uri" }, "company": { "$ref": "#/components/schemas/Company" }, "verified_at": { "type": "string", "format": "date-time" } } },
      "Company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "industry": { "type": "string" }, "headcount": { "type": "integer" }, "revenue": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "linkedin_url": { "type": "string", "format": "uri" }, "description": { "type": "string" } } },
      "EmailVerificationResult": { "type": "object", "properties": { "email": { "type": "string" }, "status": { "type": "string", "enum": ["valid", "invalid", "risky", "unknown"] }, "is_catchall": { "type": "boolean" }, "is_disposable": { "type": "boolean" }, "is_role": { "type": "boolean" } } },
      "Signal": { "type": "object", "properties": { "type": { "type": "string" }, "score": { "type": "number" }, "detected_at": { "type": "string", "format": "date-time" }, "source": { "type": "string" }, "details": { "type": "object" } } },
      "IcpDefinition": { "type": "object", "properties": { "industries": { "type": "array", "items": { "type": "string" } }, "headcount_range": { "type": "string" }, "geographies": { "type": "array", "items": { "type": "string" } }, "tech_stack": { "type": "array", "items": { "type": "string" } }, "buying_titles": { "type": "array", "items": { "type": "string" } } } },
      "HotLead": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/Contact" }, "qualification": { "type": "string", "enum": ["hot", "warm", "cold"] }, "qualification_reason": { "type": "string" }, "last_interaction_at": { "type": "string", "format": "date-time" } } }
    }
  }
}