REST API · v1

API reference

Render images, scan URLs, create short links and monitor sites over HTTP. Every response is JSON. Machine readable spec: openapi.json. Also available as an MCP server, a GitHub Action and webhooks.

Authentication

Authorization: Bearer sk_live_...
Base URL       https://app.getshareglow.com
Scopes         images, templates, scan, links, monitors, ai (chosen per key; /v1/images accepts an optional exp)

Quick start

curl -X POST https://app.getshareglow.com/v1/scan \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/blog/post"}'

Rate limits

Calls per UTC day: Free 100 · Starter 10,000 · Growth 50,000 · Scale 250,000. Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the UTC-day reset); past the limit you get a 429 with Retry-After. Get a key under Developer.

Endpoints

Scanner

Check and refresh link previews.

POST`/v1/scan`

Scan a URL

Fetches the page through the SSRF-guarded scanner and returns the score, issues and every tag found.

curl

curl -X POST "https://app.getshareglow.com/v1/scan" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Responses

200 Scan result
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
413 The JSON body is over 1 MB (`payload_too_large`).
422 The page cannot be scanned: robots.txt or the site refuses, the page is too large, or it redirects too many times (`robots_blocked`, `forbidden`, `too_large`, `too_many_redirects`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.
502 The target site could not be reached (`unreachable`).
504 The target site did not answer in time (`timeout`).

POST`/v1/refresh`

Refresh a preview everywhere

Bumps the og:image cache-buster, re-scrapes Facebook and returns the LinkedIn Post Inspector link and the X cache note.

curl

curl -X POST "https://app.getshareglow.com/v1/refresh" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/post"}'

Responses

200 Refresh result
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

Images

Render Open Graph images.

POST`/v1/images`

Render an image

Renders a template with your values and returns its permanent URL. Paid plans get an HMAC-signed URL; Free gets an unsigned, watermarked URL. Only a real render (not a cache hit) counts against the monthly image cap.

curl

curl -X POST "https://app.getshareglow.com/v1/images" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"ember","params":{"title":"Launch day","subtitle":"Shareglow"}}'

Responses

200 Rendered image
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
402 A plan cap or feature gate blocked the call (`plan_limit_exceeded`; `details` names the resource and limit).
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

Templates

Templates you can render.

GET`/v1/templates`

List templates

Bundled templates available on your plan plus your custom templates.

curl

curl -X GET "https://app.getshareglow.com/v1/templates" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY"

Responses

200 Templates
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

POST`/v1/templates/from-url`

Generate a template from a URL

Scans the site's brand (colors, fonts, logo) and picks a layout with AI. Cached per domain; costs one AI generation on a cache miss.

curl

curl -X POST "https://app.getshareglow.com/v1/templates/from-url" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Responses

200 Template choice
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
402 A plan cap or feature gate blocked the call (`plan_limit_exceeded`; `details` names the resource and limit).
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

Links

Short links with their own previews.

POST`/v1/links`

Create a short link

Creates a short link with its own preview (`og`). Extra `variants` start an A/B test (Starter and up).

curl

curl -X POST "https://app.getshareglow.com/v1/links" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination":"https://example.com/pricing","og":{"title":"Pricing","description":"Plans that scale"}}'

Responses

201 Created link
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
402 A plan cap or feature gate blocked the call (`plan_limit_exceeded`; `details` names the resource and limit).
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

PATCH`/v1/links/{id}`

Edit a short link

Changes where a link points or how its preview looks, without changing the short URL. The slug cannot be edited. Every field is optional; `null` clears a preview field. The destination goes through the same checks as on creation (public host, Safe Browsing, not another short link). Also accepts the link settings: `expiresAt`, `expiredUrl`, `password`, `pixels`, `routing`, `deepLink`. With approvals on, the change is queued and answered with 202 `pending_approval`.

id (path, required)

curl

