---
title: "Create a project"
method: POST
path: "/v1/projects"
tags: ["Projects"]
---

# Create a project

`POST /v1/projects`

## Request

- Base URL: `https://serp-agent.com`
- URL: `https://serp-agent.com/v1/projects`
- Auth: HTTP bearer

Registers a site/domain to work on. Sandbox keys are capped at **1 project** and their projects carry `sandbox: true` (audits/articles run free within the trial budget; articles are draft-only). Live keys create projects freely — audits and articles are then gated per project by an active subscription, surfaced as `access: "pending_payment"` until payment completes. `name` defaults to the URL's hostname; `language` defaults to "en", `country` to "US".

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `url` string, required: The site to work on. Normalized server-side; must be a valid http(s) URL.
  - `name` string
  - `language` string: Primary content language (lowercased). Default "en".
  - `country` string: Primary target country (uppercased). Default "US".

## Response `201`

Project created.

- Project
  - `project_id` string, required
  - `url` string, uri, required
  - `name` string, required
  - `status` 'setup' | 'running' | 'completed' | 'paused', required: Lifecycle of the project's background processing.
  - `language` string, required
  - `country` string, required
  - `sandbox` boolean, required: True for projects created with a sandbox key (draft-only articles, trial budgets).
  - `access` 'active' | 'pending_payment' | 'sandbox', required: Billing gate: audits/articles require "active" or "sandbox". "pending_payment" projects return 402 on work endpoints.
  - `created_at` string, date-time, required
  - `counts` object: Present on list/detail responses.
    - `keywords` integer
    - `articles` integer
    - `audits` integer

## Other responses

- `400`: Malformed body or invalid URL. Code: `invalid_request`.
- `401`: Missing, malformed, unknown, revoked, or expired API key. Codes: `unauthorized`, `key_revoked`, `key_expired`.
- `403`: Sandbox keys are limited to 1 project. Code: `sandbox_limit_reached`.
- `429`: Rate limit exceeded (600 requests/minute per API key). Honor `Retry-After`.

---

[API](https://skmtc.dev/serp-agent/apis/serp-agent-api.md) · [All operations](https://skmtc.dev/serp-agent/apis/serp-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/serp-agent/apis/serp-agent-api/revisions/438a943019ac?raw)