zpe-scraper

POST /_/api/v1/scrape POST /_/api/v1/scrape postScrape

POST /_/api/v1/scrape

Parameters

No parameters.

Request body application/json · required

field	type	required	notes
`url`	string (uri)	yes	The absolute address to scrape. The SSRF guard reads it before any browser opens, so a refused address costs nothing.
`formats`	array of "markdown" \| "html" \| "rawHtml" \| "links" \| "screenshot" \| "screenshot@fullPage"	no	Which readings to return. Defaults to markdown, html, rawHtml and links; duplicates are dropped.
`onlyMainContent`	boolean	no	Drop navigation, footers and other page chrome from the text. Defaults to true.
`waitFor`	integer	no	Milliseconds to wait after the page loads before reading it. Defaults to 0.
`timeout`	integer	no	The job's ceiling in milliseconds. Defaults to 60000 or the deployment's MAX_JOB_MS, whichever is lower.
`headers`	object	no	Extra request headers for the target, at most 20. Host and hop-by-hop headers are refused.

Responses

status	meaning	body
`200`	The page, read into the formats asked for, with the browser time it cost and how that time was measured.	object
`400`	The request could not be read, or the address was refused before any fetch: a blocked host, a blocked address, a scheme other than http or https, or credentials in the URL.	object
`401`	The credential is missing, or the door did not recognise it.	object
`402`	Payment required: this account holds no credit, or its balance cannot cover the browser time a scrape reserves before it starts.	object
`403`	This key may not do that: it is granted a different app, its scope does not cover this verb, or the request was refused by the site's own robots.txt.	object
`422`	The page could not be read: the address did not resolve, the redirect chain was too long, the body exceeded the size cap, or the driver reported an error.	object
`429`	Too many requests: this key has spent its request ceiling, or this account already has its browser slots open. Retry after the period the answer names.	object
`500`	This app failed while answering	object
`502`	The browser the scrape opened did not answer, so nothing could be read.	object
`503`	A service this app needs did not answer: the door could not check the credential, the ledger binding a metered call needs is absent, or the browser the scrape needs is not bound here.	object
`504`	The address did not answer in the time the request allowed.	object

Example

POST /_/api/v1/scrape, with a token from the door.

POST /_/api/v1/scrape

curl -X POST 'https://scrape.zpe.vc/_/api/v1/scrape' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "url": "https://example.com",
  "formats": [
    "markdown"
  ],
  "onlyMainContent": false,
  "waitFor": 0,
  "timeout": 0,
  "headers": {}
}'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/map POST /_/api/v1/map postMap

POST /_/api/v1/map

Parameters

No parameters.

Request body application/json · required

field	type	required	notes
`url`	string (uri)	yes	The absolute address whose links are listed. Answered from one guarded fetch, with no browser.

Responses

status	meaning	body
`200`	The links found at that address, filtered by the request, with the metered time the listing cost.	object
`400`	`url` is missing or is not a string, or the address was refused before any fetch: a blocked host, a blocked address, a scheme other than http or https, or credentials in the URL.	object
`401`	The credential is missing, or the door did not recognise it.	object
`402`	Payment required: this account holds no credit, or its balance cannot cover the time a listing reserves before it starts.	object
`403`	This key may not do that: it is granted a different app, its scope does not cover this verb, or the request was refused by the site's own robots.txt.	object
`422`	The page could not be read: the address did not resolve, the redirect chain was too long, or the body exceeded the size cap.	object
`429`	Too many requests: this key has spent its request ceiling. Retry after the period the answer names.	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer: the door could not check the credential, the ledger binding a metered call needs is absent, or the browser the scrape needs is not bound here.	object

Example

POST /_/api/v1/map, with a token from the door.

POST /_/api/v1/map

curl -X POST 'https://scrape.zpe.vc/_/api/v1/map' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "url": "https://example.com"
}'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/balance GET /_/api/v1/balance getBalance