curl -X PATCH "https://app.getshareglow.com/v1/links/LINK_ID" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination":"https://example.com/new-page","og":{"title":"New page"}}'

Responses

200 Updated link
202 Queued for owner approval (`pending_approval`); the live link is unchanged until approved.
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
404 The id does not exist in this workspace (`not_found`, `link_not_found`, `template_not_found`).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

GET`/v1/links/{id}/stats`

Link click analytics

Clicks over time with country, device, browser and referrer breakdowns, clamped to your plan's analytics retention.

id (path, required)
from (query) — YYYY-MM-DD, defaults to 30 days before `to`.
to (query) — YYYY-MM-DD, defaults to today.

curl

curl -X GET "https://app.getshareglow.com/v1/links/LINK_ID/stats" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY"

Responses

200 Click statistics
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
404 The id does not exist in this workspace (`not_found`, `link_not_found`, `template_not_found`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

GET`/v1/links/{id}/qr`

Link QR code

QR code that encodes the short URL only.

id (path, required)

curl

curl -X GET "https://app.getshareglow.com/v1/links/LINK_ID/qr" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY"

Responses

200 QR image
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
404 The id does not exist in this workspace (`not_found`, `link_not_found`, `template_not_found`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

POST`/v1/domains`

Registers a custom short-link domain and returns the DNS records to add.

curl

curl -X POST "https://app.getshareglow.com/v1/domains" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"go.example.com"}'

Responses

201 Domain and DNS records
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
402 A plan cap or feature gate blocked the call (`plan_limit_exceeded`; `details` names the resource and limit).
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

Monitors

Watch every page of a sitemap.

POST`/v1/monitors`

Create a site monitor

Monitors every page of a sitemap. The plan's monitored-page cap is checked before any page is stored.

curl

curl -X POST "https://app.getshareglow.com/v1/monitors" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sitemapUrl":"https://example.com/sitemap.xml","frequency":"weekly"}'

Responses

201 Created monitor
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
402 A plan cap or feature gate blocked the call (`plan_limit_exceeded`; `details` names the resource and limit).
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

AI

Capped AI helpers.

POST`/v1/ai/meta`

Write title, description and alt text

Suggests metadata from content you supply. The URL is never fetched. Costs one AI generation.

curl

curl -X POST "https://app.getshareglow.com/v1/ai/meta" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/pricing"}'

Responses

200 Suggestions
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
402 A plan cap or feature gate blocked the call (`plan_limit_exceeded`; `details` names the resource and limit).
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

POST`/v1/ai/background`

Pick an AI background

Returns one of a fixed set of styles plus two colors. Costs one AI generation.

curl

curl -X POST "https://app.getshareglow.com/v1/ai/background" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Responses

200 Background
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
402 A plan cap or feature gate blocked the call (`plan_limit_exceeded`; `details` names the resource and limit).
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

POST`/v1/ai/ctr-score`

Score a template's click-through potential

Pass a `templateId` of yours or a `template` object. Costs one AI generation.

curl

curl -X POST "https://app.getshareglow.com/v1/ai/ctr-score" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"TEMPLATE_ID"}'

Responses

200 Score
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
402 A plan cap or feature gate blocked the call (`plan_limit_exceeded`; `details` names the resource and limit).
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
404 The id does not exist in this workspace (`not_found`, `link_not_found`, `template_not_found`).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

POST`/v1/ai/copy-variants`

Generate copy variants for a URL

Cached per URL; a cache miss costs one AI generation.

curl

curl -X POST "https://app.getshareglow.com/v1/ai/copy-variants" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/pricing"}'

Responses

200 Variants
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
402 A plan cap or feature gate blocked the call (`plan_limit_exceeded`; `details` names the resource and limit).
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

POST`/v1/ai/copy-variants/{index}/send-to-ab`

Send a copy variant to an A/B test

Adds cached variant `index` to a link as a new A/B variant. No AI call.

index (path, required)

curl

