​
What You’ll Build

A simple Todo Manager app — Native HTTP, API key auth, 3 actions (todo.create, todo.list, todo.complete). By the end of this guide you’ll have:
  1. A running HTTP endpoint that Orceum can call
  2. An app registered in the Orceum Developer Studio
  3. The app installed from the Orceum Store so a user can actually use it

​
Step 1 — Write Your Endpoint

Deploy an HTTP server that handles Orceum action calls. Orceum will POST to it with { event, event_data, timestamp }.
app.py
from fastapi import FastAPI, Header, Request

app = FastAPI()
todos = {}

@app.post("/orceum/actions")
async def handle(
    request: Request,
    x_orceum_installation_id: str = Header(...),
):
    body = await request.json()
    event = body["event"]
    params = body["event_data"]

    if event == "todo.create":
        tid = str(len(todos) + 1)
        todos[tid] = {"id": tid, "title": params["title"], "done": False}
        return {"status": "success", "data": {"todo_id": tid}}

    if event == "todo.list":
        return {"status": "success", "data": {"todos": list(todos.values())}}

    if event == "todo.complete":
        todo = todos.get(params["todo_id"])
        if not todo:
            return {"status": "error", "error": {"message": "Not found"}}
        todo["done"] = True
        return {"status": "success", "data": {"message": f"Done: {todo['title']}"}}

    return {"status": "error", "error": {"message": f"Unknown event: {event}"}}
X-Orceum-Installation-Id is sent on every call. Use it to scope data to the specific user whose assistant triggered the action.
Deploy this somewhere publicly reachable (Railway, Render, Fly, AWS Lambda — anything works). You’ll need the URL in the next step.

​
Step 2 — Create Your App in the Developer Studio

Go to orceum.com/developer-studio and create a new app. You’ll fill in:
FieldValue
NameTodo Manager
DescriptionCreate, list, and manage todo items
App TypeNative
Endpoint URLhttps://your-app.example.com/orceum/actions
Auth TypeAPI Key
Then add your manifest — the list of actions your app exposes. For this app: 
{
  "actions": [
    {
      "event": "todo.create",
      "description": "Create a new todo item for the user",
      "parameters": [
        { "name": "title", "type": "string", "description": "The todo title", "required": true }
      ]
    },
    {
      "event": "todo.list",
      "description": "List all the user's todo items",
      "parameters": []
    },
    {
      "event": "todo.complete",
      "description": "Mark a todo item as complete",
      "parameters": [
        { "name": "todo_id", "type": "string", "description": "ID of the todo to complete", "required": true }
      ]
    }
  ]
}
Write your action descriptions in plain English — the AI reads them to decide when and how to use your app. The clearer the description, the better the results.
Hit Create App. Your app is now registered and gets an app_id.

​
Step 3 — Install the App from the Orceum Store

Once your app is registered, it appears in the Orceum Store (or you can share a direct install link). A user installs it from there — this is what creates an installation, the per-user binding that holds their credentials. For API key apps, the install flow prompts the user to enter their API key. Orceum encrypts it and automatically injects it into every call using the custom header you defined during app creation (or X-API-Key by default).
During development, you can install your own app. Go to the Orceum Store, find your app, and hit Install. Enter my-secret-key as the API key — this is what your local server will validate against.

​
Step 4 — Test It

Say to your Orceum assistant: “Create a todo: Buy groceries” Orceum calls your endpoint: 
POST /orceum/actions
X-Orceum-Installation-Id: f47ac10b-...
X-API-Key: my-secret-key

{
  "event": "todo.create",
  "event_data": { "title": "Buy groceries" },
  "timestamp": "2026-04-15T10:30:00.000000+00:00"
}
Your app returns: 
{ "status": "success", "data": { "todo_id": "1" } }
The assistant tells the user: “Done! Created your todo: Buy groceries.” Try the others:
  • “List my todos” → triggers todo.list
  • “Mark todo 1 as done” → triggers todo.complete

​
What’s Next

The Manifest

Write descriptions the AI uses correctly every time

Authentication

API key, OAuth 2.0, and no-auth options

Webhooks

Push events from your app back to Orceum

MCP Apps

Build with the Model Context Protocol