APIs and schemas

An API groups content that shares a schema. If two kinds of content, such as blog posts and announcements, have different fields or purposes, create a separate API for each. Only owners and maintainers can create an API or change its settings.

Choose a format

Format	Best for	Delivery shape
List	Multiple entries such as posts, announcements, or products	List entries or fetch one by ID
Object	A single profile or shared site settings	One object

Object format does not return a list. For example, if you create a profile in object format, use genko.apis.profile.get() in the SDK.

Create an API

Open the workspace and select "+" ("Add API") at the right end of the row of API names. If you have no API yet, select "Create an API".
Under "Basic information", enter the "API name" and "Endpoint", and a "Description (optional)" if you like. Then select "Next".
Under "Choose format", select List or Object, then select "Next". You cannot change the format after the API is created.
Under "Define the schema", add the fields you need to finish creating the API.

The API name identifies the API in the dashboard. The endpoint becomes part of the delivery URL, so use a name that says what the API is for, such as blog. Endpoints must be unique within a workspace.

txt

https://api.genko.me/v1/your-workspace/blog

Design the schema

The schema defines which fields an entry has. You can start with just a title and body, then add images, categories, authors, and more as you need them.

Display name	ID	Type	Use
Title	`title`	Text	Heading in lists and on detail pages
Body	`body`	Rich text	Entry text with headings and links
Eyecatch	`eyecatch`	Image	Image shown in entry lists
Category	`category`	Select	Classification such as `news` or `tech`
Author	`author`	Content reference	Author profile stored in another API

Values and settings for each type are described in Fields. Instead of packing everything into the body, put information you search or display on its own in separate fields. It is easier to work with.

Change a schema

Open the API and select "Schema" at the right end of the row of API names (only owners and maintainers see it). Edit the fields, then select "Save changes" to review the diff and apply it. Saved changes appear in delivery responses.

Before you change the schema, check which fields your site uses. Changing a field ID or type, or deleting a field, can break code that displays it. If you add a required field, existing entries must have a value for it the next time you save them.

Update your app in this order:

Sync the types with pull.
Update your display code for the added or changed fields.
Fetch existing entries and check how they look when a field has no value.
Run type checks and check the pages in your app.

pull does not migrate data. Add values to existing entries in the dashboard.

API settings

Open "API settings" (next to "Schema") to set the API name, endpoint, preview URL, webhooks, and more. Previews need code on your site to receive them, and webhooks need code at the receiving end.

Deleting an API also deletes its content. Check which sites and apps use the API first.

Enable multilingual content

After an owner adds an additional language in Workspace settings, turn on "Make it multilingual" under "Multiple languages" in API settings. It works for both list and object APIs. Existing main-language entries stay as they are, and you create the additional-language version of each entry as needed.

All language versions share the same schema and entry ID. Field types and IDs cannot differ by language. Field values, publish status, scheduled publish and unpublish times, draft key, and version history are separate for each language. You can edit an entry in the main language even if its additional-language versions do not exist yet.

Turning multilingual off stops delivery and editing of additional-language versions. Saved versions are kept and work again when you turn it back on. To delete a language version for good, use Edit content. To choose a language in delivery requests, see Multilingual content.