Create Project

Create a self-serve SEO Software project from a website URL

POSThttps://app.ranked.ai/api/v1/projects

Creates a software project for the account behind the API key. This is the only project type that can be created through the API: no plan or payment is needed, the project exists immediately and appears in the dashboard's Software Suite. Managed-service projects (where Ranked AI's team does the work) start from the dashboard's Add Project flow, where the plan and free trial are set up.

Requires a Read + Write API key.

Body parameters

website_urlstringbodyrequired

The website to track, e.g. acme.com or https://acme.com. Invalid URLs return a validation error.

namestringbody

Project name. Defaults to the domain.

product_modestringbodydefault: software

Only software is accepted. Any other value returns a validation error explaining that managed projects start from the dashboard.

Request

curl -X POST https://app.ranked.ai/api/v1/projects \
  -H "Authorization: Bearer rk_live_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{"website_url": "acme.com", "name": "Acme"}'

Response

{
  "success": true,
  "data": {
    "id": "8c1f2a4e-5b7d-4c3e-9a1b-2d3e4f5a6b7c",
    "name": "Acme",
    "status": "active",
    "serviceType": "seo",
    "productMode": "software",
    "websiteUrl": "https://acme.com",
    "createdAt": "2026-09-16T09:41:12.512Z",
    "dashboardUrl": "https://app.ranked.ai/dashboard/projects/8c1f2a4e-5b7d-4c3e-9a1b-2d3e4f5a6b7c?tab=keywords&subtab=keywords",
    "addServiceUrl": "https://app.ranked.ai/dashboard/projects/8c1f2a4e-5b7d-4c3e-9a1b-2d3e4f5a6b7c?addService=1",
    "plan": {
      "active": true,
      "capacity": { "keywords": 300, "prompts": 100 },
      "remaining": { "keywords": 180, "prompts": 64 },
      "pricing": "$4.99/month per 100 tracked keywords and $4.99/month per 100 AI prompts, prepaid; one plan covers every software project on the account; ...",
      "manageUrl": "https://app.ranked.ai/dashboard/projects?suite=software&addPlan=1"
    },
    "ownerUserId": "2f5e9c7a-1b3d-4e6f-8a9b-0c1d2e3f4a5b"
  },
  "meta": {
    "request_id": "req_01J8X2Y3Z4",
    "rate_limit": { "limit": 200, "remaining": 199, "reset": 1789000000 }
  }
}

Response fields

Field	Type	Description
`id`	string	The new project's UUID. Use it in every `/projects/{projectId}/...` call.
`productMode`	string	Always `software`
`dashboardUrl`	string	Deep link to the project's Rankings tab
`addServiceUrl`	string	Opens the "Add our SEO service" plan picker on the project, for upgrading it to the managed service later
`plan.active`	boolean	Whether the account has a live SEO Software plan. `false` means keywords, prompts and scans are blocked until one is added.
`plan.capacity`	object	Total tracked keywords and AI prompts the plan allows across all software projects
`plan.remaining`	object	Capacity left after existing software projects' usage
`plan.manageUrl`	string	Where to add or change the plan
`ownerUserId`	string	The account the project landed under. Usually the API key holder; if their account's software subscription belongs to another team member, the project pools there.

After creating

Add keywords with the dashboard, MCP (ranked_add_keywords) or the support chat. Adds beyond the plan's capacity are refused with a message pointing at the plan page; raise the plan's blocks and retry.
Everything on a software project scans the same way as on a managed one: keyword positions, AI prompts, audits and backlinks (5 manual audits and 5 manual backlink scans per project per rolling 24 hours).
Content endpoints (/content, /content/preferences) return no items for software projects. There is no content pipeline without the service.
To hand the project to Ranked AI's team, open addServiceUrl. Once upgraded, productMode becomes managed and the software suite is simply part of the service plan.

This page is also available as markdown for AI agents, and the whole reference as an OpenAPI spec. Questions? Developer support.