squirrelscan
GitHub

Create an audit run

Start a cloud audit run

POST/v1/agent-runs

Start a new cloud audit run. Send a `url` and, optionally, a `config` object (for example `{"maxPages":1,"enabledRulePatterns":["ax/*","core/robots-meta"],"disabledRulePatterns":["ai/page-type-match","ai/site-metadata","ai/llm-parsability"],"render":false,"externalLinksEnabled":false,"ephemeral":true}`). With an API key the run is dispatched to the cloud crawler immediately (`trigger` defaults to `api`) and progresses asynchronously; poll `GET /v1/agent-runs/{id}` for status. Cloud features are credit-gated. If the requested page count exceeds the org's plan ceiling, the run still starts at the plan's max (clamp, never a hard error) and the response carries a `notice` field (`type: "page_limit_clamped"`) saying so. A request the API cannot honour as written (an unknown `config` key, a rule pattern that matches nothing, a selection that leaves no rule to run) is a 400 `VALIDATION_ERROR` and nothing is charged or started.

Request bodyrequired

urlstring (uri)required

Site URL to audit.

trigger"api"default: api

Run origin. Optional for an API key, which gets `api` (it dispatches the cloud crawler) whether it sends it or not. A signed-in session must send it: omitting it is a 400. (`cli`/`github`/`scheduled` are internal-origin values that skip cloud dispatch and are not accepted here.)

Available options: api

modeanydefault: audit
modelstring
configobject | string

Optional run config: an object (preferred) or the same object as a JSON-encoded string (the older form, still accepted). A string that is not valid JSON, a value that is not an object, a key outside `CreateAuditRunConfig`, or a wrongly typed or invalid value is a 400 `VALIDATION_ERROR` (nothing is started or charged); it is never silently ignored. The config a run reports back in `GET /v1/agent-runs/{id}` can be sent again: the keys the server writes into it (listed in `CreateAuditRunConfig`) are accepted and dropped, and the run's own values are used instead. A completed run's config can also hold keys written during the run (timings, billing, failure detail); those are not accepted.

websiteIdstring
auditIdstring

Responses

Run created (status `pending`).

idstringrequired
status"pending" | "queued"required

`pending` once dispatched; `queued` when the run is waiting for a container slot and starts by itself (the response then carries `queue`).

Available options: pending, queued

createdAtstring (date-time)required
noticeobject

Present only when the run's requested page count exceeded the org's plan ceiling. The run is never rejected for this (clamp-and-notify, not a hard error) — it dispatches at `applied` pages instead of `requested`, and this field says so.

disabledRulePatternsstring[]

The disable list this request sent, as expanded. Present only when `config.disabledRulePatterns` was sent and not empty.

enabledRulePatternsstring[]

The include filter the run applies, as expanded (`ax` becomes `ax/*`). Present only when `config.enabledRulePatterns` was sent.

renderboolean

Whether the run renders pages. Present only when `config.render` was sent.

ephemeralboolean

Whether the one-shot treatment applies. Present only when `config.ephemeral` was sent.

ephemeralIgnoredReasonstring

Why `ephemeral` was not honoured, when `ephemeral` is `false`.

editorSummaryboolean

Whether the run builds the editor's summary. Present only when `config.enabledRulePatterns` or `config.editorSummary` was sent.

editorSummarySkippedReason"rule-filtered run" | "disabled by the run config"

Why the summary is skipped, when `editorSummary` is `false`.

Available options: rule-filtered run, disabled by the run config

curl --request POST \
  --url "https://api.squirrelscan.com/v1/agent-runs"
{
  "id": "<string>",
  "status": "pending",
  "createdAt": "2023-11-07T05:31:56Z",
  "notice": {
    "type": "<string>",
    "requested": 123,
    "applied": 123,
    "planId": "free",
    "planCap": 123,
    "upgradeHint": "<string>"
  },
  "disabledRulePatterns": [],
  "enabledRulePatterns": [],
  "render": true,
  "ephemeral": true,
  "ephemeralIgnoredReason": "<string>",
  "editorSummary": true,
  "editorSummarySkippedReason": "rule-filtered run"
}

Type to search…

↑↓ navigate↵ openesc close