Reference

Directory API

A free, public HTTP API to read the OARS-verified directory and submit a domain for verification. The authoritative contract is the OpenAPI 3.1 spec; agents can also use the MCP server.

https://knov.ai/api/v1

Authentication

None. This API exposes only public operations, so there are no API keys or OAuth flows to manage. Reads are open. The submit endpoint is open to any caller too — its protected effect (getting a domain verified or listed) is authorized by the domain-ownership challenge rather than by an account, which binds authorization to control of the specific domain. Found a security issue? See Security & disclosure.

Versioning & deprecation

The API is versioned in the path (/api/v1). Additive, backward-compatible changes (new endpoints, new optional fields) ship within the current major version. Breaking changes ship under a new major path (/api/v2); the prior version is then supported for at least 6 months, during which its responses carry a Deprecation header and a Sunset date (RFC 8594). The contract is versioned independently of the OARS spec version and declares its version in info.version.

Endpoints

List & search the directory

GET https://knov.ai/api/v1/directory

Returns listed directory entities, verified-first. All filters are optional and combine.

curl "https://knov.ai/api/v1/directory?level=3&limit=2"

{
  "count": 2,
  "total": 17,
  "limit": 2,
  "offset": 0,
  "results": [
    {
      "domain": "example.com",
      "name": "Example, Inc.",
      "entityType": "Business",
      "oarsLevel": 3,
      "verified": true,
      "verificationTier": "Reviewed",
      "categories": ["HVAC"],
      "location": ["Austin", "TX", "US"],
      "profileUrl": "https://knov.ai/profile/example.com"
    }
  ]
}

Get one domain (status + manifest)

GET https://knov.ai/api/v1/directory/{domain}

Returns the entity, its verification status, and its published oars.json. 404 if no listed or verified entity exists.

curl "https://knov.ai/api/v1/directory/example.com"

{
  "domain": "example.com",
  "name": "Example, Inc.",
  "entityType": "Business",
  "verification": {
    "verified": true,
    "verificationStatus": "verified",
    "verificationTier": "Reviewed",
    "oarsLevel": 3,
    "listed": true,
    "verifiedAt": "2026-05-20 14:11:02"
  },
  "profileUrl": "https://knov.ai/profile/example.com",
  "manifest": { "...": "the entity's oars.json" }
}

Submit a domain for verification

POST https://knov.ai/api/v1/verifications

Starts the verification flow and returns a long-running operation plus an ownership challenge. This endpoint requires an Idempotency-Key header (see Idempotency). Body is JSON.

curl -X POST "https://knov.ai/api/v1/verifications" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c2e9a-1b3d-4c7a-9e21-7a0d2c6f8b44" \
  -d '{"url":"example.com","contact_name":"Ada","contact_email":"[email protected]"}'

202 Accepted (or 200 if the domain is already known):

{
  "id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "domain": "example.com",
  "status": "pending_ownership",
  "terminal": false,
  "statusUrl": "https://knov.ai/api/v1/verifications/a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "pollAfter": 300,
  "oarsLevel": 2,
  "ownership": {
    "token": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "methods": { "manifest": { "...": "..." }, "file": { "...": "..." }, "dns": { "...": "..." } }
  }
}

Poll a verification operation

GET https://knov.ai/api/v1/verifications/{id}

Resolves the operation status. Honor pollAfter / Retry-After while non-terminal.

curl "https://knov.ai/api/v1/verifications/a1b2c3d4e5f60718293a4b5c6d7e8f90"

Long-running operations

Verification is asynchronous. The operation's status moves through these states; only succeeded and failed are terminal:

Idempotency

POST /api/v1/verifications requires an Idempotency-Key header — any unique string of at least 8 characters (a UUID is recommended). A retried request bearing the same key returns the original response and performs no duplicate side effect. Keys are honored for 24 hours. Reusing a key with a different body returns 409 idempotency_conflict.

Errors

Every error is application/problem+json (RFC 9457): a type URI (linking to the row below), a title, the status, a stable code, a retryable flag, and — on time-sensitive failures — a Retry-After header. Validation errors add a per-field errors map.

{
  "type": "https://knov.ai/api#error-rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "retryable": true,
  "retryAfter": 1800,
  "detail": "Too many requests. Retry after 1800 seconds."
}

Rate limits

Per IP, in fixed hourly windows: reads 600/hour (/api/v1/directory), submissions 30/hour (POST /api/v1/verifications). On exceed, the API returns 429 with a Retry-After header (seconds).

Security & disclosure

Report suspected vulnerabilities to [email protected]. Please give us a reasonable window to remediate before public disclosure; we acknowledge reports and keep you updated. Test only against domains you control and within the published rate limits. The machine-readable policy is at /.well-known/security.txt.