OpenAPI and the API catalog

The HTTP spec for the delivery API is published as machine-readable OpenAPI. The API catalog points to that definition and to the documentation. You can read both without an API key.

Public URLs

OpenAPI describes the endpoints, the authentication header, queries, responses, and errors. The API catalog is a list for finding where an API is documented.

Load it into a tool

In the import feature of an API client or code generator that supports OpenAPI 3.1, enter https://api.genko.me/openapi.json. For tools that read from a file, save the JSON first.

curl --fail 'https://api.genko.me/openapi.json' -o genko-openapi.json

The server URL in the definition is https://api.genko.me/v1. When you make a request, set workspace to your workspace ID (slug) and endpoint to the API's endpoint. Authentication is set up as ApiKeyHeader, and the header you send is X-API-KEY.

You don't need to authenticate to fetch the definition, but you do need an API key to fetch content or the schema. Check a key's validity period and the APIs it allows in Manage API keys.

How it differs from a workspace schema

The public OpenAPI is the HTTP spec shared by every workspace. It doesn't include the API names, field definitions, entry content, or API keys that each user creates.

User-defined content fields are treated as arbitrary keys, and list and object responses are described on the same path. Types generated from OpenAPI alone can't tell you that your blog has title and body.

Get workspace-specific definitions from the authenticated /v1/{workspace}/_schema. If you use the typed TypeScript client, generate it with the CLI's init and pull. If the key is limited to certain APIs, the schema contains only those APIs.

Read the API catalog

curl --fail 'https://genko.me/.well-known/api-catalog'

The response is in application/linkset+json format and returns an anchor that points to the delivery API, along with its references.

This is a guide to the delivery API that the product publishes. For the list of APIs you created in a workspace, use _schema. A HEAD request to the API catalog also returns the catalog's location in the Link header.

See the delivery API for real request examples, and Read as Markdown for product material to give an AI.