Working with Pages

Pages holds the documents your team writes: policies, specs, notes and plans. This guide creates a page from Markdown, changes it safely, asks for a review and goes back to an earlier version.

How it fits together

Page	A document with an id like `pg_…`. You read and write it as Markdown.
Project	Where a top-level page belongs: `general`, a product key, or a custom project. Project access decides who can see and edit it.
Nesting and folders	Pages nest inside pages, three levels deep. Folders file top-level pages within a project.
Versions	Saved as people edit. Any version can be restored, and the restore is itself saved.
Comments	Threads on a paragraph or on the whole page. They never change the page.

From a new page to a reviewed one

Create a page from Markdown. It goes at the top of a project unless you give a parent page or a folder.

cURLJavaScriptPython

curl -X POST "https://api.olamma.sh/v1/w/your-workspace/pages" \
  -H "Authorization: Bearer $OLAMMA_KEY" \
  -H "Idempotency-Key: policy-refunds-create" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund policy",
    "markdown": "# Refund policy\n\nWe refund within 14 days of purchase.",
    "project": "general",
    "icon": "hi:receipt"
  }'

const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/pages`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
    "Idempotency-Key": "policy-refunds-create",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "title": "Refund policy",
    "markdown": "# Refund policy\n\nWe refund within 14 days of purchase.",
    "project": "general",
    "icon": "hi:receipt"
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

import os
import requests

response = requests.post(
    "https://api.olamma.sh/v1/w/your-workspace/pages",
    headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}", "Idempotency-Key": "policy-refunds-create"},
    json={
        "title": "Refund policy",
        "markdown": "# Refund policy\n\nWe refund within 14 days of purchase.",
        "project": "general",
        "icon": "hi:receipt"
    },
    timeout=30,
)
data = response.json()
response.raise_for_status()

Read it. You get Markdown, its version, where it sits, and its open comments.

cURLJavaScriptPython

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

const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/pages/pg_…`, {
  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/pages/pg_…",
    headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}"},
    timeout=30,
)
data = response.json()
response.raise_for_status()

Change it safely. Send the version you read as expectedVersion; if someone saved in between, nothing is written and you get conflict.

cURLJavaScriptPython

curl -X PATCH "https://api.olamma.sh/v1/w/your-workspace/pages/pg_…" \
  -H "Authorization: Bearer $OLAMMA_KEY" \
  -H "Idempotency-Key: policy-refunds-retitle" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Refund policy (2027)",
    "expectedVersion": 3
  }'

const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/pages/pg_…`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
    "Idempotency-Key": "policy-refunds-retitle",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "title": "Refund policy (2027)",
    "expectedVersion": 3
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

import os
import requests

response = requests.patch(
    "https://api.olamma.sh/v1/w/your-workspace/pages/pg_…",
    headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}", "Idempotency-Key": "policy-refunds-retitle"},
    json={
        "title": "Refund policy (2027)",
        "expectedVersion": 3
    },
    timeout=30,
)
data = response.json()
response.raise_for_status()

Or add to the end without touching the rest; this never overwrites anyone.

cURLJavaScriptPython

curl -X POST "https://api.olamma.sh/v1/w/your-workspace/pages/pg_…/append" \
  -H "Authorization: Bearer $OLAMMA_KEY" \
  -H "Idempotency-Key: policy-refunds-note-1201" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "## Update, 1 December\n\nRefunds now go back to the original card."
  }'

const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/pages/pg_…/append`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
    "Idempotency-Key": "policy-refunds-note-1201",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "markdown": "## Update, 1 December\n\nRefunds now go back to the original card."
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

import os
import requests

response = requests.post(
    "https://api.olamma.sh/v1/w/your-workspace/pages/pg_…/append",
    headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}", "Idempotency-Key": "policy-refunds-note-1201"},
    json={
        "markdown": "## Update, 1 December\n\nRefunds now go back to the original card."
    },
    timeout=30,
)
data = response.json()
response.raise_for_status()

Ask for a review with a comment on the paragraph you mean, rather than editing someone’s words.

cURLJavaScriptPython

curl -X POST "https://api.olamma.sh/v1/w/your-workspace/pages/pg_…/comments" \
  -H "Authorization: Bearer $OLAMMA_KEY" \
  -H "Idempotency-Key: policy-refunds-question" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Should annual plans get 30 days?",
    "nearText": "within 14 days"
  }'

const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/pages/pg_…/comments`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
    "Idempotency-Key": "policy-refunds-question",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "body": "Should annual plans get 30 days?",
    "nearText": "within 14 days"
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

import os
import requests

response = requests.post(
    "https://api.olamma.sh/v1/w/your-workspace/pages/pg_…/comments",
    headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}", "Idempotency-Key": "policy-refunds-question"},
    json={
        "body": "Should annual plans get 30 days?",
        "nearText": "within 14 days"
    },
    timeout=30,
)
data = response.json()
response.raise_for_status()

Markdown you can use

Headings	`# Title, ## Section, ### Sub-section`
Lists and to-dos	`- item, 1. item, - [ ] to-do, - [x] done`
Text styles	bold, _italic_, `code`, ~~strike~~, ==highlight==
Blocks	> quote, ``` code fences ```, tables with \| pipes \|, --- divider
Links	`[text](https://…), [[pg_…]] to another page, task ids like APP-12`

Writing Markdown with Update page replaces the whole page. Use Append to page to add, and comments to suggest.

Versions

List versions shows saved versions, newest first. To go back, restore one with the page’s current version as baseVersion; the page before the restore stays in the history, so nothing is lost.

cURLJavaScriptPython

curl -X POST "https://api.olamma.sh/v1/w/your-workspace/pages/pg_…/versions/pv_…/restore" \
  -H "Authorization: Bearer $OLAMMA_KEY" \
  -H "Idempotency-Key: policy-refunds-rollback" \
  -H "Content-Type: application/json" \
  -d '{
    "baseVersion": 7
  }'

const response = await fetch(`https://api.olamma.sh/v1/w/your-workspace/pages/pg_…/versions/pv_…/restore`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OLAMMA_KEY}`,
    "Idempotency-Key": "policy-refunds-rollback",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "baseVersion": 7
  }),
});
const data = await response.json();
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`);

import os
import requests

response = requests.post(
    "https://api.olamma.sh/v1/w/your-workspace/pages/pg_…/versions/pv_…/restore",
    headers={"Authorization": f"Bearer {os.environ['OLAMMA_KEY']}", "Idempotency-Key": "policy-refunds-rollback"},
    json={
        "baseVersion": 7
    },
    timeout=30,
)
data = response.json()
response.raise_for_status()

Finding pages

List pages without query gives the outline (titles, no content). With query, it finds pages whose title or text has every word, each with a snippet.

Trash and publishing

Move to Trash takes the pages inside with it; Restore page brings them all back. A page in Trash answers conflict until it’s restored.
Publish page only proposes: a person approves it in Olamma, and only if public pages are on for the workspace. You get 202; see Approvals.

Page text can come from anyone with access, and published pages may quote outside sources. Answers list it under untrusted; see Untrusted text.