Most of what you do with the API involves three objects. A story is an article. It belongs to a space and has an owner, a user. This page describes each one and the objects attached to it. The GraphQL reference has the full list of fields.

Story

Every piece of content on a platform is a Story. A story has an owner (its user), a space, and at least one version.

Version

A StoryVersion holds the content of the story at one point in time: the title, the body, the assets, the attributes, and whether it is published. story.version returns the latest published version in the user's preferred language; pass lang to choose a language, or uuid to read a specific version.

Translations

A story can be translated into any language the platform settings allow. A new version changes one language only, but it carries every translation that exists at that moment. If a story has a French version and you post a new version in English, the new version holds your English text and the French text of the latest French version, unchanged.

Body

The body is a RichContent. When you write one, you give a format and the content as markup:

Format	Use it for
`MARKDOWN`	Markdown as other tools export it: CommonMark plus tables, footnotes and task lists.
`MARKDOWN_ELIUM`	Markdown with Elium directives (callouts, collapsible sections, assets). Markdown input format is its reference.
`HTML`	Any HTML. Elium maps the tags to its own structure as well as it can.
`HTML_ELIUM`	Canonical Elium HTML, with `el-*` elements for Elium blocks. Exact and lossless.
`SLATE`	The internal format of the editor (Slate).

Whatever the format, Elium converts the body to its internal structure. For content you generate, Markdown is the simplest. To copy content from another system without losing anything, use HTML_ELIUM.

Attributes

An attribute is a structured field defined by a template (see below): a date, a number, a text value, a choice. The ValueWrapperType in the reference lists the value types. Attributes are versioned with the story but are not translated.

Builtins

Builtins have the same shape as attributes, but they do not come from a template. They carry the basic metadata of every story, such as its title or its source.

Template

A template is a StorySchema in the API. You can set one when you create a story, with schemaId. The template gives the story its shape: it can be translated, and it can define a default title, a set of attributes, and a body with text and block placeholders.

Assets

An asset links a file, a URL or another object to a story. Most assets are either part of the body or the story's main asset. The AssetType enum lists the kinds: FILE, URL, USER, STORY, EMAIL, CLOUD_FILE, CLOUD_FOLDER and DRAWING.

You read assets through version.assets. The two common types are FileAsset, an uploaded file, and URLAsset, an external link. Their embed field holds what you usually want: the download address, thumbnails and metadata of a file, or an extract from a web page (a structured summary of it). Get a story with assets shows how to read them.

Main asset and cover

A story can have one main asset, usually a FileAsset or a URLAsset. Elium derives the story's thumbnail from it. To use another image instead, set a coverAsset, which is always a FileAsset and in practice an image.

Actions

story.actions tells you what the current user may do with the story: edit, delete, deleteVersion and so on. Read it before you call a mutation, as Errors explains.

Space

A Space is a container for stories. Types of spaces describes spaces as users see them. When you create a story, you give a spaceId; null stores it in the user's personal content.

A space group contains several spaces. There is no direct link between a story and a space group.

User

Every story needs a User at creation: that user becomes the owner. When a user creates or publishes a version, they are also added to the story's contributors.

What a user may see and change depends on their roles on the platform and in each space. Permissions and visibilities explains the rules; the API applies them to every call.