Skip to main content

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.

The Octogen Platform Catalog API v1 is a server-to-server REST API for Catalog Partner organizations. It lets you search products within a catalog, look up a product by its page URL, and list the catalogs your organization has been granted access to. Every response shape is identical to the Catalog Partner MCP server — choose the surface that fits your runtime.

​
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 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: 
https://cdn.octogen.ai/openapi/platform/v1/openapi.json
The document includes server URLs, operation IDs (listCatalogs, searchProducts, lookupProduct), 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 three endpoints.
MethodPathOperationDescription
GET/catalogslistCatalogsReturns the catalogs granted to your organization.
POST/products/lookuplookupProductResolves a product page URL to a canonical product record.
POST/products/searchsearchProductsSearches products within a single granted catalog.

​
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", "catalog"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

​
Error status codes

StatusMeaningAction
401Missing, malformed, or invalid Bearer token.Rotate or replace the API key.
403Key is valid but not authorized for this resource.Confirm the organization has access to the requested catalog.
404Catalog or product is not visible for this key.Verify the catalog key and that the product URL belongs to a granted catalog.
422Request body or field validation failed.Surface the field-level loc and msg to identify the invalid field.
Retry only transient network errors or 5xx responses. The 4xx codes listed above require a change in the caller.

​
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 forBackends, batch jobs, server-to-serverInteractive agents (Claude Code, Codex, Claude Desktop)
AuthBearer octo_live_... keyOAuth 2.1 + PKCE, audience-bound access token
Token lifetimeUntil manually revoked~5 minutes access; refresh until session expiry
RevocationRevoke the API keySign 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.