GET /_/api/v1/balance

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The credit this account holds, in milliseconds of browser time, and whether it is live or only observed.	object
`401`	The credential is missing, or the door did not recognise it.	object
`403`	This key may not do that: it is granted a different app, its scope does not cover this verb, or the request was refused by the site's own robots.txt.	object
`429`	Too many requests: this key has spent its request ceiling. Retry after the period the answer names.	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer: the door could not check the credential, the ledger binding a metered call needs is absent, or the browser the scrape needs is not bound here.	object

Example

GET /_/api/v1/balance, with a token from the door.

GET /_/api/v1/balance

curl -X GET 'https://scrape.zpe.vc/_/api/v1/balance' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/usage GET /_/api/v1/usage getUsage

GET /_/api/v1/usage

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	This account's twenty most recent scrapes, newest first, with the address, time and charge of each.	object
`401`	The credential is missing, or the door did not recognise it.	object
`403`	This key may not do that: it is granted a different app, its scope does not cover this verb, or the request was refused by the site's own robots.txt.	object
`429`	Too many requests: this key has spent its request ceiling. Retry after the period the answer names.	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer: the door could not check the credential, the ledger binding a metered call needs is absent, or the browser the scrape needs is not bound here.	object

Example

GET /_/api/v1/usage, with a token from the door.

GET /_/api/v1/usage

curl -X GET 'https://scrape.zpe.vc/_/api/v1/usage' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/keys GET /_/api/v1/keys getKeys

GET /_/api/v1/keys

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	Every key this account has minted, with its label, when it was created and last used, and whether it is revoked.	object
`401`	The credential is missing, or the door did not recognise it.	object
`403`	This key may not do that: it is granted a different app, its scope does not cover this verb, or the request was refused by the site's own robots.txt.	object
`429`	Too many requests: this key has spent its request ceiling. Retry after the period the answer names.	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer: the door could not check the credential, the ledger binding a metered call needs is absent, or the browser the scrape needs is not bound here.	object

Example

GET /_/api/v1/keys, with a token from the door.

GET /_/api/v1/keys

curl -X GET 'https://scrape.zpe.vc/_/api/v1/keys' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/keys POST /_/api/v1/keys postKeys

POST /_/api/v1/keys

Parameters

name	in	required	type	notes
`Idempotency-Key`	header	no	string	A retry handle: a second POST carrying the same value answers `200` with the first call's key and label, `secret: null`, and mints nothing.

Request body application/json · optional

field	type	required	notes
`label`	string	no	A name for the key, shown in `GET /_/api/v1/keys`. A live key with the same label is refused rather than duplicated.

Responses

status	meaning	body
`200`	A replay: this `Idempotency-Key` was already answered. The same key id and label the first call returned, `secret: null`, and nothing minted.	object
`201`	The key was minted. The secret is in this answer and nowhere else: it is stored as a keyed digest.	object
`400`	A live key with that label already exists, the `Idempotency-Key` was empty or longer than 200 characters, or the key could not be minted for a reason the answer names.	object
`401`	The credential is missing, or the door did not recognise it.	object
`403`	This key may not do that: it is granted a different app, its scope does not cover this verb, or the request was refused by the site's own robots.txt.	object
`429`	Too many requests: this key has spent its request ceiling. Retry after the period the answer names.	object
`500`	This app failed while answering	object
`503`	Keys cannot be minted here: this deployment has no token pepper or no store, or the door could not check the credential.	object

Example

POST /_/api/v1/keys, with a token from the door.

POST /_/api/v1/keys

curl -X POST 'https://scrape.zpe.vc/_/api/v1/keys' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "label": "string"
}'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

DELETE /_/api/v1/keys/{id} DELETE /_/api/v1/keys/:id deleteKeysById

DELETE /_/api/v1/keys/:id

Parameters

