OpenAPI (Generated)¶
This page renders from partner-docs/openapi.json.
Refresh that file before publishing docs:
uv run python scripts/export_openapi.py
Swiss Company Name Validation API 1.1.0¶
API for validating Swiss company names: conflict search against ZEFIX registry and legal compliance checks
Health¶
GET /health¶
Health check
Description Health check endpoint for load balancers and orchestrators. No authentication required. Returns {"status": "ok"} with 200 OK.
Response 200 OK¶
application/json
{
"status": "string"
}
Schema of the response body
{
"properties": {
"status": {
"type": "string",
"title": "Status",
"description": "Health status",
"default": "ok"
}
},
"type": "object",
"title": "HealthResponse",
"description": "Response for GET /health endpoint."
}
Search¶
POST /v1/conflicts/search¶
Search for company name conflicts
Description Search for potential conflicts with existing Swiss company names.
Returns:
- registrable: True if no identity match exists
- identityMatch: Legal identity conflict (OR Art. 951) if exists
- similarMatches: Similar names requiring assessment (OR Art. 956)
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| ClientApiKeyAuth | header | string | N/A | No | Client API key for public endpoints. |
Request body
application/json
{
"name": "string",
"limit": 0,
"minRisk": "High"
}
Schema of the request body
{
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"title": "Name",
"description": "Company name to check for conflicts"
},
"limit": {
"type": "integer",
"maximum": 100.0,
"minimum": 1.0,
"title": "Limit",
"description": "Maximum number of results (1-100)",
"default": 25
},
"minRisk": {
"$ref": "#/components/schemas/RiskLevelParam",
"description": "Minimum risk level filter (inclusive of specified level and higher)",
"default": "Low"
}
},
"type": "object",
"required": [
"name"
],
"title": "SearchRequest",
"description": "Request body for POST /v1/conflicts/search.\n\nAttributes:\n name: Original company name to check (required).\n limit: Maximum results to return (1-100, default 25).\n minRisk: Minimum risk level filter, inclusive of higher levels.",
"examples": [
{
"limit": 25,
"minRisk": "Low",
"name": "Müller & Söhne AG"
}
]
}
Response 200 OK¶
application/json
{
"input": {
"name": "string",
"nameNorm": "string",
"nameCore": "string",
"phoneticPrimary": "string",
"phoneticAlt": "string"
},
"registrable": true,
"identityMatch": null,
"similarMatches": [
{
"sourceCompanyId": "string",
"nameDisplay": "string",
"legalSeat": null,
"nameNorm": "string",
"visualScore": 10.12,
"phoneticMatch": true,
"risk": "High"
}
]
}
Schema of the response body
{
"properties": {
"input": {
"$ref": "#/components/schemas/SearchInputEcho",
"description": "Echoed and normalized input"
},
"registrable": {
"type": "boolean",
"title": "Registrable",
"description": "True if no identity match exists (name can potentially be registered)"
},
"identityMatch": {
"anyOf": [
{
"$ref": "#/components/schemas/IdentityMatchResponse"
},
{
"type": "null"
}
],
"description": "The identity match if one exists, otherwise null"
},
"similarMatches": {
"items": {
"$ref": "#/components/schemas/SimilarMatchResponse"
},
"type": "array",
"title": "Similarmatches",
"description": "List of similar matches ordered by risk"
}
},
"type": "object",
"required": [
"input",
"registrable",
"identityMatch",
"similarMatches"
],
"title": "SearchResponse",
"description": "Response body for successful conflict search.\n\nSeparates legal identity (OR Art. 951) from confusion risk (OR Art. 956):\n- identityMatch: Legally identical name → automatic rejection\n- similarMatches: Similar names → requires human assessment",
"examples": [
{
"input": {
"name": "Müller & Söhne AG",
"nameCore": "mueller soehne",
"nameNorm": "mueller soehne",
"phoneticAlt": "MLRS",
"phoneticPrimary": "MLRS"
},
"registrable": true,
"similarMatches": [
{
"legalSeat": "Zürich",
"nameDisplay": "Mueller und Soehne GmbH",
"nameNorm": "mueller soehne",
"phoneticMatch": true,
"risk": "High",
"sourceCompanyId": "CHE101835433",
"visualScore": 0.85
}
]
}
]
}
Response 400 Bad Request¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
POST /v1/trademarks/search¶
Search for similar trademarks
Description Search for potentially similar registered trademarks in the ingested IGE dataset.
Matching combines normalized text similarity (trigram), phonetic similarity,
and optional Nice class overlap context.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| ClientApiKeyAuth | header | string | N/A | No | Client API key for public endpoints. |
Request body
application/json
{
"query": "string",
"limit": 0,
"minRisk": "High",
"niceClasses": null
}
Schema of the request body
{
"properties": {
"query": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"title": "Query",
"description": "Trademark text to search for similar existing trademarks"
},
"limit": {
"type": "integer",
"maximum": 100.0,
"minimum": 1.0,
"title": "Limit",
"description": "Maximum number of results (1-100)",
"default": 25
},
"minRisk": {
"$ref": "#/components/schemas/RiskLevelParam",
"description": "Minimum risk level filter (inclusive of specified level and higher)",
"default": "Low"
},
"niceClasses": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Niceclasses",
"description": "Optional intended Nice classes (values 1-45)"
}
},
"type": "object",
"required": [
"query"
],
"title": "TrademarkSearchRequest",
"description": "Request body for POST /v1/trademarks/search.\n\nAttributes:\n query: Proposed trademark text to compare against registered trademarks.\n limit: Maximum results to return (1-100, default 25).\n minRisk: Minimum risk level filter, inclusive of higher levels.\n niceClasses: Optional intended Nice classes (1-45) to weight overlap.",
"examples": [
{
"limit": 20,
"minRisk": "Low",
"niceClasses": [
35,
42
],
"query": "Mueller Soehne"
}
]
}
Response 200 OK¶
application/json
{
"input": {
"query": "string",
"queryNorm": "string",
"queryCore": "string",
"phoneticPrimary": "string",
"phoneticAlt": "string",
"niceClasses": [
0
]
},
"goodsServicesBasis": "string",
"similarMatches": [
{
"sourceRecordId": "string",
"registrationNumber": null,
"applicationNumberText": null,
"markText": null,
"markTextNorm": "string",
"status": null,
"niceClasses": [
0
],
"classOverlap": [
0
],
"relatedClassOverlap": [
0
],
"visualScore": 10.12,
"phoneticMatch": true,
"matchBasis": [
"string"
],
"risk": "High"
}
]
}
Schema of the response body
{
"properties": {
"input": {
"$ref": "#/components/schemas/TrademarkSearchInputEcho",
"description": "Echoed and normalized input"
},
"goodsServicesBasis": {
"type": "string",
"title": "Goodsservicesbasis",
"description": "Goods/services context basis: 'nice_classes' or 'unspecified'"
},
"similarMatches": {
"items": {
"$ref": "#/components/schemas/TrademarkSimilarMatchResponse"
},
"type": "array",
"title": "Similarmatches",
"description": "List of similar trademark matches ordered by risk"
}
},
"type": "object",
"required": [
"input",
"goodsServicesBasis",
"similarMatches"
],
"title": "TrademarkSearchResponse",
"description": "Response body for POST /v1/trademarks/search."
}
Response 400 Bad Request¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
POST /v1/domains/availability¶
Check domain availability across TLDs
Description Check if a proposed domain label is already taken across selected TLDs.
This is a best-effort public-internet check using DNS and RDAP style
lookups.
Results are conservative and can be registered, likely_available, or
unknown.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| ClientApiKeyAuth | header | string | N/A | No | Client API key for public endpoints. |
Request body
application/json
{
"name": "string",
"tlds": [
"string"
]
}
Schema of the request body
{
"properties": {
"name": {
"type": "string",
"maxLength": 63,
"minLength": 1,
"title": "Name",
"description": "Base domain label to check (for example 'acme')"
},
"tlds": {
"items": {
"type": "string"
},
"type": "array",
"maxItems": 10,
"minItems": 1,
"title": "Tlds",
"description": "Target TLD list (for example ['ch', 'com'])"
}
},
"type": "object",
"required": [
"name",
"tlds"
],
"title": "DomainAvailabilityRequest",
"description": "Request body for POST /v1/domains/availability.\n\nAttributes:\n name: Base domain label to check (without TLD).\n tlds: Target TLD values from the supported allowlist.",
"examples": [
{
"name": "acme",
"tlds": [
"ch",
"swiss",
"com",
"net"
]
}
]
}
Response 200 OK¶
application/json
{
"input": {
"name": "string",
"nameNorm": "string",
"tlds": [
"string"
]
},
"results": [
{
"fqdn": "string",
"tld": "string",
"status": "registered",
"available": null,
"source": "string",
"reason": "string",
"checkedAt": "string"
}
],
"summary": {
"registeredCount": 0,
"likelyAvailableCount": 0,
"unknownCount": 0
}
}
Schema of the response body
{
"properties": {
"input": {
"$ref": "#/components/schemas/DomainAvailabilityInputEcho",
"description": "Echoed and normalized input"
},
"results": {
"items": {
"$ref": "#/components/schemas/DomainAvailabilityResultResponse"
},
"type": "array",
"title": "Results",
"description": "Per-TLD availability check results"
},
"summary": {
"$ref": "#/components/schemas/DomainAvailabilitySummaryResponse",
"description": "Summary counts by status"
}
},
"type": "object",
"required": [
"input",
"results",
"summary"
],
"title": "DomainAvailabilityResponse",
"description": "Response body for POST /v1/domains/availability.",
"examples": [
{
"input": {
"name": "acme",
"nameNorm": "acme",
"tlds": [
"ch",
"com"
]
},
"results": [
{
"available": false,
"checkedAt": "2026-03-22T12:00:00Z",
"fqdn": "acme.ch",
"reason": "dns_or_rdap_positive",
"source": "dns+rdap",
"status": "registered",
"tld": "ch"
},
{
"available": true,
"checkedAt": "2026-03-22T12:00:01Z",
"fqdn": "acme.com",
"reason": "no_delegation_and_rdap_not_found",
"source": "dns+rdap",
"status": "likely_available",
"tld": "com"
}
],
"summary": {
"likelyAvailableCount": 1,
"registeredCount": 1,
"unknownCount": 0
}
}
]
}
Response 400 Bad Request¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 502 Bad Gateway¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 504 Gateway Timeout¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Name Eligibility¶
POST /v1/name/eligibility¶
Check company name eligibility
Description Evaluates whether a proposed company name is suitable for registration in Switzerland.
Combines strict deterministic rules (regex, allowlists) with advanced
semantic analysis to ensure the name is distinctive, not misleading, and compliant with Swiss Company Name Formation Rules.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| ClientApiKeyAuth | header | string | N/A | No | Client API key for public endpoints. |
Request body
application/json
{
"companyName": "string",
"legalForm": "stock_corporation",
"activityScope": null,
"language": "de",
"ownerFullName": null,
"checkLevel": "basic"
}
Schema of the request body
{
"properties": {
"companyName": {
"type": "string",
"maxLength": 256,
"minLength": 3,
"title": "Companyname",
"description": "The proposed company name to analyze. Prefer providing the base name without legal-form suffix (e.g., 'Legiqo' instead of 'Legiqo GmbH') for best consistency."
},
"legalForm": {
"$ref": "#/components/schemas/SupportedLegalForm",
"description": "Target legal form type (language-neutral). Allowed values: 'stock_corporation' (AG/SA), 'limited_liability' (GmbH/Sàrl/Sagl), 'sole_proprietorship' (Einzelunternehmen)"
},
"activityScope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Activityscope",
"description": "Description of the company's purpose (Zweck)"
},
"language": {
"$ref": "#/components/schemas/Language",
"description": "Language context for validation. Affects name interpretation and response messages."
},
"ownerFullName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Ownerfullname",
"description": "Full name of the owner (required for Einzelunternehmen)"
},
"checkLevel": {
"$ref": "#/components/schemas/ComplianceCheckLevel",
"description": "'basic' (Deterministic rules only) or 'full' (Deterministic rules + advanced semantic analysis)",
"default": "full"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"companyName",
"legalForm",
"language"
],
"title": "ComplianceAnalysisRequest",
"description": "Request body for POST /v1/name/eligibility.\n\nAttributes:\n companyName: The proposed company name to analyze.\n legalForm: Target legal form (e.g., \"AG\", \"GmbH\").\n activityScope: Description of the company's purpose.\n language: Primary language of the name.\n ownerFullName: Full name of the owner (for Sole Proprietorship).\n checkLevel: 'basic' or 'full'.",
"examples": [
{
"activityScope": "Development of software for bakeries",
"checkLevel": "full",
"companyName": "Müller & Söhne Banking",
"language": "en",
"legalForm": "stock_corporation"
}
]
}
Response 200 OK¶
application/json
{
"input": {
"companyName": "string",
"legalForm": "stock_corporation",
"activityScope": null,
"language": "de",
"ownerFullName": null
},
"overallStatus": "COMPLIANT",
"issues": [
{
"code": "string",
"severity": "CRITICAL",
"message": "string",
"source": "string",
"ruleRef": null
}
],
"registrableNames": null,
"metadata": null
}
Schema of the response body
{
"properties": {
"input": {
"$ref": "#/components/schemas/ComplianceAnalysisInputEcho"
},
"overallStatus": {
"$ref": "#/components/schemas/ComplianceOverallStatus"
},
"issues": {
"items": {
"$ref": "#/components/schemas/ValidationIssueModel"
},
"type": "array",
"title": "Issues"
},
"registrableNames": {
"anyOf": [
{
"$ref": "#/components/schemas/RegistrableNamesModel"
},
{
"type": "null"
}
],
"description": "The full registrable company names in all 4 languages (base name + legal form suffix)"
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata",
"description": "Processing metadata"
}
},
"type": "object",
"required": [
"input",
"overallStatus",
"issues"
],
"title": "ComplianceAnalysisResponse",
"description": "Response body for compliance analysis.",
"examples": [
{
"input": {
"activityScope": "Development of software",
"companyName": "Legiqo",
"language": "en",
"legalForm": "limited_liability"
},
"issues": [],
"metadata": {
"processingTimeMs": 150
},
"overallStatus": "COMPLIANT",
"registrableNames": {
"de": "Legiqo GmbH",
"en": "Legiqo LLC",
"fr": "Legiqo Sàrl",
"it": "Legiqo Sagl"
}
}
]
}
Response 400 Bad Request¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
POST /v2/name/eligibility¶
Check company name eligibility (v2 semantic pipeline)
Description V2 eligibility check that reuses deterministic checks from v1 and applies a structured semantic LLM evaluation with explicit rule outputs.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| ClientApiKeyAuth | header | string | N/A | No | Client API key for public endpoints. |
Request body
application/json
{
"companyName": "string",
"legalForm": "stock_corporation",
"activityScope": null,
"language": "de",
"ownerSurname": null,
"legalSeat": null,
"checkLevel": "basic"
}
Schema of the request body
{
"properties": {
"companyName": {
"type": "string",
"maxLength": 256,
"minLength": 3,
"title": "Companyname",
"description": "The proposed company name to analyze. Prefer providing the base name without legal-form suffix (e.g., 'Legiqo' instead of 'Legiqo GmbH') for best consistency."
},
"legalForm": {
"$ref": "#/components/schemas/SupportedLegalForm",
"description": "Target legal form type (language-neutral). Allowed values: 'stock_corporation' (AG/SA), 'limited_liability' (GmbH/Sàrl/Sagl), 'sole_proprietorship' (Einzelunternehmen)"
},
"activityScope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Activityscope",
"description": "Description of the company's purpose (Zweck)"
},
"language": {
"$ref": "#/components/schemas/Language",
"description": "Language context for validation and response messages."
},
"ownerSurname": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Ownersurname",
"description": "Owner surname (required only for sole proprietorship checks). V2 accepts ownerSurname only."
},
"legalSeat": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Legalseat",
"description": "Optional legal seat (municipality/city) used for geographic consistency checks against geographic terms in companyName. Providing this reduces seat-context warnings and improves review quality."
},
"checkLevel": {
"$ref": "#/components/schemas/ComplianceCheckLevel",
"description": "'basic' (Deterministic rules only) or 'full' (Deterministic rules + advanced semantic analysis)",
"default": "full"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"companyName",
"legalForm",
"language"
],
"title": "ComplianceAnalysisV2Request",
"description": "Request body for POST /v2/name/eligibility.\n\nV2 keeps deterministic + semantic checks while supporting additional optional\ncontext fields used for Weisung-aligned warnings/review.",
"examples": [
{
"activityScope": "Legal tech services",
"checkLevel": "full",
"companyName": "Legiqo",
"language": "en",
"legalForm": "limited_liability",
"legalSeat": "Zürich"
}
]
}
Response 200 OK¶
application/json
{
"input": {
"companyName": "string",
"legalForm": "stock_corporation",
"activityScope": null,
"language": "de",
"ownerSurname": null,
"legalSeat": null
},
"overallStatus": "COMPLIANT",
"issues": [
{
"code": "string",
"severity": "CRITICAL",
"message": "string",
"source": "string",
"ruleRef": null
}
],
"semanticEvaluation": null,
"registrableNames": null,
"metadata": null
}
Schema of the response body
{
"properties": {
"input": {
"$ref": "#/components/schemas/ComplianceAnalysisInputEchoV2"
},
"overallStatus": {
"$ref": "#/components/schemas/ComplianceOverallStatus"
},
"issues": {
"items": {
"$ref": "#/components/schemas/ValidationIssueModel"
},
"type": "array",
"title": "Issues"
},
"semanticEvaluation": {
"anyOf": [
{
"$ref": "#/components/schemas/SemanticRegistrationEvaluationV2Model"
},
{
"type": "null"
}
],
"description": "Structured semantic evaluation from the v2 LLM pipeline (full mode only)"
},
"registrableNames": {
"anyOf": [
{
"$ref": "#/components/schemas/RegistrableNamesModel"
},
{
"type": "null"
}
],
"description": "The full registrable company names in all 4 languages (base name + legal form suffix)"
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata",
"description": "Processing metadata"
}
},
"type": "object",
"required": [
"input",
"overallStatus",
"issues"
],
"title": "ComplianceAnalysisV2Response",
"description": "Response body for v2 compliance analysis."
}
Response 400 Bad Request¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
POST /v3/name/eligibility¶
Check company name eligibility (v3 classifier extraction)
Description
V3 eligibility check:
- deterministic checks from v2
- structured LLM classifier extraction output (semanticEvaluation)
- no semantic rating/decision mapping in this endpoint
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| ClientApiKeyAuth | header | string | N/A | No | Client API key for public endpoints. |
Request body
application/json
{
"companyName": "string",
"legalForm": "stock_corporation",
"activityScope": null,
"language": "de",
"ownerSurname": null,
"legalSeat": null,
"languageVariants": [
{
"name": "string",
"lang": null
}
],
"checkLevel": "basic"
}
Schema of the request body
{
"properties": {
"companyName": {
"type": "string",
"maxLength": 256,
"minLength": 3,
"title": "Companyname",
"description": "The proposed company name to analyze. Prefer providing the base name without legal-form suffix (e.g., 'Legiqo' instead of 'Legiqo GmbH') for best consistency."
},
"legalForm": {
"$ref": "#/components/schemas/SupportedLegalForm",
"description": "Target legal form type (language-neutral). Allowed values: 'stock_corporation' (AG/SA), 'limited_liability' (GmbH/Sarl/Sagl), 'sole_proprietorship' (Einzelunternehmen)"
},
"activityScope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Activityscope",
"description": "Description of the company's purpose (Zweck)"
},
"language": {
"$ref": "#/components/schemas/Language",
"description": "Primary language context for deterministic checks/messages."
},
"ownerSurname": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Ownersurname",
"description": "Owner surname (required only for sole proprietorship checks)."
},
"legalSeat": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Legalseat",
"description": "Optional legal seat (municipality/city) for geographic checks."
},
"languageVariants": {
"items": {
"$ref": "#/components/schemas/LanguageVariantV3Model"
},
"type": "array",
"title": "Languagevariants",
"description": "Optional intended multilingual register variants to evaluate content consistency (Weisung 2.1.3.2)."
},
"checkLevel": {
"$ref": "#/components/schemas/ComplianceCheckLevel",
"description": "'basic' (Deterministic rules only) or 'full' (Deterministic rules + advanced semantic analysis)",
"default": "full"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"companyName",
"legalForm",
"language"
],
"title": "ComplianceAnalysisV3Request",
"description": "Request body for POST /v3/name/eligibility.\n\nV3 keeps v2 deterministic context and adds optional languageVariants so the\nclassifier can check multilingual consistency explicitly.",
"examples": [
{
"activityScope": "Manufacture and sale of watches",
"checkLevel": "full",
"companyName": "IED Uhrenfabrik AG",
"language": "de",
"languageVariants": [
{
"lang": "de",
"name": "IED Uhrenfabrik AG"
},
{
"lang": "en",
"name": "IED Watch Ltd"
}
],
"legalForm": "stock_corporation",
"legalSeat": "Zurich"
}
]
}
Response 200 OK¶
application/json
{
"input": {
"companyName": "string",
"legalForm": "stock_corporation",
"activityScope": null,
"language": "de",
"ownerSurname": null,
"legalSeat": null,
"languageVariants": [
{
"name": "string",
"lang": null
}
]
},
"findings": [
{
"code": "string",
"severity": "CRITICAL",
"message": "string",
"source": "string",
"ruleRef": null
}
],
"semanticEvaluation": null,
"registrableNames": null,
"metadata": null
}
Schema of the response body
{
"properties": {
"input": {
"$ref": "#/components/schemas/ComplianceAnalysisInputEchoV3"
},
"findings": {
"items": {
"$ref": "#/components/schemas/ValidationIssueModel"
},
"type": "array",
"title": "Findings",
"description": "Deterministic findings returned by the endpoint. V3 semantic extraction is exposed separately in semanticEvaluation."
},
"semanticEvaluation": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Semanticevaluation",
"description": "Structured semantic extraction payload from the v3 classifier (full mode only)"
},
"registrableNames": {
"anyOf": [
{
"$ref": "#/components/schemas/RegistrableNamesModel"
},
{
"type": "null"
}
],
"description": "The full registrable company names in all 4 languages (base name + legal form suffix)"
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata",
"description": "Processing metadata"
}
},
"type": "object",
"required": [
"input",
"findings"
],
"title": "ComplianceAnalysisV3Response",
"description": "Response body for v3 compliance analysis."
}
Response 400 Bad Request¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
Company Name Assessment¶
POST /v1/name/assessment¶
Assess company name risk
Description
Company name assessment combining:
- deterministic policy checks
- semantic extraction pipeline (when checkLevel=full)
- profile-based risk mapping (assessment.overallStatus, flags)
Important response semantics:
- HTTP 200 indicates a valid assessment execution.
- Risk outcome is expressed in `assessment.overallStatus`.
- `metadata.traceId` and `X-Trace-Id` can be used for support correlation.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| ClientApiKeyAuth | header | string | N/A | No | Client API key for public endpoints. |
Request body
application/json
{
"companyName": "string",
"legalForm": "stock_corporation",
"activityScope": null,
"language": "de",
"ownerSurname": null,
"legalSeat": null,
"languageVariants": [
{
"name": "string",
"lang": null
}
],
"checkLevel": "basic",
"riskProfile": "balanced"
}
Schema of the request body
{
"properties": {
"companyName": {
"type": "string",
"maxLength": 256,
"minLength": 3,
"title": "Companyname",
"description": "The proposed company name to analyze. For assessment, provide the full primary name including legal-form suffix (e.g., 'Legiqo GmbH') and keep it consistent with `legalForm`."
},
"legalForm": {
"$ref": "#/components/schemas/SupportedLegalForm",
"description": "Target legal form type (language-neutral). Allowed values: 'stock_corporation' (AG/SA), 'limited_liability' (GmbH/Sarl/Sagl), 'sole_proprietorship' (Einzelunternehmen)"
},
"activityScope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Activityscope",
"description": "Description of the company's purpose (Zweck)"
},
"language": {
"$ref": "#/components/schemas/Language",
"description": "Primary language context for deterministic checks/messages."
},
"ownerSurname": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Ownersurname",
"description": "Owner surname (required only for sole proprietorship checks)."
},
"legalSeat": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Legalseat",
"description": "Optional legal seat (municipality/city) for geographic checks."
},
"languageVariants": {
"items": {
"$ref": "#/components/schemas/LanguageVariantV3Model"
},
"type": "array",
"title": "Languagevariants",
"description": "Optional intended multilingual register variants to evaluate content consistency."
},
"checkLevel": {
"$ref": "#/components/schemas/ComplianceCheckLevel",
"description": "'basic' (Deterministic checks only) or 'full' (Deterministic checks + semantic extraction)",
"default": "full"
},
"riskProfile": {
"$ref": "#/components/schemas/RiskProfile",
"description": "Static risk profile used for mapping flags to final status.",
"default": "balanced"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"companyName",
"legalForm",
"language"
],
"title": "CompanyNameAssessmentRequest",
"description": "Request body for POST /v1/name/assessment.",
"examples": [
{
"activityScope": "Manufacture and sale of watches",
"checkLevel": "full",
"companyName": "IED Uhrenfabrik AG",
"language": "de",
"languageVariants": [
{
"lang": "de",
"name": "IED Uhrenfabrik AG"
},
{
"lang": "en",
"name": "IED Watch Ltd"
}
],
"legalForm": "stock_corporation",
"legalSeat": "Zurich",
"riskProfile": "balanced"
}
]
}
Response 200 OK¶
application/json
{
"assessment": {
"companyName": "string",
"overallStatus": "CLEAR_TO_FILE",
"clientProfileApplied": "balanced"
},
"flags": [
{
"code": "string",
"severity": "INFO",
"category": "SYNTAX",
"message": "string"
}
],
"semanticContext": null,
"metadata": null
}
Schema of the response body
{
"properties": {
"assessment": {
"$ref": "#/components/schemas/AssessmentSummaryModel",
"description": "Top-level assessment outcome under the selected risk profile."
},
"flags": {
"items": {
"$ref": "#/components/schemas/AssessmentFlagModel"
},
"type": "array",
"title": "Flags",
"description": "Triggered machine-readable flags. Use `code` and `severity` for deterministic client handling."
},
"semanticContext": {
"anyOf": [
{
"$ref": "#/components/schemas/SemanticContextModel"
},
{
"type": "null"
}
],
"description": "Structured semantic extraction context from the assessment pipeline (full mode only)."
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata",
"description": "Processing metadata"
}
},
"type": "object",
"required": [
"assessment",
"flags"
],
"title": "CompanyNameAssessmentResponse",
"description": "Response body for company name assessment.",
"examples": [
{
"assessment": {
"clientProfileApplied": "balanced",
"companyName": "Legiqo GmbH",
"overallStatus": "CLEAR_TO_FILE"
},
"flags": [],
"metadata": {
"processingTimeMs": 112,
"semanticFailOpen": false,
"traceId": "trc_f8bfb7db8e4848fabc0b2b2dfeb7fe48"
},
"semanticContext": {
"containsGeographicTerm": false,
"impliedActivities": [],
"isPurelyDescriptive": false
}
},
{
"assessment": {
"clientProfileApplied": "balanced",
"companyName": "Kaufhaus AG",
"overallStatus": "MANUAL_REVIEW_ADVISED"
},
"flags": [
{
"category": "SEMANTIC",
"code": "WARN_PURELY_DESCRIPTIVE",
"message": "The name appears purely descriptive and may lack distinctiveness.",
"severity": "WARNING"
}
],
"metadata": {
"processingTimeMs": 146,
"semanticFailOpen": false,
"traceId": "trc_88fe2ab77c67438e8c7a4ca886ab1652"
},
"semanticContext": {
"impliedActivities": [
"Retail"
],
"isPurelyDescriptive": true
}
},
{
"assessment": {
"clientProfileApplied": "balanced",
"companyName": "Swiss Bank Consulting GmbH",
"overallStatus": "REGISTRY_REJECTION_LIKELY"
},
"flags": [
{
"category": "REGULATORY",
"code": "WARN_FINMA_LICENSE_REQUIRED",
"message": "Regulated financial terms suggest FINMA authorization may be required.",
"severity": "ERROR"
}
],
"metadata": {
"processingTimeMs": 167,
"semanticFailOpen": false,
"traceId": "trc_3c7d870bb27a4f75986fbca863f0591c"
},
"semanticContext": {
"impliedInvestmentOrBankingActivity": true
}
}
]
}
| Name | Description | Schema |
|---|---|---|
| X-Trace-Id | Correlation id for this request. | string |
| X-RateLimit-Limit | Request limit for current window. | string |
| X-RateLimit-Remaining | Remaining requests in current window. | string |
| X-RateLimit-Reset | Unix timestamp when current window resets. | string |
Response 400 Bad Request¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
| Name | Description | Schema |
|---|---|---|
| Retry-After | Seconds to wait before retrying. | string |
| X-RateLimit-Limit | Request limit for current window. | string |
| X-RateLimit-Remaining | Always 0 when rate-limited. | string |
| X-RateLimit-Reset | Unix timestamp when current window resets. | string |
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
Admin¶
GET /v1/admin/name/assessment/check-catalog¶
Get static assessment check catalog
Description Returns the full static catalog of assessment checks, with legal basis, execution order, and possible outcomes.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
Response 200 OK¶
application/json
[
{
"stepId": "string",
"sequence": 0,
"stage": "string",
"title": "string",
"whatItDoes": "string",
"sourceType": "string",
"legalBasis": [
"string"
],
"resultingFlagCode": null,
"possibleOutcomes": [
"string"
],
"parentStepIds": [
"string"
],
"checkVersion": "string"
}
]
Schema of the response body
{
"items": {
"$ref": "#/components/schemas/AssessmentCheckCatalogItemModel"
},
"type": "array",
"title": "Response Get Assessment Check Catalog V1 Admin Name Assessment Check Catalog Get"
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
GET /v1/admin/name/assessment/traces¶
List assessment traces
Description Returns paginated assessment traces for admin users.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| consumerId | query | None | No | ||
| fromTs | query | None | No | ||
| limit | query | integer | 50 | No | |
| offset | query | integer | 0 | No | |
| overallStatus | query | None | No | ||
| riskProfile | query | None | No | ||
| toTs | query | None | No |
Response 200 OK¶
application/json
{
"items": [
{
"traceId": "string",
"createdAt": "string",
"companyName": null,
"overallStatus": null,
"riskProfile": null,
"triggeredCount": 0,
"decisiveChecks": [
"string"
],
"statusCode": 0,
"durationMs": null
}
],
"total": 0,
"limit": 0,
"offset": 0
}
Schema of the response body
{
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/AssessmentTraceListItemModel"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "AssessmentTraceListResponse",
"description": "Paginated assessment traces list for the authenticated consumer."
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /v1/admin/name/assessment/traces/{trace_id}¶
Get assessment trace by trace ID
Description Returns one persisted assessment response and explanation for admin users.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| trace_id | path | string | No |
Response 200 OK¶
application/json
{
"traceId": "string",
"createdAt": "string",
"endpoint": "string",
"statusCode": 0,
"response": {
"assessment": {
"companyName": "string",
"overallStatus": "CLEAR_TO_FILE",
"clientProfileApplied": "balanced"
},
"flags": [
{
"code": "string",
"severity": "INFO",
"category": "SYNTAX",
"message": "string"
}
],
"semanticContext": null,
"metadata": null
},
"explanation": null
}
Schema of the response body
{
"properties": {
"traceId": {
"type": "string",
"title": "Traceid"
},
"createdAt": {
"type": "string",
"title": "Createdat"
},
"endpoint": {
"type": "string",
"title": "Endpoint"
},
"statusCode": {
"type": "integer",
"title": "Statuscode"
},
"response": {
"$ref": "#/components/schemas/CompanyNameAssessmentResponse"
},
"explanation": {
"anyOf": [
{
"$ref": "#/components/schemas/AssessmentExplanationModel"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"traceId",
"createdAt",
"endpoint",
"statusCode",
"response"
],
"title": "AssessmentTraceDetailResponse",
"description": "Consumer-safe trace lookup payload for one assessment request."
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 404 Not Found¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
POST /v1/admin/name/assessment/traces/compare¶
Compare two assessment traces
Description Compares two traces in admin scope.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
Request body
application/json
{
"traceIdA": "string",
"traceIdB": "string"
}
Schema of the request body
{
"properties": {
"traceIdA": {
"type": "string",
"title": "Traceida"
},
"traceIdB": {
"type": "string",
"title": "Traceidb"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"traceIdA",
"traceIdB"
],
"title": "AssessmentTraceCompareRequest",
"description": "Input payload to compare two assessment traces."
}
Response 200 OK¶
application/json
{
"traceIdA": "string",
"traceIdB": "string",
"overallStatusA": null,
"overallStatusB": null,
"changedChecks": [
{
"stepId": "string",
"triggeredA": true,
"triggeredB": true,
"outcomeA": "string",
"outcomeB": "string"
}
],
"decisiveChecksA": [
"string"
],
"decisiveChecksB": [
"string"
]
}
Schema of the response body
{
"properties": {
"traceIdA": {
"type": "string",
"title": "Traceida"
},
"traceIdB": {
"type": "string",
"title": "Traceidb"
},
"overallStatusA": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Overallstatusa"
},
"overallStatusB": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Overallstatusb"
},
"changedChecks": {
"items": {
"$ref": "#/components/schemas/AssessmentTraceDiffCheckModel"
},
"type": "array",
"title": "Changedchecks"
},
"decisiveChecksA": {
"items": {
"type": "string"
},
"type": "array",
"title": "Decisivechecksa"
},
"decisiveChecksB": {
"items": {
"type": "string"
},
"type": "array",
"title": "Decisivechecksb"
}
},
"type": "object",
"required": [
"traceIdA",
"traceIdB"
],
"title": "AssessmentTraceCompareResponse",
"description": "Comparison summary between two assessment traces."
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 404 Not Found¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /v1/admin/restricted-terms/categories¶
List restricted-term categories
Description Returns active/inactive restricted-term categories used by deterministic validation.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
Response 200 OK¶
application/json
[
{
"id": 0,
"code": "string",
"name": "string",
"description": null,
"sectionNumber": null,
"sectionTitle": null,
"ruleRef": null,
"defaultSeverity": "string",
"matchMode": "string",
"isActive": true
}
]
Schema of the response body
{
"items": {
"$ref": "#/components/schemas/RestrictedTermCategoryModel"
},
"type": "array",
"title": "Response List Restricted Term Categories V1 Admin Restricted Terms Categories Get"
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
GET /v1/admin/restricted-terms¶
List restricted terms
Description Lists restricted terms with optional category and active-state filtering.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| categoryCode | query | None | No | ||
| isActive | query | None | No | ||
| limit | query | integer | 100 | No | |
| offset | query | integer | 0 | No | |
| search | query | None | No |
Response 200 OK¶
application/json
{
"items": [
{
"id": 0,
"categoryId": 0,
"categoryCode": "string",
"term": "string",
"description": null,
"languageCode": null,
"matchModeOverride": null,
"severityOverride": null,
"isActive": true,
"source": "string",
"createdBy": null,
"createdAt": "string",
"updatedAt": "string"
}
],
"total": 0,
"limit": 0,
"offset": 0
}
Schema of the response body
{
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/RestrictedTermModel"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "RestrictedTermListResponse",
"description": "Paginated restricted-term listing."
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
POST /v1/admin/restricted-terms¶
Create restricted term
Description Creates a new restricted term under a category.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
Request body
application/json
{
"categoryCode": "string",
"term": "string",
"description": null,
"languageCode": null,
"matchModeOverride": null,
"severityOverride": null,
"createdBy": null
}
Schema of the request body
{
"properties": {
"categoryCode": {
"type": "string",
"maxLength": 64,
"minLength": 1,
"title": "Categorycode"
},
"term": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"title": "Term"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
],
"title": "Description"
},
"languageCode": {
"anyOf": [
{
"type": "string",
"maxLength": 16
},
{
"type": "null"
}
],
"title": "Languagecode"
},
"matchModeOverride": {
"anyOf": [
{
"type": "string",
"maxLength": 64
},
{
"type": "null"
}
],
"title": "Matchmodeoverride"
},
"severityOverride": {
"anyOf": [
{
"type": "string",
"maxLength": 64
},
{
"type": "null"
}
],
"title": "Severityoverride"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "null"
}
],
"title": "Createdby"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"categoryCode",
"term"
],
"title": "RestrictedTermCreateRequest",
"description": "Create request for a restricted term."
}
Response 200 OK¶
application/json
{
"id": 0,
"categoryId": 0,
"categoryCode": "string",
"term": "string",
"description": null,
"languageCode": null,
"matchModeOverride": null,
"severityOverride": null,
"isActive": true,
"source": "string",
"createdBy": null,
"createdAt": "string",
"updatedAt": "string"
}
Schema of the response body
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"categoryId": {
"type": "integer",
"title": "Categoryid"
},
"categoryCode": {
"type": "string",
"title": "Categorycode"
},
"term": {
"type": "string",
"title": "Term"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"languageCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Languagecode"
},
"matchModeOverride": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Matchmodeoverride"
},
"severityOverride": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Severityoverride"
},
"isActive": {
"type": "boolean",
"title": "Isactive"
},
"source": {
"type": "string",
"title": "Source"
},
"createdBy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Createdby"
},
"createdAt": {
"type": "string",
"title": "Createdat"
},
"updatedAt": {
"type": "string",
"title": "Updatedat"
}
},
"type": "object",
"required": [
"id",
"categoryId",
"categoryCode",
"term",
"isActive",
"source",
"createdAt",
"updatedAt"
],
"title": "RestrictedTermModel",
"description": "Single restricted-term row."
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 404 Not Found¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 409 Conflict¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
PATCH /v1/admin/restricted-terms/{term_id}¶
Update restricted term
Description Updates one restricted term. Supports partial updates.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| term_id | path | integer | No |
Request body
application/json
{
"categoryCode": null,
"term": null,
"description": null,
"languageCode": null,
"matchModeOverride": null,
"severityOverride": null,
"isActive": null
}
Schema of the request body
{
"properties": {
"categoryCode": {
"anyOf": [
{
"type": "string",
"maxLength": 64,
"minLength": 1
},
{
"type": "null"
}
],
"title": "Categorycode"
},
"term": {
"anyOf": [
{
"type": "string",
"maxLength": 512,
"minLength": 1
},
{
"type": "null"
}
],
"title": "Term"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
],
"title": "Description"
},
"languageCode": {
"anyOf": [
{
"type": "string",
"maxLength": 16
},
{
"type": "null"
}
],
"title": "Languagecode"
},
"matchModeOverride": {
"anyOf": [
{
"type": "string",
"maxLength": 64
},
{
"type": "null"
}
],
"title": "Matchmodeoverride"
},
"severityOverride": {
"anyOf": [
{
"type": "string",
"maxLength": 64
},
{
"type": "null"
}
],
"title": "Severityoverride"
},
"isActive": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Isactive"
}
},
"additionalProperties": false,
"type": "object",
"title": "RestrictedTermUpdateRequest",
"description": "Partial update request for a restricted term."
}
Response 200 OK¶
application/json
{
"id": 0,
"categoryId": 0,
"categoryCode": "string",
"term": "string",
"description": null,
"languageCode": null,
"matchModeOverride": null,
"severityOverride": null,
"isActive": true,
"source": "string",
"createdBy": null,
"createdAt": "string",
"updatedAt": "string"
}
Schema of the response body
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"categoryId": {
"type": "integer",
"title": "Categoryid"
},
"categoryCode": {
"type": "string",
"title": "Categorycode"
},
"term": {
"type": "string",
"title": "Term"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"languageCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Languagecode"
},
"matchModeOverride": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Matchmodeoverride"
},
"severityOverride": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Severityoverride"
},
"isActive": {
"type": "boolean",
"title": "Isactive"
},
"source": {
"type": "string",
"title": "Source"
},
"createdBy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Createdby"
},
"createdAt": {
"type": "string",
"title": "Createdat"
},
"updatedAt": {
"type": "string",
"title": "Updatedat"
}
},
"type": "object",
"required": [
"id",
"categoryId",
"categoryCode",
"term",
"isActive",
"source",
"createdAt",
"updatedAt"
],
"title": "RestrictedTermModel",
"description": "Single restricted-term row."
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 404 Not Found¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 409 Conflict¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
DELETE /v1/admin/restricted-terms/{term_id}¶
Deactivate restricted term
Description Soft-deletes a restricted term by setting is_active=false.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| term_id | path | integer | No |
Response 200 OK¶
application/json
Schema of the response body
{
"type": "object",
"additionalProperties": true,
"title": "Response Delete Restricted Term V1 Admin Restricted Terms Term Id Delete"
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 404 Not Found¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /v1/admin/consumers¶
List API consumers
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| isActive | query | None | No |
Response 200 OK¶
application/json
[
{
"id": 0,
"code": "string",
"name": "string",
"description": null,
"contactEmail": null,
"isActive": true,
"createdAt": "string",
"updatedAt": "string"
}
]
Schema of the response body
{
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiConsumerModel"
},
"title": "Response List Api Consumers V1 Admin Consumers Get"
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
POST /v1/admin/consumers¶
Create API consumer
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
Request body
application/json
{
"name": "string",
"description": null,
"contactEmail": null
}
Schema of the request body
{
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"minLength": 1,
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
],
"title": "Description"
},
"contactEmail": {
"anyOf": [
{
"type": "string",
"maxLength": 320
},
{
"type": "null"
}
],
"title": "Contactemail"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name"
],
"title": "ApiConsumerCreateRequest",
"description": "Create request for an API consumer."
}
Response 200 OK¶
application/json
{
"id": 0,
"code": "string",
"name": "string",
"description": null,
"contactEmail": null,
"isActive": true,
"createdAt": "string",
"updatedAt": "string"
}
Schema of the response body
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"code": {
"type": "string",
"title": "Code"
},
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"contactEmail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Contactemail"
},
"isActive": {
"type": "boolean",
"title": "Isactive"
},
"createdAt": {
"type": "string",
"title": "Createdat"
},
"updatedAt": {
"type": "string",
"title": "Updatedat"
}
},
"type": "object",
"required": [
"id",
"code",
"name",
"isActive",
"createdAt",
"updatedAt"
],
"title": "ApiConsumerModel",
"description": "API consumer/tenant metadata."
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
PATCH /v1/admin/consumers/{consumer_id}¶
Update API consumer
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| consumer_id | path | integer | No |
Request body
application/json
{
"name": null,
"description": null,
"contactEmail": null,
"isActive": null
}
Schema of the request body
{
"properties": {
"name": {
"anyOf": [
{
"type": "string",
"maxLength": 256,
"minLength": 1
},
{
"type": "null"
}
],
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
],
"title": "Description"
},
"contactEmail": {
"anyOf": [
{
"type": "string",
"maxLength": 320
},
{
"type": "null"
}
],
"title": "Contactemail"
},
"isActive": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Isactive"
}
},
"additionalProperties": false,
"type": "object",
"title": "ApiConsumerUpdateRequest",
"description": "Partial update request for an API consumer."
}
Response 200 OK¶
application/json
{
"id": 0,
"code": "string",
"name": "string",
"description": null,
"contactEmail": null,
"isActive": true,
"createdAt": "string",
"updatedAt": "string"
}
Schema of the response body
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"code": {
"type": "string",
"title": "Code"
},
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"contactEmail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Contactemail"
},
"isActive": {
"type": "boolean",
"title": "Isactive"
},
"createdAt": {
"type": "string",
"title": "Createdat"
},
"updatedAt": {
"type": "string",
"title": "Updatedat"
}
},
"type": "object",
"required": [
"id",
"code",
"name",
"isActive",
"createdAt",
"updatedAt"
],
"title": "ApiConsumerModel",
"description": "API consumer/tenant metadata."
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /v1/admin/api-keys¶
List API keys
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| consumerId | query | None | No | ||
| isActive | query | None | No | ||
| limit | query | integer | 100 | No | |
| offset | query | integer | 0 | No |
Response 200 OK¶
application/json
{
"items": [
{
"id": 0,
"consumerId": 0,
"consumerCode": "string",
"keyPrefix": "string",
"keyLast4": "string",
"displayName": null,
"description": null,
"createdBy": null,
"isActive": true,
"expiresAt": null,
"lastUsedAt": null,
"revokedAt": null,
"createdAt": "string",
"updatedAt": "string"
}
],
"total": 0,
"limit": 0,
"offset": 0
}
Schema of the response body
{
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/ApiKeyModel"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "ApiKeyListResponse",
"description": "Paginated API-key listing."
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
POST /v1/admin/api-keys¶
Issue new API key
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
Request body
application/json
{
"consumerId": 0,
"displayName": null,
"description": null,
"createdBy": null,
"expiresAt": "2027-03-28T13:12:06.216374+00:00",
"allowNonExpiring": true
}
Schema of the request body
{
"properties": {
"consumerId": {
"type": "integer",
"minimum": 1.0,
"title": "Consumerid"
},
"displayName": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "null"
}
],
"title": "Displayname"
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "null"
}
],
"title": "Description"
},
"createdBy": {
"anyOf": [
{
"type": "string",
"maxLength": 256
},
{
"type": "null"
}
],
"title": "Createdby"
},
"expiresAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Expiresat",
"description": "Optional explicit expiry. If omitted and allowNonExpiring=false, the API defaults to now + 365 days.",
"example": "2027-03-28T13:12:06.216374+00:00"
},
"allowNonExpiring": {
"type": "boolean",
"title": "Allownonexpiring",
"default": false
}
},
"additionalProperties": false,
"type": "object",
"required": [
"consumerId"
],
"title": "ApiKeyCreateRequest",
"description": "Request to issue a new API key for a consumer."
}
Response 200 OK¶
application/json
{
"apiKey": "string",
"key": {
"id": 0,
"consumerId": 0,
"consumerCode": "string",
"keyPrefix": "string",
"keyLast4": "string",
"displayName": null,
"description": null,
"createdBy": null,
"isActive": true,
"expiresAt": null,
"lastUsedAt": null,
"revokedAt": null,
"createdAt": "string",
"updatedAt": "string"
}
}
Schema of the response body
{
"properties": {
"apiKey": {
"type": "string",
"title": "Apikey"
},
"key": {
"$ref": "#/components/schemas/ApiKeyModel"
}
},
"type": "object",
"required": [
"apiKey",
"key"
],
"title": "ApiKeyCreateResponse",
"description": "Response when issuing a new API key."
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
DELETE /v1/admin/api-keys/{key_id}¶
Revoke API key
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| key_id | path | integer | No |
Response 200 OK¶
application/json
Schema of the response body
{
"type": "object",
"additionalProperties": true,
"title": "Response Revoke Api Key V1 Admin Api Keys Key Id Delete"
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /v1/admin/metrics/search-events¶
List tracked search events
Description Returns paginated tracked API request/response events for regular client endpoints, including resolved consumer context when available.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| consumerId | query | None | No | ||
| endpoint | query | None | No | ||
| fromTs | query | None | No | ||
| limit | query | integer | 100 | No | |
| offset | query | integer | 0 | No | |
| searchTerm | query | None | No | ||
| statusCode | query | None | No | ||
| toTs | query | None | No |
Response 200 OK¶
application/json
{
"items": [
{
"id": 0,
"traceId": null,
"createdAt": "string",
"endpoint": "string",
"searchTerm": "string",
"statusCode": 0,
"durationMs": null,
"clientIp": null,
"userAgent": null,
"consumerId": null,
"consumerCode": null,
"consumerName": null,
"params": {},
"resultSummary": null
}
],
"total": 0,
"limit": 0,
"offset": 0
}
Schema of the response body
{
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/SearchEventLogModel"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "SearchEventListResponse",
"description": "Paginated list of tracked API request events."
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /v1/admin/metrics/traces/{trace_id}¶
Get full trace by trace ID
Description Returns one tracked request/response record by trace ID, including captured request parameters and response summary payload.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| trace_id | path | string | No |
Response 200 OK¶
application/json
{
"traceId": "string",
"event": {
"id": 0,
"traceId": null,
"createdAt": "string",
"endpoint": "string",
"searchTerm": "string",
"statusCode": 0,
"durationMs": null,
"clientIp": null,
"userAgent": null,
"consumerId": null,
"consumerCode": null,
"consumerName": null,
"params": {},
"resultSummary": null
}
}
Schema of the response body
{
"properties": {
"traceId": {
"type": "string",
"title": "Traceid"
},
"event": {
"$ref": "#/components/schemas/SearchEventLogModel"
}
},
"type": "object",
"required": [
"traceId",
"event"
],
"title": "SearchTraceDetailResponse",
"description": "Detailed trace record for one tracked request."
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 404 Not Found¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /v1/admin/metrics/search-overview¶
Get search metrics overview
Description Returns aggregated search activity metrics like request volume, success/error counts, latency distribution, unique consumers, and unique queried terms.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| endpoint | query | None | No | ||
| fromTs | query | None | No | ||
| toTs | query | None | No |
Response 200 OK¶
application/json
{
"periodStart": null,
"periodEnd": null,
"totalRequests": 0,
"successRequests": 0,
"errorRequests": 0,
"uniqueConsumers": 0,
"uniqueSearchTerms": 0,
"avgDurationMs": null,
"p95DurationMs": null
}
Schema of the response body
{
"properties": {
"periodStart": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Periodstart"
},
"periodEnd": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Periodend"
},
"totalRequests": {
"type": "integer",
"title": "Totalrequests"
},
"successRequests": {
"type": "integer",
"title": "Successrequests"
},
"errorRequests": {
"type": "integer",
"title": "Errorrequests"
},
"uniqueConsumers": {
"type": "integer",
"title": "Uniqueconsumers"
},
"uniqueSearchTerms": {
"type": "integer",
"title": "Uniquesearchterms"
},
"avgDurationMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Avgdurationms"
},
"p95DurationMs": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "P95Durationms"
}
},
"type": "object",
"required": [
"totalRequests",
"successRequests",
"errorRequests",
"uniqueConsumers",
"uniqueSearchTerms"
],
"title": "SearchMetricsOverviewResponse",
"description": "High-level summary metrics for tracked API requests."
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /v1/admin/metrics/search-consumers¶
Get per-consumer search metrics
Description Returns aggregated request/latency metrics grouped by API consumer.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| endpoint | query | None | No | ||
| fromTs | query | None | No | ||
| limit | query | integer | 50 | No | |
| toTs | query | None | No |
Response 200 OK¶
application/json
{
"items": [
{
"consumerId": null,
"consumerCode": null,
"consumerName": null,
"totalRequests": 0,
"successRequests": 0,
"errorRequests": 0,
"avgDurationMs": null,
"p95DurationMs": null,
"latestRequestAt": null
}
]
}
Schema of the response body
{
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/SearchConsumerMetricsModel"
},
"type": "array",
"title": "Items"
}
},
"type": "object",
"required": [
"items"
],
"title": "SearchConsumerMetricsResponse",
"description": "Per-consumer metrics list."
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /v1/admin/metrics/top-search-terms¶
Get top searched terms
Description Returns the most frequently queried search terms.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
| endpoint | query | None | No | ||
| fromTs | query | None | No | ||
| limit | query | integer | 20 | No | |
| toTs | query | None | No |
Response 200 OK¶
application/json
{
"items": [
{
"searchTerm": "string",
"requestCount": 0,
"uniqueConsumers": 0,
"avgDurationMs": null
}
]
}
Schema of the response body
{
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/SearchTopTermModel"
},
"type": "array",
"title": "Items"
}
},
"type": "object",
"required": [
"items"
],
"title": "SearchTopTermsResponse",
"description": "Top searched terms across tracked API requests."
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
GET /v1/admin/registry-stats¶
Get registry statistics
Description Returns operational statistics about registry data, including total company counts and metadata about the most recent ingestion run.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| AdminApiKeyAuth | header | string | N/A | No | Admin API key for /v1/admin/* endpoints. |
Response 200 OK¶
application/json
{
"total_companies": 0,
"active_companies": 0,
"deleted_companies": 0,
"total_company_names": 0,
"last_ingestion": null
}
Schema of the response body
{
"properties": {
"total_companies": {
"type": "integer",
"title": "Total Companies",
"description": "Total number of companies in the database"
},
"active_companies": {
"type": "integer",
"title": "Active Companies",
"description": "Number of active (non-deleted) companies"
},
"deleted_companies": {
"type": "integer",
"title": "Deleted Companies",
"description": "Number of soft-deleted companies"
},
"total_company_names": {
"type": "integer",
"title": "Total Company Names",
"description": "Total name variants across all companies"
},
"last_ingestion": {
"anyOf": [
{
"$ref": "#/components/schemas/IngestionRunInfo"
},
{
"type": "null"
}
],
"description": "Most recent ingestion run info"
}
},
"type": "object",
"required": [
"total_companies",
"active_companies",
"deleted_companies",
"total_company_names",
"last_ingestion"
],
"title": "StatsResponse",
"description": "Response for GET /v1/stats endpoint with database statistics.",
"examples": [
{
"active_companies": 745000,
"deleted_companies": 5000,
"last_ingestion": {
"finished_at": "2025-01-15T12:30:00Z",
"id": 42,
"mode": "backfill",
"rows_failed": 12,
"rows_upserted": 750000,
"started_at": "2025-01-15T10:00:00Z"
},
"total_companies": 750000,
"total_company_names": 1200000
}
]
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Company¶
GET /v1/company/{source_company_id}¶
Get company by ID
Description Look up a specific company by its source company ID (e.g., CHE number). Returns detailed company information including all name variants. Requires authentication.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
| ClientApiKeyAuth | header | string | N/A | No | Client API key for public endpoints. |
| source_company_id | path | string | No |
Response 200 OK¶
application/json
{
"source_company_id": "string",
"source_system": "string",
"name_display": "string",
"name_norm": "string",
"legal_seat": null,
"legal_form": null,
"chid": null,
"ehraid": null,
"is_deleted": true,
"name_variants": [
{
"name_raw": "string",
"name_kind": "string",
"lang": "string",
"is_primary": true
}
]
}
Schema of the response body
{
"properties": {
"source_company_id": {
"type": "string",
"title": "Source Company Id",
"description": "Unique identifier (e.g., CHE number)"
},
"source_system": {
"type": "string",
"title": "Source System",
"description": "Source system identifier"
},
"name_display": {
"type": "string",
"title": "Name Display",
"description": "Display name"
},
"name_norm": {
"type": "string",
"title": "Name Norm",
"description": "Normalized name"
},
"legal_seat": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Legal Seat",
"description": "Municipality where company is registered"
},
"legal_form": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Legal Form",
"description": "Legal form (e.g., AG, GmbH)"
},
"chid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Chid",
"description": "CH identification number"
},
"ehraid": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Ehraid",
"description": "EHRA ID"
},
"is_deleted": {
"type": "boolean",
"title": "Is Deleted",
"description": "Whether company is soft-deleted"
},
"name_variants": {
"items": {
"$ref": "#/components/schemas/CompanyNameVariant"
},
"type": "array",
"title": "Name Variants",
"description": "All name variants for this company"
}
},
"type": "object",
"required": [
"source_company_id",
"source_system",
"name_display",
"name_norm",
"legal_seat",
"legal_form",
"chid",
"ehraid",
"is_deleted",
"name_variants"
],
"title": "CompanyDetail",
"description": "Detailed company information for lookup endpoint.",
"examples": [
{
"chid": "CHE-101.835.433",
"ehraid": "12345",
"is_deleted": false,
"legal_form": "AG",
"legal_seat": "Zürich",
"name_display": "Müller & Söhne AG",
"name_norm": "mueller soehne",
"name_variants": [
{
"is_primary": true,
"lang": "de",
"name_kind": "legal",
"name_raw": "Müller & Söhne AG"
}
],
"source_company_id": "CHE101835433",
"source_system": "zefix_linda"
}
]
}
Response 401 Unauthorized¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 404 Not Found¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 429 Too Many Requests¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 500 Internal Server Error¶
application/json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "string",
"details": null
}
}
Schema of the response body
{
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Error information"
}
},
"type": "object",
"required": [
"error"
],
"title": "ErrorResponse",
"description": "Wrapper for error responses.",
"examples": [
{
"error": {
"code": "VALIDATION_ERROR",
"details": {
"field": "name",
"nameNorm": "ab"
},
"message": "name is too short after normalization"
}
}
]
}
Response 422 Unprocessable Entity¶
application/json
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
Schemas¶
ApiConsumerCreateRequest¶
| Name | Type |
|---|---|
| contactEmail | |
| description | |
| name | string |
ApiConsumerModel¶
| Name | Type |
|---|---|
| code | string |
| contactEmail | |
| createdAt | string |
| description | |
| id | integer |
| isActive | boolean |
| name | string |
| updatedAt | string |
ApiConsumerUpdateRequest¶
| Name | Type |
|---|---|
| contactEmail | |
| description | |
| isActive | |
| name |
ApiKeyCreateRequest¶
| Name | Type |
|---|---|
| allowNonExpiring | boolean |
| consumerId | integer |
| createdBy | |
| description | |
| displayName | |
| expiresAt |
ApiKeyCreateResponse¶
| Name | Type |
|---|---|
| apiKey | string |
| key | ApiKeyModel |
ApiKeyListResponse¶
| Name | Type |
|---|---|
| items | Array<ApiKeyModel> |
| limit | integer |
| offset | integer |
| total | integer |
ApiKeyModel¶
| Name | Type |
|---|---|
| consumerCode | string |
| consumerId | integer |
| createdAt | string |
| createdBy | |
| description | |
| displayName | |
| expiresAt | |
| id | integer |
| isActive | boolean |
| keyLast4 | string |
| keyPrefix | string |
| lastUsedAt | |
| revokedAt | |
| updatedAt | string |
AssessmentCheckCatalogItemModel¶
| Name | Type |
|---|---|
| checkVersion | string |
| legalBasis | Array<string> |
| parentStepIds | Array<string> |
| possibleOutcomes | Array<string> |
| resultingFlagCode | |
| sequence | integer |
| sourceType | string |
| stage | string |
| stepId | string |
| title | string |
| whatItDoes | string |
AssessmentCheckStepModel¶
| Name | Type |
|---|---|
| applicable | boolean |
| checkVersion | string |
| confidence | |
| inputSnapshot | |
| legalBasis | Array<string> |
| outcome | string |
| outputSnapshot | |
| parentStepIds | Array<string> |
| resultingFlagCode | |
| sequence | integer |
| sourceType | string |
| stage | string |
| stepId | string |
| title | string |
| triggered | boolean |
| whatItDoes | string |
AssessmentDeterministicCheckModel¶
| Name | Type |
|---|---|
| checkId | string |
| evidence | |
| reason | string |
| triggered | boolean |
AssessmentExplanationModel¶
| Name | Type |
|---|---|
| allChecks | Array<AssessmentCheckStepModel> |
| decisionPath | Array<string> |
| deterministicChecks | Array<AssessmentDeterministicCheckModel> |
| finalRationale | string |
| ruleEngineMapping | Array<AssessmentRuleEngineMappingModel> |
| semanticChecks | Array<AssessmentSemanticCheckModel> |
AssessmentFlagModel¶
| Name | Type |
|---|---|
| category | FlagCategory |
| code | string |
| message | string |
| severity | FlagSeverity |
AssessmentRuleEngineMappingModel¶
| Name | Type |
|---|---|
| category | FlagCategory |
| code | string |
| contributesToOverallStatus | boolean |
| profileSeverity | FlagSeverity |
| reason | string |
AssessmentSemanticCheckModel¶
| Name | Type |
|---|---|
| checkId | string |
| evidence | |
| reason | string |
| triggered | boolean |
| value |
AssessmentStatus¶
Type: string
AssessmentSummaryModel¶
| Name | Type |
|---|---|
| clientProfileApplied | RiskProfile |
| companyName | string |
| overallStatus | AssessmentStatus |
AssessmentTraceCompareRequest¶
| Name | Type |
|---|---|
| traceIdA | string |
| traceIdB | string |
AssessmentTraceCompareResponse¶
| Name | Type |
|---|---|
| changedChecks | Array<AssessmentTraceDiffCheckModel> |
| decisiveChecksA | Array<string> |
| decisiveChecksB | Array<string> |
| overallStatusA | |
| overallStatusB | |
| traceIdA | string |
| traceIdB | string |
AssessmentTraceDetailResponse¶
| Name | Type |
|---|---|
| createdAt | string |
| endpoint | string |
| explanation | |
| response | CompanyNameAssessmentResponse |
| statusCode | integer |
| traceId | string |
AssessmentTraceDiffCheckModel¶
| Name | Type |
|---|---|
| outcomeA | string |
| outcomeB | string |
| stepId | string |
| triggeredA | boolean |
| triggeredB | boolean |
AssessmentTraceListItemModel¶
| Name | Type |
|---|---|
| companyName | |
| createdAt | string |
| decisiveChecks | Array<string> |
| durationMs | |
| overallStatus | |
| riskProfile | |
| statusCode | integer |
| traceId | string |
| triggeredCount | integer |
AssessmentTraceListResponse¶
| Name | Type |
|---|---|
| items | Array<AssessmentTraceListItemModel> |
| limit | integer |
| offset | integer |
| total | integer |
CompanyDetail¶
| Name | Type |
|---|---|
| chid | |
| ehraid | |
| is_deleted | boolean |
| legal_form | |
| legal_seat | |
| name_display | string |
| name_norm | string |
| name_variants | Array<CompanyNameVariant> |
| source_company_id | string |
| source_system | string |
CompanyNameAssessmentRequest¶
| Name | Type |
|---|---|
| activityScope | |
| checkLevel | ComplianceCheckLevel |
| companyName | string |
| language | Language |
| languageVariants | Array<LanguageVariantV3Model> |
| legalForm | SupportedLegalForm |
| legalSeat | |
| ownerSurname | |
| riskProfile | RiskProfile |
CompanyNameAssessmentResponse¶
| Name | Type |
|---|---|
| assessment | AssessmentSummaryModel |
| flags | Array<AssessmentFlagModel> |
| metadata | |
| semanticContext |
CompanyNameVariant¶
| Name | Type |
|---|---|
| is_primary | boolean |
| lang | string |
| name_kind | string |
| name_raw | string |
ComplianceAnalysisInputEcho¶
| Name | Type |
|---|---|
| activityScope | |
| companyName | string |
| language | Language |
| legalForm | SupportedLegalForm |
| ownerFullName |
ComplianceAnalysisInputEchoV2¶
| Name | Type |
|---|---|
| activityScope | |
| companyName | string |
| language | Language |
| legalForm | SupportedLegalForm |
| legalSeat | |
| ownerSurname |
ComplianceAnalysisInputEchoV3¶
| Name | Type |
|---|---|
| activityScope | |
| companyName | string |
| language | Language |
| languageVariants | Array<LanguageVariantV3Model> |
| legalForm | SupportedLegalForm |
| legalSeat | |
| ownerSurname |
ComplianceAnalysisRequest¶
| Name | Type |
|---|---|
| activityScope | |
| checkLevel | ComplianceCheckLevel |
| companyName | string |
| language | Language |
| legalForm | SupportedLegalForm |
| ownerFullName |
ComplianceAnalysisResponse¶
| Name | Type |
|---|---|
| input | ComplianceAnalysisInputEcho |
| issues | Array<ValidationIssueModel> |
| metadata | |
| overallStatus | ComplianceOverallStatus |
| registrableNames |
ComplianceAnalysisV2Request¶
| Name | Type |
|---|---|
| activityScope | |
| checkLevel | ComplianceCheckLevel |
| companyName | string |
| language | Language |
| legalForm | SupportedLegalForm |
| legalSeat | |
| ownerSurname |
ComplianceAnalysisV2Response¶
| Name | Type |
|---|---|
| input | ComplianceAnalysisInputEchoV2 |
| issues | Array<ValidationIssueModel> |
| metadata | |
| overallStatus | ComplianceOverallStatus |
| registrableNames | |
| semanticEvaluation |
ComplianceAnalysisV3Request¶
| Name | Type |
|---|---|
| activityScope | |
| checkLevel | ComplianceCheckLevel |
| companyName | string |
| language | Language |
| languageVariants | Array<LanguageVariantV3Model> |
| legalForm | SupportedLegalForm |
| legalSeat | |
| ownerSurname |
ComplianceAnalysisV3Response¶
| Name | Type |
|---|---|
| findings | Array<ValidationIssueModel> |
| input | ComplianceAnalysisInputEchoV3 |
| metadata | |
| registrableNames | |
| semanticEvaluation |
ComplianceCheckLevel¶
Type: string
ComplianceOverallStatus¶
Type: string
DomainAvailabilityInputEcho¶
| Name | Type |
|---|---|
| name | string |
| nameNorm | string |
| tlds | Array<string> |
DomainAvailabilityRequest¶
| Name | Type |
|---|---|
| name | string |
| tlds | Array<string> |
DomainAvailabilityResponse¶
| Name | Type |
|---|---|
| input | DomainAvailabilityInputEcho |
| results | Array<DomainAvailabilityResultResponse> |
| summary | DomainAvailabilitySummaryResponse |
DomainAvailabilityResultResponse¶
| Name | Type |
|---|---|
| available | |
| checkedAt | string |
| fqdn | string |
| reason | string |
| source | string |
| status | DomainAvailabilityStatus |
| tld | string |
DomainAvailabilityStatus¶
Type: string
DomainAvailabilitySummaryResponse¶
| Name | Type |
|---|---|
| likelyAvailableCount | integer |
| registeredCount | integer |
| unknownCount | integer |
ErrorCode¶
Type: string
ErrorDetail¶
| Name | Type |
|---|---|
| code | ErrorCode |
| details | |
| message | string |
ErrorResponse¶
| Name | Type |
|---|---|
| error | ErrorDetail |
FlagCategory¶
Type: string
FlagSeverity¶
Type: string
HealthResponse¶
| Name | Type |
|---|---|
| status | string |
HTTPValidationError¶
| Name | Type |
|---|---|
| detail | Array<ValidationError> |
IdentityMatchResponse¶
| Name | Type |
|---|---|
| legalSeat | |
| nameDisplay | string |
| nameNorm | string |
| sourceCompanyId | string |
IngestionRunInfo¶
| Name | Type |
|---|---|
| finished_at | |
| id | integer |
| mode | string |
| rows_failed | integer |
| rows_upserted | integer |
| started_at | string |
Language¶
Type: string
LanguageVariantV3Model¶
| Name | Type |
|---|---|
| lang | Language |
| name | string |
RegistrableNamesModel¶
| Name | Type |
|---|---|
| de | string |
| en | string |
| fr | string |
| it | string |
RestrictedTermCategoryModel¶
| Name | Type |
|---|---|
| code | string |
| defaultSeverity | string |
| description | |
| id | integer |
| isActive | boolean |
| matchMode | string |
| name | string |
| ruleRef | |
| sectionNumber | |
| sectionTitle |
RestrictedTermCreateRequest¶
| Name | Type |
|---|---|
| categoryCode | string |
| createdBy | |
| description | |
| languageCode | |
| matchModeOverride | |
| severityOverride | |
| term | string |
RestrictedTermListResponse¶
| Name | Type |
|---|---|
| items | Array<RestrictedTermModel> |
| limit | integer |
| offset | integer |
| total | integer |
RestrictedTermModel¶
| Name | Type |
|---|---|
| categoryCode | string |
| categoryId | integer |
| createdAt | string |
| createdBy | |
| description | |
| id | integer |
| isActive | boolean |
| languageCode | |
| matchModeOverride | |
| severityOverride | |
| source | string |
| term | string |
| updatedAt | string |
RestrictedTermUpdateRequest¶
| Name | Type |
|---|---|
| categoryCode | |
| description | |
| isActive | |
| languageCode | |
| matchModeOverride | |
| severityOverride | |
| term |
RiskLevelParam¶
Type: string
RiskProfile¶
Type: string
SearchConsumerMetricsModel¶
| Name | Type |
|---|---|
| avgDurationMs | |
| consumerCode | |
| consumerId | |
| consumerName | |
| errorRequests | integer |
| latestRequestAt | |
| p95DurationMs | |
| successRequests | integer |
| totalRequests | integer |
SearchConsumerMetricsResponse¶
| Name | Type |
|---|---|
| items | Array<SearchConsumerMetricsModel> |
SearchEventListResponse¶
| Name | Type |
|---|---|
| items | Array<SearchEventLogModel> |
| limit | integer |
| offset | integer |
| total | integer |
SearchEventLogModel¶
| Name | Type |
|---|---|
| clientIp | |
| consumerCode | |
| consumerId | |
| consumerName | |
| createdAt | string |
| durationMs | |
| endpoint | string |
| id | integer |
| params | |
| resultSummary | |
| searchTerm | string |
| statusCode | integer |
| traceId | |
| userAgent |
SearchInputEcho¶
| Name | Type |
|---|---|
| name | string |
| nameCore | string |
| nameNorm | string |
| phoneticAlt | string |
| phoneticPrimary | string |
SearchMetricsOverviewResponse¶
| Name | Type |
|---|---|
| avgDurationMs | |
| errorRequests | integer |
| p95DurationMs | |
| periodEnd | |
| periodStart | |
| successRequests | integer |
| totalRequests | integer |
| uniqueConsumers | integer |
| uniqueSearchTerms | integer |
SearchRequest¶
| Name | Type |
|---|---|
| limit | integer |
| minRisk | RiskLevelParam |
| name | string |
SearchResponse¶
| Name | Type |
|---|---|
| identityMatch | |
| input | SearchInputEcho |
| registrable | boolean |
| similarMatches | Array<SimilarMatchResponse> |
SearchTopTermModel¶
| Name | Type |
|---|---|
| avgDurationMs | |
| requestCount | integer |
| searchTerm | string |
| uniqueConsumers | integer |
SearchTopTermsResponse¶
| Name | Type |
|---|---|
| items | Array<SearchTopTermModel> |
SearchTraceDetailResponse¶
| Name | Type |
|---|---|
| event | SearchEventLogModel |
| traceId | string |
SemanticContextModel¶
| Name | Type |
|---|---|
| containsGeographicTerm | |
| extractedGeographicTerms | Array<string> |
| gamblingTermsDetected | Array<string> |
| hasFantasyElement | |
| healthClaimsDetected | Array<string> |
| impliedActivities | Array<string> |
| impliedGamblingActivity | |
| impliedHealthcareActivity | |
| impliedInvestmentOrBankingActivity | |
| isGeographicFantasy | |
| isNatureGeographicTerm | |
| isPurelyDescriptive | |
| multipleLanguagesPresent | |
| protectedOrgReferenceLikely | |
| translatedUntranslatableElements | |
| translationsSemanticallyMatch |
SemanticRegistrationEvaluationV2Model¶
| Name | Type |
|---|---|
| canBeRegistered | boolean |
| primaryRejectionReason | |
| requiresLegalReview | boolean |
| ruleGeographicFantasy | SemanticRuleEvaluationV2Model |
| rulePurelyDescriptive | SemanticRuleEvaluationV2Model |
| rulePurposeDeception | SemanticRuleEvaluationV2Model |
| ruleRegulatedTermsLicensing | SemanticRuleEvaluationV2Model |
SemanticRuleEvaluationV2Model¶
| Name | Type |
|---|---|
| analysis | string |
| confidence | string |
| isViolation | boolean |
SimilarMatchResponse¶
| Name | Type |
|---|---|
| legalSeat | |
| nameDisplay | string |
| nameNorm | string |
| phoneticMatch | boolean |
| risk | RiskLevelParam |
| sourceCompanyId | string |
| visualScore | number |
StatsResponse¶
| Name | Type |
|---|---|
| active_companies | integer |
| deleted_companies | integer |
| last_ingestion | |
| total_companies | integer |
| total_company_names | integer |
SupportedLegalForm¶
Type: string
TrademarkSearchInputEcho¶
| Name | Type |
|---|---|
| niceClasses | Array<integer> |
| phoneticAlt | string |
| phoneticPrimary | string |
| query | string |
| queryCore | string |
| queryNorm | string |
TrademarkSearchRequest¶
| Name | Type |
|---|---|
| limit | integer |
| minRisk | RiskLevelParam |
| niceClasses | |
| query | string |
TrademarkSearchResponse¶
| Name | Type |
|---|---|
| goodsServicesBasis | string |
| input | TrademarkSearchInputEcho |
| similarMatches | Array<TrademarkSimilarMatchResponse> |
TrademarkSimilarMatchResponse¶
| Name | Type |
|---|---|
| applicationNumberText | |
| classOverlap | Array<integer> |
| markText | |
| markTextNorm | string |
| matchBasis | Array<string> |
| niceClasses | Array<integer> |
| phoneticMatch | boolean |
| registrationNumber | |
| relatedClassOverlap | Array<integer> |
| risk | RiskLevelParam |
| sourceRecordId | string |
| status | |
| visualScore | number |
ValidationError¶
| Name | Type |
|---|---|
| loc | Array<> |
| msg | string |
| type | string |
ValidationIssueModel¶
| Name | Type |
|---|---|
| code | string |
| message | string |
| ruleRef | |
| severity | ValidationSeverity |
| source | string |
ValidationSeverity¶
Type: string
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| ClientApiKeyAuth | apiKey | Client API key for public endpoints. | |
| AdminApiKeyAuth | apiKey | Admin API key for /v1/admin/* endpoints. |