About the API
The Elium API is a GraphQL API: what it covers, how it names things, where the reference is and how to read these guides.
One address, one language
The Elium API is a GraphQL API. Every query and every mutation goes to the same address:
https://your-platform-name.elium.com/graphql
GraphQL lets you ask for exactly the fields you need, and nothing else, in one request. You describe the shape of the answer, and the server returns a JSON document with that shape under a data key.
Any HTTP client can call it. Any GraphQL library can too. These guides use Insomnia, a free desktop client, because it handles the sign-in and shows the schema while you type.
How a program signs in
A program authenticates with OAuth 2.0, as a connected app that a system administrator registers once in Settings > Advanced > Connected apps. The app receives a client ID and a client secret, and each user approves it before it acts on their behalf. API and connected applications describes the registration. Authentication describes the token exchange.
AI assistants such as ChatGPT or Claude do not need the API: Elium also offers a Model Context Protocol (MCP) server, which these assistants connect to without any code. See About MCP.
The words the API uses
The API keeps the names Elium used when it was built. The interface has since renamed some of them.
| In the API | In the interface |
|---|---|
Story | Article |
StorySchema | Template |
Facet | Category (a family of tags) |
Instance | Platform |
These guides say "story" when they mean the API object, because that is the word you will type.
Where to look things up
- The GraphQL reference lists every type, query and mutation with its fields and arguments.
- Your own platform describes itself. GraphQL clients read the schema through introspection, so Insomnia completes field names as you type and shows the documentation of each one.
- Markdown input format is the reference for the Markdown that Elium imports, which is one of the body formats the API accepts.
How to read these guides
- Getting started takes you from a connected app to your first query (Quick start). It then explains the OAuth flows in detail (Authentication) and the one GraphQL idea you need before anything else (GraphQL IDs and nodes).
- Main concepts describes the objects and how they relate to each other (Stories, spaces and users), and how mutations report problems (Errors).
- How to gives a worked example for each common action, from reading a story to asking Elium Answer a question.