Create a check

POST

/api/v1/checks

Docs menu

Checks one or more public pages and answers 202 at once with the check queued. Read the result with GET /checks/{id}. With text, each page is searched for your text and your link; without text, each page is searched for a link to your domain. We fetch each page once, and read its robots.txt. We send no cookies or credentials.

Key
Bearer key, test or live
Scope
checks:write
Idempotency
Header recommended

Headers

Idempotency-Keystringoptional

Makes a retry safe: the same key with the same request returns the first answer. See Idempotency.

Request body

JSON. A field this endpoint does not know is refused with unknown_parameter.

pagesarray of stringrequired

The pages to check (at least one). At most your account's pages per check (100 in test mode).

client_domainstringrequired

Your website, such as example.com. We look for links to it.

textstring or nulloptional

The text you placed, at least 40 words and at most 50,000 characters. Leave it out for a link check.

modestringoptional

auto: text given means text, otherwise link_check.

Default: auto

autotextlink_check

metadataobjectoptional

Your own notes: up to 20 keys, each key up to 40 characters, each value up to 500.

project_idstring or nulloptional

Tag the check to one of your client projects (an id from the console). A project of another workspace answers not_found.

Response

202. The check, queued.

idstring

chk_...

objectstring

check

livemodeboolean
statusstring

queuedrunningcompletedfailedcanceled

modestring

textlink_check

kindstring

checkrecheck

sourcestring

apiconsolemonitor

monitor_idstring or null
client_domainstring
page_countinteger
project_idstring or null

The client project it is tagged to, in the same workspace; null when none.

pagesarray of object

Empty until the check has completed.

Show child fields
objectstring

page_result

positioninteger

0-based, in the order you sent the pages.

urlstring

The address you sent.

verdictstring or null

null only when the check failed before this page ran.

VERIFIED_LIVELIVE_NO_FINGERPRINTNOT_LIVEUNVERIFIABLELINK_LIVELIVE_NO_LINK

fetched_atstring or null

When we fetched the page (UTC). This is the age of the result.

reusedboolean

True when the result comes from a fetch made in the last 15 minutes.

final_urltext or unknown
http_statusnumber or unknown
registrable_domaintext or unknown
textobject
linksobject
disclosureobject
noindexyes/no or unknown
canonical_urltext, null or unknown
published_attext, null or unknown
unknownsarray of object

Every unknown above, by dotted field name.

chargedboolean

Whether this page was billed.

rejectedarray of object

Addresses refused at submission. Never charged.

Show child fields
inputstring
codestring

See page rejection codes on the Errors page.

summaryobject or null
creditsobject
Show child fields
heldinteger
chargedinteger or null
free_pagesinteger
failure_codestring or null
metadataobject

Your own notes: up to 20 keys, each key up to 40 characters, each value up to 500.

created_atstring
started_atstring or null
completed_atstring or null

Errors

CodeStatusMeaning
missing_scope403The API key does not have the scope this endpoint needs.
body_not_json400The request body must be a JSON object.
body_too_large413The request body is larger than 256 KB.
unknown_parameter400The request has a parameter this endpoint does not accept.
parameter_missing400A required parameter is missing.
parameter_invalid400A parameter has a value this endpoint does not accept.
pages_empty400Give at least one page address.
too_many_pages400This check has more pages than your account may send in one check.
no_usable_page400None of the page addresses could be used. Each one is listed under rejected with its reason.
client_domain_invalid400The client domain is not a public web domain, such as example.com.
text_too_short400The text is too short to recognize on a page. Send at least 40 words.
text_too_long400The text is longer than 50,000 characters.
text_given_for_link_check400A link check takes no text. Leave text out, or use mode text.
mode_unknown400The mode must be auto, text or link_check.
idempotency_key_invalid400The Idempotency-Key header must be 1 to 255 printable characters.
idempotency_key_reused422This Idempotency-Key was used with a different request.
insufficient_balance402The balance is too low for this request.
account_daily_limit429The account has used its pages for today (UTC).
pending_pages_limit429The account has too many pages waiting. Wait for a check to finish.
target_host_limit429That website has had as many checks as we make in a day. Try again tomorrow.
free_allowance_paused429Free checks are paused for today across PressProve. Top up to keep checking now, or try again tomorrow (UTC).
daily_work_budget_reached429The account has used its checking time for the last 24 hours. Work already queued still finishes; try again after the time in Retry-After.
new_account_spend_limit429A new account may spend a limited number of credits in 24 hours. The limit lifts as the account ages.
country_blocked403We cannot serve this country.
account_frozen403The account is frozen. Read requests still work; contact us to lift it.
account_not_onboarded403Finish the account details in the console first.
live_mode_closed403Live mode is not open yet. Test keys work now.
engine_unavailable503Live checks are not available right now.

Any request can also fail with missing_api_key, invalid_api_key, api_key_revoked, rate_limited or internal_error. See Errors.

In test mode