GenieOS docs

The API is versioned in the URL path (/v1/...). Within a major version, we add fields and endpoints; we do not break existing ones. Breaking changes ship as a new major (/v2/...) with at least 12 months of overlap before the previous major is sunset.

Phase 1 — Developer platform GA

The first developer-facing release. Everything below is live on /v1.

Added — 2026-09-02 · Create page + create design

POST /v1/pages — mint a new landing page from a brief + CTA and compose its tree (scope pages:write). Omitted brandId uses the workspace default brand; 409 brand_required when none exists.
POST /v1/compositions — mint a Designer canvas (default ig-square). New scope compositions:write (included in the Author and Full presets). Existing keys do not gain it until re-issued or the preset is refreshed.
MCP create_page / create_composition.
CLI genie pages create / genie designs create (alias genie compositions create).
SDKs gos.pages.create / gos.designs.create (Node + Python sync/async). gos.compositions is an alias of gos.designs.
In-app Genie chats discover the same ops via platform.find-tools / platform.call-tool — they do not HTTP to MCP.

Added — 2026-08-18 · Archive short links

DELETE /v1/links/{linkId} — soft-delete a short link. The slug stays reserved; visitors are sent to the Link Genie landing page. Mirrored on MCP (archive_short_link) and the Node SDK (gos.links.archive).

Added — 2026-08-08 · Links deep surface — get/patch, analytics, QR, webhooks

GET /v1/links/{linkId} / PATCH /v1/links/{linkId} — read and update short links (password, expiry, scheduled go-live, route rules including city, UTM, labels, tags). Create already accepted the same advanced fields; they are now documented and mirrored on MCP / CLI / SDKs.
GET /v1/links/analytics — click analytics cards (Glow+ rich cards, same gates as the SPA).
POST /v1/qr, PATCH /v1/qr/{qrId}, POST /v1/qr/{qrId}/render — create / update / render QR designs. Formats: svg | png | webp | png-print (2 credits) | pdf print-with-bleed (5 credits, every tier). Optional saveToAssets writes into the workspace DAM.
Custom short domains documented as Spark+ (1 host on Spark / Glow / Ignite; unlimited on Star+), not Ignite+.
Webhooks — link.clicked, link.created, link.updated, link.archived, link.abuse_flagged, link.disabled_for_abuse, link.reinstated (Glow+). Typed on @genie-os/sdk WebhookEventName.
MCP get_short_link, update_short_link, read_link_analytics, create_qr_design, update_qr_design, render_qr_design; widened create_short_link.
CLI genie links get|update|analytics, genie qr create|render.
SDKs Node links.get/update/analytics + qr.*; Python sync/async mirrors the same.

Added — 2026-08-05 · Short-link UTM tagging + prior-value suggestions

POST /v1/links accepts optional utm (source / medium / campaign / content / term), plus tags and domain. UTMs are stamped onto the redirect destination at click time.
GET /v1/links — list existing short links.
GET /v1/links/utm-suggestions — frequency-ranked prior UTM values (same history as the Links designer autocomplete) so agents can suggest reuse before minting.
MCP list_short_links, list_utm_suggestions, and create_short_link (with UTM). Prefer suggestions → offer → create.
CLI genie links create gains --utm-source / --utm-medium / --utm-campaign / --utm-content / --utm-term / --tags.
SDKs @genie-os/sdk links.list / links.utmSuggestions / typed links.create; @genie-os/cli; @genie-os/mcp (stdio bridge — tool schemas always come from the live server).

Added — 2026-07-20 · Email template create + compose

POST /v1/templates — create a blank draft email (scope templates:write). Same seed as New email in the designer.
POST /v1/templates/compose — Genie writes an email from a natural-language prompt and persists it as a draft. Charges compose-template credits; hero image gen off by default (includeHeroImage: true opts in).
MCP create_template / compose_template.
CLI genie templates create / genie templates compose.
SDKs @genie-os/[email protected] — gos.templates.create / gos.templates.compose; Python [email protected] mirrors the same; @genie-os/[email protected].

