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 Getting started — 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 on requests
• Credentials — an MCP OAuth token on POST /mcp, or an sk-cs-… API key, sk-csa-… agent key, or user session JWT anywhere

MCP endpointCopy Anchor Link

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, a body over 5 MiB with 413, and GET /mcp answers 405 — there is no standalone server-to-client stream.

The endpoint serves both protocol eras. A 2025-era request is answered as one text/event-stream event whose data: line is the JSON-RPC response. A 2026-07-28 request, which carries a per-request _meta envelope, is answered as plain application/json.

ConnectorsCopy Anchor Link

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 no unauthenticated catalog.

ToolsCopy Anchor Link

Built-in tool families are documented on their capability pages — Memory, Media, Web, Social — with tools/list as the authority for names and schemas. The account-management family has its own reference:

AuthenticationCopy Anchor Link

Every endpoint in this reference requires a caller credential — an MCP OAuth token on POST /mcp only, or an sk-cs-… API key, sk-csa-… agent key, or user session JWT anywhere — except the GET /health and GET /version probes, the public server card at GET /.well-known/mcp/server-card.json, and the metadata document below. The header forms, and how each credential is issued, are on Authentication.

Browser sign-inCopy Anchor Link

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://login.corespeed.io"],
  "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.

ConventionsCopy Anchor Link

• Tool names are <capability-id>__<operation> with a double underscore: memory__remember, slack__post_message. A remote MCP server your organization added publishes org__<slug>__<tool>.
• Your surface is not a static list. The public server card lists only the built-in tools. 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 one nested error envelope with type, code, and message (the MCP transport's own refusals are bare JSON-RPC errors); 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.