Platform Catalog API v1 overview

The Octogen Platform Catalog API v1 is a server-to-server REST API for Developer organizations. It lets you search products across active crawled catalogs, find products similar to a source product, look up a product by its page URL, request a product refresh, and maintain coverage URL lists that Octogen joins against its catalogs daily. Choose the REST API for API-key server workloads, or use the Developer MCP server for OAuth-based agent workflows.

Base URL and content type

All requests go to:

https://api.octogen.ai/v1

Every request body and response body uses application/json. Set Content-Type: application/json on requests that include a body.

Authentication

Send your Platform API key as a Bearer token on every request:

Authorization: Bearer octo_live_<32-hex-id>_<base64url-secret>
Content-Type: application/json

API keys are organization-scoped and currently usable only by Developer organizations. A key can search and browse every active crawled catalog, including catalogs activated later, and can never access merchant catalogs. Rotate or deactivate keys in Octogen Platform; deactivation takes effect on the next request.

Never expose your Platform API key in client-side code or public repositories. Treat it like a password.

OpenAPI specification

The machine-readable contract is published at every platform deploy:

https://cdn.octogen.ai/openapi/platform/v1/openapi.json

The document includes server URLs, operation IDs such as searchProducts, moreLikeThisProducts, lookupProduct, refreshProducts, startVoyage, getVoyage, listVoyages, createUrlList, listUrlLists, getUrlList, deleteUrlList, addUrlListUrls, removeUrlListUrls, checkUrlListUrls, and listUrlListUrls, full request and response schemas, and example error bodies. Most ecosystems can generate a typed client from it - for example openapi-generator, openapi-typescript, or oapi-codegen.

Endpoints

The public reference currently documents these endpoints.

Method	Path	Operation	Description
`POST`	`/products/lookup`	`lookupProduct`	Resolves a product page URL to a full product record.
`POST`	`/products/more-like-this`	`moreLikeThisProducts`	Finds products similar to a source product URL or UUID.
`POST`	`/products/refresh`	`refreshProducts`	Requests fresh updates for product URLs or UUIDs.
`POST`	`/products/search`	`searchProducts`	Searches products across all active crawled catalogs, or within one catalog when `catalog` is provided.
`POST`	`/voyage`	`startVoyage`	Starts or joins a voyage to add coverage for an ecommerce domain.
`GET`	`/voyage/{task_id}`	`getVoyage`	Returns the current progress of a voyage requested by your organization.
`GET`	`/voyage`	`listVoyages`	Lists your organization’s voyages and current voyage quota usage.
`POST`	`/coverage/url-lists`	`createUrlList`	Creates a coverage URL list that Octogen joins against its catalogs daily.
`GET`	`/coverage/url-lists`	`listUrlLists`	Lists your organization’s coverage URL lists.
`GET`	`/coverage/url-lists/{urlListId}`	`getUrlList`	Returns one coverage URL list, including its BigQuery listing details.
`DELETE`	`/coverage/url-lists/{urlListId}`	`deleteUrlList`	Permanently deletes a coverage URL list and its BigQuery resources.
`POST`	`/coverage/url-lists/{urlListId}/urls`	`addUrlListUrls`	Adds product URLs to a list with per-URL outcomes.
`GET`	`/coverage/url-lists/{urlListId}/urls`	`listUrlListUrls`	Pages through a list’s member URLs.
`POST`	`/coverage/url-lists/{urlListId}/urls/remove`	`removeUrlListUrls`	Removes product URLs from a list.
`POST`	`/coverage/url-lists/{urlListId}/urls/contains`	`checkUrlListUrls`	Checks which URLs are members of a list.

Error model

All error responses carry a top-level detail field. String detail (auth, authorization, and not-found errors):

{"detail": "product_not_found"}

Array detail (validation errors):

{
  "detail": [
    {
      "loc": ["body", "limit"],
      "msg": "Input should be less than or equal to 100",
      "type": "less_than_equal"
    }
  ]
}

Error status codes

Status	Meaning	Action
`401`	Missing, malformed, or invalid Bearer token.	Rotate or replace the API key.
`403`	Key is valid but not authorized for this resource.	Confirm the organization has access to the requested catalog.
`404`	Catalog or product is not visible for this key.	Verify the catalog key identifies an active crawled catalog and the product URL belongs to it.
`422`	Request body or field validation failed.	Surface the field-level `loc` and `msg` to identify the invalid field.
`429`	Per-organization rate limit exceeded.	Wait the `Retry-After` interval, then retry — see Rate limits.

Retry transient network errors, 5xx responses, and 429 (after waiting Retry-After). The other 4xx codes listed above require a change in the caller.

Rate limits

Requests are rate limited per organization — one budget shared across all of your API keys and MCP sessions. The cap is a generous safety ceiling set well above normal traffic and is not published as a fixed number; read your current allowance from the X-RateLimit-Limit response header. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When you exceed the limit, the API returns 429 Too Many Requests with detail: "rate_limit_exceeded" and a Retry-After header. See the Rate Limits guide for the headers, backoff code, and the MCP equivalent.

REST and MCP: choosing a surface

Both surfaces run against the same grants table. A grant change on one path takes effect immediately on the other.

	REST (`/v1`, API keys)	MCP (OAuth)
Best for	Backends, batch jobs, server-to-server	Interactive agents (Claude Code, Codex, Claude Desktop)
Auth	Bearer `octo_live_...` key	OAuth 2.1 + PKCE, audience-bound access token
Token lifetime	Until manually revoked	~5 minutes access; refresh until session expiry
Revocation	Revoke the API key	Sign out or remove the user from the organization

If you are building an agent-based workflow and already have OAuth in place, prefer the MCP server — the tool signatures map 1:1 to these REST endpoints.

Catalog API

Voyage API

Coverage API

Data Models

Platform Catalog API v1 overview

Base URL and content type

Authentication

OpenAPI specification

Endpoints

Error model

Error status codes

Rate limits

REST and MCP: choosing a surface

​Base URL and content type

​Authentication

​OpenAPI specification

​Endpoints

​Error model

​Error status codes

​Rate limits

​REST and MCP: choosing a surface

Base URL and content type

Authentication

OpenAPI specification

Endpoints

Error model

Error status codes

Rate limits

REST and MCP: choosing a surface