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, 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, inspect capabilities before generation, use idempotency where the contract exposes it, and require human approval before high-impact writes.

Domain-level clients can start with Gessa’s standards-aligned AI Catalog at gessa.ai/.well-known/ai-catalog.json. It advertises the public MCP Server Card and its HTTPS-bound identity metadata.

The Server Card at gessa.ai/.well-known/mcp-server-card.json follows the current draft MCP discovery extension. It declares identity and connection details only; clients still enumerate tools through MCP after authentication.

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 also advertises the verified @gessa/mcp-server stdio proxy for local MCP hosts. Version 1.1.0 exposes the gessa-mcpexecutable and forwards to the same authenticated remote service.

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 documents migrations and targets 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.

Read the dedicated, stable policy at gessa.ai/developers/api-lifecycle/.

See llms.txt, the agent catalog, and the Agent Skills index, and Gessa for AI assistants. Report contract or documentation problems to [email protected]. Integration and account support: [email protected].