{
  "openapi": "3.1.0",
  "info": {
    "title": "Datamint API",
    "summary": "Production web data ingestion, anti-bot bypass, and zero-code schema extraction.",
    "description": "Datamint provides high-reliability web crawling and structured extraction infrastructure designed specifically for autonomous AI agents, LLM pipelines, and automated research workflows. It automatically handles Chrome 133 TLS/JA4 fingerprinting, residential proxy rotation, CAPTCHA click-solving, and JSON Schema validation.",
    "version": "1.0.0",
    "termsOfService": "https://datamint.xyz/legal/terms",
    "contact": {
      "name": "Datamint Engineering & Support",
      "url": "https://datamint.xyz/contact",
      "email": "support@datamint.xyz"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    }
  },
  "servers": [
    {
      "url": "https://api.datamint.xyz",
      "description": "Production Extraction Engine"
    },
    {
      "url": "https://datamint.xyz/api",
      "description": "Datamint Frontend Proxy & Account API"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v1/mint": {
      "post": {
        "summary": "Mint a web page",
        "description": "Synchronous single-page retrieval. Returns noise-free Markdown with navigation, scripts, and boilerplate stripped, or validated JSON if a schema is provided. Automatically ladders through transport tiers (Fast TLS -> Headless Browser -> Stealth Armor) based on target anti-bot countermeasures.",
        "operationId": "mintPage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MintRequest"
              },
              "examples": {
                "fastMarkdown": {
                  "summary": "Fast sub-second fetch to Markdown",
                  "value": {
                    "url": "https://example.com/article/123",
                    "js": false,
                    "stealth": false
                  }
                },
                "stealthWithSchema": {
                  "summary": "Stealth extraction with canonical schema",
                  "value": {
                    "url": "https://example.com/products/headphones",
                    "schema": "ecommerce_item",
                    "stealth": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extraction completed successfully. Deducts 1, 5, or 15 credits depending on transport tier used (+2 credits if schema requested).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MintResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters, malformed JSON, or unsupported URL protocol.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized. Missing, malformed, or revoked API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits. Your account balance cannot cover the cost of the request. 0 credits billed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "502": {
            "description": "Extraction engine temporarily unreachable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/extract": {
      "post": {
        "summary": "Extract structured schema",
        "description": "Zero-code extraction into strict typed JSON conforming to either a pre-mapped canonical schema (e.g. `ecommerce_item`, `article`, `job_posting`, `company_profile`, `real_estate_listing`, `faq`) or an inline JSON Schema object. DOM traversal and structural normalization are handled automatically.",
        "operationId": "extractSchema",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExtractRequest"
              },
              "examples": {
                "canonicalEcommerce": {
                  "summary": "Extract product using canonical ecommerce_item schema",
                  "value": {
                    "url": "https://example.com/item/laptop-pro",
                    "schema": "ecommerce_item",
                    "stealth": true
                  }
                },
                "customJsonSchema": {
                  "summary": "Extract custom fields via JSON Schema",
                  "value": {
                    "url": "https://example.com/about",
                    "schema": {
                      "type": "object",
                      "properties": {
                        "company_name": { "type": "string" },
                        "founded": { "type": "number" },
                        "founders": { "type": "array", "items": { "type": "string" } }
                      },
                      "required": ["company_name", "founded"]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured data extracted and validated successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExtractResponse"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid schema specification.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/v1/crawl": {
      "post": {
        "summary": "Start asynchronous crawl",
        "description": "Launches an asynchronous multi-page frontier crawl starting from a seed URL. Traverses subpages within specified link depth limits and page budget caps, applying path inclusion/exclusion regex patterns. Results are delivered out-of-band via webhook callback or polled via crawl_id.",
        "operationId": "startCrawl",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CrawlRequest"
              },
              "examples": {
                "docCrawlWithWebhook": {
                  "summary": "Crawl documentation with webhook notification",
                  "value": {
                    "url": "https://example.com/docs",
                    "max_depth": 2,
                    "max_pages": 50,
                    "path_include": "^/docs/",
                    "schema": "article",
                    "webhook_url": "https://api.yourdomain.com/webhooks/datamint"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Crawl job accepted and queued for asynchronous execution.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CrawlAcceptedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid crawl boundaries (e.g. max_depth > 10).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient credits to budget estimated crawl volume.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Poll crawl status & items",
        "description": "Inspects real-time progress of an in-flight or completed crawl job, returning counters (pages completed, pages failed, credits consumed) and extracted page objects.",
        "operationId": "getCrawlStatus",
        "parameters": [
          {
            "name": "crawl_id",
            "in": "query",
            "required": true,
            "description": "Unique crawl job UUID returned by POST /v1/crawl.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of extracted page records to return (1–100, default: 25).",
            "schema": {
              "type": "integer",
              "default": 25,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Pagination offset.",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Crawl status and extracted records.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CrawlStatusResponse"
                }
              }
            }
          },
          "404": {
            "description": "Crawl ID not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiError"
                }
              }
            }
          }
        }
      }
    },
    "/api/playground/health": {
      "get": {
        "summary": "Engine cluster health check",
        "description": "Returns operational connectivity status of the backend extraction engine and proxy network.",
        "operationId": "getEngineHealth",
        "security": [],
        "responses": {
          "200": {
            "description": "Extraction engine is healthy and operational.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connected": { "type": "boolean", "example": true },
                    "status": { "type": "string", "example": "connected" },
                    "backendUrl": { "type": "string", "example": "https://api.datamint.xyz" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key (mint_live_... or mint_test_...)",
        "description": "Authenticate requests with your Datamint API key. Generate keys from https://datamint.xyz/dashboard/keys."
      }
    },
    "schemas": {
      "MintRequest": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Target web URL to fetch. Must be an absolute http or https address.",
            "example": "https://example.com/article/123"
          },
          "js": {
            "type": "boolean",
            "default": false,
            "description": "Execute JavaScript in headless Chromium before extraction. Costs 5 credits.",
            "example": false
          },
          "stealth": {
            "type": "boolean",
            "default": false,
            "description": "Route request through rotating residential proxy pool and solve CAPTCHAs. Costs 15 credits (supersedes js).",
            "example": false
          },
          "schema": {
            "oneOf": [
              {
                "type": "string",
                "description": "Registered canonical schema name (ecommerce_item, article, job_posting, company_profile, real_estate_listing, faq).",
                "example": "article"
              },
              {
                "type": "object",
                "description": "Inline JSON Schema object."
              },
              {
                "type": "boolean",
                "description": "True to run extraction using default mapping."
              }
            ],
            "description": "Optional schema pass to produce typed JSON instead of Markdown (+2 credits)."
          },
          "no_cache": {
            "type": "boolean",
            "default": false,
            "description": "Bypass cache and force an immediate upstream re-fetch.",
            "example": false
          },
          "wait_for_selector": {
            "type": "string",
            "description": "CSS selector to await in the DOM before extracting content (e.g. #content, .product-card).",
            "example": "#article-body"
          },
          "timeout": {
            "type": "integer",
            "minimum": 5,
            "maximum": 60,
            "default": 30,
            "description": "Maximum page execution timeout in seconds.",
            "example": 30
          }
        }
      },
      "MintResponse": {
        "type": "object",
        "properties": {
          "markdown": {
            "type": "string",
            "description": "Cleaned, LLM-ready Markdown content.",
            "example": "# Example Article\n\nMain content body without navigation or ads..."
          },
          "data": {
            "type": "object",
            "description": "Structured JSON payload when schema was provided."
          },
          "status": {
            "type": "integer",
            "description": "Upstream HTTP status code.",
            "example": 200
          },
          "_mint_meta": {
            "type": "object",
            "properties": {
              "tier_used": { "type": "string", "enum": ["tier_1", "tier_2", "tier_3"], "example": "tier_1" },
              "credits_billed": { "type": "integer", "example": 1 },
              "latency_ms": { "type": "integer", "example": 342 },
              "confidence": { "type": "number", "minimum": 0, "maximum": 1, "example": 0.98 }
            }
          }
        }
      },
      "ExtractRequest": {
        "type": "object",
        "required": ["url", "schema"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Target web URL to extract from.",
            "example": "https://example.com/products/456"
          },
          "schema": {
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "ecommerce_item",
                  "article",
                  "job_posting",
                  "company_profile",
                  "real_estate_listing",
                  "faq"
                ],
                "description": "Registered canonical schema name.",
                "example": "ecommerce_item"
              },
              {
                "type": "object",
                "description": "Custom JSON Schema definition."
              }
            ]
          },
          "js": {
            "type": "boolean",
            "default": false,
            "description": "Render dynamic JavaScript in headless browser."
          },
          "stealth": {
            "type": "boolean",
            "default": false,
            "description": "Route via residential proxies with anti-bot evasion."
          },
          "no_cache": {
            "type": "boolean",
            "default": false
          },
          "wait_for_selector": {
            "type": "string"
          },
          "timeout": {
            "type": "integer",
            "minimum": 5,
            "maximum": 60,
            "default": 30
          }
        }
      },
      "ExtractResponse": {
        "type": "object",
        "description": "Extracted data conforming to the requested schema.",
        "properties": {
          "data": {
            "type": "object",
            "description": "Typed extracted fields."
          },
          "status": {
            "type": "integer",
            "example": 200
          },
          "_mint_meta": {
            "type": "object",
            "properties": {
              "tier_used": { "type": "string", "example": "tier_3" },
              "credits_billed": { "type": "integer", "example": 17 },
              "latency_ms": { "type": "integer", "example": 2850 },
              "confidence": { "type": "number", "example": 0.96 }
            }
          }
        }
      },
      "CrawlRequest": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Seed root URL to begin crawl.",
            "example": "https://example.com/docs"
          },
          "max_depth": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10,
            "default": 2,
            "description": "Link depth hops from seed URL.",
            "example": 2
          },
          "max_pages": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000,
            "default": 25,
            "description": "Maximum page budget cap for the job.",
            "example": 50
          },
          "path_include": {
            "type": "string",
            "description": "Regex pattern for URLs that must be crawled.",
            "example": "^/docs/"
          },
          "path_exclude": {
            "type": "string",
            "description": "Regex pattern for URLs that should be ignored.",
            "example": "/(changelog|legacy)/"
          },
          "stealth": {
            "type": "boolean",
            "default": false,
            "description": "Route all requests across crawl via residential proxy pool."
          },
          "schema": {
            "type": "string",
            "description": "Optional registered schema name applied to all crawled pages.",
            "example": "article"
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "description": "HTTPS callback URL notified upon crawl completion.",
            "example": "https://api.yourdomain.com/webhooks/datamint"
          }
        }
      },
      "CrawlAcceptedResponse": {
        "type": "object",
        "properties": {
          "crawl_id": {
            "type": "string",
            "description": "UUID assigned to track this crawl job.",
            "example": "crl_9f8a1b2c3d4e"
          },
          "status": {
            "type": "string",
            "enum": ["queued", "in_progress", "completed", "failed"],
            "example": "in_progress"
          },
          "url": {
            "type": "string",
            "example": "https://example.com/docs"
          },
          "max_pages": {
            "type": "integer",
            "example": 50
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-21T05:00:00Z"
          }
        }
      },
      "CrawlStatusResponse": {
        "type": "object",
        "properties": {
          "crawl_id": { "type": "string", "example": "crl_9f8a1b2c3d4e" },
          "status": { "type": "string", "enum": ["in_progress", "completed", "failed"], "example": "completed" },
          "pages_completed": { "type": "integer", "example": 48 },
          "pages_failed": { "type": "integer", "example": 2 },
          "credits_used": { "type": "integer", "example": 240 },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": { "type": "string" },
                "status": { "type": "integer" },
                "markdown": { "type": "string" },
                "data": { "type": "object" },
                "latency_ms": { "type": "integer" }
              }
            }
          }
        }
      },
      "ApiError": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "invalid_request",
                  "unauthorized",
                  "insufficient_credits",
                  "upstream_error",
                  "rate_limited",
                  "internal_error"
                ],
                "description": "Stable machine-readable error code.",
                "example": "insufficient_credits"
              },
              "message": {
                "type": "string",
                "description": "Human-readable description of error.",
                "example": "This request costs 17 credits and your balance is 4. Top up or upgrade to continue."
              },
              "required": {
                "type": "integer",
                "description": "Credits required for request (present on 402).",
                "example": 17
              },
              "balance": {
                "type": "integer",
                "description": "Current credit balance (present on 402).",
                "example": 4
              }
            }
          }
        }
      }
    }
  }
}