Skip to content

Optimize: score a page

Score an existing page against its SERP competitors with durable, retry-safe Optimize runs.

POST /api/agent/v1/optimize (durable Agent contract)

POST /api/v1/optimize (synchronous internal admin contract)

Score any public URL against SERP competitors for a given keyword. The customer Agent API creates a durable asynchronous run and returns its ID immediately; the internal admin endpoint continues to execute the underlying scoring pipeline synchronously.

The Agent API run is persisted in the shared asynchronous job store. It does not create a Copywriter project or edit content. Poll or list the saved run, then retrieve its full result after completion.

The durable contract is available at /api/agent/v1/optimize and through MCP as optimize_page, optimization_get, and optimization_list. The /api/v1/optimize admin-key route is the synchronous internal scoring pipeline used by the background runner.

Option 1: Bearer token (recommended)

Use an rk_live_ API key with the optimize:run scope. This is the same auth used by all other Agent API endpoints and by MCP.

POST /api/agent/v1/optimize
Authorization: Bearer rk_live_YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: stable-logical-run-key

Option 2: Admin key (legacy)

Pass the admin key via the X-Admin-Key header. This method is supported for backward compatibility.

POST /api/v1/optimize
X-Admin-Key: your-admin-key
Content-Type: application/json
{
"url": "https://example.com/your-page",
"keyword": "target keyword",
"language": "en-US",
"client_id": "4746d28b-0a38-43f9-a1ca-5e8402ef73d4"
}
Field Type Required Default Description
url string (URL) Yes — The public URL to analyze and score. Must use http or https protocol. Private/internal hosts (localhost, private IPs, metadata endpoints) are blocked.
keyword string Yes — The target keyword to evaluate the page against
language string No "en-US" Language code for SERP data (e.g., en-US, es, de, ja). Max 10 characters.
client_id UUID No — Organization-owned client used for run attribution and history filtering.

The endpoint includes SSRF protection — URLs pointing to private networks, localhost, link-local addresses (169.254.x.x), or cloud metadata endpoints are rejected with a 400 error.

Use GET /usage and GET /usage/estimate?operation=optimize_page for the active account contract. A caller-supplied Idempotency-Key is required. The same key maps to one durable run, one reservation, and at most one provider execution.

If the authenticated user has an organization with insufficient credits, the endpoint returns:

{
"error": {
"code": "insufficient_credits",
"message": "Insufficient credits",
"details": {
"credits_required": 400,
"credits_available": 250
}
}
}

The numbers above are illustrative. The usage estimate endpoint is authoritative for the authenticated account’s active contract.

HTTP status: 402

{
"optimization_id": "opt-0123456789abcdef",
"status": "queued",
"url": "https://example.com/your-page",
"keyword": "target keyword"
}

Poll GET /api/agent/v1/optimizations/:id?view=status. After status becomes complete, request view=full. The saved result contains the scoring payload described below. GET /api/agent/v1/optimizations lists compact saved history.

{
"url": "https://example.com/your-page",
"keyword": "target keyword",
"language": "en-US",
"entities": [
{
"name": "Entity Name",
"type": "brand",
"importance": "required",
"sourceCount": 7
}
],
"rankabilityScore": 72,
"categoryScores": {
"copywriting": 16,
"readability": 8,
"seo": 12,
"structure": 8,
"coverage": 11,
"uniqueness": 14,
"credibility": 7
},
"scoreDetails": {
"categoryBreakdowns": {
"copywriting": { "score": 16, "maxScore": 20, "issues": [] },
"readability": { "score": 8, "maxScore": 10, "gradeLevel": 9.2 },
"seo": { "score": 12, "maxScore": 15, "topicPresence": { "title": true, "firstPara": true } },
"structure": { "score": 8, "maxScore": 10 },
"coverage": { "score": 11, "maxScore": 15, "entitiesFound": ["..."], "entitiesMissing": ["..."] },
"uniqueness": { "score": 14, "maxScore": 20 },
"credibility": { "score": 7, "maxScore": 10 }
},
"totalScore": 72,
"entityCoverage": { "score": 65, "found": 48, "total": 72, "percentage": 66.7 },
"scoredAt": "2026-04-08T12:00:00.000Z"
},
"sourceWordCount": 2150,
"competitorCount": 12,
"competitors": [
{
"url": "https://competitor.com/page",
"title": "Competitor Page Title",
"source": "organic",
"wordCount": 3200
}
],
"duration": 45000
}
Field Type Description
url string The analyzed URL
keyword string The target keyword
language string Language code used for SERP data
entities array Extracted entities from competitor content
entities[].name string Entity name as it appears in competitor content
entities[].type string Entity classification: brand, topic, concept, feature, or term
entities[].importance string Importance level: required (5+ competitors), recommended (2–4), or optional (1)
entities[].sourceCount number Number of competitor pages where this entity was found
rankabilityScore number Overall content score (0–100), based on entity coverage (percentage of important competitor entities found in your content) and keyword placement (primary keyword appearing in title, H1, first paragraph, subheadings, meta description)
categoryScores object Internal scoring breakdown by category (returned by the API but not surfaced in the product UI)
scoreDetails object Detailed scoring data including entity coverage percentage, keyword placement checks, and additional analysis metadata
sourceWordCount number Word count of the analyzed page (0 if page could not be scraped)
competitorCount number Number of competitor pages successfully scraped
competitors array Summary of scraped competitor pages
duration number Total processing time in milliseconds

The Rankability score (0–100) is derived from two factors:

  • Entity coverage (85% weight) — The percentage of important entities extracted from competitor pages that your content also covers. Entities are brands, concepts, features, and terms that top-ranking pages mention. Higher coverage means your content addresses the same topics competitors do.
  • Keyword placement (15% weight) — Whether your primary keyword appears in key on-page locations: the title/H1, the first paragraph, subheadings, and the meta description. Each placement carries a weighted score.

The API response also includes categoryScores and scoreDetails objects with a more granular internal breakdown, but the product experience centers on entity coverage and keyword placement as the two actionable scoring dimensions.

HTTP Error Description
400 url is required Missing or empty url field
400 keyword is required Missing or empty keyword field
400 url must be a valid URL URL cannot be parsed
400 url must use http or https protocol Non-HTTP protocol
400 url must point to a public host SSRF protection — private/internal host detected
401 Unauthorized Missing or invalid X-Admin-Key header
402 Insufficient credits Not enough credits for this operation
500 Entity extraction failed No entities could be extracted for this topic

Using Bearer token (recommended):

Terminal window
curl -X POST https://your-domain.com/api/agent/v1/optimize \
-H "Authorization: Bearer rk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seo-guide-score-v1" \
-d '{
"url": "https://example.com/blog/seo-guide",
"keyword": "seo guide",
"language": "en-US"
}'

Using admin key (legacy):

Terminal window
curl -X POST https://your-domain.com/api/v1/optimize \
-H "X-Admin-Key: your-admin-key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/blog/seo-guide",
"keyword": "seo guide",
"language": "en-US"
}'
  • The Agent API and MCP contracts are asynchronous and durable. The internal admin-key route remains synchronous for the detached runner.
  • If the source URL cannot be scraped (bot protection, timeout), the response still includes entities and competitor data but rankabilityScore will be 0 and sourceWordCount will be 0.
  • Competitor scraping has a 45-second budget — if not all competitors can be scraped within that window, the available results are used.
  • Entity extraction targets up to 90 entities from competitor content, verified against SERP data. Only entities found in at least one competitor page are included.