POST /v1/social/posts mode: "compose" — Genie writes captions from a brief (charges social-post-compose; optional composer sonnet|opus).
GET /v1/social/posts/{id}/analytics?refresh=true — poll provider metrics now (same path as the SPA Refresh button).
POST /v1/social/networks/refresh — re-sync company networks (SPA Networks parity); MCP refresh_social_networks.
MCP create_social_post accepts mode / brief / composer; get_social_post_analytics accepts refresh.

GET /v1/social/networks — connected company social accounts.
/v1/social/posts — create (copy-in), list, read, patch, schedule, publish, delete, and cached analytics. See API reference.
MCP tools list_social_networks, create_social_post, schedule_social_post, publish_social_post, and siblings — see MCP.
Scopes social:posts:read|write|publish (Send / Full presets include publish).
Webhooks social.post.created|scheduled|published|failed|deleted.

Schedule and publish reuse the live SPA stack (Ayrshare + native X / LinkedIn) — not a Firestore-only stamp. Company identities only; personal profiles are never exposed via API/MCP.

Added

REST API surface for workspace, templates, transactional, sequences, events, webhooks, and audit. See API reference and /v1/openapi.json.
Schema contract on every template. Sends are validated server-side; the contract is the source of truth for the SDK codegen.
Idempotency on every mutating endpoint, with a 24-hour deduplication window. See Idempotency.
Per-key + per-workspace rate limits, with X-RateLimit-* headers and Retry-After on 429s. See Rate limits.
Signed webhooks with HMAC-SHA256, exponential-backoff retries (8 attempts over 31 hours), and replay. See Webhooks.
Node SDK @genie-os/sdk — typed end-to-end, ESM + CJS, retries + auto-idempotency + webhook verifier.
Python SDK genieos — sync + async clients, Pydantic-typed, mirrors the Node SDK 1:1.
Genie MCP at mcp.genieos.pro/v1 — native Cursor / Claude / Continue / Zed via Model Context Protocol. See MCP.
@genie-os/mcp stdio bridge for editors that prefer stdio JSON-RPC.
genie CLI — terminal access to the workspace; see CLI.
Audit log queryable from /v1/audit, with actor.kind distinguishing API, MCP, and dashboard writes.

Compatibility

All /v0 endpoints (the closed beta) are now removed. If you\u2019re still on /v0 paths, see the migration notes below.

Migration from `/v0`

Three breaking changes you\u2019ll have hit:

/v0/send is gone. Use POST /v1/transactional/send with template+variables instead of subject+body.
Webhooks now sign with HMAC-SHA256 over t=...|body. The /v0 shape (X-MailGenius-Signature: <hex>) is no longer accepted.
Idempotency-Key is now required on POST /transactional/send for workspaces on the Pro plan and above. The default-failing rejection is validation_error / idempotency_key_invalid.

A /v0 \u2192 /v1 cheat-sheet is available on request — [email protected].

Versioning policy

Additive within a major. New optional fields, new endpoints, new response fields, new event types — all safe to add without bumping the major.
Breaking changes bump the major. Renamed fields, narrowed types, removed endpoints, new required fields, semantic changes to existing fields — all bump.
Deprecation window. A removed endpoint or field is announced via the Deprecation and Sunset HTTP headers at least 6 months before removal, and at least 12 months before the major it lived in is sunset.

If you read Sunset headers off responses, you can subscribe to the api.deprecation webhook event to get a structured copy of the same notice.

RSS / JSON feeds

This page is also served as JSON at https://docs.genieos.pro/changelog.json (coming soon) so changelog crawlers and the dashboard\u2019s "What\u2019s new" panel can ingest it. RSS is on the way.

Want to be told?

The fastest way to hear about API changes is to subscribe a webhook to the api.changelog.published event. Once Phase 2 lands, you\u2019ll also be able to subscribe via genie logs tail --type api.*.

Changelog