Hosts
Read the hosts a crawl has seen and manage their labels.
A host is a domain the crawl has encountered, such as example.com. Each host has a hash, a hex-encoded value used to address it as a path segment and to identify it.
These endpoints share the pagination and error conventions.
List hosts
/v1/hostsReturns a page of hosts the crawl has seen.
- page string
Pagination cursor. See pagination.
- per_page numberdefault: 10
Maximum number of hosts to return.
min: 1max: 100- host_hashes string[]
Return only hosts with these hashes.
- hosts string[]
Return only hosts with these exact domains.
- labels object
Return only hosts whose labels match every supplied key and value.
curl 'http://localhost:8022/v1/hosts?per_page=20' \
-H 'X-Tenant-Id: acme'Upsert hosts
/v1/hostsInserts or updates a batch of hosts by domain.
- hosts string[]required
The domains to insert or update.
min: 1max: 255
curl -X PUT 'http://localhost:8022/v1/hosts' \
-H 'X-Tenant-Id: acme' \
-H 'Content-Type: application/json' \
-d '{ "hosts": ["example.com", "docs.example.com"] }'Get a host
/v1/hosts/{host_hash}Returns a single host by hash. The {host_hash} path segment is the host's
hash.
curl 'http://localhost:8022/v1/hosts/9a2f…' \
-H 'X-Tenant-Id: acme'List a host's links
/v1/hosts/{host_hash}/linksReturns a page of links belonging to a host. The {host_hash} path segment is
the host's hash.
- page string
Pagination cursor. See pagination.
- per_page numberdefault: 10
Maximum number of links to return.
min: 1max: 100- url_hashes string[]
Return only links with these hashes.
- urls string[]
Return only links with these exact URLs.
- labels object
Return only links whose labels match every supplied key and value.
curl 'http://localhost:8022/v1/hosts/9a2f…/links?per_page=20' \
-H 'X-Tenant-Id: acme'Get a host's labels
/v1/hosts/{host_hash}/labelsReturns the labels for a host. The {host_hash} path segment is the host's
hash.
curl 'http://localhost:8022/v1/hosts/9a2f…/labels' \
-H 'X-Tenant-Id: acme'Set a host's labels
/v1/hosts/{host_hash}/labelsMerges the supplied labels into a host's labels, replacing the value of any key that already exists.
- labels objectrequired
String key and value pairs to set on the host.
curl -X PUT 'http://localhost:8022/v1/hosts/9a2f…/labels' \
-H 'X-Tenant-Id: acme' \
-H 'Content-Type: application/json' \
-d '{ "labels": { "tier": "primary" } }'Delete a host's labels
/v1/hosts/{host_hash}/labelsDeletes the named label keys from a host.
- keys string[]
The label keys to delete.
curl -X DELETE 'http://localhost:8022/v1/hosts/9a2f…/labels?keys=tier' \
-H 'X-Tenant-Id: acme'