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 · Section citation
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 · Live API migration notice · Public crawl API reference · Public agentic search reference
Version guidance and retired endpoints
Evidence basis: implementation_review · Section citation
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 · Public extraction API reference · Public crawl API reference
Operation families and their completion signals
Evidence basis: implementation_review · Section citation
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 · Public product listing reference · Public extraction API reference · Public agentic search reference · Public synchronous search reference · Public API usage reference · Live API migration notice
Authentication and processing costs
Evidence basis: public_source · Section citation
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 · Public crawl API reference · Public API error reference · Public API usage reference
Illustrative current extraction request
Evidence basis: public_source · Section citation
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
POST https://api.getcatalog.ai/v3/extract
Content-Type: application/json
x-api-key: <server-side account key>
{
"urls": ["https://example.com/products/example-product"]
}Sources: Live API migration notice