> ## Documentation Index > Fetch the complete documentation index at: https://docs.cookiechimp.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Start a scan > Queue a scan of the account's website. Only one scan can run at a time per account, and accounts have a daily scan limit — both come back as a `422`, as does a mobile app account, which has no website to crawl. Scanning is asynchronous: the scan is created `queued`, and the report appears on the scan once its status reaches `completed`. ## OpenAPI ````yaml post /scans openapi: 3.1.0 info: title: CookieChimp API description: | API for CookieChimp.com. ## Request bodies Resource endpoints expect the resource wrapped under its own key, e.g. `{"category": {"name": "Analytics"}}` rather than a bare object. `PUT /password` wraps in `user`. Two endpoints take their body unwrapped: `POST /auth`, which takes `email` and `password` at the top level, and `POST /consent-banners/from-template`, which takes `jurisdiction_id` — a selector for which template to build from, not an attribute of the banner it creates. ## Response envelopes Listing endpoints — including `GET /groups` and `GET /accounts` — return `{"pagination": {...}, "data": [...]}`. `GET /banner-templates` is the exception: it returns `{"data": [...]}` with no pagination, being a fixed catalogue rather than a collection of the account's records. Most single-resource endpoints return `{"data": {...}}`; a single group or account is returned unwrapped. Resource-deletion endpoints return `{"message": "..."}`; `DELETE /auth` returns an empty object. version: 1.2.0 servers: - url: https://cookiechimp.com/api/v1 security: - authorization: [] paths: /scans: post: tags: - Scans summary: Start a scan description: | Queue a scan of the account's website. Only one scan can run at a time per account, and accounts have a daily scan limit — both come back as a `422`, as does a mobile app account, which has no website to crawl. Scanning is asynchronous: the scan is created `queued`, and the report appears on the scan once its status reaches `completed`. operationId: createScan parameters: - $ref: '#/components/parameters/account_id' requestBody: description: Scan to queue required: true content: application/json: schema: $ref: '#/components/schemas/ScanWriteRequest' responses: '201': description: Queued scan content: application/json: schema: $ref: '#/components/schemas/ScanResponse' '400': $ref: '#/components/responses/AmbiguousAccount' '401': $ref: '#/components/responses/AccountTokenRequired' '403': $ref: '#/components/responses/AccountAdminRequired' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' components: parameters: account_id: name: account_id in: query description: | Which account to act on, as the account's API id. Only meaningful for a user API key, which may reach several accounts — an account key already identifies exactly one and ignores this. Accepted by the endpoints that declare it; others act on the account the key resolves to on its own. Optional for reads, where it narrows the request to that account. Required for writes that declare it when the key can reach more than one account: without it the request would act on an account it picked rather than one you named, so it is refused with a `400`. required: false schema: type: string schemas: ScanWriteRequest: type: object properties: scan: $ref: '#/components/schemas/ScanWrite' required: - scan example: scan: starting_url: https://example.com max_pages: 25 crawl_subdomains: false ScanResponse: type: object properties: data: $ref: '#/components/schemas/Scan' ScanWrite: type: object properties: starting_url: type: string description: > URL the crawl starts from. A missing scheme is treated as `https://`. Defaults to the account's own domain when omitted. max_pages: type: integer minimum: 1 maximum: 100 description: Maximum pages to crawl crawl_subdomains: type: boolean description: Whether the crawl follows links onto subdomains Scan: type: object properties: id: type: string readOnly: true status: type: string enum: - queued - in_progress - completed - failed readOnly: true starting_url: type: string domain: type: string readOnly: true description: Host derived from `starting_url`, without a `www.` prefix max_pages: type: - integer - 'null' crawl_subdomains: type: boolean response_code: type: - string - 'null' readOnly: true report: type: object readOnly: true description: | Only present once `status` is `completed`. Storage items found before and after consent, grouped by vendor and storage type. properties: before_consent: type: object additionalProperties: true after_consent: type: object additionalProperties: true created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true example: id: scn1 status: queued starting_url: https://example.com domain: example.com max_pages: 25 crawl_subdomains: false response_code: null created_at: '2023-03-01T09:00:00Z' updated_at: '2023-03-01T09:00:00Z' Error: type: object description: | The standard error envelope, used for authentication, authorization, pagination and not-found errors. properties: errors: type: array items: type: object properties: code: type: integer message: type: string example: errors: - code: 401 message: Invalid API Key ValidationError: type: object description: | Returned when a create or update fails validation. Each entry carries a single human-readable `error` string. properties: errors: type: array items: type: object properties: error: type: string example: errors: - error: Name can't be blank responses: AmbiguousAccount: description: | A user API key that can reach more than one account attempted a write without saying which account it meant. Pass `account_id` (the account's API id) as a query parameter. Account keys are never ambiguous. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: 400 message: >- Specify account_id when the API key can access more than one account AccountTokenRequired: description: | Missing or invalid API token, or a token that does not resolve to an account. Account-scoped endpoints accept an account token, or a user token whose user belongs to an account; partner tokens are rejected. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: 401 message: API key must belong to an account AccountAdminRequired: description: | The token resolved to a user who is not an admin of this account. Configuration changes are admin-only, mirroring the dashboard — a group admin qualifies even without a direct membership, since a group role supersedes one. Account tokens carry the account's own authority and never see this; reads are unaffected. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: 403 message: User must be an admin of this account ValidationError: description: The record could not be saved content: application/json: schema: $ref: '#/components/schemas/ValidationError' RateLimited: description: | Too many requests. The general limit is 300 requests per 5 minutes per API token; the auth endpoints are throttled more tightly per IP. headers: Retry-After: description: Seconds until the current rate-limit window resets schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: 429 message: Too many requests. Please retry later. securitySchemes: authorization: type: http scheme: bearer description: API token obtained from the login endpoint or the dashboard ````