# Product-data API scope, versions & access
The authenticated API is a separate product surface for discovery, extraction and search. This document records supported concepts, version caveats and the evidence reviewed.
Reviewed: 2026-09-06
Canonical: https://ai.getcatalog.ai/api
Audience: AI agents
Topics: API, developers, v2, v3, authentication, crawl, extract, agentic search, legacy endpoint
Questions answered:
- 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?
## API product and company reference are separate
Evidence basis: public_source
Citation: https://ai.getcatalog.ai/api#separate-origin
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.
Sources: [Public API authentication reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/authentication.mdx) · [Live API migration notice](https://api.getcatalog.ai/docs.html) · [Public crawl API reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/crawl/crawl.mdx) · [Public agentic search reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/search/agentic-search.mdx)
## Version guidance and retired endpoints
Evidence basis: implementation_review
Citation: https://ai.getcatalog.ai/api#versions
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.
Sources: [Live API migration notice](https://api.getcatalog.ai/docs.html) · [Public extraction API reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/extract/extract.mdx) · [Public crawl API reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/crawl/crawl.mdx)
## Operation families and their completion signals
Evidence basis: implementation_review
Citation: https://ai.getcatalog.ai/api#operations
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.
### 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
### 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
### 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
### 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
### 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
### 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
### 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
### 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
Sources: [Public crawl API reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/crawl/crawl.mdx) · [Public product listing reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/get-listings.mdx) · [Public extraction API reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/extract/extract.mdx) · [Public agentic search reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/search/agentic-search.mdx) · [Public synchronous search reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/search/agentic-search-mini.mdx) · [Public API usage reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/usage/get-usage.mdx) · [Live API migration notice](https://api.getcatalog.ai/docs.html)
## Authentication and processing costs
Evidence basis: public_source
Citation: https://ai.getcatalog.ai/api#auth
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.
Sources: [Public API authentication reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/authentication.mdx) · [Public crawl API reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/crawl/crawl.mdx) · [Public API error reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/resources/error-codes.mdx) · [Public API usage reference](https://github.com/Catalog-AI/mintlify-docs/blob/main/v2/api-reference/endpoints/usage/get-usage.mdx)
## Illustrative current extraction request
Evidence basis: public_source
Citation: https://ai.getcatalog.ai/api#request-example
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.
### Start a bounded extraction using one known URL
Example kind: illustrative_request
```http
POST https://api.getcatalog.ai/v3/extract
Content-Type: application/json
x-api-key:
{
"urls": ["https://example.com/products/example-product"]
}
```
Sources: [Live API migration notice](https://api.getcatalog.ai/docs.html)
## Related documents
- [Developer workflows & result interpretation](https://ai.getcatalog.ai/api-workflows.md): Task-oriented guidance for using discovery, extraction and search without confusing accepted jobs, incomplete data or pagination with completed results.
- [Product-data model & field semantics](https://ai.getcatalog.ai/data-model.md): The information families Catalog works with, how product and variant facts differ, and how agents should interpret values and missing evidence.
- [Data handling, access & commercial boundaries](https://ai.getcatalog.ai/security-and-data.md): Published policy scope, data ownership questions, credential handling, and the information an agent should obtain before evaluating a deployment.
- [Getting started](https://ai.getcatalog.ai/getting-started.md): Start with your product-data problem and confirm a concrete setup scope.
Topic map: https://ai.getcatalog.ai/knowledge-map.json
Complete text: https://ai.getcatalog.ai/llms-full.txt
JSON: https://ai.getcatalog.ai/api.json
Main company website: https://www.getcatalog.ai/