Introduction

The Olamma API lets your own servers read and change your workspace: the same data your team works with in Olamma, with the same permissions.

What you can do

• Keep systems in step. Send orders, customers or sign-ups from your app into a table as they happen.
• Build on your data. Read records into reports, dashboards or another tool, page by page.
• Automate safely. Writes are attributed to the key that made them, can be retried without doubling up, and risky ones wait for a person to approve.

How it is organised

Everything sits under one address for your workspace. Each app in the workspace, such as Tables, has its own endpoints beneath it, and every app shares the same keys, errors, paging and retry rules, so once you know one you know them all.

https://api.olamma.sh/v1/w/your-workspace

Replace your-workspace with your workspace’s name as it appears in Olamma’s web address. Apps that aren’t in the API yet are listed in the API reference.

Quickstart

1. Create a key. In Olamma, open Settings → Agents, add an agent, give it access to the apps it needs and copy its key. The key is shown once. More on keys.
2. Keep it on your server. Put it in an environment variable, such as OLAMMA_KEY. Never put it in a browser, a phone app or your code repository.
3. Make your first call. Ask who the key is:
   cURLJavaScriptPython

   curl "https://api.olamma.sh/v1/w/your-workspace/me" \
     -H "Authorization: Bearer $OLAMMA_KEY"

   const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/me`, {
     headers: {
       Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
     },
   });
   const data = await response.json();
   if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

   import os
   import requests
   
   response = requests.get(
       "https://api.olamma.sh/v1/w/your-workspace/me",
       headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}"},
       timeout=30,
   )
   data = response.json()
   response.raise_for_status()

   It answers with the agent the key acts as, what it may do, and how many writes it has left today:
   Response 200

   {
     "identity": "53f3b4fc1f2f430dbb62286fa0588c84.key",
     "kind": "agent",
     "name": "Orders sync",
     "owner": "ada@yourcompany.com",
     "role": "member",
     "grants": { "tables": "write" },
     "limits": { "dailyWrites": 1000, "usedToday": 12 },
     "expiresAt": null
   }

4. Call an app. For example, list the bases in Tables to find a table, then read it. Working with Tables walks through it end to end.

Where next