Overview

This reference documents the wire contract, one operation per page. If you are setting up a client for the first time, start with the Quickstart — it covers browser sign-in and one-click install instead of raw requests.

Base URL

https://api.corespeed.io

Transport

HTTPS · Streamable HTTP (stateless)

Content type

application/json

Credentials

MCP OAuth token · sk-cs-… API key · user session JWT

MCP endpoint

Every connector and built-in tool is served from one endpoint, POST /mcp. The transport is stateless: one JSON-RPC call per HTTP request. Arrays (JSON-RPC batches) are rejected with 400, and GET /mcp answers 405 — there is no SSE downstream.

Connectors

One authenticated call returns every connector visible to this caller, with static metadata and the caller's own connection state in the same entry. There is no per-connector fan-out, and the public GET /catalog is retired (404).

Authentication

Every endpoint in this reference except GET /health requires a caller credential. Three header forms are accepted:

An MCP OAuth token is not a general-purpose credential. It comes from a different issuer than the session JWT and is audience-bound to the /mcp resource (RFC 8707), and only /mcp accepts that issuer — the connector routes verify bearer JWTs against the session issuer alone, so an MCP OAuth token there answers 401 invalid_jwt. Use an API key or a session JWT for GET/DELETE /connectors.

Identity resolves to one member inside one organization. That pair — not the request body — decides which connectors, accounts, and tools a response contains. See Authentication for how each credential is issued.

Browser sign-in

An unauthenticated POST /mcp returns 401 with a WWW-Authenticate header naming the RFC 9728 protected-resource metadata document:

{
  "resource": "https://api.corespeed.io/mcp",
  "authorization_servers": ["https://<authkit-domain>"],
  "bearer_methods_supported": ["header"]
}

The client then reads the authorization server's RFC 8414 metadata, registers itself, runs OAuth 2.1 + PKCE in the browser, and retries with the issued token. CoreSpeed is only the resource server — it issues and stores no OAuth tokens. The token's audience is bound to this /mcp resource (RFC 8707), so it cannot be replayed against another server.

Conventions

• Tool names are <capability-id>__<operation> with a double underscore: memory__remember, slack__post_message.
• Nothing is enumerable from a static list. Discovery is per caller: read GET /connectors for connector and account state, and MCP tools/list for the callable surface.
• Two error layers. HTTP failures carry an error envelope — nested for identity and billing, flat on connector routes; tool failures arrive inside HTTP 200 with result.isError: true. Both layers and every envelope shape are listed in Errors & status codes.
• URLs in responses (mcp_url, icon_url, url) are derived from the request origin, so they match the host you called.