> ## Documentation Index > Fetch the complete documentation index at: https://www.octogen.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Platform Catalog API v1 overview > REST API reference for the Octogen Platform Catalog API v1 - base URL, authentication, endpoints, error codes, and OpenAPI spec link. The Octogen Platform Catalog API v1 is a server-to-server REST API for Catalog Partner organizations. It lets you search products across your granted catalogs, find products similar to a source product, look up a product by its page URL, request a product refresh, and list the catalogs your organization has been granted access to. Choose the REST API for API-key server workloads, or use the [Catalog Partner MCP server](/mcp/overview) for OAuth-based agent workflows. ## Base URL and content type All requests go to: ```http theme={null} 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: ```http theme={null} Authorization: Bearer octo_live_<32-hex-id>_ Content-Type: application/json ``` API keys are organization-scoped and currently usable only by Catalog Partner organizations. A key can access only the catalogs granted to the organization that owns it. Rotate or deactivate keys via the partner portal; 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: ```text theme={null} https://cdn.octogen.ai/openapi/platform/v1/openapi.json ``` The document includes server URLs, operation IDs (`listCatalogs`, `searchProducts`, `moreLikeThisProducts`, `lookupProduct`, `refreshProducts`), 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 API exposes these endpoints. | Method | Path | Operation | Description | | ------ | -------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------ | | `GET` | `/catalogs` | `listCatalogs` | Returns the catalogs granted to your organization. | | `POST` | `/products/lookup` | `lookupProduct` | Resolves a product page URL to a canonical 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 granted catalogs, or within one catalog when `catalog` is provided. | ## Error model All error responses carry a top-level `detail` field. **String detail** (auth, authorization, and not-found errors): ```json theme={null} {"detail": "product_not_found"} ``` **Array detail** (validation errors): ```json theme={null} { "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 and that the product URL belongs to a granted catalog. | | `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](#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](/guides/rate-limits) 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.