curl -X POST "https://app.getshareglow.com/v1/ai/copy-variants/0/send-to-ab" \
  -H "Authorization: Bearer $SHAREGLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkId":"LINK_ID"}'

Responses

201 Variant added
202 Queued for approval. The workspace requires approvals, so the variant is added only after an owner approves it. The approval is attributed to the workspace owner.
400 Validation failed (`bad_request`, `invalid_url`, ...).
401 Missing, unknown or revoked API key.
402 A plan cap or feature gate blocked the call (`plan_limit_exceeded`; `details` names the resource and limit).
403 The API key is valid but lacks the scope this endpoint needs (images, templates, scan, links, monitors or ai).
404 The id does not exist in this workspace (`not_found`, `link_not_found`, `template_not_found`).
413 The JSON body is over 1 MB (`payload_too_large`).
429 Daily call limit reached. Retry after the `Retry-After` seconds.

Free tools

Public helpers that need no API key.

POST`/v1/links/phone-test`

Phone test link

Creates a preview link that lives for one hour, plus a QR code, to open a page's real link preview on a phone. No API key; limited per IP.

curl

curl -X POST "https://app.getshareglow.com/v1/links/phone-test" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Responses

200 Preview link
400 Validation failed (`bad_request`, `invalid_url`, ...).
422 The page cannot be scanned: robots.txt or the site refuses, the page is too large, or it redirects too many times (`robots_blocked`, `forbidden`, `too_large`, `too_many_redirects`).
429 Per-IP limit reached. Retry after the `Retry-After` seconds.
502 The target site could not be reached (`unreachable`).
504 The target site did not answer in time (`timeout`).

GET`/v1/snippets/spa`

SPA crawler snippet

Plain-text snippet that serves crawlers a static snapshot of a single-page app. No API key; unmetered.

framework (query, required)
snapshot (query) — Absolute http(s) URL of the snapshot. Defaults to a placeholder.

curl

curl -X GET "https://app.getshareglow.com/v1/snippets/spa?framework=nextjs"

Responses

200 Snippet source
400 Validation failed (`bad_request`, `invalid_url`, ...).

Errors

Every error has the same shape. 400 validation, 401 bad key, 402 plan limit (plan_limit_exceeded), 403 forbidden (insufficient_scope when the key lacks the scope the endpoint needs), 404 not found, 429 rate limited, 500 unexpected.

402 example

{
  "error": {
    "code": "plan_limit_exceeded",
    "message": "The free plan allows 100 images per period.",
    "details": { "resource": "images", "limit": 100, "used": 100, "plan": "free" }
  }
}

API reference

Endpoints

Scanner

POST/v1/scan

POST/v1/refresh

Images

POST/v1/images

Templates

GET/v1/templates

POST/v1/templates/from-url

Links

POST/v1/links

PATCH/v1/links/{id}

GET/v1/links/{id}/stats

GET/v1/links/{id}/qr

POST/v1/domains

Monitors

POST/v1/monitors

AI

POST/v1/ai/meta

POST/v1/ai/background

POST/v1/ai/ctr-score

POST/v1/ai/copy-variants

POST/v1/ai/copy-variants/{index}/send-to-ab

Free tools

POST/v1/links/phone-test

GET/v1/snippets/spa

Errors

POST`/v1/scan`

POST`/v1/refresh`

POST`/v1/images`

GET`/v1/templates`

POST`/v1/templates/from-url`

POST`/v1/links`

PATCH`/v1/links/{id}`

GET`/v1/links/{id}/stats`

GET`/v1/links/{id}/qr`

POST`/v1/domains`

POST`/v1/monitors`

POST`/v1/ai/meta`

POST`/v1/ai/background`

POST`/v1/ai/ctr-score`

POST`/v1/ai/copy-variants`

POST`/v1/ai/copy-variants/{index}/send-to-ab`

POST`/v1/links/phone-test`

GET`/v1/snippets/spa`