{ "openapi": "3.1.0", "info": { "title": "Vouch API", "version": "1.0.0", "description": "Prove ownership of a domain by publishing a DNS TXT record. Generated from the action registry (packages/core/src/actions/registry.ts): every path, request shape, and error code below is read directly from the same Zod schemas the server validates against, not maintained by hand." }, "servers": [ { "url": "/", "description": "Relative to whatever origin this deployment is served from. Vouch has no separate API host." } ], "paths": { "/api/v1/claims": { "post": { "operationId": "createDomainClaim", "summary": "Start a domain ownership claim and get the TXT record to publish.", "tags": ["Domain claims"], "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "claim": { "$ref": "#/components/schemas/ClaimView" }, "record": { "$ref": "#/components/schemas/TxtRecordInstructions" } }, "required": ["claim", "record"], "additionalProperties": false } }, "required": ["success", "data"], "additionalProperties": false } } } }, "400": { "description": "`{ success: false, error }`, with `error.code` one of: `VALIDATION_FAILED`, `DOMAIN_INVALID_FORMAT`, `DOMAIN_IS_PUBLIC_SUFFIX`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "`{ success: false, error }`, with `error.code` one of: `UNAUTHENTICATED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`{ success: false, error }`, with `error.code` one of: `DOMAIN_ALREADY_CLAIMED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`{ success: false, error }`, with `error.code` one of: `RATE_LIMITED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`{ success: false, error }`, with `error.code` one of: `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1 } }, "required": ["domain"], "additionalProperties": false } } } } }, "get": { "operationId": "listDomainClaims", "summary": "List every domain claim belonging to the caller's organization.", "tags": ["Domain claims"], "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "claims": { "type": "array", "items": { "$ref": "#/components/schemas/ClaimView" } } }, "required": ["claims"], "additionalProperties": false } }, "required": ["success", "data"], "additionalProperties": false } } } }, "401": { "description": "`{ success: false, error }`, with `error.code` one of: `UNAUTHENTICATED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`{ success: false, error }`, with `error.code` one of: `RATE_LIMITED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`{ success: false, error }`, with `error.code` one of: `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/claims/{id}": { "get": { "operationId": "getDomainClaim", "summary": "Read a single claim's persisted state. No DNS I/O, no state transition.", "tags": ["Domain claims"], "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "claim": { "$ref": "#/components/schemas/ClaimView" }, "record": { "$ref": "#/components/schemas/TxtRecordInstructions" } }, "required": ["claim", "record"], "additionalProperties": false } }, "required": ["success", "data"], "additionalProperties": false } } } }, "401": { "description": "`{ success: false, error }`, with `error.code` one of: `UNAUTHENTICATED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`{ success: false, error }`, with `error.code` one of: `UNAUTHORIZED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`{ success: false, error }`, with `error.code` one of: `CLAIM_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`{ success: false, error }`, with `error.code` one of: `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim id (domainClaims.id).", "schema": { "type": "string" } } ] }, "delete": { "operationId": "releaseDomainClaim", "summary": "Release a domain claim, revoking ownership if it was verified.", "tags": ["Domain claims"], "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "The request succeeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "claim": { "$ref": "#/components/schemas/ClaimView" } }, "required": ["claim"], "additionalProperties": false } }, "required": ["success", "data"], "additionalProperties": false } } } }, "401": { "description": "`{ success: false, error }`, with `error.code` one of: `UNAUTHENTICATED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "`{ success: false, error }`, with `error.code` one of: `UNAUTHORIZED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`{ success: false, error }`, with `error.code` one of: `CLAIM_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`{ success: false, error }`, with `error.code` one of: `CLAIM_NOT_PENDING`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`{ success: false, error }`, with `error.code` one of: `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim id (domainClaims.id).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1 } }, "additionalProperties": false } } } } } }, "/api/v1/claims/{id}/check": { "post": { "operationId": "checkDnsRecord", "summary": "Look up the challenge TXT record without changing the claim's state.", "tags": ["Domain claims"], "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "The request was handled successfully. The response is `{ success: true, data }` on a match, or `{ success: false, error }` when the DNS lookup itself succeeded but reported one of: `DNS_NO_TXT_FOUND`, `DNS_TOKEN_MISMATCH`, `DNS_RECORD_WRONG_HOSTNAME`, `DNS_NXDOMAIN`, `DNS_LOOKUP_TIMEOUT`, `DNS_LOOKUP_FAILED`. These are outcomes of a check that worked correctly, not request failures: read `success`, not the status code.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "claim": { "$ref": "#/components/schemas/ClaimView" }, "matched": { "type": "boolean", "const": true }, "recordHost": { "type": "string" }, "observedValue": { "type": "string" } }, "required": [ "claim", "matched", "recordHost", "observedValue" ], "additionalProperties": false } }, "required": ["success", "data"], "additionalProperties": false }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "401": { "description": "`{ success: false, error }`, with `error.code` one of: `UNAUTHENTICATED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`{ success: false, error }`, with `error.code` one of: `CLAIM_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`{ success: false, error }`, with `error.code` one of: `CLAIM_NOT_PENDING`, `CLAIM_EXPIRED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`{ success: false, error }`, with `error.code` one of: `RATE_LIMITED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`{ success: false, error }`, with `error.code` one of: `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim id (domainClaims.id).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/api/v1/claims/{id}/verify": { "post": { "operationId": "verifyAndClaimDomain", "summary": "Check DNS and, on a match, finalize the domain claim.", "tags": ["Domain claims"], "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "The request was handled successfully. The response is `{ success: true, data }` on a match, or `{ success: false, error }` when the DNS lookup itself succeeded but reported one of: `DNS_NO_TXT_FOUND`, `DNS_TOKEN_MISMATCH`, `DNS_RECORD_WRONG_HOSTNAME`, `DNS_NXDOMAIN`, `DNS_LOOKUP_TIMEOUT`, `DNS_LOOKUP_FAILED`. These are outcomes of a check that worked correctly, not request failures: read `success`, not the status code.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "claim": { "$ref": "#/components/schemas/ClaimView" }, "matched": { "type": "boolean", "const": true } }, "required": ["claim", "matched"], "additionalProperties": false } }, "required": ["success", "data"], "additionalProperties": false }, { "$ref": "#/components/schemas/ErrorEnvelope" } ] } } } }, "401": { "description": "`{ success: false, error }`, with `error.code` one of: `UNAUTHENTICATED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "`{ success: false, error }`, with `error.code` one of: `CLAIM_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "`{ success: false, error }`, with `error.code` one of: `CLAIM_NOT_PENDING`, `CLAIM_ALREADY_VERIFYING`, `CLAIM_EXPIRED`, `DOMAIN_ALREADY_CLAIMED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`{ success: false, error }`, with `error.code` one of: `RATE_LIMITED`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "`{ success: false, error }`, with `error.code` one of: `INTERNAL_ERROR`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The claim id (domainClaims.id).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } } }, "components": { "schemas": { "ClaimView": { "type": "object", "properties": { "id": { "type": "string" }, "orgId": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_dns", "verifying", "verified", "failed", "expired", "revoked" ] }, "statusReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "dnsVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "recordAssertedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "recordFirstSeenAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time" }, "verifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "orgId", "domain", "status", "statusReason", "createdAt", "dnsVerifiedAt", "recordAssertedAt", "recordFirstSeenAt", "expiresAt", "verifiedAt", "revokedAt", "revokedReason", "lastCheckedAt" ], "additionalProperties": false }, "TxtRecordInstructions": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "const": "TXT" }, "value": { "type": "string" } }, "required": ["name", "type", "value"], "additionalProperties": false }, "ActionError": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "VALIDATION_FAILED", "DOMAIN_INVALID_FORMAT", "DOMAIN_IS_PUBLIC_SUFFIX", "DOMAIN_ALREADY_CLAIMED", "CLAIM_NOT_FOUND", "CLAIM_NOT_PENDING", "CLAIM_ALREADY_VERIFYING", "CLAIM_EXPIRED", "DNS_NO_TXT_FOUND", "DNS_TOKEN_MISMATCH", "DNS_RECORD_WRONG_HOSTNAME", "DNS_NXDOMAIN", "DNS_LOOKUP_TIMEOUT", "DNS_LOOKUP_FAILED", "RATE_LIMITED", "UNAUTHENTICATED", "UNAUTHORIZED", "INTERNAL_ERROR" ] }, "message": { "type": "string" }, "detail": { "type": "string" }, "remediation": { "type": "string" }, "isRetriable": { "type": "boolean" }, "fault": { "type": "string", "enum": ["user", "system", "external"] }, "retryAfterMs": { "type": "number" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "traceId": { "type": "string" }, "evidence": { "type": "object", "properties": { "expectedValue": { "type": "string" }, "observedValues": { "type": "array", "items": { "type": "string" } }, "queriedHostname": { "type": "string" }, "foundAtHostname": { "type": "string" } }, "additionalProperties": false }, "simulated": { "description": "Adapter-added, not part of core's ActionError type. Present, and true, only when this failure came from the demo-mode simulation seam rather than a real outcome.", "type": "boolean" } }, "required": ["code", "message", "isRetriable", "fault"], "additionalProperties": false }, "ErrorEnvelope": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "$ref": "#/components/schemas/ActionError" } }, "required": ["success", "error"], "additionalProperties": false } }, "securitySchemes": { "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "better-auth.session_token", "description": "A signed-in Better Auth session cookie. In production this is set as __Secure-better-auth.session_token instead. There is no API key auth yet." } } }, "security": [ { "sessionCookie": [] } ] }