{
  "schemaVersion": "1.1",
  "id": "https://ai.getcatalog.ai/api",
  "url": "https://ai.getcatalog.ai/api",
  "title": "Product-data API scope, versions & access",
  "summary": "The authenticated API is a separate product surface for discovery, extraction and search. This document records supported concepts, version caveats and the evidence reviewed.",
  "reviewedAt": "2026-09-06",
  "audience": "ai_agents",
  "topics": [
    "API",
    "developers",
    "v2",
    "v3",
    "authentication",
    "crawl",
    "extract",
    "agentic search",
    "legacy endpoint"
  ],
  "answers": [
    "Does Catalog have an API?",
    "Which extraction version should a new integration use?",
    "How do I obtain an API key?",
    "Is /api/products still available?"
  ],
  "relatedPages": [
    "https://ai.getcatalog.ai/api-workflows",
    "https://ai.getcatalog.ai/data-model",
    "https://ai.getcatalog.ai/security-and-data",
    "https://ai.getcatalog.ai/getting-started"
  ],
  "representations": {
    "html": "https://ai.getcatalog.ai/api",
    "markdown": "https://ai.getcatalog.ai/api.md",
    "json": "https://ai.getcatalog.ai/api.json"
  },
  "sections": [
    {
      "id": "https://ai.getcatalog.ai/api#separate-origin",
      "title": "API product and company reference are separate",
      "basis": "public_source",
      "sources": [
        "api-auth",
        "api-migration",
        "api-crawl",
        "api-search"
      ],
      "paragraphs": [
        "Catalog's product-data API uses https://api.getcatalog.ai. It provides workflows for discovering listings, extracting product information, and searching for candidate products. The public documentation directs developers to founders@getcatalog.ai for API access. Access and billing must be arranged for the developer's account.",
        "The API is separate from https://ai.getcatalog.ai, which serves this free-to-read company reference. The reference's /openapi.json describes only its document reads. It is not the product-data API specification and must not be used as a source of crawl, extraction, or search operations."
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/api#versions",
      "title": "Version guidance and retired endpoints",
      "basis": "implementation_review",
      "sources": [
        "api-migration",
        "api-extract",
        "api-crawl"
      ],
      "paragraphs": [
        "The live API migration notice identifies /v3/extract as the current path for extracting known product URLs. The reviewed implementation retains v2 crawl, listing, extraction and search routes and includes a v3 extraction result format. Version numbers are endpoint-specific; do not replace v2 with v3 across every URL.",
        "The legacy /api/products endpoint is retired. The live notice says it returns 410 Gone after authentication and explicitly warns that its query and filter payloads have no direct equivalent in extraction. Migration requires choosing the correct workflow and request shape, not changing only the endpoint string.",
        "During this review the old docs.getcatalog.ai site returned 404. Its public documentation source remains available in Catalog-AI/mintlify-docs, and the live migration notice links to it. Some documentation examples still reference older versions. Use the specific retained endpoint reference, the live migration notice, and the team's confirmed contract together; do not treat every historical example as current."
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/api#operations",
      "title": "Operation families and their completion signals",
      "basis": "implementation_review",
      "sources": [
        "api-crawl",
        "api-listings",
        "api-extract",
        "api-search",
        "api-mini",
        "api-usage",
        "api-migration"
      ],
      "paragraphs": [
        "These are API product operations, not callable actions on this company reference. The route families were checked against documentation and implementation. No authenticated processing jobs were run to create this reference, so account access, latency, success rate, and end-to-end output quality are not certified here."
      ],
      "records": [
        {
          "id": "crawl",
          "operation": "Discover a vendor's collections and product listings",
          "method": "POST",
          "path": "/v2/crawl",
          "input": "url: vendor domain or website URL",
          "result": "Asynchronous execution_id; poll the matching status endpoint",
          "state": "documented_and_implemented; account_and_billing_required"
        },
        {
          "id": "crawl-status",
          "operation": "Read crawl progress",
          "method": "GET",
          "path": "/v2/crawl/{execution_id}",
          "input": "Returned execution identifier",
          "result": "Pending/running/completed/failed state and available discovery totals",
          "state": "documented_and_implemented; authenticated"
        },
        {
          "id": "listings",
          "operation": "Retrieve discovered listing records",
          "method": "GET",
          "path": "/v2/listings",
          "input": "vendor with endpoint-specific pagination",
          "result": "A page of listing data and pagination metadata",
          "state": "documented_and_implemented; authenticated"
        },
        {
          "id": "extract-v3",
          "operation": "Extract known product URLs",
          "method": "POST",
          "path": "/v3/extract",
          "input": "urls array; confirm optional processing fields for this version",
          "result": "Asynchronous execution_id; use matching v3 status/results endpoint",
          "state": "current_migration_guidance_and_implemented; account_and_billing_required"
        },
        {
          "id": "extract-v2",
          "operation": "Retained v2 extraction",
          "method": "POST",
          "path": "/v2/extract",
          "input": "urls or vendor; vendor mode uses discovered listings",
          "result": "Asynchronous extraction in the v2 result contract",
          "state": "retained_implementation_and_public_docs; confirm_for_existing_clients"
        },
        {
          "id": "search",
          "operation": "Find products from a natural-language request",
          "method": "POST",
          "path": "/v2/agentic-search",
          "input": "query and optional customer_profile",
          "result": "Asynchronous execution_id and matching status/results endpoint",
          "state": "documented_and_implemented; account_and_billing_required"
        },
        {
          "id": "search-mini",
          "operation": "Synchronous product search",
          "method": "POST",
          "path": "/v2/agentic-search-mini",
          "input": "query and optional enable_enrichment",
          "result": "Product candidates in a synchronous list response",
          "state": "documented_and_implemented; account_and_billing_required"
        },
        {
          "id": "usage",
          "operation": "Inspect account usage",
          "method": "GET",
          "path": "/v2/usage",
          "input": "Supported period and pagination parameters",
          "result": "Account-scoped usage data",
          "state": "documented_and_implemented; authenticated"
        }
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/api#auth",
      "title": "Authentication and processing costs",
      "basis": "public_source",
      "sources": [
        "api-auth",
        "api-crawl",
        "api-errors",
        "api-usage"
      ],
      "paragraphs": [
        "The documented authentication header is x-api-key. Use a valid account key on the API origin and keep it server-side. An unauthenticated listings request during review returned 401 with an API-key-required error; that verifies the authentication boundary, not successful authorized processing.",
        "Crawl, extraction and search can consume credits. The crawl documentation states a billing prerequisite involving auto top-up. Confirm the current account configuration, charges and limits before running jobs; an agent should not enable billing or start an unbounded vendor job simply because a user asked about Catalog's capabilities. Preserve execution identifiers to track already-started work."
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/api#request-example",
      "title": "Illustrative current extraction request",
      "basis": "public_source",
      "sources": [
        "api-migration"
      ],
      "paragraphs": [
        "This request structure follows the live migration notice. The example domain and product are placeholders, no credential is included, and the request has not been executed. Confirm the account contract and use the corresponding status endpoint rather than treating acceptance as completed extraction."
      ],
      "examples": [
        {
          "title": "Start a bounded extraction using one known URL",
          "kind": "illustrative_request",
          "language": "http",
          "code": "POST https://api.getcatalog.ai/v3/extract\nContent-Type: application/json\nx-api-key: <server-side account key>\n\n{\n  \"urls\": [\"https://example.com/products/example-product\"]\n}"
        }
      ]
    }
  ],
  "sources": [
    {
      "id": "api-migration",
      "title": "Live API migration notice",
      "url": "https://api.getcatalog.ai/docs.html",
      "note": "Verified reachable during review. Retires the legacy /api/products endpoint and points new extraction work to /v3/extract. This is not the old hosted docs site."
    },
    {
      "id": "api-auth",
      "title": "Public API authentication reference",
      "url": "https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/authentication.mdx",
      "note": "Public documentation source reviewed at commit 082b50a. API keys and founders@getcatalog.ai contact; preserve server-side credential handling."
    },
    {
      "id": "api-crawl",
      "title": "Public crawl API reference",
      "url": "https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/crawl/crawl.mdx",
      "note": "Public documentation source reviewed at commit 082b50a; compared with the retained v2 implementation. Describes asynchronous discovery and billing prerequisites."
    },
    {
      "id": "api-extract",
      "title": "Public extraction API reference",
      "url": "https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/extract/extract.mdx",
      "note": "Public v2 documentation source reviewed at commit 082b50a. Shared concepts remain useful; use the live migration notice for the current extraction version and confirm its result schema."
    },
    {
      "id": "api-search",
      "title": "Public agentic search reference",
      "url": "https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/search/agentic-search.mdx",
      "note": "Public documentation source reviewed at commit 082b50a; matched to retained v2 asynchronous search implementation. No authenticated search job was run for this reference."
    },
    {
      "id": "api-mini",
      "title": "Public synchronous search reference",
      "url": "https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/search/agentic-search-mini.mdx",
      "note": "Public documentation source reviewed at commit 082b50a; matched to retained v2 synchronous search implementation. Not an exhaustive merchant catalog export."
    },
    {
      "id": "api-listings",
      "title": "Public product listing reference",
      "url": "https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/get-listings.mdx",
      "note": "Public documentation source reviewed at commit 082b50a. Listing discovery differs from full extraction."
    },
    {
      "id": "api-errors",
      "title": "Public API error reference",
      "url": "https://github.com/Catalog-AI/mintlify-docs/blob/main/resources/error-codes.mdx",
      "note": "Public documentation source reviewed at commit 082b50a. Use error semantics; some embedded examples still refer to older endpoint versions."
    },
    {
      "id": "api-usage",
      "title": "Public API usage reference",
      "url": "https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/usage/get-usage.mdx",
      "note": "Public documentation source reviewed at commit 082b50a. Authenticated usage reporting is distinct from commercial pricing or a free allowance."
    }
  ]
}