{"openapi":"3.1.0","info":{"title":"GenieOS API","version":"2026-05-01","description":"Public REST surface for GenieOS. Auth: Bearer token using a workspace-scoped API key (gos_live_* or gos_test_*). Idempotency via Idempotency-Key header on mutating endpoints. See https://genieos.pro/developers for guides."},"servers":[{"url":"https://api.genieos.pro"}],"paths":{"/v1/workspace":{"get":{"summary":"Resolve token home workspace"}},"/v1/marketing/strategy":{"get":{"summary":"Read live marketing strategy (summary; ?detail=full for full doc)"},"patch":{"summary":"Patch live marketing strategy (same merge as SPA)"}},"/v1/marketing/icps":{"get":{"summary":"List Ideal Customer Profiles"},"post":{"summary":"Create an ICP"}},"/v1/marketing/icps/{icpId}":{"get":{"summary":"Read one ICP"},"patch":{"summary":"Update an ICP"}},"/v1/marketing/creation-defaults":{"get":{"summary":"Read workspace creation defaults (stored + resolved)"},"patch":{"summary":"Merge-patch creation defaults"}},"/v1/creations":{"get":{"summary":"List campaigns / creations with strategy status"},"post":{"summary":"Spawn a campaign (creation)"}},"/v1/creations/{creationId}":{"get":{"summary":"Read one creation (?detail=full for raw CampaignDoc)"}},"/v1/creations/{creationId}/approve-strategy":{"post":{"summary":"Approve campaign strategy and start build"}},"/v1/lists":{"get":{"summary":"List contact lists"},"post":{"summary":"Create a contact list"}},"/v1/lists/{listId}":{"get":{"summary":"Read one contact list"},"patch":{"summary":"Update list metadata"},"delete":{"summary":"Delete a list"}},"/v1/lists/{listId}/members":{"post":{"summary":"Add contacts to a list"}},"/v1/lists/{listId}/members/remove":{"post":{"summary":"Remove contacts from a list"}},"/v1/approvals/policies":{"get":{"summary":"List approval policies by surface"}},"/v1/approvals/policies/{surfaceKind}":{"put":{"summary":"Upsert approval policy for a surface"}},"/v1/approvals/pending":{"get":{"summary":"List pending approval requests"}},"/v1/approvals/pending/{requestId}/decide":{"post":{"summary":"Decide an approval (requires actingAsMemberUid)"}},"/v1/links":{"get":{"summary":"List short links","description":"Newest first. Query: includeArchived=true, limit=1..500 (default 100)."},"post":{"summary":"Create a short link (1 credit)","description":"Body: destinationUrl (required). Optional: slug, label, tags, campaignId, utm (source/medium/campaign/content/term stamped onto the redirect at click time), routeRules (geo/platform/device dynamic routing — first match wins, incl. { kind: \"city\", cities: [...] }) XOR abVariants (Glow+ A/B split — two or more { id, label, destinationUrl, weight }; sticky cookie assignment; not combinable with routeRules), password (plaintext, hashed server-side; every tier), expiresAt / scheduledGoLiveAt (ISO-8601 schedule gates; every tier), domain (Spark+ workspaces with a claimed custom short domain — omit for the shared gogen.ie domain). Prefer GET /v1/links/utm-suggestions first to reuse prior UTM values."}},"/v1/links/utm-suggestions":{"get":{"summary":"List prior UTM values used on workspace short links","description":"Frequency-ranked suggestions for utm_source/medium/campaign/content/term. Query: field=source|medium|campaign|content|term, includeCounts=false."}},"/v1/links/analytics":{"get":{"summary":"Read short-link click analytics (HogQL, cache-first, metered)","description":"Query: cardKey (required — headline|timeseries|geo|geo_city|devices|referrers|utm_campaign|utm_source|utm_medium), linkId (omit for workspace-wide), days=1..365 (default 30), forceRefresh=true. Cache hits are free; misses charge credits per event scanned. Requires Glow tier or above."}},"/v1/links/{linkId}":{"get":{"summary":"Read one short link"},"patch":{"summary":"Update a short link (free)","description":"Free edits to destinationUrl, label, tags, utm, routeRules, abVariants, abAction (pause|resume|conclude + concludedVariantId), expiresAt/scheduledGoLiveAt, and password. Pass clearLabel/clearUtm/clearRouteRules/clearAbVariants/clearExpiresAt/clearScheduledGoLiveAt/clearPassword: true to remove a field. abVariants / abAction are Glow+. A live link cannot have routeRules and an A/B split together — clear one before setting the other."}},"/v1/qr":{"post":{"summary":"Create a QR design (1 credit)","description":"Body: encodes (required — { kind: \"shortLink\", linkId } | { kind: \"static\", payload } | { kind: \"wifi\", ssid, password, encryption } | { kind: \"vcard\", vcardSource }). Optional: label, tags, style (colours/shapes/logo — defaults from the brand kit), frame. Does not render bytes — call POST /v1/qr/{qrId}/render for that."}},"/v1/qr/{qrId}":{"patch":{"summary":"Update a QR design (free — style/frame/label/tags)","description":"Does not re-render bytes; call POST /v1/qr/{qrId}/render afterwards for a fresh preview/download."}},"/v1/qr/{qrId}/render":{"post":{"summary":"Render a QR design to bytes","description":"Body: format=svg|png|webp|png-print|pdf (default png), size=128..2048 (web formats only), saveToAssets=true to write the render into the workspace Asset Manager. svg/png/webp are free; png-print costs 2 credits, pdf costs 5. Returns fileBase64 (raw bytes, base64-encoded, no data: prefix)."}},"/v1/pages":{"get":{"summary":"List landing pages"},"post":{"summary":"Create a landing page from a brief and compose its tree","description":"Body: brief or intake.headlineAngle (required), objective, ctaLabel, ctaUrl, slug, vibe, length, brandId, blank. Requires pages:write. Charges compose-page credits."}},"/v1/compositions":{"post":{"summary":"Create a Designer composition (canvas)","description":"Body: name, brief, and a size — cropPresetId from GET /v1/compositions/sizes (e.g. li-banner, print-a4-landscape, custom-1600x900), or width + height in pixels (16–8192; an exact preset match is used when one exists). Default ig-square. The brief names the design; it does not lay it out. Requires compositions:write."}},"/v1/compositions/sizes":{"get":{"summary":"List every Designer canvas size (social, email, print) with ids, labels and pixels"}},"/v1/pages/{idOrSlug}":{"get":{"summary":"Read one landing page (metadata)"}},"/v1/pages/{idOrSlug}/compose":{"post":{"summary":"Compose (and optionally persist) a page tree"}},"/v1/pages/{idOrSlug}/publish":{"post":{"summary":"Publish a landing page"}},"/v1/pages/{idOrSlug}/unpublish":{"post":{"summary":"Unpublish a landing page"}},"/v1/lead-magnets":{"get":{"summary":"List lead magnets (document pages)"},"post":{"summary":"Create a lead magnet from a brief and compose its tree","description":"Body: brief (required), headlineAngle, objective, vibe, length, ctaLabel, ctaUrl, slug, brandId, themeId, document (format, pageSize, length, nextStep). Requires pages:write. Charges compose-page credits."}},"/v1/lead-magnets/{idOrSlug}":{"get":{"summary":"Read one lead magnet (metadata + document settings)"}},"/v1/lead-magnets/{idOrSlug}/compose":{"post":{"summary":"Recompose a lead magnet from a new brief"}},"/v1/lead-magnets/{idOrSlug}/publish":{"post":{"summary":"Publish to a public download page + .pdf link (exports first if changed)"}},"/v1/lead-magnets/{idOrSlug}/unpublish":{"post":{"summary":"Take the download page and PDF link down"}},"/v1/lead-magnets/{idOrSlug}/export":{"post":{"summary":"Export lead magnet to PDF","description":"Renders the document to PDF, uploads to Cloud Storage, and creates an asset. Requires pages:export. Charges 1 credit (or free if unchanged content). Returns assetId, downloadUrl, unchanged."}},"/v1/social/networks/refresh":{"post":{"summary":"Re-sync company social networks from the provider"}},"/v1/templates":{"get":{"summary":"List templates"},"post":{"summary":"Create a blank draft email template"}},"/v1/templates/compose":{"post":{"summary":"Compose an email from a brief and persist it"}},"/v1/templates/{key}":{"get":{"summary":"Get template by key"}},"/v1/templates/{key}/render":{"post":{"summary":"Render template"}},"/v1/templates/{key}/send":{"post":{"summary":"Send template (idempotent)"}},"/v1/messaging/transactional/kit":{"get":{"summary":"List installed transactional SMS templates"}},"/v1/messaging/transactional/catalog":{"get":{"summary":"Browse platform transactional SMS reserved keys"}},"/v1/messaging/transactional/preview":{"post":{"summary":"Preview a transactional SMS with variables"}},"/v1/messaging/transactional":{"post":{"summary":"Send transactional SMS by reserved template key"}},"/v1/messaging/transactional/deliveries":{"get":{"summary":"List recent transactional SMS deliveries"}},"/v1/social/transactional/catalog":{"get":{"summary":"Browse reserved Transactional Socials event keys"}},"/v1/social/transactional/templates":{"get":{"summary":"List installed Transactional Socials templates"}},"/v1/social/transactional/preview":{"post":{"summary":"Render a Transactional Socials event without posting"}},"/v1/social/transactional/events":{"get":{"summary":"List recent Transactional Socials event runs"},"post":{"summary":"Trigger a Transactional Socials event in preview, draft, or publish mode"}},"/v1/social/networks":{"get":{"summary":"List connected company social networks (organic)"}},"/v1/social/posts":{"get":{"summary":"List organic social posts"},"post":{"summary":"Create organic social post(s) — mode copy|compose|hold (hold = free content-plan slot)"}},"/v1/campaigns/planned":{"post":{"summary":"Create a planned email holding (dated draft campaign, no template yet)"}},"/v1/content-plan":{"get":{"summary":"Everything dated in a window (?from&to&kinds=social,email,blog) — holdings, drafts and live items, each with appUrl"}},"/v1/content-plan/runs":{"get":{"summary":"Recent weekly Planner runs"},"post":{"summary":"Start the weekly Planner for a week (default next Monday)"}},"/v1/content-plan/runs/{runId}":{"get":{"summary":"Planner run: stage, open gate, analysis, plan, drafts with appUrl"}},"/v1/content-plan/runs/{runId}/decide":{"post":{"summary":"Approve a gate, answer a question, drop / keep ideas, or stop"}},"/v1/market-news":{"get":{"summary":"Curated Market News articles and post ideas from recent briefs"}},"/v1/market-news/{dayYmd}/items/{itemId}/vote":{"post":{"summary":"Vote an article useful / not useful (null clears)"}},"/v1/blog/posts":{"get":{"summary":"List blog articles (?status=draft|published)"},"post":{"summary":"Create a blog article — title + brief + scheduledAt = planned holding; with bodyHtml = draft"}},"/v1/blog/posts/{postId}":{"get":{"summary":"Read a blog article"},"patch":{"summary":"Update a blog article (merges; live articles need blog:publish)"}},"/v1/blog/posts/{postId}/publish":{"post":{"summary":"Publish a blog article live"}},"/v1/approvals/requests":{"post":{"summary":"Submit social posts / pages / emails / sequences for approval"}},"/v1/approvals/requests/{requestId}":{"get":{"summary":"Read one approval request with its review link"}},"/v1/workspace/members":{"get":{"summary":"Workspace members — uids for actingAsMemberUid and reviewers"}},"/v1/social/posts/{postId}":{"get":{"summary":"Read an organic social post"},"patch":{"summary":"Update a draft/ready organic social post"},"delete":{"summary":"Delete a draft/ready post; ?fromProvider=true also removes from the network"}},"/v1/social/posts/{postId}/schedule":{"post":{"summary":"Schedule an organic post via Ayrshare or native X/LinkedIn (idempotent)"}},"/v1/social/posts/{postId}/publish":{"post":{"summary":"Publish an organic post now (idempotent)"}},"/v1/social/posts/{postId}/analytics":{"get":{"summary":"Read cached engagement metrics for a published post"}},"/v1/templates/{key}/schema":{"get":{"summary":"Inspect declared/observed/pending schema contract"}},"/v1/templates/{key}/change-requests":{"get":{"summary":"List schema change requests"},"post":{"summary":"Open a schema change request"}},"/v1/templates/{key}/change-requests/{cid}/ack":{"post":{"summary":"Acknowledge (accept/reject) a schema change request"}},"/v1/sequences":{"get":{"summary":"List published sequences"}},"/v1/sequences/{keyOrId}":{"get":{"summary":"Get sequence by key or id"}},"/v1/sequences/{keyOrId}/graph":{"patch":{"summary":"Atomically patch a sequence graph with SMP operations"}},"/v1/sequences/{keyOrId}/simulate":{"post":{"summary":"Simulate a sequence without side effects"}},"/v1/sequences/{keyOrId}/runs":{"get":{"summary":"List recent sequence runs"}},"/v1/sequences/{keyOrId}/enroll":{"post":{"summary":"Enroll a contact (idempotent)"}},"/v1/sequence-runs/{runId}":{"get":{"summary":"Inspect a sequence run"}},"/v1/sequence-runs/{runId}/actions":{"post":{"summary":"Pause, resume, retry, skip, or force-timeout a run"}},"/v1/sequence-runs/{runId}/cancel":{"post":{"summary":"Cancel an active run"}},"/v1/flows/{flowKey}/enroll":{"post":{"summary":"Legacy alias for /v1/sequences/{flowKey}/enroll"}},"/v1/subjects":{"post":{"summary":"Upsert subject (legacy)"}},"/v1/events":{"post":{"summary":"Emit a customer event (PRD §10.3). Triggers any matching event.matches sequences."}},"/v1/stats/templates/{key}":{"get":{"summary":"Template stats"}},"/v1/sends":{"get":{"summary":"List sends (createdAt desc). One of templateKey|status|to|apiKeyId + optional since/until."}},"/v1/sends/{id}":{"get":{"summary":"SendPublic status + events timeline"}},"/v1/brand":{"get":{"summary":"List brands"}},"/v1/brand/{id}":{"get":{"summary":"Get brand by id (or \"default\")"}},"/v1/connectors/catalog":{"get":{"summary":"Public connector catalog (unauthenticated)"}},"/v1/connectors":{"get":{"summary":"List the workspace's installed connectors"}},"/v1/keys":{"get":{"summary":"List the workspace's API keys"}},"/v1/keys/{id}":{"get":{"summary":"Inspect a single API key"}},"/v1/webhooks":{"get":{"summary":"List webhook subscriptions"},"post":{"summary":"Create a webhook subscription"}},"/v1/webhooks/{id}":{"get":{"summary":"Inspect a webhook subscription"},"patch":{"summary":"Update a webhook subscription (events / disabled flag)"},"delete":{"summary":"Delete a webhook subscription"}},"/v1/audit":{"get":{"summary":"Paginated audit event log"}}},"x-idempotency-key":{"description":"Mutating endpoints (templates/send, sequences/enroll, events) accept Idempotency-Key. 24h dedup window per workspace per key. Same key + same body replays cached response (Idempotency-Replay: true header). Same key + different body returns 409 idempotency_conflict."}}