Optimize: score a page
Score an existing page against its SERP competitors with durable, retry-safe Optimize runs.
Optimize — Score a page
Section titled “Optimize — Score a page”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.
Authentication
Section titled “Authentication”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/optimizeAuthorization: Bearer rk_live_YOUR_API_KEYContent-Type: application/jsonIdempotency-Key: stable-logical-run-keyOption 2: Admin key (legacy)
Pass the admin key via the X-Admin-Key header. This method is supported for backward compatibility.
POST /api/v1/optimizeX-Admin-Key: your-admin-keyContent-Type: application/jsonRequest body
Section titled “Request body”{ "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. |
Security
Section titled “Security”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.
Credits
Section titled “Credits”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
Accepted Agent response (202)
Section titled “Accepted Agent response (202)”{ "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.
Full saved result
Section titled “Full saved result”{ "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 |
How the Rankability score works
Section titled “How the Rankability score works”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.
Error responses
Section titled “Error responses”| 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 |
Example: Score a page
Section titled “Example: Score a page”Using Bearer token (recommended):
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):
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
rankabilityScorewill be0andsourceWordCountwill be0. - 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.
