{"components":{"schemas":{"ClaimStatus":{"properties":{"federation":{"description":"Federation projection placeholders. Seam-only in v1a: always present, usually empty.","items":{"type":"object"},"type":"array"},"reason":{"type":"string"},"status":{"type":"string"},"tier":{"enum":["keyed","anchored",null],"nullable":true,"type":"string"}},"required":["status","tier","reason","federation"],"type":"object"},"Error":{"properties":{"error":{"description":"Deterministic error code, e.g. AUTH_MISSING, FORBIDDEN_SCOPE, NOT_FOUND, CHALLENGE_INVALID, INVALID_FIELD.","type":"string"},"field":{"description":"For INVALID_FIELD: the client-supplied field whose value is out of vocabulary.","type":"string"},"reason":{"description":"Structured sub-reason where one exists (e.g. a challenge failure).","type":"string"}},"required":["error"],"type":"object"},"GenericInitiation":{"properties":{"reference":{"description":"Opaque reference. Identical in shape whether or not the business exists — initiation never confirms existence.","type":"string"},"status":{"enum":["received"],"type":"string"}},"required":["status","reference"],"type":"object"}},"securitySchemes":{"apiKey":{"description":"Tenant/agent API key, form clk_<id>_<secret>. Only its SHA-256 hash is stored.","scheme":"bearer","type":"http"},"principalSession":{"description":"HMAC-signed session cookie bound to one principal, established by an approval POST or a sign-in link.","in":"cookie","name":"cl_session","type":"apiKey"}}},"info":{"description":"Shared claim-verification service for directories. One account. Proof per business. The proof lives in the ClaimListing ledger, never with the agent. Agent guide: /.well-known/claim-instructions. Phase A adds tenant listing sync (contract v2 (a)), the Door A hand-off, and pull grant consumption (contract v2 (c)). 1b.2 adds read-only tenant inspection under grants.read: per-listing contacts + stored eligibility, and the tenant's outbox summary.","title":"ClaimListing API","version":"1b.2"},"openapi":"3.0.3","paths":{"/api/openapi.json":{"get":{"operationId":"getOpenApiDocument","responses":{"200":{"description":"OpenAPI 3 document"}},"summary":"This OpenAPI document"}},"/api/v1/approvals/{token}":{"get":{"operationId":"openApproval","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Approval view: listing, action, requesting actor, canApprove"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_FOUND"}},"summary":"Render the approval moment. READ ONLY: opening never consumes the challenge (email scanners are safe)."},"post":{"operationId":"approveClaim","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Approved (or routed under_review by the gate)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"CHALLENGE_INVALID"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_FOUND"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_ACTIONABLE"}},"summary":"The deliberate approval action — the ONLY consumer of the challenge. On success it also establishes a principal session cookie."}},"/api/v1/auth/signin":{"post":{"operationId":"consumeSignInToken","requestBody":{"content":{"application/json":{"schema":{"properties":{"token":{"type":"string"}},"required":["token"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Signed in — principal session cookie set"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"CHALLENGE_INVALID"}},"summary":"Consume a one-use sign-in token (the deliberate POST from the sign-in page; GET never consumes). Sets the principal session cookie."}},"/api/v1/auth/signin-request":{"post":{"operationId":"requestSignInLink","requestBody":{"content":{"application/json":{"schema":{"properties":{"email":{"type":"string"}},"required":["email"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericInitiation"}}},"description":"Received (generic)"}},"summary":"Request a principal sign-in link. Always answers generically; a one-use link is enqueued through the outbox only when the email is a known principal login."}},"/api/v1/claims":{"post":{"operationId":"initiateClaim","parameters":[{"description":"Retries with the same key + same claim return the same reference.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"agentIdentity":{"nullable":true,"type":"object"},"authorizationId":{"nullable":true,"type":"string"},"authorizationMode":{"enum":["direct_human","transaction_approval","standing_delegation","unverified_agent_assertion"],"type":"string"},"claimMethod":{"enum":["web_form","api","tool_call","internal"],"type":"string"},"claimantType":{"enum":["human_direct","agent_assisted","agent_autonomous","unknown"],"type":"string"},"entityId":{"format":"uuid","type":"string"},"listingRef":{"type":"string"},"principalId":{"format":"uuid","nullable":true,"type":"string"},"sourceChannel":{"enum":["direct","directory_referred","agent_referred","agent_initiated"],"type":"string"},"tierSought":{"enum":["keyed","anchored"],"type":"string"}},"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericInitiation"}}},"description":"Received (generic — never confirms existence)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"INVALID_FIELD — a client-supplied enum field (claimantType, claimMethod, authorizationMode, sourceChannel, tierSought) is out of vocabulary; the offending field is named in `field`. No claim is created."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"AUTH_MISSING / AUTH_INVALID / AUTH_REVOKED"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"FORBIDDEN_SCOPE / MANDATE_NOT_FOUND / MANDATE_INACTIVE / MANDATE_OUT_OF_SCOPE (a presented mandate is verified before any claim is created)"}},"security":[{"apiKey":[]}],"summary":"Initiate a claim (idempotent; generic response)"}},"/api/v1/claims/{claimId}/challenge":{"post":{"operationId":"issueChallenge","parameters":[{"in":"path","name":"claimId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Issued (or NO_CONTACT / NOT_ISSUABLE outcome object)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Authentication failed"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"FORBIDDEN_SCOPE / FORBIDDEN_TENANT"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_FOUND (uniform shape)"}},"security":[{"apiKey":[]}],"summary":"Issue or re-issue the Doorstep challenge (link goes only to the on-file contact)"}},"/api/v1/claims/{claimId}/dispute":{"post":{"operationId":"disputeClaim","parameters":[{"in":"path","name":"claimId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"token":{"type":"string"}},"required":["token"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Dispute recorded"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"CHALLENGE_INVALID"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_FOUND (uniform shape)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_ACTIONABLE"}},"summary":"One-click dispute from the notify email. The dispute token in the body is the credential; no account auth."}},"/api/v1/claims/{claimId}/status":{"get":{"operationId":"getClaimStatus","parameters":[{"in":"path","name":"claimId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimStatus"}}},"description":"Claim status"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Authentication failed"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"FORBIDDEN_SCOPE / FORBIDDEN_TENANT / NOT_OWNER"}},"security":[{"apiKey":[]},{"principalSession":[]}],"summary":"Structured claim status {status, tier, reason, federation}"}},"/api/v1/claims/{claimId}/withdraw":{"post":{"operationId":"withdrawClaim","parameters":[{"in":"path","name":"claimId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Withdrawn"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Authentication failed"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_OWNER / FORBIDDEN_SCOPE"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_FOUND (uniform shape)"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_ACTIONABLE"}},"security":[{"principalSession":[]},{"apiKey":[]}],"summary":"The claiming principal withdraws their claim (session, or tenant key acting for that principal)"}},"/api/v1/handoff/{token}":{"get":{"operationId":"presentHandoff","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Hand-off view {businessName, directoryName, csrfToken, returnUrl?}"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"HANDOFF_INVALID — generic refusal (bad signature, unknown tenant/listing, expired, or revoked)"}},"summary":"Present a Door A hand-off token. PURE READ: presentation consumes nothing and may be repeated any number of times (mail scanners are safe). On success returns the business and directory names from ClaimListing synced records (never from the token) plus a csrfToken, and binds the hand-off to a browser session cookie. Every failure is the same generic HANDOFF_INVALID refusal."}},"/api/v1/handoff/{token}/initiate":{"post":{"operationId":"initiateHandoffClaim","parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"csrfToken":{"type":"string"}},"required":["csrfToken"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericInitiation"}}},"description":"Received (generic)"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"HANDOFF_INVALID — generic refusal (any verification, session, CSRF, or replay failure)"}},"summary":"The deliberate Door A claim initiation. Requires the hand-off session cookie set by presentation plus the matching csrfToken in the body. Consumes the hand-off nonce atomically (a replay refuses generically), resolves or creates the principal, initiates the claim as directory_referred, and issues the approval challenge only when the listing evaluation is eligible. Always answers with the generic initiation shape on success."}},"/api/v1/principal/authorizations":{"get":{"operationId":"listPrincipalAuthorizations","responses":{"200":{"description":"Mandates list"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"SESSION_INVALID"}},"security":[{"principalSession":[]}],"summary":"The signed-in principal's agent mandates (dashboard data)"}},"/api/v1/principal/authorizations/{authorizationId}/revoke":{"post":{"operationId":"revokeAuthorization","parameters":[{"in":"path","name":"authorizationId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked (idempotent)"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"SESSION_INVALID"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_FOUND (also for another principal's mandate)"}},"security":[{"principalSession":[]}],"summary":"Revoke one of the principal's mandates (one-click revoke)"}},"/api/v1/principal/claims":{"get":{"operationId":"listPrincipalClaims","responses":{"200":{"description":"Claims list"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"SESSION_INVALID"}},"security":[{"principalSession":[]}],"summary":"The signed-in principal's claims (dashboard data)"}},"/api/v1/principal/grants":{"get":{"operationId":"listPrincipalGrants","responses":{"200":{"description":"Grants list"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"SESSION_INVALID"}},"security":[{"principalSession":[]}],"summary":"The signed-in principal's verification grants (dashboard data)"}},"/api/v1/queue":{"get":{"operationId":"listExceptionQueue","responses":{"200":{"description":"Open exception items"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Authentication failed"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"FORBIDDEN_SCOPE"}},"security":[{"apiKey":[]}],"summary":"Operator exception queue (requires queue.admin scope): open items with reason codes and claim context"}},"/api/v1/queue/{exceptionId}/resolve":{"post":{"operationId":"resolveException","parameters":[{"in":"path","name":"exceptionId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"action":{"enum":["resolve","dismiss","retry_challenge"],"type":"string"}},"required":["action"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Resolved"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"INVALID_FIELD — the resolve `action` is not one of resolve | dismiss | retry_challenge."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Authentication failed"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"FORBIDDEN_SCOPE / FORBIDDEN_TENANT"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"QUEUE_NOT_FOUND"},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"QUEUE_ALREADY_CLOSED"}},"security":[{"apiKey":[]}],"summary":"Resolve an exception: action = resolve | dismiss | retry_challenge (re-issues the Doorstep challenge for the claim)"}},"/api/v1/tenants/me/grants":{"get":{"operationId":"listTenantGrants","parameters":[{"description":"Epoch milliseconds; only grants changed strictly after this instant are returned.","in":"query","name":"since","required":false,"schema":{"default":0,"type":"number"}}],"responses":{"200":{"description":"Grant list, oldest first"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"INVALID_FIELD — `since` is not a non-negative number"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"AUTH_MISSING / AUTH_INVALID / AUTH_REVOKED"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"FORBIDDEN_SCOPE"}},"security":[{"apiKey":[]}],"summary":"Grants-changed pull feed for the authenticated tenant (contract v2 (c)-pull): every grant with a lifecycle timestamp after `since` (epoch ms). Refs are merge-resolved — a grant on a merged-away listing reports the surviving listingRef plus mergedFromRef. badgeEligible is true only for an active top-tier grant. Requires the grants.read scope."}},"/api/v1/tenants/me/listings/sync":{"post":{"operationId":"syncTenantListings","requestBody":{"content":{"application/json":{"schema":{"properties":{"listings":{"items":{"properties":{"businessName":{"type":"string"},"city":{"nullable":true,"type":"string"},"contacts":{"items":{"properties":{"dateObtained":{"format":"date","type":"string"},"evidenceKind":{"enum":["operator_supplied","own_site","registry","aggregator","claimant",null],"nullable":true,"type":"string"},"evidenceRefs":{"items":{"type":"string"},"type":"array"},"flagged":{"type":"boolean"},"kind":{"enum":["email","phone","domain","address"],"type":"string"},"provenanceSource":{"enum":["first_party","registry","aggregator","claimant","stale"],"type":"string"},"suppressed":{"type":"boolean"},"value":{"type":"string"}},"required":["kind","value","provenanceSource","dateObtained"],"type":"object"},"type":"array"},"externalListingRef":{"type":"string"},"mergedIntoRef":{"nullable":true,"type":"string"},"publicListingUrl":{"nullable":true,"type":"string"},"relationshipKey":{"nullable":true,"type":"string"},"state":{"nullable":true,"type":"string"},"status":{"default":"active","enum":["active","unpublished","merged"],"type":"string"}},"required":["externalListingRef","businessName","contacts"],"type":"object"},"type":"array"}},"required":["listings"],"type":"object"}}},"required":true},"responses":{"200":{"description":"Sync applied: {synced, mergesProcessed, evaluated}"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"INVALID_FIELD — a client-supplied field is out of vocabulary; the offending field is named in `field`."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"AUTH_MISSING / AUTH_INVALID / AUTH_REVOKED"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"FORBIDDEN_SCOPE"}},"security":[{"apiKey":[]}],"summary":"Push listing + contact sync for the authenticated tenant (contract v2 (a)). Idempotent upsert keyed by (tenant, externalListingRef); sync is authoritative for on-file contacts — a contact absent from a listing payload is superseded. Each sync re-runs the eligibility evaluation over the tenant and applies merge effects. Requires the listings.sync scope."}},"/api/v1/tenants/me/listings/{listingRef}/claim-status":{"get":{"operationId":"getListingClaimStatus","parameters":[{"in":"path","name":"listingRef","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Claim status for the (surviving) listing"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"AUTH_MISSING / AUTH_INVALID / AUTH_REVOKED"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"FORBIDDEN_SCOPE"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_FOUND — no such listing for this tenant"}},"security":[{"apiKey":[]}],"summary":"Claim status for one of the tenant listings, merge-resolved to the surviving listing: {listingRef, claimed, grant}. Requires the grants.read scope."}},"/api/v1/tenants/me/listings/{listingRef}/contacts":{"get":{"operationId":"getListingContacts","parameters":[{"in":"path","name":"listingRef","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"{listingRef, contacts: [{kind, value, active, provenanceSource, updatedAt}], eligibility}"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"AUTH_MISSING / AUTH_INVALID / AUTH_REVOKED"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"FORBIDDEN_SCOPE"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"NOT_FOUND — no such listing for this tenant"}},"security":[{"apiKey":[]}],"summary":"Inspection read for one of the tenant's listings: every contact on file for its entity (superseded rows included, each with an active flag; updatedAt is the row's last change — supersession time, else first-recorded time) plus the stored eligibility evaluation {eligible, reasonCode, evaluatedAt} (null when never evaluated). The tenant reads back only its own synced data. Pure read. Requires the grants.read scope."}},"/api/v1/tenants/me/outbox/summary":{"get":{"operationId":"getTenantOutboxSummary","responses":{"200":{"description":"Outbox counts for the authenticated tenant"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"AUTH_MISSING / AUTH_INVALID / AUTH_REVOKED"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"FORBIDDEN_SCOPE"}},"security":[{"apiKey":[]}],"summary":"Inspection read: the tenant's outbox counts grouped by status, {counts: {pending, sent, failed, dead_letter}}. A row counts only when it is attributed to the tenant through its claim; claim-less rows (sign-in links) are excluded, never global counts. Pure read. Requires the grants.read scope."}}},"servers":[{"url":"/"}]}