Type at least two letters.

    ↑ ↓ to moveEnter to open

    Sites API

    Add, read, change and remove sites.

    Updated

    12 live operations. Built from the OpenAPI contract at every release, so this page never lists an endpoint that does not work. Paths are relative to the base URL.

    To try these with your own account, sign in and open Automation → Try the API in the app.

    List sites in the workspace

    GET/api/v1/sites
    Scope: sites:readoperationId: listSites

    Parameters

    cursorstring · query
    limitinteger · query
    stackstring · query

    Responses

    200object

    Sites

    2 fields
    nextCursorstring or null
    dataarray of Site
    12 fields of data
    idstringrequired
    originstring (uri)required
    urlstring (uri)

    The address an audit reads.

    namestring
    scheduleSchedule
    lastRunobject or null

    Status and per-area counts of the latest audit.

    4 fields of lastRun
    idstring
    statusstring

    One of: queued, running, succeeded, partial, failed

    finishedAtstring or null (date-time)
    summaryarray of AreaSummary
    7 fields of summary
    areastring

    One of: availability, security, email, performance, marketing, accessibility, privacy, technology, exposure

    passinteger
    failinteger
    noDatainteger
    notTestedinteger
    regressedinteger
    improvedinteger
    stackstring or null
    verificationVerificationrequired
    lastRunIdstring or null
    openFindingsinteger
    labelsLabels

    Free key-value pairs, e.g. release, pipeline, NeoLoad test ID, Jira key.

    createdAtstring (date-time)
    ErrorProblem (application/problem+json)

    RFC 9457 problem

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.

    Add a site. The URL policy runs before anything is stored.

    POST/api/v1/sites
    Scope: sites:writeoperationId: createSite

    Parameters

    Idempotency-Keystring · header

    Request body SiteCreate

    urlstring (uri)required
    namestring

    At most 120 characters

    stackstring
    scheduleScheduleInput

    Recurring audit. The first run of a new schedule is one period from now.

    1 field of schedule
    frequencystringrequired

    One of: none, weekly, monthly

    labelsLabels

    Free key-value pairs, e.g. release, pipeline, NeoLoad test ID, Jira key.

    {
      "url": "https://www.example.com",
      "name": "Example"
    }

    Responses

    201Site

    Created

    12 fields
    idstringrequired
    originstring (uri)required
    urlstring (uri)

    The address an audit reads.

    namestring
    scheduleSchedule
    2 fields of schedule
    frequencystring

    One of: none, weekly, monthly

    nextRunAtstring or null (date-time)
    lastRunobject or null

    Status and per-area counts of the latest audit.

    4 fields of lastRun
    idstring
    statusstring

    One of: queued, running, succeeded, partial, failed

    finishedAtstring or null (date-time)
    summaryarray of AreaSummary
    7 fields of summary
    areastring

    One of: availability, security, email, performance, marketing, accessibility, privacy, technology, exposure

    passinteger
    failinteger
    noDatainteger
    notTestedinteger
    regressedinteger
    improvedinteger
    stackstring or null
    verificationVerificationrequired
    4 fields of verification
    statusstring

    `failed`: the last check did not find the proof.

    One of: unverified, verified, failed

    methodstring or null

    One of: dns_txt, file, null

    verifiedAtstring or null (date-time)
    checkedAtstring or null (date-time)
    lastRunIdstring or null
    openFindingsinteger
    labelsLabels

    Free key-value pairs, e.g. release, pipeline, NeoLoad test ID, Jira key.

    createdAtstring (date-time)
    ErrorProblem (application/problem+json)

    RFC 9457 problem

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.

    Get one site with its latest audit

    GET/api/v1/sites/{siteId}
    Scope: sites:readoperationId: getSite

    Parameters

    siteIdstring · pathrequired

    Responses

    200Site

    Site

    12 fields
    idstringrequired
    originstring (uri)required
    urlstring (uri)

    The address an audit reads.

    namestring
    scheduleSchedule
    2 fields of schedule
    frequencystring

    One of: none, weekly, monthly

    nextRunAtstring or null (date-time)
    lastRunobject or null

    Status and per-area counts of the latest audit.

    4 fields of lastRun
    idstring
    statusstring

    One of: queued, running, succeeded, partial, failed

    finishedAtstring or null (date-time)
    summaryarray of AreaSummary
    7 fields of summary
    areastring

    One of: availability, security, email, performance, marketing, accessibility, privacy, technology, exposure

    passinteger
    failinteger
    noDatainteger
    notTestedinteger
    regressedinteger
    improvedinteger
    stackstring or null
    verificationVerificationrequired
    4 fields of verification
    statusstring

    `failed`: the last check did not find the proof.

    One of: unverified, verified, failed

    methodstring or null

    One of: dns_txt, file, null

    verifiedAtstring or null (date-time)
    checkedAtstring or null (date-time)
    lastRunIdstring or null
    openFindingsinteger
    labelsLabels

    Free key-value pairs, e.g. release, pipeline, NeoLoad test ID, Jira key.

    createdAtstring (date-time)
    ErrorProblem (application/problem+json)

    RFC 9457 problem

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.

    Rename a site or change its recurring audit schedule

    PATCH/api/v1/sites/{siteId}
    Scope: sites:writeoperationId: updateSite

    Parameters

    siteIdstring · pathrequired

    Request body

    namestring

    At most 120 characters

    scheduleScheduleInput

    Recurring audit. The first run of a new schedule is one period from now.

    1 field of schedule
    frequencystringrequired

    One of: none, weekly, monthly

    {
      "schedule": {
        "frequency": "weekly"
      }
    }

    Responses

    200Site

    Site

    12 fields
    idstringrequired
    originstring (uri)required
    urlstring (uri)

    The address an audit reads.

    namestring
    scheduleSchedule
    2 fields of schedule
    frequencystring

    One of: none, weekly, monthly

    nextRunAtstring or null (date-time)
    lastRunobject or null

    Status and per-area counts of the latest audit.

    4 fields of lastRun
    idstring
    statusstring

    One of: queued, running, succeeded, partial, failed

    finishedAtstring or null (date-time)
    summaryarray of AreaSummary
    7 fields of summary
    areastring

    One of: availability, security, email, performance, marketing, accessibility, privacy, technology, exposure

    passinteger
    failinteger
    noDatainteger
    notTestedinteger
    regressedinteger
    improvedinteger
    stackstring or null
    verificationVerificationrequired
    4 fields of verification
    statusstring

    `failed`: the last check did not find the proof.

    One of: unverified, verified, failed

    methodstring or null

    One of: dns_txt, file, null

    verifiedAtstring or null (date-time)
    checkedAtstring or null (date-time)
    lastRunIdstring or null
    openFindingsinteger
    labelsLabels

    Free key-value pairs, e.g. release, pipeline, NeoLoad test ID, Jira key.

    createdAtstring (date-time)
    ErrorProblem (application/problem+json)

    RFC 9457 problem

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.

    Remove a site with its runs and observations

    DELETE/api/v1/sites/{siteId}
    Scope: sites:writeoperationId: deleteSite

    Parameters

    siteIdstring · pathrequired

    Responses

    204

    Removed

    ErrorProblem (application/problem+json)

    RFC 9457 problem

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.

    Who gets the audit report of this site by email

    GET/api/v1/sites/{siteId}/report-email
    Scope: sites:readoperationId: getSiteReportEmail

    When an audit of the site finishes, the report can be mailed to the account's own address and, on a verified site, to up to five other recipients. At most one report mail per site per hour. The mail holds counts and the titles of the failed checks, nothing read from the audited page.

    Parameters

    siteIdstring · pathrequired

    Responses

    200ReportEmail

    Report email settings

    5 fields
    ownerboolean

    The report goes to the address of the account.

    recipientsarray of object
    3 fields of recipients
    idstring
    emailstring (email)
    addedAtstring or null (date-time)
    recipientLimitinteger
    recipientsAllowedboolean

    True on a verified site. While false, no recipient can be added and the listed ones get no mail.

    lastSentAtstring or null (date-time)
    ErrorProblem (application/problem+json)

    RFC 9457 problem

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.

    Turn the report mail to the account's own address on or off

    PATCH/api/v1/sites/{siteId}/report-email
    Scope: sites:writeoperationId: updateSiteReportEmail

    Parameters

    siteIdstring · pathrequired

    Request body

    ownerbooleanrequired
    {
      "owner": true
    }

    Responses

    200ReportEmail

    Report email settings

    5 fields
    ownerboolean

    The report goes to the address of the account.

    recipientsarray of object
    3 fields of recipients
    idstring
    emailstring (email)
    addedAtstring or null (date-time)
    recipientLimitinteger
    recipientsAllowedboolean

    True on a verified site. While false, no recipient can be added and the listed ones get no mail.

    lastSentAtstring or null (date-time)
    ErrorProblem (application/problem+json)

    RFC 9457 problem

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.

    Add another recipient of the report (verified sites only)

    POST/api/v1/sites/{siteId}/report-email/recipients
    Scope: sites:writeoperationId: addSiteReportRecipient

    Needs a verified site (403 `verification_required`) and `confirmed: true`: with it you state that the person agreed to get the reports; who is added is your responsibility. 409 `recipient_limit` (five per site), `recipient_exists`, or `recipient_opted_out` when the address stopped the reports of this account. Every mail tells the recipient who added them and has a link that stops it.

    Parameters

    siteIdstring · pathrequired

    Request body

    emailstring (email)required
    confirmedbooleanrequired
    {
      "email": "string",
      "confirmed": true
    }

    Responses

    201ReportEmail

    Report email settings with the new recipient

    5 fields
    ownerboolean

    The report goes to the address of the account.

    recipientsarray of object
    3 fields of recipients
    idstring
    emailstring (email)
    addedAtstring or null (date-time)
    recipientLimitinteger
    recipientsAllowedboolean

    True on a verified site. While false, no recipient can be added and the listed ones get no mail.

    lastSentAtstring or null (date-time)
    ErrorProblem (application/problem+json)

    RFC 9457 problem

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.

    Remove a recipient

    DELETE/api/v1/sites/{siteId}/report-email/recipients/{recipientId}
    Scope: sites:writeoperationId: removeSiteReportRecipient

    Parameters

    siteIdstring · pathrequired
    recipientIdstring · pathrequired

    Responses

    200ReportEmail

    Report email settings without the recipient

    5 fields
    ownerboolean

    The report goes to the address of the account.

    recipientsarray of object
    3 fields of recipients
    idstring
    emailstring (email)
    addedAtstring or null (date-time)
    recipientLimitinteger
    recipientsAllowedboolean

    True on a verified site. While false, no recipient can be added and the listed ones get no mail.

    lastSentAtstring or null (date-time)
    ErrorProblem (application/problem+json)

    RFC 9457 problem

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.

    Stop the report mails to an address (the link in the mail)

    POST/api/v1/report-emails/stop
    PublicoperationId: stopReportEmails

    No key: the token from the mail is the only credential. Stops every report from that account to that address; the account cannot add it again. Always answers 200, whether or not the token was known.

    Request body

    tokenstringrequired
    {
      "token": "string"
    }

    Responses

    200object

    Done

    1 field
    okboolean

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.

    Ownership state of a site, and what to publish to prove it

    GET/api/v1/sites/{siteId}/verification
    Scope: sites:readoperationId: getSiteVerification

    A passive audit runs on any public site. A deep audit needs a verified site. Publish the value as a DNS TXT record or as a file, then call `verifySite`. The proof must stay in place: it is checked again before every deep audit.

    Parameters

    siteIdstring · pathrequired

    Responses

    200VerificationDetail

    Verification state and instructions

    6 fields
    statusstring

    `failed`: the last check did not find the proof.

    One of: unverified, verified, failed

    methodstring or null

    One of: dns_txt, file, null

    verifiedAtstring or null (date-time)
    checkedAtstring or null (date-time)
    unlocksarray of string

    Audit levels a verified site can run.

    instructionsobject
    2 fields of instructions
    dns_txtobject
    3 fields of dns_txt
    typestring
    namestring
    valuestring
    fileobject
    2 fields of file
    urlstring (uri)
    contentstring
    ErrorProblem (application/problem+json)

    RFC 9457 problem

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.

    Look for the DNS TXT record or the file that proves ownership

    POST/api/v1/sites/{siteId}/verification
    Scope: sites:writeoperationId: verifySite

    Answers 200 whether or not the proof was found (`found`). At most one check per site every ten seconds (429 `verification_cooldown`).

    Parameters

    siteIdstring · pathrequired

    Request body

    methodstringrequired

    One of: dns_txt, file

    {
      "method": "dns_txt"
    }

    Responses

    200object

    Verification state after the check

    7 fields
    statusstring

    `failed`: the last check did not find the proof.

    One of: unverified, verified, failed

    methodstring or null

    One of: dns_txt, file, null

    verifiedAtstring or null (date-time)
    checkedAtstring or null (date-time)
    unlocksarray of string

    Audit levels a verified site can run.

    instructionsobject
    2 fields of instructions
    dns_txtobject
    3 fields of dns_txt
    typestring
    namestring
    valuestring
    fileobject
    2 fields of file
    urlstring (uri)
    contentstring
    foundboolean
    429Problem (application/problem+json)

    RFC 9457 problem

    ErrorProblem (application/problem+json)

    RFC 9457 problem

    Try it: signed in, open this operation in the app. It runs against your own account, with no key to paste.