# SiteShot Agent Context

This file combines the core SiteShot agent-readable documentation. It is generated from the same Markdown pages linked by `/llms.txt`.

## Pricing

Use `GET /api/v1/agent/plans/` to list public SiteShot tariffs. Agents must use this endpoint instead of scraping the human pricing page.

Each plan includes:

- `id`: tariff identifier used when creating a Checkout Session.
- `name`: public plan name.
- `screenshots_included`: screenshots included in the billing period.
- `number_of_workers`: dedicated parallel workers.
- `price_per_additional_screenshot`: overage unit price.
- `monthly_payment`: recurring plan price.
- `currency`: billing currency.
- `frequency`: billing frequency.

Only public tariffs can be selected for agent checkout.

## Signup

Use `POST /api/v1/agent/signup/` with `email`, `first_name`, and `last_name` to start an email-gated account setup.

The endpoint creates an inactive account when the email is new and sends a secure setup link. The user confirms the email address and sets a password on SiteShot. Agents must not ask users to share passwords in chat.

The endpoint returns `202 Accepted` with a generic `setup_email_sent` status. The generic response avoids revealing whether an email address already has an account.

## Authentication

SiteShot agent actions use OAuth 2.0 authorization code flow with scoped access tokens.

ChatGPT Actions should be configured as a confidential OAuth client with a client secret. The SiteShot ChatGPT Actions flow does not require PKCE.

Required scopes:

- `account:read`: read profile and subscription status.
- `usage:read`: read screenshot usage and quota summary.
- `billing:checkout`: create Stripe Checkout Sessions.
- `api_key:read`: explicitly reveal the full screenshot API key.

ChatGPT Actions should import `/openapi.json` and use the OAuth configuration from the `SiteShotOAuth` security scheme.

## Subscription flow

Use `POST /api/v1/agent/checkout-sessions/` with a public `tariff_id` to start a subscription.

The endpoint requires a verified account and the `billing:checkout` OAuth scope. It returns a Stripe Checkout URL. The user confirms payment in Stripe; the agent must not collect card details.

After Stripe confirms the Checkout Session, the existing SiteShot Stripe webhook activates the subscription. Use `GET /api/v1/agent/subscription/` to read the current status.

## Usage

Use `GET /api/v1/agent/usage/` with the `usage:read` scope to read the current quota summary.

The response includes:

- current plan.
- subscription status.
- billing period start and end.
- next payment date.
- screenshots included.
- screenshots used.
- screenshots remaining.
- additional screenshots created over the included quota.
- open screenshot API connections.

The v1 agent API does not expose daily breakdowns or per-request logs.

## Screenshot API

The screenshot generation API remains `https://api.site-shot.com/`.

Agents should use the existing screenshot API key as the `userkey` parameter:

```text
https://api.site-shot.com/?url=https://example.com/&userkey=YOUR_API_KEY
```

Important parameters include `url`, `width`, `height`, `full_size`, `max_height`, `format`, `response_type`, `delay_time`, `timeout`, `country`, `language`, `time_zone`, `geolocation`, `no_ads`, and `no_cookie_popup`.

The agent-ready v1 project documents the existing screenshot API. It does not rewrite the screenshot generation backend.

## Security

Agents may help users discover plans, start signup, authorize access, create Checkout Sessions, read status, and explicitly reveal an API key.

Agents must not:

- collect or store SiteShot passwords.
- collect or store payment card details.
- claim that payment is complete before Stripe confirms it.
- call billing actions without the `billing:checkout` scope.
- reveal the screenshot API key without the `api_key:read` scope and explicit `reveal_api_key` action.

Read-only status calls never include the full screenshot API key.

## API key handling

The SiteShot screenshot API key is a long-lived operational secret used by `https://api.site-shot.com/`.

Generic profile, subscription, and usage endpoints never return the full key. They may return a masked representation for identification.

Use `POST /api/v1/agent/reveal-api-key/` with the `api_key:read` scope to reveal the key. The response includes a warning, an audit log id, a dashboard link, and a reset link.

If the key is exposed, the user should reset it from the SiteShot dashboard.