DEVELOPERS

API reference

Integrate directly against the Roami REST API. Defaults to the beta-scoped surface; switch to Full catalog for non-beta keys.

Beta Full catalog

Showing the beta-scoped catalog. Switch to Full catalog if your key is not beta-restricted.

Authentication

Base URL: https://api.roami.xyz

Send either header. Bearer tokens that start with sk_ are treated as API keys; other Bearer tokens are treated as session JWTs.

Authorization: Bearer sk_...
x-api-key: sk_...

curl 'https://api.roami.xyz/api/posts' \
  -H 'Authorization: Bearer sk_...'

Posts & Ideas

Create and update drafts, search content, manage ideas, and link related posts. Beta MCP tools: create_post, update_post, get_post, get_post_content, search_content, create_idea, get_idea, update_idea, link_related_posts.

Not available to beta keys

Direct publish (POST /api/posts/:id/publish returns 403 for beta keys)
Newsletter send
Affiliate link management
API key mint/revoke

GET/api/posts

List posts for the authenticated project.

Request: Optional query: status, search, limit, offset.

Response: { success, data: Post[] }

curl -X GET 'https://api.roami.xyz/api/posts?status=DRAFT&limit=20' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

POST/api/posts

Create a post (defaults to DRAFT).

Request: { title, slug?, content?, projectId, status? }

Response: { success, data: Post }

curl -X POST 'https://api.roami.xyz/api/posts' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Notes from the road","projectId":"..."}'

GET/api/posts/:id

Fetch a post by id (includes blocks, tags, places when requested).

Response: { success, data: Post }

curl -X GET 'https://api.roami.xyz/api/posts/POST_ID' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

PUT/api/posts/:id

Update post fields; can set placeIds and related post links.

Request: { title?, content?, placeIds?, relatedPostIds?, ... }

Response: { success, data: Post }

curl -X PUT 'https://api.roami.xyz/api/posts/POST_ID' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Updated title","relatedPostIds":["OTHER_ID"]}'

POST/api/posts/:id/publish

Publish a draft post.

Response: { success, data: Post } or 403 for beta keys

Beta API keys receive 403. Publish from the CMS instead: https://app.roami.xyz

curl -X POST 'https://api.roami.xyz/api/posts/POST_ID/publish' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

POST/api/posts/:id/tags

Attach tags to a post (MCP: attach_tag_to_post).

Request: { tagIds: string[] }

Response: { success, data }

curl -X POST 'https://api.roami.xyz/api/posts/POST_ID/tags' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"tagIds":["TAG_ID"]}'

GET/api/ideas

List ideas for the project.

Response: { success, data: Idea[] }

curl -X GET 'https://api.roami.xyz/api/ideas' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

POST/api/ideas

Create an idea.

Request: { title, description?, projectId }

Response: { success, data: Idea }

curl -X POST 'https://api.roami.xyz/api/ideas' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Essay angle","projectId":"..."}'

GET/api/ideas/:id

Fetch one idea.

Response: { success, data: Idea }

curl -X GET 'https://api.roami.xyz/api/ideas/IDEA_ID' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

PUT/api/ideas/:id

Update an idea.

Request: { title?, description?, status? }

Response: { success, data: Idea }

curl -X PUT 'https://api.roami.xyz/api/ideas/IDEA_ID' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Refined angle"}'

Media

Images, galleries, videos, and photo stories (reels). Beta MCP tools: list_images, update_image, list/create/update galleries, list/update videos, photo story CRUD + photo set helpers.

Not available to beta keys

Bulk media hygiene mutations (bulk_fix_media_hygiene)
Newsletter / affiliate surfaces

GET/api/media/images

List media library images.

Request: Optional query: search, folderId, limit.

Response: { success, data: Image[] }

curl -X GET 'https://api.roami.xyz/api/media/images?limit=50' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

PUT/api/media/images/:id

Update image metadata (title, alt, caption, GPS).

Request: { title?, altText?, caption?, latitude?, longitude? }

Response: { success, data: Image }

curl -X PUT 'https://api.roami.xyz/api/media/images/IMAGE_ID' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"altText":"Sunrise over the ridge"}'

GET/api/galleries

List galleries.

Response: { success, data: Gallery[] }

curl -X GET 'https://api.roami.xyz/api/galleries' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

POST/api/galleries

Create a gallery.

Request: { title, projectId, description? }

Response: { success, data: Gallery }

curl -X POST 'https://api.roami.xyz/api/galleries' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Coast road","projectId":"..."}'

