{"service":"dVeracity Semantic API","version":"1","base_url":"https://api.dveracity.com","path_resolution":"Every \"path\" in this document is relative to base_url. Do not resolve paths against the host you fetched this manifest from: the manifest is also served at https://dveracity.com/api/v1/semantic/manifest, which proxies only the manifest itself — all other paths 404 there.","description":"Natural-language and template queries over the dVeracity verified-emissions knowledge graph (Open Footprint / PPDM / OGMP-methane virtual knowledge graphs).","authentication":{"type":"api_key","header":"X-Api-Key","obtain":"Create a key at POST /api/v1/api-keys (requires an api-tier subscription; see pricing_url). Keys are prefixed dvrc_.","pricing_url":"https://dveracity.com/pricing","applies_to":"Every endpoint listed below, including those priced at 0 credits. Free of charge is not the same as anonymous: zero-credit endpoints still require a key so usage is attributable.","auth_required_semantics":"A response of HTTP 401 with body {error: \"auth_required\", header, signupUrl, createKey} means no credential was presented. An agent cannot resolve this alone — subscribing needs a human. Give your operator the signupUrl, then retry with the key they create.","keri":{"description":"Optional verified-agent identity layer (vLEI). An agent holding a dVeracity Agent Authorization credential (issued by its Legal Entity, chained to the GLEIF root) authenticates by verifiable presentation instead of secret alone; usage is then attributed to the agent AID and Legal Entity LEI. Billing still requires the API key.","challenge":{"path":"/api/v1/semantic/auth/challenge","method":"GET"},"exchange":{"path":"/api/v1/semantic/auth/keri","method":"POST","body":{"aid":"agent AID (issuee of the credential)","nonce":"from /auth/challenge","presentation":"self-contained CESR credential presentation","sig":"optional signature over the nonce by the agent AID"}},"session_header":"X-Keri-Session","credential_schema":"EFyhIYqAgOxRNikVRQzcvJpHr_589-_40oMo4Urc2--J"}},"billing":{"unit":"credits","purchase":{"path":"/api/v1/vaas/credits/purchase","method":"POST"},"balance":{"path":"/api/v1/vaas/credits","method":"GET"},"payment_required_semantics":"A response of HTTP 402 with body {error: \"insufficient_credits\", balance, needed, purchaseUrl} means the account has run out of credits. Purchase credits (or ask your human operator to subscribe at pricing_url), then retry the request."},"endpoints":[{"auth":"api_key","path":"/api/v1/semantic/query","method":"POST","credits":1,"body":{"query":"natural-language question (string, required)","sessionId":"optional"},"description":"Answers a natural-language question by translating it to SPARQL and executing it against the verified-emissions knowledge graph."},{"auth":"api_key","path":"/api/v1/semantic/templates","method":"GET","credits":0,"description":"Catalog of supported query templates and their parameters."},{"auth":"api_key","path":"/api/v1/ofp/models","method":"GET","credits":0,"description":"The eight canonical Open Footprint model domains, and which DDL dialects carry published output. Design-time reference: build against the standard rather than inferring it."},{"auth":"api_key","path":"/api/v1/ofp/entities/{domain}/{entity}","method":"GET","credits":0,"description":"One canonical entity: fields, types, keys, relationships, and the physical table implementing it. Use the domain-qualified form — 48 entity names are defined in more than one domain, and the bare-name route returns 409 with candidates rather than guessing."},{"auth":"api_key","path":"/api/v1/ofp/entities/export","method":"GET","credits":0,"description":"The whole canonical model in one response: every entity with full field and O-DEF semantic detail, plus the code reverse-index. Building a local index? Use this one call instead of walking 239 entity fetches through the rate limiter."},{"auth":"api_key","path":"/api/v1/ofp/sectors","method":"GET","credits":0,"description":"Industry sectors across both classification axes, each with a status. Gate on it: \"planned\" means declared with nothing published."},{"auth":"api_key","path":"/api/v1/ofp/semantics","method":"GET","credits":0,"description":"O-DEF semantic codes carried by the canonical model, for aligning fields from another system onto Open Footprint. Each code reports how many fields share it; a high count is a generic fallback, so filter with ?maxFieldCount=10 for codes precise enough to align on."},{"auth":"api_key","path":"/api/v1/ofp/validate","method":"POST","credits":1,"body":{"entity":"canonical entity name, or domain-qualified id (string, required)","domain":"optional; required when the entity name is ambiguous","payload":"the instance to check (object, required)","sector":"optional; when supplied, that sector's Rego guardrails are evaluated too","entityType":"optional; the record type the guardrails discriminate on (e.g. \"directEmission\"). Defaults to the entity name, which will usually not match — check policy.recognisedEntityTypes in the response."},"description":"Check a payload against the canonical model and, when a sector is named, its published guardrails. The response is a contract: `checked` lists the checks that ran and `checks_not_run` lists every catalogued check that did not (value_range, unit_coherence, temporal_consistency, referential_integrity, factor_provenance, materiality, sector_policy), each with a reason. `schemaValid` is the structural verdict and `assuranceLevel` the depth earned (schema-only | schema-and-value | schema-value-and-policy | full); `valid` is deprecated and removed no earlier than 0.6.0. Every violation and warning carries severity. Four guardrail outcomes, never conflated: passed, denied, not_applicable (the rules do not cover this record type), or unevaluable (the payload lacks the inputs the rules read, policy.missingInputs). An unchecked payload is never reported as a compliant one, and rules that do not apply or could not be evaluated are never reported as denials."},{"auth":"api_key","path":"/api/v1/ofp/sectors/{id}/policies","method":"GET","credits":0,"description":"Rego policy guardrails for a sector. When none are published this returns published:false with a reason — an explicit absence of rules, which must not be read as an absence of constraints or filled in by the caller."}]}