Update project context
Merge new facts into a website's project context and append a line to its research log.
https://api.rankparse.com/v1/site-contextFreeAPI keyChanges the project context of one website. Only the fields you send change: a text field replaces its stored value, add_* fields add or update list entries, remove_* fields drop them, and append_research_log adds one line to the log. Send at least one field.
An agent should save only what it learned or confirmed with you, and confirm anything it inferred before saving it.
Query parameters
site_idstringrequiredA website id from Websites, sent in the query string. A missing, unknown, archived or other workspace's id returns 404 site_context_site_not_found.
Body parameters
The body is JSON. Unknown fields return 400 invalid_site_context.
business_overviewstring | nullWhat the business sells, to whom, and how it makes money. Stored up to 2,000 characters.
current_goalstring | nullThe outcome wanted from SEO right now. Stored up to 1,000 characters.
audiencestring | nullWho the customers are. Stored up to 1,000 characters.
marketsstring | nullCountries and languages. Stored up to 500 characters.
preferencesstring | nullHow the team likes to work. Stored up to 1,000 characters.
For the five text fields: null or an empty string clears the field. A longer text is cut to the limit, and a text more than twice the limit returns 400 invalid_site_context. Control characters and invisible direction marks are removed.
add_competitorsarray of objectsUp to 20 entries, each { "domain": "rival.com", "note": "Main rival" }. The domain may be a bare domain or a URL; it is stored as a lower-case bare domain, and a value that is not a domain returns 400 invalid_site_context. A domain already listed (ignoring www. and the path) has its note replaced. note is optional, stored up to 200 characters.
remove_competitorsarray of stringsUp to 20 domains or URLs to remove. Removals are applied before additions.
add_key_pagesarray of objectsUp to 30 entries, each { "url": "https://example.com/pricing", "purpose": "Converts trials" }. The URL must start with http:// or https://; the fragment is dropped. A URL already listed (ignoring case and a trailing slash) has its purpose replaced. purpose is optional, stored up to 200 characters.
remove_key_pagesarray of stringsUp to 30 URLs to remove. Removals are applied before additions.
append_research_logobjectAdds one log entry: { "summary": "Site audit: example.com. Verdict: fix broken links first", "skill": "seo-audit" }. summary is required, 1 to 1,000 characters, stored up to 500. skill is optional: lower-case letters, digits and hyphens, up to 40 characters. The log keeps the newest 100 entries per website.
Response
The updated context, in the same shape as Get project context (site_id, host, context, missing_fields, updated_at, research_log), plus:
research_log_entry_idstringOnly when append_research_log was sent: the id of the new entry.
Behavior and limits
- Cost: 0 credits.
- Lists have a ceiling: a website keeps at most 20 competitors and 30 key pages. A request that would go over answers
400 site_context_limit_reachedand changes nothing. Remove entries first. - Concurrent writes: the merge is checked against the version it started from. If another write lands first, the request retries up to 3 times and then answers
409 site_context_conflict; repeat the request. - Not all-or-nothing across fields: the context and the log entry are separate writes. The context is saved first; the log entry is added after it succeeds.
- Permissions: needs the
site.editcapability. - Rate limit: 60 requests per minute per key. See Rate limiting.
Errors
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_site_context | The body is not valid JSON or has an unknown field, a value is too long or the wrong type, a competitor is not a domain, a key page is not an http(s) URL, or nothing was sent. The message names the field. |
| 400 | site_context_limit_reached | The change would leave more than 20 competitors or 30 key pages. |
| 401 | invalid_api_key | Missing, invalid or revoked API key. |
| 403 | capability_missing | Your workspace role cannot edit websites. |
| 404 | site_context_site_not_found | site_id is missing or not a website in your workspace. |
| 409 | site_context_conflict | Another write changed the context while this one was saving. Repeat the request. |
| 429 | rate_limited | More than 60 requests in a minute. |
See Errors for the error body format.
Related
MCP tool: update_site_context (accepts every body parameter above plus site_id).