PUT/api/galleries/:id

Update gallery metadata or membership.

Response: { success, data: Gallery }

curl -X PUT 'https://api.roami.xyz/api/galleries/GALLERY_ID' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Coast road — edit"}'

GET/api/videos

List videos.

Response: { success, data: Video[] }

curl -X GET 'https://api.roami.xyz/api/videos' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

PUT/api/videos/:id

Update video metadata.

Response: { success, data: Video }

curl -X PUT 'https://api.roami.xyz/api/videos/VIDEO_ID' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Market walk"}'

GET/api/reels

List photo stories (reels).

Response: { success, data: Reel[] }

curl -X GET 'https://api.roami.xyz/api/reels' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

POST/api/reels

Create a photo story.

Request: { title, projectId, ... }

Response: { success, data: Reel }

curl -X POST 'https://api.roami.xyz/api/reels' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Weekend strip","projectId":"..."}'

GET/api/reels/:id

Fetch one photo story (MCP: get_photo_story).

Response: { success, data: Reel }

curl -X GET 'https://api.roami.xyz/api/reels/REEL_ID' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

PUT/api/reels/:id

Update photo story fields and photo membership.

Response: { success, data: Reel }

curl -X PUT 'https://api.roami.xyz/api/reels/REEL_ID' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Weekend strip — v2"}'

Places

Geographic places linked to posts. Beta MCP tools: search_places, create_place, link_post_places.

Not available to beta keys

Landing-page place curation tools (full catalog)

GET/api/places/search

Search places by name/region.

Request: Query: q (required).

Response: { success, data: Place[] }

curl -X GET 'https://api.roami.xyz/api/places/search?q=Chiang%20Mai' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

POST/api/places

Create a place.

Request: { name, country?, region?, latitude?, longitude?, projectId }

Response: { success, data: Place }

curl -X POST 'https://api.roami.xyz/api/places' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Chiang Mai","country":"Thailand","projectId":"..."}'

PUT/api/posts/:id

Link places to a post via placeIds (MCP: link_post_places).

Request: { placeIds: string[] }

Response: { success, data: Post }

curl -X PUT 'https://api.roami.xyz/api/posts/POST_ID' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"placeIds":["PLACE_ID"]}'

Trip Journal

Trip capture pipeline (logs → scaffold). Beta MCP tools: list_trip_journals, create_trip_journal, get_trip_journal, add_trip_journal_log, create_journal_entry.

Not available to beta keys

Newsletter / affiliate / key management

GET/api/trip-journal/trips

List trip journals for the caller.

Response: { success, data: TripJournal[] }

curl -X GET 'https://api.roami.xyz/api/trip-journal/trips' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

POST/api/trip-journal/trips

Create a trip journal.

Request: { title, startDate?, endDate? }

Response: { success, data: TripJournal }

curl -X POST 'https://api.roami.xyz/api/trip-journal/trips' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Leh road trip"}'

GET/api/trip-journal/trips/:id

Fetch one trip with logs.

Response: { success, data: TripJournal }

curl -X GET 'https://api.roami.xyz/api/trip-journal/trips/TRIP_ID' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json'

POST/api/trip-journal/trips/:id/logs

Add a log entry to a trip (MCP: add_trip_journal_log).

Request: { text, loggedAt?, placeName? }

Response: { success, data }

curl -X POST 'https://api.roami.xyz/api/trip-journal/trips/TRIP_ID/logs' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"text":"Crossed the pass at 16:00"}'

POST/api/journals

Create a journal entry (MCP: create_journal_entry).

Request: { content, mood?, projectId, ... }

Response: { success, data: JournalEntry }

curl -X POST 'https://api.roami.xyz/api/journals' \
  -H 'Authorization: Bearer sk_...' \
  -H 'Content-Type: application/json' \
  -d '{"content":"Quiet morning.","projectId":"..."}'

Hygiene (read-only)

Read-only SEO and media audits. Exposed as MCP tools (no dedicated REST routes). Beta allowlist includes both audit tools so partners can check drafts before CMS review.

Not available to beta keys

fix_content_metadata
fix_content_relations
bulk_fix_media_hygiene

MCP tools

audit_content_hygiene

Audit a post or landing page for metadata, internal links, places, media coverage, and block structure.

audit_media_hygiene

Audit image metadata (title, alt, caption, GPS) for a post, gallery, or project-wide.

Authentication

Posts & Ideas

Media

Tags

Places

Trip Journal

Hygiene (read-only)