Platform API Reference

Base URL: https://api.cortexhub.ai

The Platform API is the REST surface for managing your CortexHub organization. Use it to manage members and roles, configure governance, manage approvals, and mint credentials for the MCP gateway.

Authentication

The Platform API uses OAuth 2.0 client credentials.

1. From your dashboard, create an OAuth client for your organization and grant it the scopes you need.
2. Exchange the client credentials at POST /v1/oauth/token for an access token.
3. Send Authorization: Bearer <access_token> on every request.

Create the OAuth client in your dashboard, then grant it the scopes your integration needs. One organization credential operates the whole organization programmatically.

Scopes

Scopes are minimum-privilege. Request only what your integration needs.

Scope	Purpose
org.read	Read organization profile, members, and groups.
org.write	Manage organization settings, governance groups, toolkits, and members (invite, update, remove, assign roles).
mcp_gateway_keys.mint	Mint, rotate, and revoke the org MCP gateway key.
org.toolkits.read	Read toolkit catalogue and member connection status.
org.toolkits.connect	Connect and disconnect toolkit credentials for a member.
org.documents.parse	Parse documents into markdown and text chunks.
org.router.invoke	List organization LLM models and invoke the CortexHub LLM router (native SSE and chat completions).
org.context.compress	Compress message context before LLM calls.

What this reference covers

Endpoints are grouped by topic:

• Organizations and members
• Roles (owner, admin, member)
• Agents, toolkits, and connections
• Platform LLM router, document parsing, and context compression
• Governance groups, entitlements, and guardrails
• Approval roles and approval decisions
• Org MCP gateway key
• OAuth discovery and token endpoints

What lives elsewhere

Need	Use
Call tools from your runtime	MCP gateway
Authenticate the MCP gateway with the org MCP gateway key	Org MCP gateway key
Concepts and how the platform works	Learn

Conventions

• All resources are namespaced under /v1/orgs/{orgId}. Member self-service endpoints live under /v1/orgs/{orgId}/me/...; admin endpoints under /v1/orgs/{orgId}/{groups,toolkits,members,usage,audit,integrations,agents}.
• Identifiers are opaque strings with a stable prefix (cxh_org_…, cxh_agent_…). Treat them as case-sensitive.
• Timestamps are RFC 3339 UTC.
• Pagination uses page and page_size query parameters; responses carry a page_info block with total and has_more.
• Errors follow a consistent envelope (code, message, details). Permission denials return 403; missing or expired tokens return 401.

Versioning

The API is versioned in the URL (/v1/…). Breaking changes ship under a new version prefix. Additive changes (new fields, new endpoints, new optional parameters) ship on the existing version.