# Create Project

Source: https://www.ranked.ai/developers/api-reference/projects/create

`POST https://app.ranked.ai/api/v1/projects`

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

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.

> **Info:** Creating the project is free. Adding keywords or AI prompts and running scans needs a live SEO Software plan on the account: $4.99/month per 100 tracked keywords and $4.99/month per 100 AI prompts, prepaid, one plan for every software project on the account, unlimited websites and users. The response tells you whether a plan is active (`plan.active`) and where to add one (`plan.manageUrl`).

### Body parameters

- `website_url` (body, string, required): The website to track, e.g. `acme.com` or `https://acme.com`. Invalid URLs return a validation error.

- `name` (body, string): Project name. Defaults to the domain.

- `product_mode` (body, string, default software): Only `software` is accepted. Any other value returns a validation error explaining that managed projects start from the dashboard.

**Request**

```bash cURL
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"}'
```

```javascript JavaScript
const response = await fetch('https://app.ranked.ai/api/v1/projects', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer rk_live_your_write_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ website_url: 'acme.com', name: 'Acme' }),
});
const { data } = await response.json();

console.log(data.id, data.plan.active ? 'ready to track' : `add a plan: ${data.plan.manageUrl}`);
```

```python Python
import requests

response = requests.post(
    'https://app.ranked.ai/api/v1/projects',
    headers={'Authorization': 'Bearer rk_live_your_write_key'},
    json={'website_url': 'acme.com', 'name': 'Acme'},
)
project = response.json()['data']
print(project['id'], project['plan']['active'])
```

**Response**

```json 201
{
  "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 }
  }
}
```

```json 400
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "errors": [
        {
          "field": "product_mode",
          "message": "Only \"software\" projects can be created through the API. Managed-service projects start from the dashboard (Add Project), where the plan and free trial are set up."
        }
      ]
    }
  }
}
```

```json 403
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "This API key does not have the required permissions. Generate a new API key with write access from Settings > API."
  }
}
```

### 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.