Projects

Create a project

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

post/v1/projects

Request

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

Headers

Idempotency-Keystring

Any unique string (max 200 chars). Retrying a request with the same key replays the stored response verbatim (with header Idempotent-Replayed: true) instead of re-executing — including one-time secrets in the original body. Keys are scoped per account (per client IP on the unauthenticated signup) and pruned after 24h. Reusing a key on a different endpoint returns 409 idempotency_conflict.

Request body

urlstring required

The site to work on. Normalized server-side; must be a valid http(s) URL.

namestring
languagestring

Primary content language (lowercased). Default "en".

countrystring

Primary target country (uppercased). Default "US".

Response

Project created.

project_idstring required
urlstring uri required
namestring required
status'setup' | 'running' | 'completed' | 'paused' required

Lifecycle of the project's background processing.

languagestring required
countrystring required
sandboxboolean 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_atstring date-time required

Example response

{
  "language": "en",
  "country": "US"
}

Changes

No recorded changes to this operation across all 1 revision of this API.