Developers

Developer API

Programmatic access to your XenonFlare workspace for integrations, CI pipelines, and internal tools.

curl -H "Authorization: Bearer xf_live_xxxxxxxx" \
  https://api.xenonflare.com/api/v1/properties

Overview

The Developer API is organization-scoped. Each API key belongs to one workspace and carries explicit permission scopes. All authenticated routes return JSON with a consistent envelope and include a requestId in meta for support.

• Read endpoints list properties, jobs, organization details, and usage.
• Write endpoints create properties and queue SEO scans or crawls.
• Keys use the format xf_live_... (live) or xf_test_... (sandbox) and can be revoked instantly from the app.

Authentication

Send your API key as a Bearer token in the Authorization header. Create keys in the web app — they are shown once at creation; store them securely.

curl -H "Authorization: Bearer xf_live_xxxxxxxx" \
  https://api.xenonflare.com/api/v1/properties

Revoked or invalid keys receive 401 with error.code: "api_key_invalid".

Test keys (sandbox)

Choose Test when creating a key to get an xf_test_… sandbox credential. Test keys read real workspace data but write endpoints return mock responses with no side effects — ideal for CI pipelines and integrator onboarding. Writes include the X-Developer-Api-Mode: test response header.

Agencies and portfolio monitoring

Agencies on Growth run one workspace with many client properties, then automate nightly POST /scans/batch, webhook alerts, and CSV activity exports for client reporting. Scoped keys let you separate read-only dashboards from automation that queues crawls. See the agency portfolio guide and SEO automation API landing for positioning and integration patterns.

Request ID

Send an optional X-Request-Id header on any authenticated request. When provided, the same value is echoed in meta.requestId on success and error responses — useful when contacting support or correlating logs on your side.

curl -H "Authorization: Bearer xf_live_xxxxxxxx" \
  -H "X-Request-Id: deploy-2026-06-07-001" \
  https://api.xenonflare.com/api/v1/organization

Scopes

When creating a key, select only the scopes your integration needs.

See also the nightly crawl guide, CI pipeline guide, and agency portfolio guide for automation patterns.

Endpoints

System

Organization

Properties

Optional scan/crawl body: { "maxPages": number, "maxDepth": number }. Successful queue responses return 202 Accepted. Use ?include=gsc,lastScan on property list/detail to embed GSC summary or last scan metadata without extra round trips.

{
  "job": {
    "id": "507f1f77bcf86cd799439014",
    "type": "seo-scan",
    "status": "cancelled",
    "progress": 42,
    "propertyId": "507f1f77bcf86cd799439012"
  },
  "message": "Crawl progress was saved. You can resume this scan from the dashboard.",
  "resumeCrawlAvailable": true
}

curl -H "Authorization: Bearer xf_live_..." \
  https://api.xenonflare.com/api/v1/properties/PROPERTY_ID/content/workspace

curl -H "Authorization: Bearer xf_live_..." \
  https://api.xenonflare.com/api/v1/properties/PROPERTY_ID/backlinks/workspace

curl -H "Authorization: Bearer xf_live_..." \
  https://api.xenonflare.com/api/v1/properties/PROPERTY_ID/geo/settings

curl -H "Authorization: Bearer xf_live_..." \
  https://api.xenonflare.com/api/v1/properties/PROPERTY_ID/competitors/changes

curl -X PATCH -H "Authorization: Bearer xf_live_..." \
  -H "Content-Type: application/json" \
  -d '{"assignedToUserId":"USER_ID","dueAt":"2026-07-01T12:00:00.000Z"}' \
  https://api.xenonflare.com/api/v1/properties/PROPERTY_ID/issue-tasks/ISSUE_KEY

curl -H "Authorization: Bearer xf_live_..." \
  https://api.xenonflare.com/api/v1/organization/product-capabilities

{
  "event": "job.cancelled",
  "test": true,
  "deliveredAt": "2026-06-07T12:02:00.000Z",
  "resume": {
    "resumeCrawlAvailable": true,
    "checkpointPagesDone": 42,
    "crawlMaxPages": 500
  },
  "job": {
    "id": "000000000000000000000000",
    "type": "seo-scan",
    "status": "cancelled",
    "propertyId": "507f1f77bcf86cd799439012"
  }
}

curl -H "Authorization: Bearer xf_live_..." \
  https://api.xenonflare.com/api/v1/reports?limit=20

Response format

Successful responses wrap data in a consistent envelope. Errors use the same meta.requestId.

{
  "data": { },
  "meta": {
    "requestId": "...",
    "hasMore": false,
    "nextCursor": null
  }
}

Examples

{
  "data": {
    "organization": {
      "id": "507f1f77bcf86cd799439011",
      "name": "Acme Marketing",
      "plan": "starter"
    },
    "usage": { "plan": "starter", "periodLabel": "Jun 2026" },
    "totals": { "properties": 3, "activeJobs": 1 }
  },
  "meta": { "requestId": "req_abc123" }
}

Pagination

List endpoints accept limit (max 100, default 40) and cursor. When more results exist, meta.hasMore is true and meta.nextCursor contains an opaque token for the next page.

GET https://api.xenonflare.com/api/v1/properties?limit=40&cursor=opaque_token

Idempotency

Write endpoints (POST) accept an optional Idempotency-Key header (max 128 characters). Repeating the same key within 24 hours returns the original successful response without duplicating side effects — useful for retries in CI or webhook handlers.

curl -X POST \
  -H "Authorization: Bearer xf_live_..." \
  -H "Idempotency-Key: scan-2026-06-07-example-com" \
  https://api.xenonflare.com/api/v1/properties/PROPERTY_ID/scans

Full guide: Idempotency for write requests (TTL, replay rules, CI key patterns, retry matrix).

Rate limits

Two layers apply: API rate limits (per key / per org) and plan quotas (scans, websites, crawl pages). Plan quotas are enforced on write endpoints and return 403 plan_required; API rate limits return 429 rate_limit.

Headers and live counters

Successful responses include X-Developer-Api-RateLimit-read-* or X-Developer-Api-RateLimit-write-* headers (Limit, Remaining, Reset). For programmatic backoff, call GET /rate-limits (usage:read):

curl -H "Authorization: Bearer xf_live_..." \
  https://api.xenonflare.com/api/v1/rate-limits

Static plan caps (including documented API limits) are on GET /limits under data.developerApi and data.uptime (monitoring availability, probe interval, history retention, status page caps). When exceeded, the API returns 429 with a Retry-After header (seconds until the window resets) — see the 429 response tab above.

For XenonFlare platform availability, see status.xenonflare.com. For your own monitored sites, use GET /uptime and publish customer pages via PUT /properties/:id/status-page (public URL xenonflare.com/status/{slug}). AI assistants can use the llms.txt index for a concise map of endpoints and guides.

Step-by-step

1. Sign in at app.xenonflare.com on a Starter or Growth plan.
2. Open Developer API in the sidebar and create a key with properties:read and jobs:write as needed.
3. List properties, queue a scan, and poll job status:

curl -H "Authorization: Bearer xf_live_..." \
  https://api.xenonflare.com/api/v1/properties

Error catalog

SDK & code generation

npx @openapitools/openapi-generator-cli generate \
  -i https://xenonflare.com/openapi/developer-v1.yaml \
  -g typescript-fetch \
  -o ./src/generated/xenonflare-api

OpenAPI

Machine-readable specification for code generation and API clients: developer-v1.yaml (OpenAPI 3.1). Download from the quickstart panel above or import into your preferred API client.