{
  "schemaVersion": "1.1",
  "id": "https://ai.getcatalog.ai/api-workflows",
  "url": "https://ai.getcatalog.ai/api-workflows",
  "title": "Developer workflows & result interpretation",
  "summary": "Task-oriented guidance for using discovery, extraction and search without confusing accepted jobs, incomplete data or pagination with completed results.",
  "reviewedAt": "2026-09-06",
  "audience": "ai_agents",
  "topics": [
    "API workflow",
    "pagination",
    "polling",
    "errors",
    "retries",
    "product comparison",
    "async jobs"
  ],
  "answers": [
    "How do I go from a vendor website to product records?",
    "How should I poll extraction?",
    "What should a client do on API errors?"
  ],
  "relatedPages": [
    "https://ai.getcatalog.ai/api",
    "https://ai.getcatalog.ai/data-model",
    "https://ai.getcatalog.ai/enrichment",
    "https://ai.getcatalog.ai/measurement"
  ],
  "representations": {
    "html": "https://ai.getcatalog.ai/api-workflows",
    "markdown": "https://ai.getcatalog.ai/api-workflows.md",
    "json": "https://ai.getcatalog.ai/api-workflows.json"
  },
  "sections": [
    {
      "id": "https://ai.getcatalog.ai/api-workflows#known-urls",
      "title": "When product URLs are already known",
      "basis": "editorial_guidance",
      "sources": [
        "api-migration",
        "api-extract",
        "api-pagination"
      ],
      "paragraphs": [
        "Start with a small, explicit URL set. Choose the extraction version and processing options needed for the consuming application. Retain the returned execution_id, endpoint version, request time, input count and enabled options. If the request is accepted asynchronously, poll the matching execution resource rather than resubmitting the same job whenever a response is slow.",
        "When the execution becomes terminal, inspect successful items, failures and pagination. Fetch all required result pages before reporting the delivered count. Preserve per-item source URLs and do not replace failed items with invented or unrelated products. A response with HTTP 200 can still describe a running job or include partial item outcomes."
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/api-workflows#vendor",
      "title": "When starting with a vendor domain",
      "basis": "editorial_guidance",
      "sources": [
        "api-crawl",
        "api-listings",
        "api-extract"
      ],
      "paragraphs": [
        "Use discovery to locate collections and product listings for the vendor. Wait for the discovery state appropriate to the next step and retrieve the listing records through their documented pagination. Then extract a deliberate sample or an explicitly authorized scope. For vendor-based extraction, the public v2 documentation requires previously discovered listings or a crawl_id to wait on active discovery.",
        "Report discovery coverage and extraction coverage separately. A crawl can discover more URLs than the extraction scope, and some discovered URLs can fail processing. A vendor-level operation can be much larger than a small URL request. Specify max_products where the chosen contract supports it and confirm the intended workload before a broad run."
      ],
      "records": [
        {
          "id": "discovered",
          "checkpoint": "Listings discovered",
          "evidence": "Discovery output or paginated listing records",
          "notEquivalentTo": "Extracted or published product records"
        },
        {
          "id": "accepted",
          "checkpoint": "Processing accepted",
          "evidence": "Execution identifier and accepted response",
          "notEquivalentTo": "Successful completion"
        },
        {
          "id": "completed",
          "checkpoint": "Processing complete",
          "evidence": "Terminal execution status plus item outcomes",
          "notEquivalentTo": "All submitted items necessarily succeeded"
        },
        {
          "id": "delivered",
          "checkpoint": "Results retrieved",
          "evidence": "Required pages saved and counts reconciled",
          "notEquivalentTo": "Merchant storefront publication"
        }
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/api-workflows#search",
      "title": "When the starting point is a shopping intent",
      "basis": "editorial_guidance",
      "sources": [
        "api-search",
        "api-mini"
      ],
      "paragraphs": [
        "Use search when the task is to find candidate products from a natural-language query rather than enumerate one merchant's complete catalog. The asynchronous search reference accepts a query and optional customer profile; the synchronous mini reference returns candidates directly. Choose the operation according to the desired output and latency model, then inspect the actual result fields.",
        "Search results are candidates for evaluation. Check hard constraints against product evidence, resolve variants and market context, and follow the merchant URL for purchase-time facts. Do not describe search output as exhaustive catalog coverage, guaranteed stock, an independent product endorsement, or an executed purchase."
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/api-workflows#pagination",
      "title": "Pagination and missing fields",
      "basis": "public_source",
      "sources": [
        "api-pagination",
        "api-listings",
        "api-extract"
      ],
      "paragraphs": [
        "The public API documentation describes paginated list responses. Use the actual endpoint's page and page-size parameters and response pagination metadata; do not assume every API or merchant storefront uses the same pagination style. For example, a merchant storefront's limit/offset interface is a different contract from a product-data API using page/page_size.",
        "Processing options can change which fields are populated. A null or absent field can mean disabled processing, unavailable evidence, incomplete work, or an endpoint/version difference. Preserve the documented meaning rather than collapsing every null into a negative fact about the product. Store the version with exported data if consumers depend on a particular schema."
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/api-workflows#errors",
      "title": "Handle failures without duplicating paid work",
      "basis": "editorial_guidance",
      "sources": [
        "api-errors",
        "api-auth",
        "api-migration"
      ],
      "paragraphs": [
        "Use HTTP status, the structured error code, the execution state and per-item outcomes together. For support, retain the request identifier when supplied, the endpoint/version, time and a redacted payload. Never include an API key in a support artifact. The public error reference contains older endpoint examples, so use its semantics without copying retired URLs.",
        "Apply bounded timeouts and backoff to safe retries. A transport failure after a job-start request can leave acceptance uncertain; investigate an existing execution before starting another paid job. Rate limiting is not a reason to run a faster loop. Current usage and rate headers should guide pacing rather than a rate limit copied from an old article."
      ],
      "records": [
        {
          "id": "bad-input",
          "status": "400",
          "meaning": "Request or validation problem",
          "response": "Correct the payload; repeating identical invalid input will not fix it."
        },
        {
          "id": "auth",
          "status": "401 or 403",
          "meaning": "Authentication or access problem",
          "response": "Check the intended account and authorization; do not guess credentials."
        },
        {
          "id": "billing",
          "status": "402",
          "meaning": "Billing or credit prerequisite",
          "response": "Resolve account billing with authorization; do not silently enable spending."
        },
        {
          "id": "missing",
          "status": "404",
          "meaning": "Resource or route unavailable",
          "response": "Check endpoint version and identifier; do not turn it into an empty success."
        },
        {
          "id": "retired",
          "status": "410",
          "meaning": "Retired resource",
          "response": "Follow the migration contract; old query payloads may have no equivalent."
        },
        {
          "id": "conflict",
          "status": "409",
          "meaning": "Operation conflicts with current state",
          "response": "Inspect the existing job or state before starting another operation."
        },
        {
          "id": "rate",
          "status": "429",
          "meaning": "Rate limit",
          "response": "Respect Retry-After when present and use bounded backoff."
        },
        {
          "id": "server",
          "status": "5xx or transport timeout",
          "meaning": "Server or transport failure",
          "response": "Retry safe reads with bounds; reconcile uncertain job creation before resubmitting."
        }
      ]
    },
    {
      "id": "https://ai.getcatalog.ai/api-workflows#handoff",
      "title": "A useful integration result",
      "basis": "editorial_guidance",
      "sources": [
        "api-extract",
        "api-errors",
        "quality"
      ],
      "paragraphs": [
        "For a reproducible development handoff, include the operation and version, execution identifiers, requested and completed counts, failed item count, pagination completion, processing options, and the location of saved responses. Show a small representative sample with the actual evidence fields. Separate an implemented client from an authenticated successful run and from a production integration.",
        "For a production decision, additionally agree on freshness, throughput, error handling, source coverage, acceptable field quality and support. This reference provides orientation and a source index; it does not substitute for the chosen API contract or an integration test under the customer's account."
      ]
    }
  ],
  "sources": [
    {
      "id": "quality",
      "title": "Product data quality",
      "url": "https://www.getcatalog.ai/blog/product-data-quality",
      "note": "Published July 10, 2026; updated July 31, 2026. Definitions, category-specific validation and evaluation guidance."
    },
    {
      "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-pagination",
      "title": "Public API pagination guide",
      "url": "https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/guides/pagination.mdx",
      "note": "Public documentation source reviewed at commit 082b50a. Request and response pagination belong to the chosen endpoint/version."
    }
  ]
}