name	in	required	type	notes
`id`	path	yes	string	The key's id, as `GET /v1/keys` answered it.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The key is revoked. A second call for the same id answers `404`: there is no live key left to revoke.	object
`401`	The credential is missing, or the door did not recognise it.	object
`403`	This key may not do that: it is granted a different app, its scope does not cover this verb, or the request was refused by the site's own robots.txt.	object
`404`	No live key with that id belongs to this account.	object
`429`	Too many requests: this key has spent its request ceiling. Retry after the period the answer names.	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer: the door could not check the credential, the ledger binding a metered call needs is absent, or the browser the scrape needs is not bound here.	object

Example

DELETE /_/api/v1/keys/:id, with a token from the door.

DELETE /_/api/v1/keys/{id}

curl -X DELETE 'https://scrape.zpe.vc/_/api/v1/keys/string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/domains GET /_/api/v1/domains getDomains

GET /_/api/v1/domains

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	Every domain this account has claimed, with the state of each claim and the TXT record it was proved with.	object
`401`	The credential is missing, or the door did not recognise it.	object
`403`	This key may not do that: it is granted a different app, its scope does not cover this verb, or the request was refused by the site's own robots.txt.	object
`429`	Too many requests: this key has spent its request ceiling. Retry after the period the answer names.	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer: the door could not check the credential, the ledger binding a metered call needs is absent, or the browser the scrape needs is not bound here.	object

Example

GET /_/api/v1/domains, with a token from the door.

GET /_/api/v1/domains

curl -X GET 'https://scrape.zpe.vc/_/api/v1/domains' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/domains POST /_/api/v1/domains postDomains

POST /_/api/v1/domains

Parameters

No parameters.

Request body application/json · required

field	type	required	notes
`domain`	string	yes	A bare hostname like `example.com`. It is normalized to lower case, and a scheme or a path is refused.

Responses

status	meaning	body
`200`	The claim exists: proved, already proved, or waiting for the TXT record the answer names.	object
`400`	The body could not be read, or `domain` is not a bare hostname like example.com.	object
`401`	The credential is missing, or the door did not recognise it.	object
`403`	This key may not do that: it is granted a different app, its scope does not cover this verb, or the request was refused by the site's own robots.txt.	object
`429`	Too many requests: this key has spent its request ceiling. Retry after the period the answer names.	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer: the door could not check the credential, the ledger binding a metered call needs is absent, or the browser the scrape needs is not bound here.	object

Example

POST /_/api/v1/domains, with a token from the door.

POST /_/api/v1/domains

curl -X POST 'https://scrape.zpe.vc/_/api/v1/domains' \
  -H 'Authorization: Bearer $ZPE_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
  "domain": "string"
}'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

DELETE /_/api/v1/domains/{domain} DELETE /_/api/v1/domains/:domain deleteDomainsById

DELETE /_/api/v1/domains/:domain

Parameters

name	in	required	type	notes
`domain`	path	yes	string	The bare hostname whose claim is dropped, as `GET /v1/domains` answered it.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The claim is dropped, so the site's robots.txt rules apply to this account again.	object
`400`	That is not a domain this route can read.	object
`401`	The credential is missing, or the door did not recognise it.	object
`403`	This key may not do that: it is granted a different app, its scope does not cover this verb, or the request was refused by the site's own robots.txt.	object
`404`	No claim for that domain belongs to this account.	object
`429`	Too many requests: this key has spent its request ceiling. Retry after the period the answer names.	object
`500`	This app failed while answering	object
`503`	A service this app needs did not answer: the door could not check the credential, the ledger binding a metered call needs is absent, or the browser the scrape needs is not bound here.	object

Example

DELETE /_/api/v1/domains/:domain, with a token from the door.

DELETE /_/api/v1/domains/{domain}

curl -X DELETE 'https://scrape.zpe.vc/_/api/v1/domains/string' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Matches in other apps

Parameters

Request body application/json · required

Responses

Example

Parameters

Request body application/json · required

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body application/json · optional

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body application/json · required

Responses

Example

Parameters

Request body

Responses

Example