Auth: Send
Authorization: Bearer <token>. Two token types work:
- Typely API key (recommended for AI / scripts) — create one at
Account → API Keys. Format:
typly_sk_….
Scope each key to read or read+write, pick which modules it can touch
(page, theme, seo, blogs,
integrations, sites, lifecycle), and set an expiry.
- Kinde JWT — an access_token or id_token from your Kinde tenant, if you'd rather
use Kinde-managed identities.
Plan gate: Content and configuration endpoints require the target site to be on the
Pro plan — other tiers return
403 pro_required. Lifecycle endpoints (create, upgrade, downgrade) work for any authenticated user regardless of the target site's plan, so you can bootstrap a new Pro site entirely from the API.
Responses: success →
{"data": …, "meta": …}. Errors →
{"error": {"code": …, "message": …}}.
Auth & Identity
Send Authorization: Bearer <token>. Two token types are accepted: a Typely API key (typly_sk_…, managed at Account → API Keys) — recommended for scripts and AI assistants; or a Kinde JWT if you'd rather use Kinde-managed identities. Content/config endpoints require the target site to be on Pro.
GET
/api/v1/me
Return the authenticated user and the sites they can operate on.
Any valid Typely API key or Kinde token.
curl -H 'Authorization: Bearer $TYPELY_TOKEN' https://dev.hellotypely.io/api/v1/me
Sites
Site-level basics. Mirrors the Basics tab in the dashboard.
GET
/api/v1/sites
List your Pro sites.
GET
/api/v1/sites/{site_id}
Read a single site.
PATCH
/api/v1/sites/{site_id}
Update site_name, page_title, adult, profile_picture.
Site lifecycle
Create new sites and change plans. Lifecycle endpoints are available to any authenticated user — you don't need Pro to create a site or to upgrade one. Payment happens in a browser via a Stripe Checkout URL we return; the API never collects card data directly.
POST
/api/v1/sites
Create a Free site. Body: <code>{subdomain, site_name?}</code>. Enforces the 3-free-site cap and the subdomain moderation blocklist.
POST
/api/v1/sites/{site_id}/upgrade
Return a Stripe Checkout URL to upgrade this site to a paid plan. Body: <code>{plan_code: 'basic'|'pro', interval?: 'month'|'year'}</code>. Defaults to Pro monthly.
POST
/api/v1/sites/{site_id}/downgrade
Downgrade the site. Body: <code>{target: 'free'|'basic', confirm: 'downgrade_<subdomain>'}</code>. Confirm phrase must match verbatim.
Page + Draft
Markdown content, mirrors /dashboard/page.
GET
/api/v1/sites/{site_id}/page
Read the published Markdown.
PUT
/api/v1/sites/{site_id}/page
Replace the published page. Body: JSON {markdown: '...'} or text/plain.
GET
/api/v1/sites/{site_id}/draft
Read the current draft (falls back to published).
PUT
/api/v1/sites/{site_id}/draft
Save a draft.
POST
/api/v1/sites/{site_id}/draft/publish
Promote draft → published, delete the draft.
DELETE
/api/v1/sites/{site_id}/draft
Discard the current draft.
Styling
Theme name + color palette. Mirrors the Styling right-panel.
GET
/api/v1/sites/{site_id}/theme
Current theme + colors + valid theme list.
PUT
/api/v1/sites/{site_id}/theme
Update theme + optional colors. Regenerates the CSS file.
SEO
Description, OG image, keywords, robots directive.
GET
/api/v1/sites/{site_id}/seo
Read SEO settings.
PUT
/api/v1/sites/{site_id}/seo
Set description, og_image_url, keywords, robots (partial updates OK).
Blogs
Per-site blogs and posts. Mirrors /dashboard/blogs.
GET
/api/v1/sites/{site_id}/blogs
List blogs on this site.
POST
/api/v1/sites/{site_id}/blogs
Create a blog. Body: {name, slug?, description?, tags?, show_in_nav?}.
GET
/api/v1/sites/{site_id}/blogs/{blog_id}
Read a blog.
PATCH
/api/v1/sites/{site_id}/blogs/{blog_id}
Update name / description / tags / show_in_nav.
DELETE
/api/v1/sites/{site_id}/blogs/{blog_id}
Delete the blog and all its posts.
GET
/api/v1/sites/{site_id}/blogs/{blog_id}/posts
List posts in a blog.
POST
/api/v1/sites/{site_id}/blogs/{blog_id}/posts
Create a post. Body: {content: '# Title\n\nMarkdown…'}.
GET
/api/v1/sites/{site_id}/blogs/{blog_id}/posts/{post_id}
Read a post + its content.
PUT
/api/v1/sites/{site_id}/blogs/{blog_id}/posts/{post_id}
Replace a post's content. Title/slug re-derived from the first H1.
DELETE
/api/v1/sites/{site_id}/blogs/{blog_id}/posts/{post_id}
Delete the post.
Integrations & Shortcodes
Machine-readable catalog of the Markdown shortcodes available on this site. Designed for AI assistants that need to know which markup they can safely emit into the page content. Default response only lists connected integrations (so an AI won't hallucinate a shortcode that would render as nothing) — add ?include=all to also see integrations available for setup.
GET
/api/v1/sites/{site_id}/integrations
List integrations connected to this site. Each record includes shortcodes (syntax + parameters + example) and runtime state (Dropbox folders, YouTube channel handle, etc.).
GET
/api/v1/sites/{site_id}/integrations?include=all
Also list integrations the site could connect but hasn't yet. Each has a `connect_url` pointing at the dashboard flow the human user needs to complete.