​
API reference

Clay’s HTTP surface is described by an OpenAPI 3.1 document and validated at the edge by Zod schemas. The OpenAPI document lives at apps/backend/openapi/openapi.yaml and is regenerated from the route handlers.

​
Schema sources

Hono app

apps/backend/src/index.ts

Exporter

apps/backend/scripts/export-openapi.ts

Generated contract

apps/backend/openapi/openapi.yaml

​
Implemented endpoints

MethodPathOperationTagResponsePurpose
GET/getRoothealthtext/plain stringMinimal backend hello response.
GET/healthgetHealthhealthHealthResponse JSONBackend health check.
GET/openapi.json— (runtime)—OpenAPI 3.1 documentLive document for ad-hoc debugging.
The backend also returns ErrorResponse JSON for unmatched routes via the shared notFound handler.
/openapi.json is served by the running Worker through app.doc31(...). It is not part of the generated openapi/openapi.yaml because it is rendered at runtime; treat it as a debugging aid, not as the durable contract.

​
Registered schemas

SchemaShapeWhere it is used
HealthResponse{ status: "ok", service: "clay-backend" }200 response of GET /health
ErrorResponse{ error: string }404 responses on GET /, GET /health, and the shared notFound handler
Inline plain stringz.string().openapi({ example: "Hello, world!" })200 response of GET / (text/plain)
Schemas registered with .openapi("<Name>") appear under components.schemas in the generated YAML. Inline Zod chains stay inline for single-use shapes.

​
Local validation

pnpm --filter @clay/backend openapi:check
This lints the OpenAPI document with Redocly CLI. Run it after any change to route handlers or Zod schemas.

​
Naming convention

Prefer explicit multi-word names such as opportunityRoutes, IntentionSignalSchema, and OpportunityRecommendationSchema. Avoid single-word or vague names.
Never use TypeScript enums — use Zod enums instead, and never use as or any to bypass type checks. Route handlers must not contain business logic; delegate to siblings under src/.

​
Planned schemas

When the opportunity surface lands, names should follow the AGENTS.md guidance: opportunityRoutes, IntentionSignalSchema, OpportunityRecommendationSchema, PersonalitySignalSchema. Until then, the public surface is the routes and schemas in the tables above.

Backend overview

The Hono + OpenAPI contract, layout, and deployment boundaries.

Architecture

Where this backend sits inside the Turborepo surface layout.

Deploy

The Wrangler commands used to publish the Worker.