Domains
Verifying a domain proves that your organization controls it. Products use the proof: for example, a knowledge website source on a verified domain gets higher limits and scheduled refresh.
A verification belongs to your organization only. Another organization's verification of the same domain never counts for you.
Knowledge website sources use the domains verified on this page; they are verified nowhere else. Website sources themselves are not available yet.
Who can manage domains: see Who can manage integrations. In short, portal owners and admins, or an API key with domains:write on a management key.
Verify a domain
-
Add it. In the portal, open Settings → Integrations → Domains and choose Add domain. With the API:
curl -X POST "https://api.infus.ai/v1/domains" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "example.com"}'Enter a registrable domain (
example.com) or a host below one (docs.example.com), withouthttps://, a port or a path. The answer (201,status: unverified) holds the values to publish inchallenges. -
Publish the proof with one of the methods below. The DNS record is the simplest and covers the most.
-
Check it. Choose Check now in the portal, or:
curl -X POST "https://api.infus.ai/v1/domains/$DOMAIN_ID:verify" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"method": "dns_txt"}'The answer is
202with the domain andcheck_running: true. PollGET /v1/domains/{domain_id}untilcheck_runningisfalse:statusis thenverified, orfailedwithlast_error.
Methods
The token is one value per organization and registrable domain. It is the same for every method and every host below that domain, and it never changes.
Method (method) | What to publish | What it covers |
|---|---|---|
DNS record (dns_txt, recommended) | A TXT record on the registrable domain itself (example.com, also when you want docs.example.com) with the value infus-verification=<token> (challenges.dns_txt) | The registrable domain and every host below it. Only for a registrable domain |
File (well_known) | A plain-text file at https://<host>/.well-known/infus-verification whose whole content is the value in challenges.well_known.content | That one host |
Meta tag (meta) | The tag in challenges.meta.html inside the <head> of the page in challenges.meta.url (by default https://<host>/; choose another page on the same host with check_url) | That one host |
Things that make a check fail:
- DNS record. Many DNS providers write the apex as
@or an empty name. A differentinfus-verification=value istoken_mismatch; no matching record istxt_not_found. New records can take up to an hour to be visible: check again later. Adns_txtcheck on a host answers422 method_not_allowed_for_domain. - File. The address must answer
200directly: redirects are not followed (file_redirected). The body must be exactly the value; a file that only contains it, or is larger than 4 KiB, isfile_not_found. - Meta tag. The page must answer without a redirect, and the tag must be in the HTML the server sends, inside
<head>. A tag added later by JavaScript is not seen (meta_not_found). - The site must let the check in. File and tag checks follow the site's robots.txt and do not get around bot protection. If they cannot reach the file or page, a first check fails with
fetch_error. The DNS method sends no request to your site.
A host below a registrable domain verified with the DNS record needs no proof of its own: it shows covered_by with the id of the domain that covers it. A file or meta tag on the registrable domain covers only that one host, not the hosts below it.
Statuses
status | Portal | Meaning |
|---|---|---|
unverified | Not checked yet | Added; no check has run |
pending | Checking… | A first check is running |
verified | Verified | A proof holds (verified_method, verified_at). It stays verified while it is checked again |
failed | Not verified | The latest check did not pass; last_error says why |
lost | Verification lost | A verified domain could no longer be confirmed (lost_at) |
proofs lists every method you tried on the domain, each with its own status.
Keeping a domain verified
Leave the record, file or tag in place. The platform checks every verified domain at least once a day, and products can ask for a fresh check before they rely on it.
- The proof is gone or changed: that proof is lost at that check. The domain stays verified while another of its proofs (
proofs) still holds, and is lost when none does. - The check cannot decide (DNS or the site does not answer,
401,403,429,5xx, a challenge page, robots.txt): the domain stays verified and is lost only when no check has succeeded for 72 hours. A short outage never costs you the verification.
When a domain is lost, the organization owner gets one Domain verification lost email per domain and day. Verifying it again restores it.
No webhooks for domains. Verification changes are not sent as webhook events. To watch them, poll GET /v1/domains (for example ?status=lost) or rely on the email.
Manage domains
| Operation | Endpoint |
|---|---|
List (filter with ?status=) / get | GET /v1/domains, GET /v1/domains/{domain_id} |
| Add | POST /v1/domains |
| Check now | POST /v1/domains/{domain_id}:verify with method (and check_url for meta) |
| Delete | DELETE /v1/domains/{domain_id} |
- Checking again while a check runs starts no second check.
- Each organization can start 30 checks per clock hour (
429 verification_rate_limited). - Deleting a domain removes its proofs. Products stop relying on it at once: for example, a knowledge website source falls back to the unverified tier unless another of your verified domains (such as the registrable domain with its DNS record) still covers it.
Every field is in the Integrations API Reference.
Errors
| Code | Status | Meaning |
|---|---|---|
domain_invalid | 422 | Not a registrable domain or a host below one (a public suffix, an IP address, a port, a path or a wildcard) |
domain_exists | 409 | Your organization already has this name (details.domain_id) |
method_not_allowed_for_domain | 422 | dns_txt on a host: the DNS record is for the registrable domain only |
domain_blocked | 403 | The domain, or a parent of it, is blocked by your platform operator |
verification_rate_limited | 429 | More than 30 checks this hour (retry_after_seconds) |
The codes every area shares are in the overview.