Skip to content
Shareglow
Get started

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.

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 response carries X-RateLimit-Limit and X-RateLimit-Remaining; past the limit you get a 429 with Retry-After. Get a key under Developer.

01

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).
  • 429 Daily call limit reached. Retry after the `Retry-After` seconds.

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).
  • 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).
  • 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).
  • 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).
  • 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 '{}'

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).
  • 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).
  • 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 '{}'

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).
  • 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 '{}'

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).
  • 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 '{}'

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).
  • 429 Daily call limit reached. Retry after the `Retry-After` seconds.

02

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" }
  }
}