AGENTIC MODE · PLANNED

Connect your AI agent to RankWin.

Your agent brings the reasoning. Read and opt-in write APIs are implemented for release validation across business context, research, content, links, visibility, integrations, guarded saves, and publishing. They are not labelled generally available before the production release gate passes; the packaged agent skill remains planned.

The skill is not published yet — this is the command it will use.

npx skills add rankwin/growth-agent

QUICK START

The planned path from API key to first project.

1
Create a RankWin account
Complete the project setup — the workspace your agent will read from.
2
API keys in Settings
Create a project-scoped key in Settings; it authenticates the implemented read endpoints below once release access opens.
3
The RankWin skill, or plain REST
The packaged skill for Codex, Claude, and Cursor is not published yet; the REST surface below is implemented and pending release validation.

AUTHENTICATION

Bearer token

API base: https://rankwin.co/api/v1. Use a project API key from Settings; CMS delivery keys are separate. Replace example IDs with your project, keyword and destination IDs.

Create a project-scoped API key in Settings and send it in the Authorization header. Reads work with every active key; writes additionally require write access, enabled per key in Settings, and refuse read-only keys.

Authorization: Bearer rank_live_••••••••••••

GET/projects

List projects

Return the projects available to the current API key.

Example response

{
  "data": [
    {
      "id": "project_example",
      "name": "Example",
      "description": "Customer support software",
      "country": "France",
      "language": "fr",
      "regions": [],
      "paused": false,
      "createdAt": "2026-09-01T00:00:00.000Z"
    }
  ],
  "next_cursor": null
}

GET/projects/:id/context

Get business context

Read approved company, product, customer, competitor, voice, and proof context.

Example response

Example before business context is saved. Once configured, data is an object containing the project description, audiences, product, features, proof and other writing context.

{
  "data": null,
  "next_cursor": null
}

POST/projects/:id/keywords/research

Research keywords

Queue automatic keyword research for a topic; scored opportunities land on the project when the durable job completes.

Example request body

{
  "topic": "customer support software alternatives",
  "location": "France"
}

Example response

HTTP 202 acknowledges a queued job. Keywords appear after research completes.

{
  "ok": true,
  "operationId": "operation_example",
  "jobRunId": "job_example",
  "deduplicated": false
}

GET/projects/:id/content

List content

Read up to 200 content items, most recently updated first, including their current status. This endpoint does not accept status filters or pagination cursors.

Example response

Example with no content. Items contain slug, title, keywordText, status, week, progress and updatedAt.

{
  "data": [],
  "next_cursor": null,
  "limit": 200
}

POST/projects/:id/content

Create content

Queue article generation for one of the project's planned keywords.

Example request body

{
  "keywordId": "keyword_example"
}

Example response

HTTP 202 acknowledges generation; the article is not ready yet.

{
  "ok": true,
  "operationId": "operation_example",
  "jobRunId": "job_example",
  "deduplicated": false
}

PATCH/projects/:id/content/:slug

Update content

Revise title, sections, metadata, hero image, pre-publish status, or a version note — the same guarded save the editor uses.

Example request body

{
  "title": "Choosing customer support software",
  "expectedVersionNo": 3
}

Example response

HTTP 200 confirms a saved revision. Use the current revision number to avoid overwriting another edit.

{
  "ok": true,
  "operationId": "operation_example",
  "deduplicated": false,
  "result": {
    "ok": true,
    "versionNo": 4,
    "completedUserTaskIds": []
  }
}

POST/projects/:id/content/:slug/publish

Publish content

Publish an approved page to RankWin CMS destinations now or on a schedule; external CMS destinations stay fail-closed until their live evidence passes.

Example request body

{
  "destinationIds": [
    "destination_example"
  ],
  "expectedVersionNo": 4
}

Example response

Example of an accepted publication job. A queued receipt is not proof that the public article is live. Scheduled requests also return scheduledFor and scheduledPublications.

{
  "ok": true,
  "operationId": "operation_example",
  "deduplicated": false,
  "result": {
    "ok": true,
    "publications": [],
    "publishedSlug": null,
    "queued": [
      {
        "publicationId": "publication_example",
        "destinationId": "destination_example",
        "provider": "rankwin-cms",
        "jobRunId": "job_example",
        "operationId": "publish_operation_example"
      }
    ]
  }
}

GET/projects/:id/links

List link opportunities

Read up to 100 internal-link opportunities, most recently updated first. Exchange and outreach opportunities are not returned by this endpoint.

Example response

Example with no internal-link opportunities.

{
  "data": {
    "internal": []
  },
  "next_cursor": null,
  "limit": 100
}

GET/projects/:id/visibility

Get visibility

Read up to 90 daily search-metric rows, newest first. Each row identifies measured or estimated data; AI mentions and citations are not included.

Example response

Example with no metrics. Rows contain date, clicks, impressions, ctr, position and source.

{
  "data": {
    "searchMetrics": []
  },
  "next_cursor": null,
  "limit": 90
}

GET/projects/:id/integrations

List integrations

Read configured provider connections and their public configuration. Credentials and RankWin CMS delivery keys are never returned.

Example response

Example with no provider connections. Items contain provider, status, isPublishingDestination, configPublic and lastCheckedAt.

{
  "data": [],
  "next_cursor": null
}