![](\"hero.jpg\")
",
"largeResources": [
{ "url": "https://example.com/hero.jpg", "size": 524288, "sizeKb": 512, "type": "image" }
],
"clsCulprits": ["div.banner"]
}
}
```
> Returns null for metrics if no PageSpeed data has been collected yet. Metrics are from mobile device audits.
#### GET /api/v1/pages/compare
Compare two pages for SEO analysis.
**Query Parameters:**
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| url1 | string (URL) | **required** | First page URL |
| url2 | string (URL) | **required** | Second page URL |
**Response:**
```json
{
"success": true,
"data": {
"page1": {
"url": "https://example.com/page1",
"title": "Page 1",
"canonicalUrl": "https://example.com/page1",
"ogImage": "https://example.com/og1.jpg",
"wordCount": 1500
},
"page2": {
"url": "https://example.com/page2",
"title": "Page 2",
"wordCount": 1000
},
"comparison": {
"wordCountDiff": 500,
"h1CountDiff": 0,
"schemaTypesOnlyIn1": ["LocalBusiness"],
"schemaTypesOnlyIn2": [],
"schemaTypesInBoth": ["Article"]
}
}
}
```
---
### Page Issues
#### GET /api/v1/pages/issues
Get SEO page issues: orphan pages (not linked internally), duplicate titles, and duplicate meta descriptions.
**Query Parameters:**
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| type | string | `all` | `orphan`, `duplicate_titles`, `duplicate_descriptions`, or `all` |
| limit | integer | 20 | Max 100 |
**Response:**
```json
{
"success": true,
"data": {
"orphanPages": [],
"duplicateTitles": [],
"duplicateDescriptions": []
}
}
```
---
### Image Analysis
AI-powered image alt text analysis and suggestions.
#### GET /api/v1/image-analysis
List analyzed images with AI-suggested alt text, titles, and filenames.
**Query Parameters:**
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| filter | string | `all` | `all` or `needs_alt` |
| source | string | `all` | `all`, `cron` (ranking-page sweep), `manual` (dashboard Generate tab), or `api` (POST /generate) |
| limit | integer | 50 | Max 100 |
| offset | integer | 0 | Pagination offset |
**Response:**
```json
{
"success": true,
"data": [
{
"id": "uuid",
"pageUrl": "https://example.com/page",
"imageSrc": "https://example.com/image.jpg",
"imageIndex": 0,
"currentAlt": "",
"currentFilename": "IMG_001.jpg",
"suggestedAlt": "Professional headshot of team member",
"suggestedTitle": "Team Member Photo",
"suggestedFilename": "team-member-headshot.jpg",
"suggestedDescription": "Professional portrait...",
"isDecorative": false,
"imageCategory": "photograph",
"analysisStatus": "completed",
"analyzedAt": "2024-12-31T10:00:00Z",
"fileSizeBytes": 184729,
"contentType": "image/jpeg",
"widthAttr": 1200,
"heightAttr": 800,
"loadingAttr": "lazy",
"isLazyLoaded": false,
"source": "cron"
}
],
"pagination": { "total": 120, "limit": 50, "offset": 0, "hasMore": true },
"summary": {
"total": 120,
"completed": 100,
"needs_alt": 45,
"decorative": 8,
"skipped": 0,
"failed": 0,
"by_source": { "cron": 115, "manual": 4, "api": 1 }
}
}
```
> Manual / API rows have synthetic `pageUrl` values (`manual:Monday morning, fresh data. Here's what moved since we last talked.
Your SEO score held steady at 62 this week, with corporate headshots chicago jumping eight positions to #7. Track AI Visibility next week.
Small moves compound.
", "recapTone": "encouraging", "keywordsImproved": 8, "keywordsDeclined": 3, "topKeyword": "professional headshots", "biggestGain": 7, "biggestLoss": 4, "daChange": 1, "newReviews": 2, "competitorBacklinksGained": 15, "generatedAt": "2026-03-02T04:00:00Z" } } ``` > Returns 404 if no recap has been generated yet. > `recapText` is sanitized HTML. Allowed tags: ``, ``, ``. No attributes, no links. Render as HTML, not plain text. --- ### AI Visibility AI brand visibility — how your business appears in AI-generated responses. #### Citation data model Each AI-visibility run now carries per-entity citation attribution. The shape divides into three buckets: 1. **Per-entity supporting sources** (`businesses[].supportingSources[]` on the per-query endpoint) — URLs Haiku attributed to a specific business Claude named. Deduped by URL within a business. Each source carries `citedPassages` (the count), `citedText` (earliest-passage excerpt — what appears in the collapsed view), and `passages[]` (every passage citing that URL, ordered by `passagePosition`). 2. **Unattributed cited sources** (`unattributedSources[]`) — URLs Claude cited in its response as general evidence (advice blogs, ranking posts without named parties, background context). Not tied to any specific entity. Same dedup + `citedPassages` + `citedText` + `passages[]` shape. 3. **Considered but not cited** (`consideredSources[]`) — URLs Claude searched and surfaced but did not cite in its final response. Deduped by URL. `passages[]` is empty for these. **Per-entity `reasons`:** alongside `supportingSources[]`, each entity carries a `reasons: string[]` field. These are short phrases Haiku extracted from Claude's prose describing *why* the business was recommended (e.g., `["cinematic lighting", "fast turnaround", "corporate focus"]`). Distinct from citations — these are distilled from the response text itself, not tied to any specific URL. **Movement badges** (`new` / `retained` / `dropped` / `null`) on each source compare this run to the most-recent prior same-persona run with `extraction_version >= 2`. Null when no prior run exists. **Tenant identification** flows through the `ai_market_tenant_matches` table — a per-(run, tenant) layered match (exact domain → normalized name → token subset → Jaro-Winkler → Haiku disambiguation). `isTenant: true` on a business means the match resolved to that business for the authenticated tenant. **Rotation cycle scoping:** All AI visibility endpoints return only rows captured under the current rotation cycle's anchor date. Rows from a prior cycle (e.g., pre-2026-04-19 rotation) are not exposed via this API. This keeps the `weekNumber` field monotonic within a cycle and aligns every tenant on the same community-discussion prompt each week. To inspect historical cycles, use the admin API with an explicit `anchor_date` query parameter. **Drill-down flow:** 1. Call `GET /api/v1/ai-visibility/weekly` (or `/api/v1/ai-visibility`) to list per-persona results. 2. For any result where `hasCitations: true`, call `GET /api/v1/ai-visibility/query/{visibilityId}` with the `visibilityId` to retrieve the full per-query detail. #### GET /api/v1/ai-visibility Structured summary of AI brand visibility across the current persona rotation. Returns aggregate stats, a per-persona breakdown with the full business leaderboard extracted from each AI response, and a week-over-week trend. For raw AI response text per prompt, see [GET /api/v1/ai-visibility/weekly](#get-apiv1ai-visibilityweekly). **Query Parameters:** | Param | Type | Default | Description | |-------|------|---------|-------------| | market | uuid | — | Filter by market (Team tier only) | **Response:** ```json { "success": true, "schemaVersion": "2", "data": { "visibility": { "overall": { "mentionRate": 0.5, "avgRank": 2, "bestRank": 1, "totalResponses": 4, "lastFetched": "2026-04-13T09:00:00Z" }, "byPersona": [ { "visibilityId": "9f5b4145-f94f-41d8-b39c-83c824f0a8ac", "persona": "ai-vis-market-1-1", "promptName": "CEO, Self-Booking", "promptText": "I'm the founder and CEO of a growing company in Chicago, IL...", "tenantMentioned": true, "tenantRank": 1, "totalBusinesses": 3, "mentionedBusinesses": [ { "name": "Your Business", "domain": "you.com", "domainConfidence": "high", "rank": 1, "reasons": ["industry-ready"], "isTenant": true, "competitorId": null }, { "name": "Competitor One", "domain": "comp1.com", "domainConfidence": "high", "rank": 2, "reasons": ["corporate focus"], "isTenant": false, "competitorId": "4a3f9c22-..." } ], "hasCitations": true, "citationSummary": { "businessesWithCitations": 3, "unattributedSources": 4 }, "weekNumber": 3, "fetchedAt": "2026-04-13T09:00:00Z" } ], "trend": { "previousPeriod": { "mentionRate": 0.25, "avgRank": 3 } } }, "sentiment": { /* ... */ }, "discoveredCompetitors": [ /* ... */ ] } } ``` **Key fields:** - `schemaVersion: "2"` — this endpoint's response shape. Bump signals a breaking change. See [Response Envelope & Versioning](#response-envelope--versioning) below. - `visibility.overall.mentionRate` — fraction (0–1) of the current rotation's personas where your tenant is mentioned. - `visibility.byPersona[].tenantMentioned`/`tenantRank` — derived at query time from `mentionedBusinesses` matching your tenant's `target_domain`. - `visibility.byPersona[].mentionedBusinesses` — every business named in the AI response, ordered by rank, with a `competitorId` when the domain matches a tracked competitor. - `visibility.byPersona[].visibilityId` / `hasCitations` / `citationSummary` — added April 2026 (non-breaking). Pass `visibilityId` to `GET /api/v1/ai-visibility/query/{visibilityId}` when `hasCitations: true` to drill into full citation detail. - `visibility.trend.previousPeriod` — mention rate + avg rank from the prior rotation window. `null` if no prior data. #### GET /api/v1/ai-visibility/weekly Get weekly AI visibility reports — what AI assistants tell potential clients when asked for photographer recommendations in your market. Each week is a 4-prompt batch from a rolling 41-week rotation (mix of market-scoped and tenant-scoped brand prompts depending on where the week lands). Each result includes the full structured business leaderboard alongside the raw AI response text. When the tenant has a stored comparison for the week, it's appended as an additional tenant-scoped result. Use the `week` parameter to paginate through historical weeks. **Query Parameters:** | Param | Type | Default | Description | |-------|------|---------|-------------| | week | integer | — | Specific week number. Omit for latest available week. | | market | uuid | — | Filter by market (Team tier only) | **Response:** ```json { "success": true, "schemaVersion": "2", "data": { "weekNumber": 3, "fetchedAt": "2026-04-13T09:00:00Z", "results": [ { "visibilityId": "9f5b4145-f94f-41d8-b39c-83c824f0a8ac", "promptName": "CEO, Self-Booking", "promptText": "I'm the founder and CEO of a growing company in Chicago, IL...", "responseText": "Based on my research, here are my top three recommendations...", "tenantMentioned": true, "tenantRank": 1, "mentionedBusinesses": [ { "name": "Your Business", "domain": "you.com", "domainConfidence": "high", "rank": 1, "reasons": ["industry-ready"], "isTenant": true, "competitorId": null } ], "hasCitations": true, "citationSummary": { "businessesWithCitations": 3, "unattributedSources": 4 }, "fetchedAt": "2026-04-13T09:00:00Z", "weekNumber": 3 } ], "availableWeeks": [ { "weekNumber": 3, "fetchedAt": "2026-04-13T09:00:00Z" }, { "weekNumber": 2, "fetchedAt": "2026-04-06T09:00:00Z" } ] } } ``` > `responseText` is null for prompts that have not been fetched for the tenant's tier. Starter tenants see 1 result per week; Pro/Team see all 5. > `tenantMentioned` and `tenantRank` come from the normalized `mentionedBusinesses` rows — they're authoritative, not heuristic. > Use `availableWeeks` to discover which weeks have data for pagination. > `visibilityId` + `hasCitations` + `citationSummary` were added April 2026 (non-breaking). Pass `visibilityId` to `GET /api/v1/ai-visibility/query/{visibilityId}` when `hasCitations: true` to drill into full citation detail. #### GET /api/v1/ai-visibility/query/{visibilityId} Per-query citation detail — returns authoritative per-entity citation attribution for a single AI-visibility run. Each business Claude named is returned with its supporting URLs (deduped by URL, with cited-text excerpts and per-passage counts). A separate `unattributedSources[]` bucket holds citations Claude made as general evidence that Haiku did not tie to any specific entity. **Obtain `visibilityId` from:** `GET /api/v1/ai-visibility/weekly` results — any row with `hasCitations: true` can be drilled into. Rows with `hasCitations: false` return 404 here. **Plan:** Pro or Team. Rate-limited. **Path parameter:** | Param | Type | Description | |-------|------|-------------| | visibilityId | uuid | Run identifier from `/api/v1/ai-visibility/weekly` | **Response (200):** ```json { "success": true, "schemaVersion": "1", "data": { "visibilityId": "9f5b4145-f94f-41d8-b39c-83c824f0a8ac", "marketId": "065144fd-2c0b-4836-a4fe-d0c5c87cd81f", "persona": "ai-vis-market-3-2", "promptSlug": "ceo-self-booking", "promptText": "I'm the founder and CEO of a growing company in Chicago, IL...", "responseText": "Based on my research, here are my top three recommendations...", "fetchedAt": "2026-04-13T09:00:00Z", "searchQueries": [ { "queryText": "best headshot photographers Chicago actors", "queryPosition": 1 } ], "businesses": [ { "businessId": "b1111111-0000-0000-0000-000000000001", "name": "312 Elements", "rank": 1, "domain": "312elements.com", "reasons": ["industry-ready portfolios", "strong CEO headshot specialty", "fast turnaround"], "isTenant": true, "competitorId": null, "competitorLabel": null, "supportingSources": [ { "url": "https://312elements.com/", "urlNormalized": "312elements.com/", "domain": "312elements.com", "title": "312 Elements Headshot Photography", "citedText": "cinematic lighting and fast turnaround", "citedPassages": 3, "passages": [ { "citedText": "cinematic lighting and fast turnaround", "passagePosition": 142 }, { "citedText": "boutique studio experience", "passagePosition": 410 }, { "citedText": "curated portfolio of executive headshots", "passagePosition": 892 } ], "movement": "retained" } ] } ], "unattributedSources": [ { "url": "https://thelightcommittee.com/blog/common-mistakes-actors-make-in-headshots/", "urlNormalized": "thelightcommittee.com/blog/common-mistakes-actors-make-in-headshots", "domain": "thelightcommittee.com", "title": "Common Mistakes Actors Make in Headshots", "citedText": "avoid busy backgrounds and dated wardrobe choices", "citedPassages": 1, "passages": [ { "citedText": "avoid busy backgrounds and dated wardrobe choices", "passagePosition": 1024 } ], "movement": "new" } ], "consideredSources": [ { "url": "https://headshotcrew.com/chicago", "urlNormalized": "headshotcrew.com/chicago", "domain": "headshotcrew.com", "title": "Chicago Headshot Photographers", "citedText": "", "citedPassages": 0, "passages": [], "movement": null } ], "previousVisibilityId": "412ed0ee-20fa-430f-99a2-3db12327499c" } } ``` **Error responses** follow the standard v1 envelope `{ success: false, error: { code, message, details? } }` (see [Error Handling](#error-handling)): - `400` — `code: "VALIDATION_ERROR"` when the path param isn't a valid UUID. - `404` — `code: "NOT_FOUND"` when the run doesn't exist OR belongs to a market not owned by your tenant. **Key fields:** - `businesses[].supportingSources[]` — deduped per URL within a business. `citedPassages` is the number of distinct passages in Claude's response citing that URL; `citedText` is an earliest-passage excerpt (the collapsed-view quote); `passages[]` holds every passage citing that URL, ordered by `passagePosition`, each with its own `citedText`. - `businesses[].reasons[]` — short phrases Haiku extracted from Claude's prose describing why this business was recommended (e.g., `"fast turnaround"`, `"corporate focus"`). Distilled from the response; not tied to any specific URL. - `businesses[].isTenant` — resolved via `ai_market_tenant_matches` (layered domain/name match). True on the one business that represents the authenticated tenant in this run. - `businesses[].competitorId` / `competitorLabel` — populated when the business domain matches a tracked competitor. - `unattributedSources[]` — URLs Claude cited as general evidence, not attributed to any entity above. - `consideredSources[]` — URLs Claude searched but did not cite. - `movement` — per-URL diff against the prior same-persona run with `extraction_version >= 2`. Values: `new`, `retained`, `dropped`, `null` (no prior run). - `previousVisibilityId` — the run used for movement diff; `null` when none exists. --- ### Reviews Google Reviews scoreboard comparing your business to competitors. #### GET /api/v1/reviews Get review scoreboard data — your tenant's reviews vs competitors in the same market and geographic area. **Query Parameters:** None. **Response:** ```json { "success": true, "data": { "tenant": { "targetDomain": "example.com", "reviewCount": 87, "reviewRating": 4.8, "reviewHistory": [{ "date": "2026-02-01", "count": 85, "rating": 4.8 }], "googlePlaceId": "ChIJ..." }, "competitors": [ { "domain": "competitor.com", "reviewCount": 142, "reviewRating": 4.5, "reviewHistory": [{ "date": "2026-02-01", "count": 138, "rating": 4.5 }], "googlePlaceId": "ChIJ..." } ] } } ``` > Competitors are scoped to the same state or metro area (e.g., NYC includes NY/NJ, DC includes DC/MD/VA). --- ### PAA Questions People Also Ask questions extracted from your tracked keyword SERPs. #### GET /api/v1/paa-questions Get PAA questions, optionally grouped by keyword. **Query Parameters:** | Param | Type | Default | Description | |-------|------|---------|-------------| | grouped | boolean | `false` | `true` to group questions by keyword | | market | uuid | — | Filter by market (Team tier only) | **Response (flat):** ```json { "success": true, "data": [ { "question": "What are the best SEO tools?", "keyword": "best seo tools", "keywordId": "uuid" }, { "question": "How much do SEO tools cost?", "keyword": "best seo tools", "keywordId": "uuid" } ] } ``` **Response (grouped=true):** ```json { "success": true, "data": [ { "keyword": "best seo tools", "keywordId": "uuid", "questions": [ "What are the best SEO tools?", "How much do SEO tools cost?" ] } ] } ``` --- ### SERP Features SERP feature ownership analysis and competitor visibility. #### GET /api/v1/serp-features/opportunities Get SERP feature opportunities — features you are not yet capturing but could target. **Query Parameters:** | Param | Type | Default | Description | |-------|------|---------|-------------| | limit | integer | 50 | Max 100 | | market | uuid | — | Filter by market (Team tier only) | **Response:** ```json { "success": true, "data": [ { "keyword": "best seo tools", "keywordId": "uuid", "featureType": "featured_snippet", "currentOwner": "competitor.com", "yourPosition": 5, "ownerPosition": 1 } ] } ``` #### GET /api/v1/serp-features/ownership Get who owns each SERP feature (featured snippets, local packs, PAA, etc.) for your tracked keywords. **Query Parameters:** | Param | Type | Default | Description | |-------|------|---------|-------------| | feature_type | string | — | Filter by type: `featured_snippet`, `local_pack`, etc. | | keyword_id | uuid | — | Filter to a specific keyword | | limit | integer | 100 | Max 500 | | market | uuid | — | Filter by market (Team tier only) | **Response:** ```json { "success": true, "data": [ { "keyword": "best seo tools", "featureType": "featured_snippet", "ownerDomain": "example.com", "isOwnSite": true } ], "summary": { "total": 50, "ownedByUs": 12 } } ``` #### GET /api/v1/serp-features/visibility Get competitor SERP feature presence across your keywords — which competitors appear in the most SERP features. **Query Parameters:** | Param | Type | Default | Description | |-------|------|---------|-------------| | limit | integer | 20 | Max 50 | | market | uuid | — | Filter by market (Team tier only) | **Response:** ```json { "success": true, "data": { "competitors": [ { "domain": "competitor.com", "featureCount": 12, "featureTypes": ["featured_snippet", "local_pack"] } ], "totalCompetitors": 20 } } ``` --- ### Webhooks Manage webhook endpoints for real-time event notifications. #### GET /api/v1/webhooks List all configured webhooks for your tenant. **Response:** ```json { "success": true, "webhooks": [ { "id": "uuid", "name": "Ranking Alerts", "url": "https://example.com/webhook", "secret": "whk_...", "event_types": ["ranking.changed", "keyword.added"], "categories": ["rankings"], "min_priority": "medium", "is_active": true, "total_deliveries": 25, "successful_deliveries": 24, "failed_deliveries": 1, "last_triggered_at": "2024-12-31T10:00:00Z", "consecutive_failures": 0, "created_at": "2024-12-01T00:00:00Z" } ], "meta": { "total": 1, "limit": 10 } } ``` #### POST /api/v1/webhooks Create a new webhook endpoint. **Request Body:** ```json { "name": "Ranking Alerts", "url": "https://example.com/webhook", "event_types": ["ranking.changed"], "categories": ["rankings"], "min_priority": "medium", "test_on_create": true } ``` **Response:** ```json { "success": true, "webhook": { "id": "uuid", "name": "Ranking Alerts", "url": "https://example.com/webhook", "secret": "whk_full_secret_shown_on_create_only", "event_types": ["ranking.changed"], "categories": ["rankings"], "min_priority": "medium", "is_active": true, "created_at": "2024-12-31T10:00:00Z" }, "test_result": { "success": true, "statusCode": 200, "responseTime": 150 } } ``` > The webhook secret is only shown in full on creation — save it immediately. URL must use HTTPS and cannot point to localhost or internal IPs. Set `test_on_create=true` to send a test event on creation. Maximum 10 webhooks per tenant. #### GET /api/v1/webhooks/:id Get detailed information for a specific webhook. **Response:** ```json { "success": true, "webhook": { "id": "uuid", "name": "Ranking Alerts", "url": "https://example.com/webhook", "secret": "whk_...", "event_types": ["ranking.changed"], "is_active": true, "total_deliveries": 25, "successful_deliveries": 24, "failed_deliveries": 1, "last_triggered_at": "2024-12-31T10:00:00Z", "last_error": null, "consecutive_failures": 0 } } ``` #### PATCH /api/v1/webhooks/:id Update an existing webhook. All fields are optional — only include fields you want to change. **Request Body:** ```json { "name": "Updated Name", "url": "https://example.com/new-webhook", "event_types": ["ranking.changed", "keyword.added"], "is_active": true } ``` **Response:** ```json { "success": true, "webhook": { "id": "uuid", "name": "Updated Name", "url": "https://example.com/new-webhook", "event_types": ["ranking.changed", "keyword.added"], "is_active": true, "updated_at": "2024-12-31T10:00:00Z" } } ``` #### DELETE /api/v1/webhooks/:id Delete a webhook. **Response:** ```json { "success": true, "deleted": true } ``` #### POST /api/v1/webhooks/:id Send a test event to a webhook to verify it is receiving events correctly. **Response:** ```json { "success": true, "test_result": { "success": true, "statusCode": 200, "error": null, "responseTime": 150 }, "webhook_id": "uuid" } ``` ### Content Pages (Keyword Planner) Content page → keyword mapping from the keyword planner. Shows which keywords are assigned to which pages, with current position data and assignment status. > Content pages now include a `groupId` field for topic group assignment. Use the topic group endpoints below to organize pages by category. #### GET /api/v1/content-pages List all content pages with their assigned keywords. **Response:** ```json { "success": true, "data": [ { "id": "uuid", "url": "https://example.com/actor-headshots", "title": "actor headshots chicago", "status": "published", "groupId": "uuid-or-null", "keywords": [ { "id": "uuid", "phrase": "actor headshots chicago", "role": "primary", "status": "active", "currentPosition": 3, "previousPosition": 5, "positionChange": 2 }, { "id": "uuid", "phrase": "headshot photographer near me", "role": "secondary", "status": "queued", "currentPosition": null, "previousPosition": null, "positionChange": null } ], "createdAt": "2024-12-01T00:00:00Z", "updatedAt": "2024-12-31T10:00:00Z" } ], "meta": { "totalPages": 15, "totalKeywords": 42, "pagesWithKeywords": 12 } } ``` **Keyword fields:** | Field | Description | |-------|-------------| | `role` | `"primary"` or `"secondary"` — the keyword's role on this page | | `status` | `"active"` — has SERP data; `"queued"` — pending first weekly SERP fetch (position fields will be null) | | `currentPosition` | Latest SERP position (null for queued keywords) | | `previousPosition` | Previous week's position (null for queued keywords) | | `positionChange` | Position delta (positive = improved, null for queued keywords) | **Page status values:** `planned`, `published`, `monitoring` > Keywords marked for removal (`pending_remove`) are excluded automatically. Queued keywords appear immediately after being added but have no SERP data until the next weekly fetch cycle. #### POST /api/v1/content-pages/sync Sync content pages from your sitemap. Fetches the sitemap, discovers pages, and syncs them into the content planner. Run this before assigning keywords if you have no content pages. **Response (200):** ```json { "success": true, "data": { "sitemapPages": 47, "imported": 12, "removed": 3, "skipped": 32 } } ``` > Safe to run repeatedly — existing pages are preserved. If sitemap returns 0 pages, existing content pages are not removed (safety guard). May take a few seconds due to live sitemap fetch. #### POST /api/v1/content-pages/:id/keywords Assign a tracked keyword to a content page. Each keyword can only be assigned to one page. **Request Body:** | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | keywordId | uuid | Yes | — | ID of the tracked keyword | | role | string | No | `"secondary"` | `"primary"` or `"secondary"` | **Response (201):** ```json { "success": true, "data": { "pageId": "f1e2d3c4-b5a6-7890-abcd-ef1234567890", "keywordId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "role": "primary" } } ``` > Returns `409` with the existing page title if the keyword is already assigned to a different page. If the keyword is already on this page, the role is updated. Returns `404` if the content page does not exist. #### DELETE /api/v1/content-pages/:id/keywords/:keywordId Remove a keyword assignment from a content page. This does not remove the keyword from tracking. **Response (200):** ```json { "success": true, "data": { "deleted": true } } ``` > Returns `404` if the content page does not exist. #### GET /api/v1/content-pages/groups List all topic groups. **Response:** ```json { "success": true, "data": [ { "id": "uuid", "name": "Service Pages", "displayOrder": 0, "pageCount": 8, "createdAt": "2026-03-20T00:00:00Z", "updatedAt": "2026-03-20T00:00:00Z" } ] } ``` #### POST /api/v1/content-pages/groups Create a topic group. **Request Body:** | Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Topic group name (1-255 chars) | **Response (201):** ```json { "success": true, "data": { "id": "uuid", "name": "Blog Posts", "displayOrder": 1, "pageCount": 0, "createdAt": "2026-03-20T00:00:00Z", "updatedAt": "2026-03-20T00:00:00Z" } } ``` #### PATCH /api/v1/content-pages/groups/:groupId Update a topic group (rename). **Request Body:** | Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | No | New name (1-255 chars) | **Response (200):** `{ "success": true, "data": { "updated": true } }` #### DELETE /api/v1/content-pages/groups/:groupId Delete a topic group. Pages in the group are moved to ungrouped (not deleted). **Response (200):** `{ "success": true, "data": { "deleted": true } }` #### PATCH /api/v1/content-pages/:id/group Assign a content page to a topic group, or ungroup it. **Request Body:** | Field | Type | Required | Description | |-------|------|----------|-------------| | groupId | uuid \| null | Yes | Topic group ID, or `null` to ungroup | **Response (200):** ```json { "success": true, "data": { "pageId": "uuid", "groupId": "uuid" } } ``` > The `groupId` field is also returned on each content page in `GET /api/v1/content-pages`. --- ### Markets Geographic market configuration. Returns the tenant's primary market and any dedicated zip markets (Team tier only). #### GET /api/v1/markets Get your market configuration including primary market and dedicated zip markets. Use the returned market IDs with the `?market=` parameter on other endpoints. **No query parameters.** **Response:** ```json { "success": true, "data": { "primary": { "id": "550e8400-e29b-41d4-a716-446655440000", "city": "Chicago", "state": "IL", "zip": "60614", "country": "US" }, "dedicated": [ { "id": "660e8400-e29b-41d4-a716-446655440001", "city": "Naperville (60540)", "state": "IL", "zip": "60540", "country": "US", "isAddon": false } ], "limits": { "includedDedicatedZips": 3, "used": 1 } } } ``` **Response fields:** | Field | Description | |-------|-------------| | `data.primary` | Primary market (null if not yet configured) | | `data.primary.id` | Market UUID — use with `?market=` on other endpoints | | `data.primary.zip` | Postal code (US zip, Canadian postal code, or UK postcode) | | `data.primary.country` | Country code: `US`, `CA`, or `GB` | | `data.dedicated[]` | Dedicated zip markets (empty for Pro users) | | `data.dedicated[].isAddon` | Whether this is a paid add-on zip (Phase 2) | | `data.limits.includedDedicatedZips` | Number of dedicated zips included in plan (0 for Pro, 3 for Team) | | `data.limits.used` | Number of dedicated zips currently configured | > Pro users see only their primary market with an empty `dedicated` array and `limits.includedDedicatedZips = 0`. Team users see up to 3 dedicated zip markets in addition to their primary. --- ### Recon Ranking keywords discovered during tenant onboarding via Moz. Includes your own domain's ranking keywords (`tenant`) and competitor keywords (`data`), grouped by domain. #### GET /api/v1/recon/competitors Get ranking keywords for your domain and competitors, plus keyword slot capacity. **Query Parameters:** | Param | Type | Default | Description | |-------|------|---------|-------------| | limit | integer | 10 | Max competitors per page (max 50) | | offset | integer | 0 | Number of competitors to skip | **Response:** ```json { "success": true, "tenant": { "domain": "yoursite.com", "keywordCount": 25, "bestPosition": 2, "isTenant": true, "keywords": [ { "phrase": "chicago headshots", "position": 2, "volume": 3200, "difficulty": 28, "rankingPage": "https://yoursite.com/headshots", "isTracked": true, "trackedPosition": 3, "trackedKeywordId": "550e8400-e29b-41d4-a716-446655440001" } ] }, "data": [ { "domain": "competitorsite.com", "keywordCount": 12, "serpAppearances": 51, "top3Appearances": 5, "top10Appearances": 21, "bestPosition": 3, "isTenant": false, "keywords": [ { "phrase": "professional headshots chicago", "position": 3, "volume": 2400, "difficulty": 35, "rankingPage": "https://competitorsite.com/headshots", "isTracked": true, "trackedPosition": 5, "trackedKeywordId": "550e8400-e29b-41d4-a716-446655440002" }, { "phrase": "corporate photography", "position": 8, "volume": 1900, "difficulty": 42, "rankingPage": "https://competitorsite.com/corporate", "isTracked": false, "trackedPosition": null, "trackedKeywordId": null } ] } ], "keywordSlots": { "used": 18, "limit": 25 }, "pagination": { "total": 8, "limit": 10, "offset": 0, "hasMore": false } } ``` **Response fields:** | Field | Description | |-------|-------------| | `tenant` | Your own domain's ranking keywords (null if no Moz data yet) | | `tenant.isTenant` | Always `true` | | `data[].domain` | Competitor domain name | | `data[].isTenant` | Always `false` for competitor entries | | `data[].keywordCount` | Number of keywords this domain ranks for | | `data[].bestPosition` | Best ranking position across all keywords (null if no positions) | | `*.keywords[].position` | Moz ranking position | | `*.keywords[].isTracked` | Whether you are already tracking this keyword phrase | | `*.keywords[].trackedPosition` | Your current position from our SERP tracking (null if not tracked) | | `*.keywords[].trackedKeywordId` | Keyword UUID for detail lookup via `GET /api/v1/keywords` (null if not tracked) | | `*.keywords[].rankingPage` | The URL the domain ranks with for this keyword | | `keywordSlots.used` | Current number of tracked keywords | | `keywordSlots.limit` | Maximum keywords allowed on your plan | | `pagination.total` | Total number of competitors available | | `pagination.hasMore` | Whether more competitors exist beyond this page | > Your domain is always in the `tenant` field (not paginated). Competitors in `data` are sorted by keyword count (descending). Keywords within each domain are sorted by position (ascending, nulls last). Blacklisted competitors are excluded automatically. --- ### Page Audit #### `POST /api/v1/page-audit` Run an on-demand SEO audit on any URL. Analyzes 50+ signals including headings, keyword placement, keyword density, content quality, images (with file sizes via PageSpeed Insights), schema markup, Open Graph, canonical tags, indexability, site-level signals, NAP presence, readability, and platform detection. **Rate limits:** 10 audits/hour, 20/day. **Request body:** | Field | Type | Required | Description | |-------|------|----------|-------------| | `url` | string | Yes | The page URL to audit | | `targetKeyword` | string | Yes | The keyword you want this page to rank for | **Example:** ```bash curl -X POST https://seo.312elements.com/api/v1/page-audit \ -H "Authorization: Bearer kt_live_..." \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com/headshots", "targetKeyword": "professional headshots chicago"}' ``` **Response:** | Field | Description | |-------|-------------| | `data.hash` | Unique report ID — retrieve later via `GET /api/page-audit/report/{hash}` | | `data.report.headings` | H1/H2/H3 counts, text, and hierarchy validation | | `data.report.keywordPlacement` | Whether target keyword appears in title, H1, meta, first 100 words, alt text, URL slug | | `data.report.keywordDensity` | Keyword frequency, density percentage, top 2-word and 3-word phrases | | `data.report.titleTag` | Title presence, text, length, too short/long flags | | `data.report.metaDescription` | Meta description presence, text, length, too short/long flags | | `data.report.content` | Word count, thin content flag, content-to-HTML ratio, pre-JS vs post-JS comparison | | `data.report.images` | Image list with src, alt text, loading attribute, fetchpriority, file size (bytes) | | `data.report.schema` | Schema.org presence and types detected | | `data.report.openGraph` | OG title, description, image presence | | `data.report.technical` | HTTP status, redirect detection, mixed content, lang, favicon, platform | | `data.report.siteLevel` | Sitemap, robots.txt, llms.txt, HTTPS redirect, www consistency, custom 404 | | `data.report.nap` | Phone and address detection (local SEO) | | `data.report.readability` | Flesch readability score and label | --- ## Cron Job Examples ### Python — Export to CSV Run with cron: `0 9 * * 0 python sync_rankings.py` ```python #!/usr/bin/env python3 """Weekly ranking sync - exports all data to CSV files""" import requests import csv from datetime import datetime import os API_KEY = os.environ.get('KEYWORD_TRACKER_API_KEY', 'kt_live_your_key_here') BASE_URL = 'https://seo.312elements.com' def export_rankings(): headers = {'Authorization': f'Bearer {API_KEY}'} # Get all data in one request response = requests.get( f'{BASE_URL}/api/v1/export', headers=headers, params={'include': 'keywords,competitors,opportunities,rankings', 'history_days': 7} ) response.raise_for_status() data = response.json() # Export keywords to CSV today = datetime.now().strftime('%Y-%m-%d') with open(f'rankings_{today}.csv', 'w', newline='') as f: writer = csv.writer(f) writer.writerow(['Keyword', 'Position', 'Previous', 'Change', 'URL', 'Volume', 'Difficulty']) for kw in data.get('keywords', []): writer.writerow([ kw['phrase'], kw['currentPosition'], kw['previousPosition'], kw['positionChange'], '', kw.get('volume', ''), kw.get('difficulty', '') ]) print(f"Exported {len(data.get('keywords', []))} keywords to rankings_{today}.csv") # Export opportunities opps = data.get('opportunities', {}) striking = opps.get('strikingDistance', {}).get('keywords', []) if striking: with open(f'opportunities_{today}.csv', 'w', newline='') as f: writer = csv.writer(f) writer.writerow(['Keyword', 'Position', 'Best Recent', 'Score']) for opp in striking: writer.writerow([opp['keyword'], opp['currentPosition'], opp['bestRecentPosition'], opp['opportunityScore']]) print(f"Exported {len(striking)} opportunities") if __name__ == '__main__': export_rankings() ``` ### Node.js — Sync to Database Run with cron: `0 9 * * 0 node sync_to_db.js` ```javascript #!/usr/bin/env node const fetch = require('node-fetch'); const Database = require('better-sqlite3'); const API_KEY = process.env.KEYWORD_TRACKER_API_KEY || 'kt_live_your_key_here'; const BASE_URL = 'https://seo.312elements.com'; async function syncRankings() { const response = await fetch(`${BASE_URL}/api/v1/export?include=keywords,rankings&history_days=30`, { headers: { 'Authorization': `Bearer ${API_KEY}` } }); if (!response.ok) throw new Error(`API error: ${response.status}`); const data = await response.json(); const db = new Database('rankings.db'); db.exec(` CREATE TABLE IF NOT EXISTS rankings ( date TEXT, keyword TEXT, position INTEGER, url TEXT, PRIMARY KEY (date, keyword) ) `); const insert = db.prepare('INSERT OR REPLACE INTO rankings VALUES (?, ?, ?, ?)'); const today = new Date().toISOString().split('T')[0]; const transaction = db.transaction((keywords) => { for (const kw of keywords) { insert.run(today, kw.phrase, kw.currentPosition, ''); } }); transaction(data.keywords || []); console.log(`Synced ${data.keywords?.length || 0} keywords to database`); db.close(); } syncRankings().catch(console.error); ``` ### Google Sheets — Apps Script Go to Extensions > Apps Script > paste this code > set a weekly trigger. ```javascript const API_KEY = 'kt_live_your_key_here'; const BASE_URL = 'https://seo.312elements.com'; function syncRankings() { const options = { method: 'GET', headers: { 'Authorization': 'Bearer ' + API_KEY }, muteHttpExceptions: true }; const response = UrlFetchApp.fetch( BASE_URL + '/api/v1/export?include=keywords,opportunities', options ); if (response.getResponseCode() !== 200) { throw new Error('API Error: ' + response.getContentText()); } const data = JSON.parse(response.getContentText()); const ss = SpreadsheetApp.getActiveSpreadsheet(); // Update Rankings sheet let sheet = ss.getSheetByName('Rankings') || ss.insertSheet('Rankings'); sheet.clear(); sheet.appendRow(['Keyword', 'Position', 'Change', 'Volume', 'Difficulty', 'Updated']); const today = new Date().toISOString().split('T')[0]; (data.keywords || []).forEach(kw => { sheet.appendRow([ kw.phrase, kw.currentPosition, kw.positionChange, kw.volume || '', kw.difficulty || '', today ]); }); // Update Opportunities sheet const opps = data.opportunities?.strikingDistance?.keywords || []; if (opps.length > 0) { let oppSheet = ss.getSheetByName('Opportunities') || ss.insertSheet('Opportunities'); oppSheet.clear(); oppSheet.appendRow(['Keyword', 'Position', 'Best Recent', 'Score']); opps.forEach(opp => { oppSheet.appendRow([opp.keyword, opp.currentPosition, opp.bestRecentPosition, opp.opportunityScore]); }); } SpreadsheetApp.getUi().alert('Synced ' + (data.keywords?.length || 0) + ' keywords!'); } ``` ### cURL — Quick Export ```bash # Export all data to JSON file curl -s -H "Authorization: Bearer kt_live_your_key_here" \ "https://seo.312elements.com/api/v1/export?include=keywords,competitors,opportunities,rankings" \ | jq '.' > export_$(date +%Y-%m-%d).json # Get just keywords as CSV (using jq) curl -s -H "Authorization: Bearer kt_live_your_key_here" \ "https://seo.312elements.com/api/v1/keywords" \ | jq -r '.data[] | [.phrase, .currentPosition, .positionChange, .volume] | @csv' > keywords.csv ``` ### PHP — WordPress Integration ```php array( 'Authorization' => 'Bearer ' . KEYWORD_TRACKER_API_KEY, ), 'timeout' => 30, ) ); if (is_wp_error($response)) { error_log('Keyword Tracker API Error: ' . $response->get_error_message()); return; } $data = json_decode(wp_remote_retrieve_body($response), true); if (!$data['success']) { error_log('Keyword Tracker API failed: ' . json_encode($data)); return; } // Store in WordPress options or custom table update_option('keyword_rankings', $data['keywords']); update_option('keyword_rankings_updated', current_time('mysql')); $striking = count($data['opportunities']['strikingDistance'] ?? []); $declining = count($data['opportunities']['declining'] ?? []); error_log("Synced rankings: {$striking} striking distance, {$declining} declining"); } add_action('sync_keyword_rankings', 'sync_keyword_rankings'); if (!wp_next_scheduled('sync_keyword_rankings')) { wp_schedule_event(time(), 'weekly', 'sync_keyword_rankings'); } ?> ``` ### Slack — Weekly Summary Run with cron: `0 9 * * 1 node slack_summary.js` ```javascript #!/usr/bin/env node const fetch = require('node-fetch'); const API_KEY = process.env.KEYWORD_TRACKER_API_KEY || 'kt_live_your_key_here'; const SLACK_WEBHOOK = process.env.SLACK_WEBHOOK_URL || 'https://hooks.slack.com/services/xxx/xxx/xxx'; const BASE_URL = 'https://seo.312elements.com'; async function sendSlackSummary() { const response = await fetch(`${BASE_URL}/api/v1/export?include=keywords,opportunities`, { headers: { 'Authorization': `Bearer ${API_KEY}` } }); const data = await response.json(); const keywords = data.keywords || []; const improving = keywords.filter(k => (k.positionChange || 0) < 0).length; const declining = keywords.filter(k => (k.positionChange || 0) > 0).length; const stable = keywords.filter(k => k.positionChange === 0).length; const avgPosition = keywords.length > 0 ? (keywords.reduce((sum, k) => sum + (k.currentPosition || 100), 0) / keywords.length).toFixed(1) : 'N/A'; const message = { blocks: [ { type: 'header', text: { type: 'plain_text', text: ':chart_with_upwards_trend: Weekly SEO Report' } }, { type: 'section', fields: [ { type: 'mrkdwn', text: `*Improving:* :arrow_up: ${improving}` }, { type: 'mrkdwn', text: `*Declining:* :arrow_down: ${declining}` }, { type: 'mrkdwn', text: `*Stable:* :left_right_arrow: ${stable}` }, { type: 'mrkdwn', text: `*Avg Position:* ${avgPosition}` }, ] }, { type: 'section', text: { type: 'mrkdwn', text: `*Opportunities:* ${data.opportunities?.strikingDistance?.length || 0} keywords in striking distance` } } ] }; await fetch(SLACK_WEBHOOK, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(message) }); console.log('Slack summary sent!'); } sendSlackSummary().catch(console.error); ``` --- ## SDK & Client Generation Generate typed clients automatically from the OpenAPI specification. ### TypeScript — Generate Types ```bash # Install the generator npm install -D openapi-typescript # Generate types from the API npx openapi-typescript https://seo.312elements.com/api/v1/openapi.json -o ./src/types/api.ts # Usage in your code: import type { paths, components } from './types/api'; type Keyword = components['schemas']['Keyword']; type KeywordListResponse = paths['/api/v1/keywords']['get']['responses']['200']['content']['application/json']; ``` ### Python — Generate Client ```bash # Install OpenAPI Generator (requires Java 8+) npm install -g @openapitools/openapi-generator-cli # Generate Python client openapi-generator-cli generate \ -i https://seo.312elements.com/api/v1/openapi.json \ -g python \ -o ./python-client \ --additional-properties=packageName=keyword_tracker # Usage: cd python-client && pip install . from keyword_tracker import ApiClient, KeywordsApi client = ApiClient() client.configuration.access_token = 'kt_live_your_key_here' api = KeywordsApi(client) keywords = api.list_keywords(limit=50) ``` ### Other Languages ```bash # JavaScript/Node.js (fetch-based) openapi-generator-cli generate -i https://seo.312elements.com/api/v1/openapi.json -g javascript -o ./js-client # Go openapi-generator-cli generate -i https://seo.312elements.com/api/v1/openapi.json -g go -o ./go-client # Ruby openapi-generator-cli generate -i https://seo.312elements.com/api/v1/openapi.json -g ruby -o ./ruby-client # PHP openapi-generator-cli generate -i https://seo.312elements.com/api/v1/openapi.json -g php -o ./php-client # C#/.NET openapi-generator-cli generate -i https://seo.312elements.com/api/v1/openapi.json -g csharp -o ./csharp-client # See all available generators: openapi-generator-cli list ``` ### Direct Spec Access ```bash # Download the spec curl -o openapi.json https://seo.312elements.com/api/v1/openapi.json # View in Swagger UI (local) npx @redocly/cli preview-docs openapi.json ```