---
title: "Add a site to audit; your human completes its checkout"
method: POST
path: "/v1/sites"
tags: ["sites"]
---

# Add a site to audit; your human completes its checkout

`POST /v1/sites`

## Request

- Base URL: `https://frontshelf.io/api`
- URL: `https://frontshelf.io/api/v1/sites`
- Auth: HTTP bearer

Add a site to audit. A site is the unit of purchase: the answer carries `checkout_url`, the site's checkout link your human opens to subscribe on Whop (card on file; $79/month per site, billed every 30 days; 3-day free trial on a workspace's first site; later sites are charged at checkout; the answer's `billing.trial_offered` says which this site's checkout is). Nothing is charged until your human pays, and nothing crawls until then: the first crawl starts by itself when the subscription lands, so do not call crawls_start on an `unpaid` site. It starts a billing path, so it asks for confirmation: call it with dry_run: true first, then with confirm: true. Hand `checkout_url` to your human word for word; never open it yourself. Adding a site you already have answers that site (and, while it is unpaid, a fresh checkout). Next: sites_get once your human has paid.

## Request body

- object
  - `url` string, uri, required: Any URL on the site; the server keeps its origin (https://example.com).
  - `display_name` string: A label for the site; without one, Frontshelf names it by its title or host.
  - `max_pages` integer: The most pages one crawl reads (the plan's cap still applies); leave it out for the default budget.
  - `dry_run` boolean: true: check the call and say what it would do, without doing it.
  - `confirm` boolean: true: go ahead with a change that asks for confirmation.

## Response `201`

Add a site to audit; your human completes its checkout

- object
  - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
  - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
  - `next_actions` object[], required: What to call next, best first. Follow them.
    - `capability` string, required: What to call next: a capability.
    - `arguments` object, required: Its arguments, complete; pass them as they are.
    - `instruction` string, required: What to do, written to you.
  - `site` object, required
    - `id` string, required: The canonical site id every other capability takes.
    - `origin` string, required
    - `display_name` string, nullable, required
    - `billing` object, required
      - `phase` 'unpaid' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unmetered' | 'comped', required: `unpaid` and `canceled` sites are read-only; `unmetered` means billing is off; `comped` means Frontshelf includes the site, fully on (`current_period_end` is when that ends, null for no end); nothing is charged for it unless `whop_renewal` says a Whop subscription still renews.
      - `read_only` boolean, required: True: reads work, crawls and verification refuse with BILLING_REQUIRED. Give your human `checkout_url`.
      - `trial_ends_at` string, nullable, required: While trialing: when the card is charged (ISO 8601).
      - `current_period_end` string, nullable, required: The end of the paid period, or when a cancellation takes effect (ISO 8601).
      - `cancel_at_period_end` boolean, required
      - `checkout_url` string, nullable, required: Present exactly when the site needs a checkout to run. Hand it to your human word for word.
      - `trial_offered` boolean, required: True: the checkout starts with the free trial (the workspace's first site, card required). False: it charges at checkout. Say which to your human; false whenever `checkout_url` is null.
      - `whop_renewal` object, nullable, required: Only while `comped`: a Whop subscription bought for this site still renews, so your human is still charged until it is cancelled (on the site's Plan and billing in the Frontshelf app, a signed-in person's act; the site stays included). `renews_at` is its next charge (ISO 8601) when known. Null otherwise.
        - `renews_at` string, nullable, required
    - `dashboard_url` string, required: The page in Frontshelf to hand your human (app-relative).
  - `checkout_url` string, nullable, required: The site's checkout link (a stable address on Frontshelf that opens Whop's checkout) your human completes to subscribe; null when nothing is owed (billing is off, or the site is already paid).

## Other responses

- `400`: VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `403`: ORGANIZATION_FROZEN, SCOPE_DENIED
- `409`: AGENT_STOPPED
- `428`: CONFIRMATION_REQUIRED
- `503`: PLATFORM_READ_ONLY, DEPENDENCY_UNAVAILABLE

---

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