Gessa developer resources

The canonical machine-readable contract is https://api.gessa.ai/openapi.json. It describes the supported public generation surface. Generate clients and function-call tools from that contract, not from undocumented implementation routes.

The core workflow is: inspect capabilities, request a quote, create a generation job, observe or fetch it, and cancel it when needed. Streaming event endpoints are documented separately from JSON function-call operations.

REST callers use a scoped workspace API key or short-lived capability token issued by Gessa. Send the credential only to https://api.gessa.ai. Start with read operations, request a quote before billable generation, use idempotency where the contract exposes it, and require human approval before high-impact writes or spend.

The Streamable HTTP endpoint is https://api.gessa.ai/mcp/rpc. Remote clients use the OAuth 2.1 discovery metadata published under /.well-known/. A GET request to the RPC route may return 405 by design; MCP clients initialize with the protocol’s supported HTTP method and negotiated session headers.

Machine clients can discover the live remote transport from the MCP Registry manifest at gessa.ai/.well-known/mcp. The manifest is remote-only and does not advertise the optional npm proxy until that package is public.

Treat documented 4xx responses as requests for correction and 5xx/503 responses as potentially transient. Log the request identifier, preserve the machine-readable error code, and surface the human-readable message. Never assume an undocumented response shape or retry a mutation merely because a transport failed.

Applicable API responses expose RateLimit and RateLimit-Policy. Slow down before the remaining budget reaches zero. On HTTP 429, wait forRetry-After; use bounded exponential backoff only for retry-safe operations.

The supported public contract follows semantic versions. Omit x-api-versionfor the current default or send x-api-version: 1 to pin major version 1. Unsupported major values fail explicitly. Additive compatible changes may ship within v1; breaking request or response changes require a new major API version. Gessa will document migrations and target at least 90 days of notice before retiring a generally available version. Actually deprecated routes emit the standardDeprecation signal, a deprecation link, and a Sunset date when one has been scheduled. Current routes are never marked deprecated pre-emptively.

See llms.txt, the agent catalog, and Gessa for AI assistants. Report contract or documentation problems to [email protected].