CNF API · v1

Overview

Version 1 exposes DNS operations for zones you have claimed through DNS Management. Create and revoke tokens under Account → API keys.

Base URL and versioning

https://api.c.nf/v1

All endpoints are below /v1. Breaking changes will use a new major-version path. Backwards-compatible fields and endpoints may be added to v1 and will be recorded in the changelog.

Authentication and scopes

Every request that reads or changes account data must include a Bearer token. Tokens begin with cnf_ followed by 32 hexadecimal characters.

curl https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer cnf_a1b2c3d4e5f60718293a4b5c6d7e8f90"

Tokens are stored as one-way hashes and the complete value is shown only when it is created. If a token is lost, revoke it and create another.

Each token carries scopes. A token with no configured scope receives dns:read by default. Write scope also permits reads.

A mismatch returns 403 forbidden_scope and includes both required_scopes and token_scopes for diagnosis.

Per-user isolation

A Bearer token resolves to exactly one user_id. Every zone handler checks that user’s verified claim before any read or write. There is no administrator override, impersonation path or cross-user bypass.

Even a token with * can act only on zones verified by its own user. Attempting to use another account’s zone returns 403 forbidden_zone.

Response envelope

Successful response

{
  "success": true,
  "data": { "zones": [] },
  "request_id": "req_abc123def456abcd"
}

Error response

{
  "success": false,
  "error": "forbidden_zone",
  "message": "zone not verified for this account (or does not exist)",
  "request_id": "req_abc123def456abcd",
  "zone": "example.com"
}

request_id appears on every response and is safe to record with client-side logs.

Error codes

Zone verification

When POST /v1/dns/zones claims a zone, the server chooses one of these paths:

1. Instant verification (method: "auto") — Used when no other account has claimed the zone. The claim is immediately verified. Records become authoritative only after the owner points the registrar’s NS delegation to the returned nameservers.
2. TXT verification — Used for a contested claim. Add the returned TXT value at _cnfdns-verify.<zone>, then call POST /v1/dns/zones/{zone}/verify.
3. Legacy NS verification — Older pending claims may use verify_method: "ns". Verification compares the zone’s live NS answers with its expected nameserver set.

Verification is idempotent. Repeating it for a verified claim returns verified: true without changing the claim.

Record types and limits

Supported record types

A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR, SPF.

priority is required for MX and SRV and ignored for other types. ttl must be between 60 and 2,592,000 seconds.

Endpoints

Public utilities

Small dependable endpoints that need no account: time, address, country, exchange rates and hashes.

Account

Who a token belongs to, and what it is allowed to do.

DNS

Claim a domain, prove you control it, then manage its records.

Credentials

The private credential store behind the credentials tool.

Files

Personal file storage: list, upload, edit, share and delete.

CDN

Edge caching and traffic for the files you share.

SMS forwarder

Messages relayed from your phone, and the keys that let it in.

Static sites

Upload a zip, serve a site.

Deployments

The form, webhook and shortlink endpoints you have deployed.

Domains

Your domain portfolio and its registration data.

Packages

Publish releases and read back their versions and download counts.

WHOIS

Registration data for a domain, cached and shared with the domain tools.

For AI agents

Point an agent at /v1/ai for a brief written to be pasted straight into a prompt, or at /v1/ai?format=json for the same endpoints as tool definitions. /v1/openapi.json is the full OpenAPI 3.1 contract, and /llms.txt is the crawler map. All four are generated from the same route table as this page, so none of them can describe an endpoint that does not exist.

curl https://api.c.nf/v1/ai
curl https://api.c.nf/v1/ai?format=json
curl https://api.c.nf/v1/openapi.json

Request fields

Create a zone claim

Create a DNS record

Update a DNS record

Examples

curl -H "Authorization: Bearer $CNF_TOKEN" \
  https://api.c.nf/v1/dns/zones

curl -X POST https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com"}'

curl -X POST https://api.c.nf/v1/dns/zones/example.com/verify \
  -H "Authorization: Bearer $CNF_TOKEN"

curl -X POST https://api.c.nf/v1/dns/zones/example.com/records \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"api","value":"192.0.2.10"}'

Quick start

1. Create an API key with dns:write at Account → API keys, and copy it when it is shown.
2. Store the token in a protected environment variable on your machine.
3. Call GET /v1/account/me to confirm the token and its scopes.
4. Claim a zone. The response says whether verification is instant, TXT-based or legacy NS-based.
5. Complete the returned DNS proof when one is required, then call the verify endpoint.
6. Create, read, update or delete records only after the claim is verified.

Changelog

v1.1.0 — zone management

• Added API-based zone claims, including instant and TXT verification paths.
• Added single-zone status and idempotent verification endpoints.
• Added claim revocation without implicit record deletion.
• Added verified, pending and all filters to the zone list.

v1.0.0 — initial release

• Added Bearer-token authentication and per-user zone isolation.
• Added read and write scopes.
• Added account, zone-list and record-management endpoints.
• Added a consistent response envelope with a request identifier.