> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aventure.vc/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aventure.vc/_mcp/server.

# Suggest entity classifications

GET https://api.aventure.vc/v1/entities/{entityId}/classifications/suggestions

Default classification discovery path for enrichment agents. Returns ranked embedding-derived tag and standardized-code suggestions; empty array means no embedding neighbors. Create joins with the entity classifications create endpoint. A signed-in user is admitted for public entities; callers with private-visibility authority (admin key or ROLE_ADMIN) also resolve hidden/private entities, and includePrivate=true requires that authority, otherwise hidden/private entities 404.

Reference: https://docs.aventure.vc/api-reference/entity-classifications/suggest-entity-classifications

## Authentication

- `Authorization` header (bearer token, required) — User bearer token: Clerk session JWT, Clerk OAuth access token, or Clerk personal API key
- `X-API-Key` header (required) — Admin API key for system-to-system write operations
- `X-Client-Secret` header (required) — Client secret for read-only service-to-service access (no writes)

## Request

### Path parameters

- `entityId` (string, required) — Canonical entity UUID

### Query parameters

- `limit` (integer, optional) — Maximum suggestions to return; default 12, maximum 50.
- `includePrivate` (boolean, optional) — Include private/hidden entity suggestions when the caller has private-visibility authority (admin key or ROLE_ADMIN). Without that authority hidden/private entities 404.

## Response

### 200

OK

- `list of object`
  - `alreadyJoined` (boolean, required) — True when the entity already has a current or historical matching join.
  - `classification` (object or object, required) — Suggested writable editorial tag or standardized classification code candidate.
    - EntityTag
      - `creatable` (boolean, required)
      - `name` (string, required) — Display name. Capped to the standardized taxonomy storage limit because this shared read contract covers NAICS/SIC/ISIC-style classification labels as well as editorial tags.
      - `writable` (boolean, required)
      - `creatable` (boolean, required) — Whether this bucket permits creating missing values by type plus name.
      - `id` (integer, required) — Classification tag registry id from res_type_ref; use as EntityClassificationMutation.tagId.
      - `name` (string, required) — Name
      - `type` (string, required) — Canonical tag classification type
      - `writable` (boolean, required) — Whether this existing tag can be joined through tagId.
      - `isCurrent` (boolean, optional, nullable)
      - `isPrimary` (boolean, optional, nullable)
      - `bucket` (string, optional, nullable) — Canonical entity-classification bucket key. Use this as EntityClassificationMutation.type when creating by type plus name; `type` remains the registry wire value for tag search and catalog round-trips.
      - `classificationId` (integer, optional, nullable) — Entity classification join row id for update/delete; present on entity classification responses and null on discovery responses.
      - `createdAt` (datetime, optional, nullable) — Registry tag creation timestamp, not the entity join timestamp.
      - `isCurrent` (boolean, optional, nullable) — Current-state flag for this context: registry active flag in discovery, entity join current flag in entity-classification responses.
      - `isPrimary` (boolean, optional, nullable) — Entity join primary flag within its bucket; null on catalog/tag discovery.
      - `slug` (string, optional, nullable) — Slug
      - `updatedAt` (datetime, optional, nullable) — Registry tag update timestamp; join updates return isCurrent/isPrimary but no join updatedAt.
    - StandardizedClassification
      - `creatable` (boolean, required)
      - `name` (string, required) — Display name. Capped to the standardized taxonomy storage limit because this shared read contract covers NAICS/SIC/ISIC-style classification labels as well as editorial tags.
      - `writable` (boolean, required)
      - `category` (string, required) — Standardized category token.
      - `creatable` (boolean, required) — Standardized taxonomy rows are join-existing-only.
      - `id` (integer, required) — Standardized classification registry id from res_classification_ref; use as EntityClassificationMutation.classificationId.
      - `name` (string, required) — Name
      - `writable` (boolean, required) — Existing standardized rows can be joined through classificationId.
      - `isCurrent` (boolean, optional, nullable)
      - `isPrimary` (boolean, optional, nullable)
      - `code` (integer, optional, nullable) — Standardized classification code when present.
      - `createdAt` (datetime, optional, nullable) — Registry row creation timestamp.
      - `entityClassificationId` (integer, optional, nullable) — Entity classification join row id for update/delete; present on entity classification responses and null on discovery responses.
      - `isCurrent` (boolean, optional, nullable) — Standardized reference rows are current by definition.
      - `isPrimary` (boolean, optional, nullable) — Entity join primary flag within this standardized category.
      - `level` (integer, optional, nullable) — Hierarchy level when present.
      - `updatedAt` (datetime, optional, nullable) — Registry row update timestamp.
  - `creatable` (boolean, required) — Whether a missing editorial tag value may be created with type plus name instead of tagId.
  - `rank` (integer, required) — One-based rank within this suggestion response.
  - `score` (double, required) — Composite embedding similarity score; larger values rank higher.
  - `writable` (boolean, required) — Whether this suggestion can be joined through the classification mutation endpoint.

## Errors

### 400 Bad Request Error

Bad Request

- `circuitBreaker` (string, optional, nullable)
- `code` (enum, optional) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes indicate infra/admin-only conditions where the correct agent action is to surface the error and stop, not retry.
  - Allowed values: `not_authorized`, `rateLimited`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `JOBRUNR_STORAGE_UNAVAILABLE`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `sentry_api_error`, `swagger_headers_unconfigured`, `frontend_cache_epoch_mode_not_targeted`, `image_blocklist_match`, `image_monochrome`, `image_too_small`, `image_wrong_aspect`, `image_monogram`, `image_unreadable`, `image_processing_error`, `image_brand_mismatch`, `web_crawl_fetch_failed`, `news_rss_feed_fetch_failed`, `news_rss_article_fetch_failed`, `r2_fetch_failed`, `r2_delete_failed`, `r2_upload_failed`, `source_document_body_unavailable`, `source_document_capture_limit_exceeded`, `news_similarity_embedding_unavailable`, `search_provider_not_configured`, `search_provider_error`, `sec_edgar_fetch_failed`, `github_fetch_failed`, `INFERENCE_PROVIDER_ERROR`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `INFERENCE_PROVIDER_INVALID_JSON`, `INFERENCE_PROFILES_MISSING`, `INFERENCE_PROFILE_API_KEY_MISSING`
- `conflictingRecord` (object, optional, nullable) — Current slug owner
  - `id` (string, required)
  - `isHidden` (boolean, required)
  - `resourceType` (enum, required) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
  - `showOnSitemap` (boolean, required)
  - `slug` (string, required)
  - `deletedAt` (datetime, optional, nullable)
  - `nameBrand` (string, optional, nullable)
- `detail` (string, optional)
- `details` (object or object or object or object or object, optional, nullable) — Structured conflict details. Create duplicate reviews and deterministic lookup ambiguity return DuplicateCreateReview; the returned candidates are the decision surface for update, create-with-override, or block. score/threshold rank review priority and are not proof that the requested record is absent.
  - UrlDuplicateConflict
    - `existingJoin` (list of object, required) — Every current owner that already holds the normalized URL with this urlType. Non-empty when this conflict is emitted.
      - `owner` (object, required) — Owner of the URL: either entityId or personId is populated depending on the owner kind. Use the populated id to read or update the owner's URL.
        - `entityId` (string, optional, nullable) — Canonical entity UUID
        - `personId` (string, optional, nullable) — Canonical person UUID
      - `urlId` (integer, required) — Internal URL row id (res_weburl.id) — opaque to API clients.
    - `fragmentIgnored` (boolean, required) — True when URL fragment differences were ignored during duplicate matching (i.e., the conflict ignores everything after '#').
    - `guidance` (string, required) — Human-readable guidance on how to resolve the conflict. Defaults to the standard inspect-then-demote/promote sequence.
    - `requestedOwner` (object, required) — Owner the caller attempted to attach the URL to.
      - `entityId` (string, optional, nullable) — Canonical entity UUID
      - `personId` (string, optional, nullable) — Canonical person UUID
    - `url` (string, required) — Raw URL as submitted by the caller (pre-normalization).
    - `urlType` (string, required) — URL type submitted by the caller (e.g., 'website', 'twitter'). The conflict applies only within this urlType.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key used for duplicate detection. Null when normalization could not produce a stable key (e.g., malformed input).
  - StrictUrlLookupConflict
    - `candidateEntityId` (list of string, required) — Every entity id that currently owns the normalized URL. May be empty when the conflict is between persons; combined with candidatePersonId always > 1.
    - `candidatePersonId` (list of string, required) — Every person id that currently owns the normalized URL. May be empty when the conflict is between entities; combined with candidateEntityId always > 1.
    - `hint` (string, required) — Human-readable hint describing which disambiguating query parameters to add.
    - `url` (string, required) — Raw URL the caller queried.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key the lookup resolved against. Null when normalization could not produce a stable key.
    - `urlType` (string, optional, nullable) — URL type the caller specified, or null if the lookup did not constrain by urlType.
  - DuplicateCreateReview
    - `threshold` (integer, required) — Review threshold used by duplicate scoring. Scores below this value can still be useful candidate context; this value does not prove absence or authorize create.
    - `candidate` (list of object, optional, nullable) — Entity/person candidates returned by lookup or create duplicate review. If a candidate is the requested record, read/update that candidate by id. Create with duplicate override only after every candidate is reviewed as distinct.
      - `id` (string, required) — Candidate id to read or update when this candidate is the requested record.
      - `reason` (list of string, required) — Match reasons such as name-exact, slug-exact, url-match, url-type, or precomputed-similarity. url-match proves the supplied URL/domain matched; url-type only means the candidate has the same URL category and is review context, not URL identity evidence.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended record when reason/name/slug/typeRecord match.
      - `externalId` (string, optional, nullable) — Matched external identifier when duplicate scoring used one.
      - `name` (string, optional, nullable) — Candidate display name from the existing record.
      - `operatingStatus` (string, optional, nullable) — Current operating status for entity candidates.
      - `publicPath` (string, optional, nullable) — Public API/UI path for the candidate when available.
      - `slug` (string, optional, nullable) — Candidate slug from the existing record.
      - `typeRecord` (enum, optional, nullable) — Candidate entity type from the existing record.
        - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`
    - `newsCandidate` (list of object, optional, nullable) — News candidates returned by lookup or create duplicate review. If a candidate is the requested article, read/update that article by id. Otherwise block until source evidence proves a distinct article.
      - `id` (integer, required) — News article id to read or update when this candidate is the requested article.
      - `reason` (list of string, required) — Match reasons for reviewing the candidate. Exact reasons are decision signals regardless of whether score crosses the review threshold.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended article when reason/slug/externalId match.
      - `externalId` (string, optional, nullable) — Matched external article identifier when duplicate scoring used one.
      - `slug` (string, optional, nullable) — Candidate article slug from the existing record.
    - `overridePath` (string, optional, nullable) — Create endpoint to retry only after reviewing the returned candidates and supplying overrideGate=duplicate and overrideReason as query parameters. Null for detail lookup ambiguity, where the next action is review/update/block.
  - ClassificationInactiveTagDetails
    - `availableOverrides` (list of enum, required) — Allowed inactiveTagOverride values for this conflict
      - Allowed values: `REACTIVATE`, `ATTACH_INACTIVE`
    - `slug` (string, required) — Existing dormant value slug or lookup key
    - `tagId` (integer, required) — Existing tag id in res_type_ref
  - NewsSourceUrlConflict
    - `conflictingArticleId` (integer, required) — Existing article id (NewsId.value) that already owns this publication + URL pair.
    - `conflictingArticleSlug` (string, required) — Existing article slug, or empty string when the existing article has no slug. Use with GET /v1/news/detail?slug= to fetch the conflicting article.
    - `conflictingArticleTitle` (string, required) — Existing article title for human-readable diagnostics.
- `error` (map from string to string, optional, nullable)
- `existingRedirect` (object, optional, nullable) — Redirect slug path
  - `oldUrl` (string, required)
  - `newUrl` (string, optional, nullable)
  - `targetCurrentSlug` (string, optional, nullable)
  - `targetId` (string, optional, nullable)
  - `targetResourceType` (enum, optional, nullable) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable)
- `limitType` (enum, optional)
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `CLERK_PUBLIC_ADMISSION`, `CLERK_SCRIPT_LOAD`, `ORIGIN_DETAIL`, `INFERENCE_PROVIDER`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `remaining` (long, optional, nullable)
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable)
- `resolution` (object, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
  - `action` (enum, required) — Next action category for the client or agent.
    - Allowed values: `setField`, `setParameter`, `removeParameter`, `useEndpoint`, `reviewCandidates`, `authenticate`
  - `acceptedValue` (list of string, optional, nullable) — Accepted values for the field or parameter, when enumerable.
  - `endpoint` (string, optional, nullable) — Endpoint to call for the next action, when applicable.
  - `fieldPath` (string, optional, nullable) — Request-body field path that needs attention, when applicable.
  - `parameter` (string, optional, nullable) — Query parameter that needs attention, when applicable.
  - `retryable` (boolean, optional, nullable) — Whether the same logical request can be retried after the next action.
- `retryAfterSeconds` (long, optional, nullable)
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable)
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable)

### 401 Unauthorized Error

Unauthorized

- `circuitBreaker` (string, optional, nullable)
- `code` (enum, optional) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes indicate infra/admin-only conditions where the correct agent action is to surface the error and stop, not retry.
  - Allowed values: `not_authorized`, `rateLimited`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `JOBRUNR_STORAGE_UNAVAILABLE`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `sentry_api_error`, `swagger_headers_unconfigured`, `frontend_cache_epoch_mode_not_targeted`, `image_blocklist_match`, `image_monochrome`, `image_too_small`, `image_wrong_aspect`, `image_monogram`, `image_unreadable`, `image_processing_error`, `image_brand_mismatch`, `web_crawl_fetch_failed`, `news_rss_feed_fetch_failed`, `news_rss_article_fetch_failed`, `r2_fetch_failed`, `r2_delete_failed`, `r2_upload_failed`, `source_document_body_unavailable`, `source_document_capture_limit_exceeded`, `news_similarity_embedding_unavailable`, `search_provider_not_configured`, `search_provider_error`, `sec_edgar_fetch_failed`, `github_fetch_failed`, `INFERENCE_PROVIDER_ERROR`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `INFERENCE_PROVIDER_INVALID_JSON`, `INFERENCE_PROFILES_MISSING`, `INFERENCE_PROFILE_API_KEY_MISSING`
- `conflictingRecord` (object, optional, nullable) — Current slug owner
  - `id` (string, required)
  - `isHidden` (boolean, required)
  - `resourceType` (enum, required) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
  - `showOnSitemap` (boolean, required)
  - `slug` (string, required)
  - `deletedAt` (datetime, optional, nullable)
  - `nameBrand` (string, optional, nullable)
- `detail` (string, optional)
- `details` (object or object or object or object or object, optional, nullable) — Structured conflict details. Create duplicate reviews and deterministic lookup ambiguity return DuplicateCreateReview; the returned candidates are the decision surface for update, create-with-override, or block. score/threshold rank review priority and are not proof that the requested record is absent.
  - UrlDuplicateConflict
    - `existingJoin` (list of object, required) — Every current owner that already holds the normalized URL with this urlType. Non-empty when this conflict is emitted.
      - `owner` (object, required) — Owner of the URL: either entityId or personId is populated depending on the owner kind. Use the populated id to read or update the owner's URL.
        - `entityId` (string, optional, nullable) — Canonical entity UUID
        - `personId` (string, optional, nullable) — Canonical person UUID
      - `urlId` (integer, required) — Internal URL row id (res_weburl.id) — opaque to API clients.
    - `fragmentIgnored` (boolean, required) — True when URL fragment differences were ignored during duplicate matching (i.e., the conflict ignores everything after '#').
    - `guidance` (string, required) — Human-readable guidance on how to resolve the conflict. Defaults to the standard inspect-then-demote/promote sequence.
    - `requestedOwner` (object, required) — Owner the caller attempted to attach the URL to.
      - `entityId` (string, optional, nullable) — Canonical entity UUID
      - `personId` (string, optional, nullable) — Canonical person UUID
    - `url` (string, required) — Raw URL as submitted by the caller (pre-normalization).
    - `urlType` (string, required) — URL type submitted by the caller (e.g., 'website', 'twitter'). The conflict applies only within this urlType.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key used for duplicate detection. Null when normalization could not produce a stable key (e.g., malformed input).
  - StrictUrlLookupConflict
    - `candidateEntityId` (list of string, required) — Every entity id that currently owns the normalized URL. May be empty when the conflict is between persons; combined with candidatePersonId always > 1.
    - `candidatePersonId` (list of string, required) — Every person id that currently owns the normalized URL. May be empty when the conflict is between entities; combined with candidateEntityId always > 1.
    - `hint` (string, required) — Human-readable hint describing which disambiguating query parameters to add.
    - `url` (string, required) — Raw URL the caller queried.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key the lookup resolved against. Null when normalization could not produce a stable key.
    - `urlType` (string, optional, nullable) — URL type the caller specified, or null if the lookup did not constrain by urlType.
  - DuplicateCreateReview
    - `threshold` (integer, required) — Review threshold used by duplicate scoring. Scores below this value can still be useful candidate context; this value does not prove absence or authorize create.
    - `candidate` (list of object, optional, nullable) — Entity/person candidates returned by lookup or create duplicate review. If a candidate is the requested record, read/update that candidate by id. Create with duplicate override only after every candidate is reviewed as distinct.
      - `id` (string, required) — Candidate id to read or update when this candidate is the requested record.
      - `reason` (list of string, required) — Match reasons such as name-exact, slug-exact, url-match, url-type, or precomputed-similarity. url-match proves the supplied URL/domain matched; url-type only means the candidate has the same URL category and is review context, not URL identity evidence.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended record when reason/name/slug/typeRecord match.
      - `externalId` (string, optional, nullable) — Matched external identifier when duplicate scoring used one.
      - `name` (string, optional, nullable) — Candidate display name from the existing record.
      - `operatingStatus` (string, optional, nullable) — Current operating status for entity candidates.
      - `publicPath` (string, optional, nullable) — Public API/UI path for the candidate when available.
      - `slug` (string, optional, nullable) — Candidate slug from the existing record.
      - `typeRecord` (enum, optional, nullable) — Candidate entity type from the existing record.
        - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`
    - `newsCandidate` (list of object, optional, nullable) — News candidates returned by lookup or create duplicate review. If a candidate is the requested article, read/update that article by id. Otherwise block until source evidence proves a distinct article.
      - `id` (integer, required) — News article id to read or update when this candidate is the requested article.
      - `reason` (list of string, required) — Match reasons for reviewing the candidate. Exact reasons are decision signals regardless of whether score crosses the review threshold.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended article when reason/slug/externalId match.
      - `externalId` (string, optional, nullable) — Matched external article identifier when duplicate scoring used one.
      - `slug` (string, optional, nullable) — Candidate article slug from the existing record.
    - `overridePath` (string, optional, nullable) — Create endpoint to retry only after reviewing the returned candidates and supplying overrideGate=duplicate and overrideReason as query parameters. Null for detail lookup ambiguity, where the next action is review/update/block.
  - ClassificationInactiveTagDetails
    - `availableOverrides` (list of enum, required) — Allowed inactiveTagOverride values for this conflict
      - Allowed values: `REACTIVATE`, `ATTACH_INACTIVE`
    - `slug` (string, required) — Existing dormant value slug or lookup key
    - `tagId` (integer, required) — Existing tag id in res_type_ref
  - NewsSourceUrlConflict
    - `conflictingArticleId` (integer, required) — Existing article id (NewsId.value) that already owns this publication + URL pair.
    - `conflictingArticleSlug` (string, required) — Existing article slug, or empty string when the existing article has no slug. Use with GET /v1/news/detail?slug= to fetch the conflicting article.
    - `conflictingArticleTitle` (string, required) — Existing article title for human-readable diagnostics.
- `error` (map from string to string, optional, nullable)
- `existingRedirect` (object, optional, nullable) — Redirect slug path
  - `oldUrl` (string, required)
  - `newUrl` (string, optional, nullable)
  - `targetCurrentSlug` (string, optional, nullable)
  - `targetId` (string, optional, nullable)
  - `targetResourceType` (enum, optional, nullable) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable)
- `limitType` (enum, optional)
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `CLERK_PUBLIC_ADMISSION`, `CLERK_SCRIPT_LOAD`, `ORIGIN_DETAIL`, `INFERENCE_PROVIDER`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `remaining` (long, optional, nullable)
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable)
- `resolution` (object, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
  - `action` (enum, required) — Next action category for the client or agent.
    - Allowed values: `setField`, `setParameter`, `removeParameter`, `useEndpoint`, `reviewCandidates`, `authenticate`
  - `acceptedValue` (list of string, optional, nullable) — Accepted values for the field or parameter, when enumerable.
  - `endpoint` (string, optional, nullable) — Endpoint to call for the next action, when applicable.
  - `fieldPath` (string, optional, nullable) — Request-body field path that needs attention, when applicable.
  - `parameter` (string, optional, nullable) — Query parameter that needs attention, when applicable.
  - `retryable` (boolean, optional, nullable) — Whether the same logical request can be retried after the next action.
- `retryAfterSeconds` (long, optional, nullable)
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable)
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable)

### 403 Forbidden Error

Forbidden

- `circuitBreaker` (string, optional, nullable)
- `code` (enum, optional) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes indicate infra/admin-only conditions where the correct agent action is to surface the error and stop, not retry.
  - Allowed values: `not_authorized`, `rateLimited`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `JOBRUNR_STORAGE_UNAVAILABLE`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `sentry_api_error`, `swagger_headers_unconfigured`, `frontend_cache_epoch_mode_not_targeted`, `image_blocklist_match`, `image_monochrome`, `image_too_small`, `image_wrong_aspect`, `image_monogram`, `image_unreadable`, `image_processing_error`, `image_brand_mismatch`, `web_crawl_fetch_failed`, `news_rss_feed_fetch_failed`, `news_rss_article_fetch_failed`, `r2_fetch_failed`, `r2_delete_failed`, `r2_upload_failed`, `source_document_body_unavailable`, `source_document_capture_limit_exceeded`, `news_similarity_embedding_unavailable`, `search_provider_not_configured`, `search_provider_error`, `sec_edgar_fetch_failed`, `github_fetch_failed`, `INFERENCE_PROVIDER_ERROR`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `INFERENCE_PROVIDER_INVALID_JSON`, `INFERENCE_PROFILES_MISSING`, `INFERENCE_PROFILE_API_KEY_MISSING`
- `conflictingRecord` (object, optional, nullable) — Current slug owner
  - `id` (string, required)
  - `isHidden` (boolean, required)
  - `resourceType` (enum, required) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
  - `showOnSitemap` (boolean, required)
  - `slug` (string, required)
  - `deletedAt` (datetime, optional, nullable)
  - `nameBrand` (string, optional, nullable)
- `detail` (string, optional)
- `details` (object or object or object or object or object, optional, nullable) — Structured conflict details. Create duplicate reviews and deterministic lookup ambiguity return DuplicateCreateReview; the returned candidates are the decision surface for update, create-with-override, or block. score/threshold rank review priority and are not proof that the requested record is absent.
  - UrlDuplicateConflict
    - `existingJoin` (list of object, required) — Every current owner that already holds the normalized URL with this urlType. Non-empty when this conflict is emitted.
      - `owner` (object, required) — Owner of the URL: either entityId or personId is populated depending on the owner kind. Use the populated id to read or update the owner's URL.
        - `entityId` (string, optional, nullable) — Canonical entity UUID
        - `personId` (string, optional, nullable) — Canonical person UUID
      - `urlId` (integer, required) — Internal URL row id (res_weburl.id) — opaque to API clients.
    - `fragmentIgnored` (boolean, required) — True when URL fragment differences were ignored during duplicate matching (i.e., the conflict ignores everything after '#').
    - `guidance` (string, required) — Human-readable guidance on how to resolve the conflict. Defaults to the standard inspect-then-demote/promote sequence.
    - `requestedOwner` (object, required) — Owner the caller attempted to attach the URL to.
      - `entityId` (string, optional, nullable) — Canonical entity UUID
      - `personId` (string, optional, nullable) — Canonical person UUID
    - `url` (string, required) — Raw URL as submitted by the caller (pre-normalization).
    - `urlType` (string, required) — URL type submitted by the caller (e.g., 'website', 'twitter'). The conflict applies only within this urlType.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key used for duplicate detection. Null when normalization could not produce a stable key (e.g., malformed input).
  - StrictUrlLookupConflict
    - `candidateEntityId` (list of string, required) — Every entity id that currently owns the normalized URL. May be empty when the conflict is between persons; combined with candidatePersonId always > 1.
    - `candidatePersonId` (list of string, required) — Every person id that currently owns the normalized URL. May be empty when the conflict is between entities; combined with candidateEntityId always > 1.
    - `hint` (string, required) — Human-readable hint describing which disambiguating query parameters to add.
    - `url` (string, required) — Raw URL the caller queried.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key the lookup resolved against. Null when normalization could not produce a stable key.
    - `urlType` (string, optional, nullable) — URL type the caller specified, or null if the lookup did not constrain by urlType.
  - DuplicateCreateReview
    - `threshold` (integer, required) — Review threshold used by duplicate scoring. Scores below this value can still be useful candidate context; this value does not prove absence or authorize create.
    - `candidate` (list of object, optional, nullable) — Entity/person candidates returned by lookup or create duplicate review. If a candidate is the requested record, read/update that candidate by id. Create with duplicate override only after every candidate is reviewed as distinct.
      - `id` (string, required) — Candidate id to read or update when this candidate is the requested record.
      - `reason` (list of string, required) — Match reasons such as name-exact, slug-exact, url-match, url-type, or precomputed-similarity. url-match proves the supplied URL/domain matched; url-type only means the candidate has the same URL category and is review context, not URL identity evidence.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended record when reason/name/slug/typeRecord match.
      - `externalId` (string, optional, nullable) — Matched external identifier when duplicate scoring used one.
      - `name` (string, optional, nullable) — Candidate display name from the existing record.
      - `operatingStatus` (string, optional, nullable) — Current operating status for entity candidates.
      - `publicPath` (string, optional, nullable) — Public API/UI path for the candidate when available.
      - `slug` (string, optional, nullable) — Candidate slug from the existing record.
      - `typeRecord` (enum, optional, nullable) — Candidate entity type from the existing record.
        - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`
    - `newsCandidate` (list of object, optional, nullable) — News candidates returned by lookup or create duplicate review. If a candidate is the requested article, read/update that article by id. Otherwise block until source evidence proves a distinct article.
      - `id` (integer, required) — News article id to read or update when this candidate is the requested article.
      - `reason` (list of string, required) — Match reasons for reviewing the candidate. Exact reasons are decision signals regardless of whether score crosses the review threshold.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended article when reason/slug/externalId match.
      - `externalId` (string, optional, nullable) — Matched external article identifier when duplicate scoring used one.
      - `slug` (string, optional, nullable) — Candidate article slug from the existing record.
    - `overridePath` (string, optional, nullable) — Create endpoint to retry only after reviewing the returned candidates and supplying overrideGate=duplicate and overrideReason as query parameters. Null for detail lookup ambiguity, where the next action is review/update/block.
  - ClassificationInactiveTagDetails
    - `availableOverrides` (list of enum, required) — Allowed inactiveTagOverride values for this conflict
      - Allowed values: `REACTIVATE`, `ATTACH_INACTIVE`
    - `slug` (string, required) — Existing dormant value slug or lookup key
    - `tagId` (integer, required) — Existing tag id in res_type_ref
  - NewsSourceUrlConflict
    - `conflictingArticleId` (integer, required) — Existing article id (NewsId.value) that already owns this publication + URL pair.
    - `conflictingArticleSlug` (string, required) — Existing article slug, or empty string when the existing article has no slug. Use with GET /v1/news/detail?slug= to fetch the conflicting article.
    - `conflictingArticleTitle` (string, required) — Existing article title for human-readable diagnostics.
- `error` (map from string to string, optional, nullable)
- `existingRedirect` (object, optional, nullable) — Redirect slug path
  - `oldUrl` (string, required)
  - `newUrl` (string, optional, nullable)
  - `targetCurrentSlug` (string, optional, nullable)
  - `targetId` (string, optional, nullable)
  - `targetResourceType` (enum, optional, nullable) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable)
- `limitType` (enum, optional)
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `CLERK_PUBLIC_ADMISSION`, `CLERK_SCRIPT_LOAD`, `ORIGIN_DETAIL`, `INFERENCE_PROVIDER`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `remaining` (long, optional, nullable)
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable)
- `resolution` (object, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
  - `action` (enum, required) — Next action category for the client or agent.
    - Allowed values: `setField`, `setParameter`, `removeParameter`, `useEndpoint`, `reviewCandidates`, `authenticate`
  - `acceptedValue` (list of string, optional, nullable) — Accepted values for the field or parameter, when enumerable.
  - `endpoint` (string, optional, nullable) — Endpoint to call for the next action, when applicable.
  - `fieldPath` (string, optional, nullable) — Request-body field path that needs attention, when applicable.
  - `parameter` (string, optional, nullable) — Query parameter that needs attention, when applicable.
  - `retryable` (boolean, optional, nullable) — Whether the same logical request can be retried after the next action.
- `retryAfterSeconds` (long, optional, nullable)
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable)
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable)

### 404 Not Found Error

Not Found

- `circuitBreaker` (string, optional, nullable)
- `code` (enum, optional) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes indicate infra/admin-only conditions where the correct agent action is to surface the error and stop, not retry.
  - Allowed values: `not_authorized`, `rateLimited`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `JOBRUNR_STORAGE_UNAVAILABLE`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `sentry_api_error`, `swagger_headers_unconfigured`, `frontend_cache_epoch_mode_not_targeted`, `image_blocklist_match`, `image_monochrome`, `image_too_small`, `image_wrong_aspect`, `image_monogram`, `image_unreadable`, `image_processing_error`, `image_brand_mismatch`, `web_crawl_fetch_failed`, `news_rss_feed_fetch_failed`, `news_rss_article_fetch_failed`, `r2_fetch_failed`, `r2_delete_failed`, `r2_upload_failed`, `source_document_body_unavailable`, `source_document_capture_limit_exceeded`, `news_similarity_embedding_unavailable`, `search_provider_not_configured`, `search_provider_error`, `sec_edgar_fetch_failed`, `github_fetch_failed`, `INFERENCE_PROVIDER_ERROR`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `INFERENCE_PROVIDER_INVALID_JSON`, `INFERENCE_PROFILES_MISSING`, `INFERENCE_PROFILE_API_KEY_MISSING`
- `conflictingRecord` (object, optional, nullable) — Current slug owner
  - `id` (string, required)
  - `isHidden` (boolean, required)
  - `resourceType` (enum, required) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
  - `showOnSitemap` (boolean, required)
  - `slug` (string, required)
  - `deletedAt` (datetime, optional, nullable)
  - `nameBrand` (string, optional, nullable)
- `detail` (string, optional)
- `details` (object or object or object or object or object, optional, nullable) — Structured conflict details. Create duplicate reviews and deterministic lookup ambiguity return DuplicateCreateReview; the returned candidates are the decision surface for update, create-with-override, or block. score/threshold rank review priority and are not proof that the requested record is absent.
  - UrlDuplicateConflict
    - `existingJoin` (list of object, required) — Every current owner that already holds the normalized URL with this urlType. Non-empty when this conflict is emitted.
      - `owner` (object, required) — Owner of the URL: either entityId or personId is populated depending on the owner kind. Use the populated id to read or update the owner's URL.
        - `entityId` (string, optional, nullable) — Canonical entity UUID
        - `personId` (string, optional, nullable) — Canonical person UUID
      - `urlId` (integer, required) — Internal URL row id (res_weburl.id) — opaque to API clients.
    - `fragmentIgnored` (boolean, required) — True when URL fragment differences were ignored during duplicate matching (i.e., the conflict ignores everything after '#').
    - `guidance` (string, required) — Human-readable guidance on how to resolve the conflict. Defaults to the standard inspect-then-demote/promote sequence.
    - `requestedOwner` (object, required) — Owner the caller attempted to attach the URL to.
      - `entityId` (string, optional, nullable) — Canonical entity UUID
      - `personId` (string, optional, nullable) — Canonical person UUID
    - `url` (string, required) — Raw URL as submitted by the caller (pre-normalization).
    - `urlType` (string, required) — URL type submitted by the caller (e.g., 'website', 'twitter'). The conflict applies only within this urlType.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key used for duplicate detection. Null when normalization could not produce a stable key (e.g., malformed input).
  - StrictUrlLookupConflict
    - `candidateEntityId` (list of string, required) — Every entity id that currently owns the normalized URL. May be empty when the conflict is between persons; combined with candidatePersonId always > 1.
    - `candidatePersonId` (list of string, required) — Every person id that currently owns the normalized URL. May be empty when the conflict is between entities; combined with candidateEntityId always > 1.
    - `hint` (string, required) — Human-readable hint describing which disambiguating query parameters to add.
    - `url` (string, required) — Raw URL the caller queried.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key the lookup resolved against. Null when normalization could not produce a stable key.
    - `urlType` (string, optional, nullable) — URL type the caller specified, or null if the lookup did not constrain by urlType.
  - DuplicateCreateReview
    - `threshold` (integer, required) — Review threshold used by duplicate scoring. Scores below this value can still be useful candidate context; this value does not prove absence or authorize create.
    - `candidate` (list of object, optional, nullable) — Entity/person candidates returned by lookup or create duplicate review. If a candidate is the requested record, read/update that candidate by id. Create with duplicate override only after every candidate is reviewed as distinct.
      - `id` (string, required) — Candidate id to read or update when this candidate is the requested record.
      - `reason` (list of string, required) — Match reasons such as name-exact, slug-exact, url-match, url-type, or precomputed-similarity. url-match proves the supplied URL/domain matched; url-type only means the candidate has the same URL category and is review context, not URL identity evidence.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended record when reason/name/slug/typeRecord match.
      - `externalId` (string, optional, nullable) — Matched external identifier when duplicate scoring used one.
      - `name` (string, optional, nullable) — Candidate display name from the existing record.
      - `operatingStatus` (string, optional, nullable) — Current operating status for entity candidates.
      - `publicPath` (string, optional, nullable) — Public API/UI path for the candidate when available.
      - `slug` (string, optional, nullable) — Candidate slug from the existing record.
      - `typeRecord` (enum, optional, nullable) — Candidate entity type from the existing record.
        - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`
    - `newsCandidate` (list of object, optional, nullable) — News candidates returned by lookup or create duplicate review. If a candidate is the requested article, read/update that article by id. Otherwise block until source evidence proves a distinct article.
      - `id` (integer, required) — News article id to read or update when this candidate is the requested article.
      - `reason` (list of string, required) — Match reasons for reviewing the candidate. Exact reasons are decision signals regardless of whether score crosses the review threshold.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended article when reason/slug/externalId match.
      - `externalId` (string, optional, nullable) — Matched external article identifier when duplicate scoring used one.
      - `slug` (string, optional, nullable) — Candidate article slug from the existing record.
    - `overridePath` (string, optional, nullable) — Create endpoint to retry only after reviewing the returned candidates and supplying overrideGate=duplicate and overrideReason as query parameters. Null for detail lookup ambiguity, where the next action is review/update/block.
  - ClassificationInactiveTagDetails
    - `availableOverrides` (list of enum, required) — Allowed inactiveTagOverride values for this conflict
      - Allowed values: `REACTIVATE`, `ATTACH_INACTIVE`
    - `slug` (string, required) — Existing dormant value slug or lookup key
    - `tagId` (integer, required) — Existing tag id in res_type_ref
  - NewsSourceUrlConflict
    - `conflictingArticleId` (integer, required) — Existing article id (NewsId.value) that already owns this publication + URL pair.
    - `conflictingArticleSlug` (string, required) — Existing article slug, or empty string when the existing article has no slug. Use with GET /v1/news/detail?slug= to fetch the conflicting article.
    - `conflictingArticleTitle` (string, required) — Existing article title for human-readable diagnostics.
- `error` (map from string to string, optional, nullable)
- `existingRedirect` (object, optional, nullable) — Redirect slug path
  - `oldUrl` (string, required)
  - `newUrl` (string, optional, nullable)
  - `targetCurrentSlug` (string, optional, nullable)
  - `targetId` (string, optional, nullable)
  - `targetResourceType` (enum, optional, nullable) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable)
- `limitType` (enum, optional)
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `CLERK_PUBLIC_ADMISSION`, `CLERK_SCRIPT_LOAD`, `ORIGIN_DETAIL`, `INFERENCE_PROVIDER`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `remaining` (long, optional, nullable)
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable)
- `resolution` (object, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
  - `action` (enum, required) — Next action category for the client or agent.
    - Allowed values: `setField`, `setParameter`, `removeParameter`, `useEndpoint`, `reviewCandidates`, `authenticate`
  - `acceptedValue` (list of string, optional, nullable) — Accepted values for the field or parameter, when enumerable.
  - `endpoint` (string, optional, nullable) — Endpoint to call for the next action, when applicable.
  - `fieldPath` (string, optional, nullable) — Request-body field path that needs attention, when applicable.
  - `parameter` (string, optional, nullable) — Query parameter that needs attention, when applicable.
  - `retryable` (boolean, optional, nullable) — Whether the same logical request can be retried after the next action.
- `retryAfterSeconds` (long, optional, nullable)
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable)
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable)

### 406 Not Acceptable Error

Not Acceptable

- `circuitBreaker` (string, optional, nullable)
- `code` (enum, optional) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes indicate infra/admin-only conditions where the correct agent action is to surface the error and stop, not retry.
  - Allowed values: `not_authorized`, `rateLimited`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `JOBRUNR_STORAGE_UNAVAILABLE`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `sentry_api_error`, `swagger_headers_unconfigured`, `frontend_cache_epoch_mode_not_targeted`, `image_blocklist_match`, `image_monochrome`, `image_too_small`, `image_wrong_aspect`, `image_monogram`, `image_unreadable`, `image_processing_error`, `image_brand_mismatch`, `web_crawl_fetch_failed`, `news_rss_feed_fetch_failed`, `news_rss_article_fetch_failed`, `r2_fetch_failed`, `r2_delete_failed`, `r2_upload_failed`, `source_document_body_unavailable`, `source_document_capture_limit_exceeded`, `news_similarity_embedding_unavailable`, `search_provider_not_configured`, `search_provider_error`, `sec_edgar_fetch_failed`, `github_fetch_failed`, `INFERENCE_PROVIDER_ERROR`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `INFERENCE_PROVIDER_INVALID_JSON`, `INFERENCE_PROFILES_MISSING`, `INFERENCE_PROFILE_API_KEY_MISSING`
- `conflictingRecord` (object, optional, nullable) — Current slug owner
  - `id` (string, required)
  - `isHidden` (boolean, required)
  - `resourceType` (enum, required) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
  - `showOnSitemap` (boolean, required)
  - `slug` (string, required)
  - `deletedAt` (datetime, optional, nullable)
  - `nameBrand` (string, optional, nullable)
- `detail` (string, optional)
- `details` (object or object or object or object or object, optional, nullable) — Structured conflict details. Create duplicate reviews and deterministic lookup ambiguity return DuplicateCreateReview; the returned candidates are the decision surface for update, create-with-override, or block. score/threshold rank review priority and are not proof that the requested record is absent.
  - UrlDuplicateConflict
    - `existingJoin` (list of object, required) — Every current owner that already holds the normalized URL with this urlType. Non-empty when this conflict is emitted.
      - `owner` (object, required) — Owner of the URL: either entityId or personId is populated depending on the owner kind. Use the populated id to read or update the owner's URL.
        - `entityId` (string, optional, nullable) — Canonical entity UUID
        - `personId` (string, optional, nullable) — Canonical person UUID
      - `urlId` (integer, required) — Internal URL row id (res_weburl.id) — opaque to API clients.
    - `fragmentIgnored` (boolean, required) — True when URL fragment differences were ignored during duplicate matching (i.e., the conflict ignores everything after '#').
    - `guidance` (string, required) — Human-readable guidance on how to resolve the conflict. Defaults to the standard inspect-then-demote/promote sequence.
    - `requestedOwner` (object, required) — Owner the caller attempted to attach the URL to.
      - `entityId` (string, optional, nullable) — Canonical entity UUID
      - `personId` (string, optional, nullable) — Canonical person UUID
    - `url` (string, required) — Raw URL as submitted by the caller (pre-normalization).
    - `urlType` (string, required) — URL type submitted by the caller (e.g., 'website', 'twitter'). The conflict applies only within this urlType.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key used for duplicate detection. Null when normalization could not produce a stable key (e.g., malformed input).
  - StrictUrlLookupConflict
    - `candidateEntityId` (list of string, required) — Every entity id that currently owns the normalized URL. May be empty when the conflict is between persons; combined with candidatePersonId always > 1.
    - `candidatePersonId` (list of string, required) — Every person id that currently owns the normalized URL. May be empty when the conflict is between entities; combined with candidateEntityId always > 1.
    - `hint` (string, required) — Human-readable hint describing which disambiguating query parameters to add.
    - `url` (string, required) — Raw URL the caller queried.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key the lookup resolved against. Null when normalization could not produce a stable key.
    - `urlType` (string, optional, nullable) — URL type the caller specified, or null if the lookup did not constrain by urlType.
  - DuplicateCreateReview
    - `threshold` (integer, required) — Review threshold used by duplicate scoring. Scores below this value can still be useful candidate context; this value does not prove absence or authorize create.
    - `candidate` (list of object, optional, nullable) — Entity/person candidates returned by lookup or create duplicate review. If a candidate is the requested record, read/update that candidate by id. Create with duplicate override only after every candidate is reviewed as distinct.
      - `id` (string, required) — Candidate id to read or update when this candidate is the requested record.
      - `reason` (list of string, required) — Match reasons such as name-exact, slug-exact, url-match, url-type, or precomputed-similarity. url-match proves the supplied URL/domain matched; url-type only means the candidate has the same URL category and is review context, not URL identity evidence.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended record when reason/name/slug/typeRecord match.
      - `externalId` (string, optional, nullable) — Matched external identifier when duplicate scoring used one.
      - `name` (string, optional, nullable) — Candidate display name from the existing record.
      - `operatingStatus` (string, optional, nullable) — Current operating status for entity candidates.
      - `publicPath` (string, optional, nullable) — Public API/UI path for the candidate when available.
      - `slug` (string, optional, nullable) — Candidate slug from the existing record.
      - `typeRecord` (enum, optional, nullable) — Candidate entity type from the existing record.
        - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`
    - `newsCandidate` (list of object, optional, nullable) — News candidates returned by lookup or create duplicate review. If a candidate is the requested article, read/update that article by id. Otherwise block until source evidence proves a distinct article.
      - `id` (integer, required) — News article id to read or update when this candidate is the requested article.
      - `reason` (list of string, required) — Match reasons for reviewing the candidate. Exact reasons are decision signals regardless of whether score crosses the review threshold.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended article when reason/slug/externalId match.
      - `externalId` (string, optional, nullable) — Matched external article identifier when duplicate scoring used one.
      - `slug` (string, optional, nullable) — Candidate article slug from the existing record.
    - `overridePath` (string, optional, nullable) — Create endpoint to retry only after reviewing the returned candidates and supplying overrideGate=duplicate and overrideReason as query parameters. Null for detail lookup ambiguity, where the next action is review/update/block.
  - ClassificationInactiveTagDetails
    - `availableOverrides` (list of enum, required) — Allowed inactiveTagOverride values for this conflict
      - Allowed values: `REACTIVATE`, `ATTACH_INACTIVE`
    - `slug` (string, required) — Existing dormant value slug or lookup key
    - `tagId` (integer, required) — Existing tag id in res_type_ref
  - NewsSourceUrlConflict
    - `conflictingArticleId` (integer, required) — Existing article id (NewsId.value) that already owns this publication + URL pair.
    - `conflictingArticleSlug` (string, required) — Existing article slug, or empty string when the existing article has no slug. Use with GET /v1/news/detail?slug= to fetch the conflicting article.
    - `conflictingArticleTitle` (string, required) — Existing article title for human-readable diagnostics.
- `error` (map from string to string, optional, nullable)
- `existingRedirect` (object, optional, nullable) — Redirect slug path
  - `oldUrl` (string, required)
  - `newUrl` (string, optional, nullable)
  - `targetCurrentSlug` (string, optional, nullable)
  - `targetId` (string, optional, nullable)
  - `targetResourceType` (enum, optional, nullable) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable)
- `limitType` (enum, optional)
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `CLERK_PUBLIC_ADMISSION`, `CLERK_SCRIPT_LOAD`, `ORIGIN_DETAIL`, `INFERENCE_PROVIDER`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `remaining` (long, optional, nullable)
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable)
- `resolution` (object, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
  - `action` (enum, required) — Next action category for the client or agent.
    - Allowed values: `setField`, `setParameter`, `removeParameter`, `useEndpoint`, `reviewCandidates`, `authenticate`
  - `acceptedValue` (list of string, optional, nullable) — Accepted values for the field or parameter, when enumerable.
  - `endpoint` (string, optional, nullable) — Endpoint to call for the next action, when applicable.
  - `fieldPath` (string, optional, nullable) — Request-body field path that needs attention, when applicable.
  - `parameter` (string, optional, nullable) — Query parameter that needs attention, when applicable.
  - `retryable` (boolean, optional, nullable) — Whether the same logical request can be retried after the next action.
- `retryAfterSeconds` (long, optional, nullable)
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable)
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable)

### 429 Too Many Requests Error

Too Many Requests

- `circuitBreaker` (string, optional, nullable)
- `code` (enum, optional) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes indicate infra/admin-only conditions where the correct agent action is to surface the error and stop, not retry.
  - Allowed values: `not_authorized`, `rateLimited`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `JOBRUNR_STORAGE_UNAVAILABLE`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `sentry_api_error`, `swagger_headers_unconfigured`, `frontend_cache_epoch_mode_not_targeted`, `image_blocklist_match`, `image_monochrome`, `image_too_small`, `image_wrong_aspect`, `image_monogram`, `image_unreadable`, `image_processing_error`, `image_brand_mismatch`, `web_crawl_fetch_failed`, `news_rss_feed_fetch_failed`, `news_rss_article_fetch_failed`, `r2_fetch_failed`, `r2_delete_failed`, `r2_upload_failed`, `source_document_body_unavailable`, `source_document_capture_limit_exceeded`, `news_similarity_embedding_unavailable`, `search_provider_not_configured`, `search_provider_error`, `sec_edgar_fetch_failed`, `github_fetch_failed`, `INFERENCE_PROVIDER_ERROR`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `INFERENCE_PROVIDER_INVALID_JSON`, `INFERENCE_PROFILES_MISSING`, `INFERENCE_PROFILE_API_KEY_MISSING`
- `conflictingRecord` (object, optional, nullable) — Current slug owner
  - `id` (string, required)
  - `isHidden` (boolean, required)
  - `resourceType` (enum, required) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
  - `showOnSitemap` (boolean, required)
  - `slug` (string, required)
  - `deletedAt` (datetime, optional, nullable)
  - `nameBrand` (string, optional, nullable)
- `detail` (string, optional)
- `details` (object or object or object or object or object, optional, nullable) — Structured conflict details. Create duplicate reviews and deterministic lookup ambiguity return DuplicateCreateReview; the returned candidates are the decision surface for update, create-with-override, or block. score/threshold rank review priority and are not proof that the requested record is absent.
  - UrlDuplicateConflict
    - `existingJoin` (list of object, required) — Every current owner that already holds the normalized URL with this urlType. Non-empty when this conflict is emitted.
      - `owner` (object, required) — Owner of the URL: either entityId or personId is populated depending on the owner kind. Use the populated id to read or update the owner's URL.
        - `entityId` (string, optional, nullable) — Canonical entity UUID
        - `personId` (string, optional, nullable) — Canonical person UUID
      - `urlId` (integer, required) — Internal URL row id (res_weburl.id) — opaque to API clients.
    - `fragmentIgnored` (boolean, required) — True when URL fragment differences were ignored during duplicate matching (i.e., the conflict ignores everything after '#').
    - `guidance` (string, required) — Human-readable guidance on how to resolve the conflict. Defaults to the standard inspect-then-demote/promote sequence.
    - `requestedOwner` (object, required) — Owner the caller attempted to attach the URL to.
      - `entityId` (string, optional, nullable) — Canonical entity UUID
      - `personId` (string, optional, nullable) — Canonical person UUID
    - `url` (string, required) — Raw URL as submitted by the caller (pre-normalization).
    - `urlType` (string, required) — URL type submitted by the caller (e.g., 'website', 'twitter'). The conflict applies only within this urlType.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key used for duplicate detection. Null when normalization could not produce a stable key (e.g., malformed input).
  - StrictUrlLookupConflict
    - `candidateEntityId` (list of string, required) — Every entity id that currently owns the normalized URL. May be empty when the conflict is between persons; combined with candidatePersonId always > 1.
    - `candidatePersonId` (list of string, required) — Every person id that currently owns the normalized URL. May be empty when the conflict is between entities; combined with candidateEntityId always > 1.
    - `hint` (string, required) — Human-readable hint describing which disambiguating query parameters to add.
    - `url` (string, required) — Raw URL the caller queried.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key the lookup resolved against. Null when normalization could not produce a stable key.
    - `urlType` (string, optional, nullable) — URL type the caller specified, or null if the lookup did not constrain by urlType.
  - DuplicateCreateReview
    - `threshold` (integer, required) — Review threshold used by duplicate scoring. Scores below this value can still be useful candidate context; this value does not prove absence or authorize create.
    - `candidate` (list of object, optional, nullable) — Entity/person candidates returned by lookup or create duplicate review. If a candidate is the requested record, read/update that candidate by id. Create with duplicate override only after every candidate is reviewed as distinct.
      - `id` (string, required) — Candidate id to read or update when this candidate is the requested record.
      - `reason` (list of string, required) — Match reasons such as name-exact, slug-exact, url-match, url-type, or precomputed-similarity. url-match proves the supplied URL/domain matched; url-type only means the candidate has the same URL category and is review context, not URL identity evidence.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended record when reason/name/slug/typeRecord match.
      - `externalId` (string, optional, nullable) — Matched external identifier when duplicate scoring used one.
      - `name` (string, optional, nullable) — Candidate display name from the existing record.
      - `operatingStatus` (string, optional, nullable) — Current operating status for entity candidates.
      - `publicPath` (string, optional, nullable) — Public API/UI path for the candidate when available.
      - `slug` (string, optional, nullable) — Candidate slug from the existing record.
      - `typeRecord` (enum, optional, nullable) — Candidate entity type from the existing record.
        - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`
    - `newsCandidate` (list of object, optional, nullable) — News candidates returned by lookup or create duplicate review. If a candidate is the requested article, read/update that article by id. Otherwise block until source evidence proves a distinct article.
      - `id` (integer, required) — News article id to read or update when this candidate is the requested article.
      - `reason` (list of string, required) — Match reasons for reviewing the candidate. Exact reasons are decision signals regardless of whether score crosses the review threshold.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended article when reason/slug/externalId match.
      - `externalId` (string, optional, nullable) — Matched external article identifier when duplicate scoring used one.
      - `slug` (string, optional, nullable) — Candidate article slug from the existing record.
    - `overridePath` (string, optional, nullable) — Create endpoint to retry only after reviewing the returned candidates and supplying overrideGate=duplicate and overrideReason as query parameters. Null for detail lookup ambiguity, where the next action is review/update/block.
  - ClassificationInactiveTagDetails
    - `availableOverrides` (list of enum, required) — Allowed inactiveTagOverride values for this conflict
      - Allowed values: `REACTIVATE`, `ATTACH_INACTIVE`
    - `slug` (string, required) — Existing dormant value slug or lookup key
    - `tagId` (integer, required) — Existing tag id in res_type_ref
  - NewsSourceUrlConflict
    - `conflictingArticleId` (integer, required) — Existing article id (NewsId.value) that already owns this publication + URL pair.
    - `conflictingArticleSlug` (string, required) — Existing article slug, or empty string when the existing article has no slug. Use with GET /v1/news/detail?slug= to fetch the conflicting article.
    - `conflictingArticleTitle` (string, required) — Existing article title for human-readable diagnostics.
- `error` (map from string to string, optional, nullable)
- `existingRedirect` (object, optional, nullable) — Redirect slug path
  - `oldUrl` (string, required)
  - `newUrl` (string, optional, nullable)
  - `targetCurrentSlug` (string, optional, nullable)
  - `targetId` (string, optional, nullable)
  - `targetResourceType` (enum, optional, nullable) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable)
- `limitType` (enum, optional)
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `CLERK_PUBLIC_ADMISSION`, `CLERK_SCRIPT_LOAD`, `ORIGIN_DETAIL`, `INFERENCE_PROVIDER`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `remaining` (long, optional, nullable)
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable)
- `resolution` (object, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
  - `action` (enum, required) — Next action category for the client or agent.
    - Allowed values: `setField`, `setParameter`, `removeParameter`, `useEndpoint`, `reviewCandidates`, `authenticate`
  - `acceptedValue` (list of string, optional, nullable) — Accepted values for the field or parameter, when enumerable.
  - `endpoint` (string, optional, nullable) — Endpoint to call for the next action, when applicable.
  - `fieldPath` (string, optional, nullable) — Request-body field path that needs attention, when applicable.
  - `parameter` (string, optional, nullable) — Query parameter that needs attention, when applicable.
  - `retryable` (boolean, optional, nullable) — Whether the same logical request can be retried after the next action.
- `retryAfterSeconds` (long, optional, nullable)
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable)
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable)

### 500 Internal Server Error

Internal Server Error

- `circuitBreaker` (string, optional, nullable)
- `code` (enum, optional) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes indicate infra/admin-only conditions where the correct agent action is to surface the error and stop, not retry.
  - Allowed values: `not_authorized`, `rateLimited`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `JOBRUNR_STORAGE_UNAVAILABLE`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `sentry_api_error`, `swagger_headers_unconfigured`, `frontend_cache_epoch_mode_not_targeted`, `image_blocklist_match`, `image_monochrome`, `image_too_small`, `image_wrong_aspect`, `image_monogram`, `image_unreadable`, `image_processing_error`, `image_brand_mismatch`, `web_crawl_fetch_failed`, `news_rss_feed_fetch_failed`, `news_rss_article_fetch_failed`, `r2_fetch_failed`, `r2_delete_failed`, `r2_upload_failed`, `source_document_body_unavailable`, `source_document_capture_limit_exceeded`, `news_similarity_embedding_unavailable`, `search_provider_not_configured`, `search_provider_error`, `sec_edgar_fetch_failed`, `github_fetch_failed`, `INFERENCE_PROVIDER_ERROR`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `INFERENCE_PROVIDER_INVALID_JSON`, `INFERENCE_PROFILES_MISSING`, `INFERENCE_PROFILE_API_KEY_MISSING`
- `conflictingRecord` (object, optional, nullable) — Current slug owner
  - `id` (string, required)
  - `isHidden` (boolean, required)
  - `resourceType` (enum, required) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
  - `showOnSitemap` (boolean, required)
  - `slug` (string, required)
  - `deletedAt` (datetime, optional, nullable)
  - `nameBrand` (string, optional, nullable)
- `detail` (string, optional)
- `details` (object or object or object or object or object, optional, nullable) — Structured conflict details. Create duplicate reviews and deterministic lookup ambiguity return DuplicateCreateReview; the returned candidates are the decision surface for update, create-with-override, or block. score/threshold rank review priority and are not proof that the requested record is absent.
  - UrlDuplicateConflict
    - `existingJoin` (list of object, required) — Every current owner that already holds the normalized URL with this urlType. Non-empty when this conflict is emitted.
      - `owner` (object, required) — Owner of the URL: either entityId or personId is populated depending on the owner kind. Use the populated id to read or update the owner's URL.
        - `entityId` (string, optional, nullable) — Canonical entity UUID
        - `personId` (string, optional, nullable) — Canonical person UUID
      - `urlId` (integer, required) — Internal URL row id (res_weburl.id) — opaque to API clients.
    - `fragmentIgnored` (boolean, required) — True when URL fragment differences were ignored during duplicate matching (i.e., the conflict ignores everything after '#').
    - `guidance` (string, required) — Human-readable guidance on how to resolve the conflict. Defaults to the standard inspect-then-demote/promote sequence.
    - `requestedOwner` (object, required) — Owner the caller attempted to attach the URL to.
      - `entityId` (string, optional, nullable) — Canonical entity UUID
      - `personId` (string, optional, nullable) — Canonical person UUID
    - `url` (string, required) — Raw URL as submitted by the caller (pre-normalization).
    - `urlType` (string, required) — URL type submitted by the caller (e.g., 'website', 'twitter'). The conflict applies only within this urlType.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key used for duplicate detection. Null when normalization could not produce a stable key (e.g., malformed input).
  - StrictUrlLookupConflict
    - `candidateEntityId` (list of string, required) — Every entity id that currently owns the normalized URL. May be empty when the conflict is between persons; combined with candidatePersonId always > 1.
    - `candidatePersonId` (list of string, required) — Every person id that currently owns the normalized URL. May be empty when the conflict is between entities; combined with candidateEntityId always > 1.
    - `hint` (string, required) — Human-readable hint describing which disambiguating query parameters to add.
    - `url` (string, required) — Raw URL the caller queried.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key the lookup resolved against. Null when normalization could not produce a stable key.
    - `urlType` (string, optional, nullable) — URL type the caller specified, or null if the lookup did not constrain by urlType.
  - DuplicateCreateReview
    - `threshold` (integer, required) — Review threshold used by duplicate scoring. Scores below this value can still be useful candidate context; this value does not prove absence or authorize create.
    - `candidate` (list of object, optional, nullable) — Entity/person candidates returned by lookup or create duplicate review. If a candidate is the requested record, read/update that candidate by id. Create with duplicate override only after every candidate is reviewed as distinct.
      - `id` (string, required) — Candidate id to read or update when this candidate is the requested record.
      - `reason` (list of string, required) — Match reasons such as name-exact, slug-exact, url-match, url-type, or precomputed-similarity. url-match proves the supplied URL/domain matched; url-type only means the candidate has the same URL category and is review context, not URL identity evidence.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended record when reason/name/slug/typeRecord match.
      - `externalId` (string, optional, nullable) — Matched external identifier when duplicate scoring used one.
      - `name` (string, optional, nullable) — Candidate display name from the existing record.
      - `operatingStatus` (string, optional, nullable) — Current operating status for entity candidates.
      - `publicPath` (string, optional, nullable) — Public API/UI path for the candidate when available.
      - `slug` (string, optional, nullable) — Candidate slug from the existing record.
      - `typeRecord` (enum, optional, nullable) — Candidate entity type from the existing record.
        - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`
    - `newsCandidate` (list of object, optional, nullable) — News candidates returned by lookup or create duplicate review. If a candidate is the requested article, read/update that article by id. Otherwise block until source evidence proves a distinct article.
      - `id` (integer, required) — News article id to read or update when this candidate is the requested article.
      - `reason` (list of string, required) — Match reasons for reviewing the candidate. Exact reasons are decision signals regardless of whether score crosses the review threshold.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended article when reason/slug/externalId match.
      - `externalId` (string, optional, nullable) — Matched external article identifier when duplicate scoring used one.
      - `slug` (string, optional, nullable) — Candidate article slug from the existing record.
    - `overridePath` (string, optional, nullable) — Create endpoint to retry only after reviewing the returned candidates and supplying overrideGate=duplicate and overrideReason as query parameters. Null for detail lookup ambiguity, where the next action is review/update/block.
  - ClassificationInactiveTagDetails
    - `availableOverrides` (list of enum, required) — Allowed inactiveTagOverride values for this conflict
      - Allowed values: `REACTIVATE`, `ATTACH_INACTIVE`
    - `slug` (string, required) — Existing dormant value slug or lookup key
    - `tagId` (integer, required) — Existing tag id in res_type_ref
  - NewsSourceUrlConflict
    - `conflictingArticleId` (integer, required) — Existing article id (NewsId.value) that already owns this publication + URL pair.
    - `conflictingArticleSlug` (string, required) — Existing article slug, or empty string when the existing article has no slug. Use with GET /v1/news/detail?slug= to fetch the conflicting article.
    - `conflictingArticleTitle` (string, required) — Existing article title for human-readable diagnostics.
- `error` (map from string to string, optional, nullable)
- `existingRedirect` (object, optional, nullable) — Redirect slug path
  - `oldUrl` (string, required)
  - `newUrl` (string, optional, nullable)
  - `targetCurrentSlug` (string, optional, nullable)
  - `targetId` (string, optional, nullable)
  - `targetResourceType` (enum, optional, nullable) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable)
- `limitType` (enum, optional)
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `CLERK_PUBLIC_ADMISSION`, `CLERK_SCRIPT_LOAD`, `ORIGIN_DETAIL`, `INFERENCE_PROVIDER`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `remaining` (long, optional, nullable)
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable)
- `resolution` (object, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
  - `action` (enum, required) — Next action category for the client or agent.
    - Allowed values: `setField`, `setParameter`, `removeParameter`, `useEndpoint`, `reviewCandidates`, `authenticate`
  - `acceptedValue` (list of string, optional, nullable) — Accepted values for the field or parameter, when enumerable.
  - `endpoint` (string, optional, nullable) — Endpoint to call for the next action, when applicable.
  - `fieldPath` (string, optional, nullable) — Request-body field path that needs attention, when applicable.
  - `parameter` (string, optional, nullable) — Query parameter that needs attention, when applicable.
  - `retryable` (boolean, optional, nullable) — Whether the same logical request can be retried after the next action.
- `retryAfterSeconds` (long, optional, nullable)
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable)
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable)

### 503 Service Unavailable Error

Service Unavailable

- `circuitBreaker` (string, optional, nullable)
- `code` (enum, optional) — Machine-readable secondary code on ProblemDetail.code. Agents should branch on this value when the HTTP status alone does not identify the recovery path. Code groups include auth/session, rate limiting, job infrastructure, RBAC, external providers, image processing, R2 storage, search, and inference. Many codes indicate infra/admin-only conditions where the correct agent action is to surface the error and stop, not retry.
  - Allowed values: `not_authorized`, `rateLimited`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `JOBRUNR_STORAGE_UNAVAILABLE`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `sentry_api_error`, `swagger_headers_unconfigured`, `frontend_cache_epoch_mode_not_targeted`, `image_blocklist_match`, `image_monochrome`, `image_too_small`, `image_wrong_aspect`, `image_monogram`, `image_unreadable`, `image_processing_error`, `image_brand_mismatch`, `web_crawl_fetch_failed`, `news_rss_feed_fetch_failed`, `news_rss_article_fetch_failed`, `r2_fetch_failed`, `r2_delete_failed`, `r2_upload_failed`, `source_document_body_unavailable`, `source_document_capture_limit_exceeded`, `news_similarity_embedding_unavailable`, `search_provider_not_configured`, `search_provider_error`, `sec_edgar_fetch_failed`, `github_fetch_failed`, `INFERENCE_PROVIDER_ERROR`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `INFERENCE_PROVIDER_INVALID_JSON`, `INFERENCE_PROFILES_MISSING`, `INFERENCE_PROFILE_API_KEY_MISSING`
- `conflictingRecord` (object, optional, nullable) — Current slug owner
  - `id` (string, required)
  - `isHidden` (boolean, required)
  - `resourceType` (enum, required) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
  - `showOnSitemap` (boolean, required)
  - `slug` (string, required)
  - `deletedAt` (datetime, optional, nullable)
  - `nameBrand` (string, optional, nullable)
- `detail` (string, optional)
- `details` (object or object or object or object or object, optional, nullable) — Structured conflict details. Create duplicate reviews and deterministic lookup ambiguity return DuplicateCreateReview; the returned candidates are the decision surface for update, create-with-override, or block. score/threshold rank review priority and are not proof that the requested record is absent.
  - UrlDuplicateConflict
    - `existingJoin` (list of object, required) — Every current owner that already holds the normalized URL with this urlType. Non-empty when this conflict is emitted.
      - `owner` (object, required) — Owner of the URL: either entityId or personId is populated depending on the owner kind. Use the populated id to read or update the owner's URL.
        - `entityId` (string, optional, nullable) — Canonical entity UUID
        - `personId` (string, optional, nullable) — Canonical person UUID
      - `urlId` (integer, required) — Internal URL row id (res_weburl.id) — opaque to API clients.
    - `fragmentIgnored` (boolean, required) — True when URL fragment differences were ignored during duplicate matching (i.e., the conflict ignores everything after '#').
    - `guidance` (string, required) — Human-readable guidance on how to resolve the conflict. Defaults to the standard inspect-then-demote/promote sequence.
    - `requestedOwner` (object, required) — Owner the caller attempted to attach the URL to.
      - `entityId` (string, optional, nullable) — Canonical entity UUID
      - `personId` (string, optional, nullable) — Canonical person UUID
    - `url` (string, required) — Raw URL as submitted by the caller (pre-normalization).
    - `urlType` (string, required) — URL type submitted by the caller (e.g., 'website', 'twitter'). The conflict applies only within this urlType.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key used for duplicate detection. Null when normalization could not produce a stable key (e.g., malformed input).
  - StrictUrlLookupConflict
    - `candidateEntityId` (list of string, required) — Every entity id that currently owns the normalized URL. May be empty when the conflict is between persons; combined with candidatePersonId always > 1.
    - `candidatePersonId` (list of string, required) — Every person id that currently owns the normalized URL. May be empty when the conflict is between entities; combined with candidateEntityId always > 1.
    - `hint` (string, required) — Human-readable hint describing which disambiguating query parameters to add.
    - `url` (string, required) — Raw URL the caller queried.
    - `normalizedUrl` (string, optional, nullable) — Normalized URL match key the lookup resolved against. Null when normalization could not produce a stable key.
    - `urlType` (string, optional, nullable) — URL type the caller specified, or null if the lookup did not constrain by urlType.
  - DuplicateCreateReview
    - `threshold` (integer, required) — Review threshold used by duplicate scoring. Scores below this value can still be useful candidate context; this value does not prove absence or authorize create.
    - `candidate` (list of object, optional, nullable) — Entity/person candidates returned by lookup or create duplicate review. If a candidate is the requested record, read/update that candidate by id. Create with duplicate override only after every candidate is reviewed as distinct.
      - `id` (string, required) — Candidate id to read or update when this candidate is the requested record.
      - `reason` (list of string, required) — Match reasons such as name-exact, slug-exact, url-match, url-type, or precomputed-similarity. url-match proves the supplied URL/domain matched; url-type only means the candidate has the same URL category and is review context, not URL identity evidence.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended record when reason/name/slug/typeRecord match.
      - `externalId` (string, optional, nullable) — Matched external identifier when duplicate scoring used one.
      - `name` (string, optional, nullable) — Candidate display name from the existing record.
      - `operatingStatus` (string, optional, nullable) — Current operating status for entity candidates.
      - `publicPath` (string, optional, nullable) — Public API/UI path for the candidate when available.
      - `slug` (string, optional, nullable) — Candidate slug from the existing record.
      - `typeRecord` (enum, optional, nullable) — Candidate entity type from the existing record.
        - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service`
    - `newsCandidate` (list of object, optional, nullable) — News candidates returned by lookup or create duplicate review. If a candidate is the requested article, read/update that article by id. Otherwise block until source evidence proves a distinct article.
      - `id` (integer, required) — News article id to read or update when this candidate is the requested article.
      - `reason` (list of string, required) — Match reasons for reviewing the candidate. Exact reasons are decision signals regardless of whether score crosses the review threshold.
      - `score` (integer, required) — Ranking score for duplicate review. It is not an absence proof; a low score can still be the intended article when reason/slug/externalId match.
      - `externalId` (string, optional, nullable) — Matched external article identifier when duplicate scoring used one.
      - `slug` (string, optional, nullable) — Candidate article slug from the existing record.
    - `overridePath` (string, optional, nullable) — Create endpoint to retry only after reviewing the returned candidates and supplying overrideGate=duplicate and overrideReason as query parameters. Null for detail lookup ambiguity, where the next action is review/update/block.
  - ClassificationInactiveTagDetails
    - `availableOverrides` (list of enum, required) — Allowed inactiveTagOverride values for this conflict
      - Allowed values: `REACTIVATE`, `ATTACH_INACTIVE`
    - `slug` (string, required) — Existing dormant value slug or lookup key
    - `tagId` (integer, required) — Existing tag id in res_type_ref
  - NewsSourceUrlConflict
    - `conflictingArticleId` (integer, required) — Existing article id (NewsId.value) that already owns this publication + URL pair.
    - `conflictingArticleSlug` (string, required) — Existing article slug, or empty string when the existing article has no slug. Use with GET /v1/news/detail?slug= to fetch the conflicting article.
    - `conflictingArticleTitle` (string, required) — Existing article title for human-readable diagnostics.
- `error` (map from string to string, optional, nullable)
- `existingRedirect` (object, optional, nullable) — Redirect slug path
  - `oldUrl` (string, required)
  - `newUrl` (string, optional, nullable)
  - `targetCurrentSlug` (string, optional, nullable)
  - `targetId` (string, optional, nullable)
  - `targetResourceType` (enum, optional, nullable) — Resource type whose slug is being changed
    - Allowed values: `entity`, `person`, `news`, `blog`, `content`
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `hammingDistance` (long, optional, nullable)
- `hint` (string, optional, nullable)
- `instance` (string, optional)
- `limit` (long, optional, nullable)
- `limitType` (enum, optional)
  - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `CLERK_PUBLIC_ADMISSION`, `CLERK_SCRIPT_LOAD`, `ORIGIN_DETAIL`, `INFERENCE_PROVIDER`
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `parseError` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `remaining` (long, optional, nullable)
- `requiredRole` (string, optional, nullable)
- `resetAt` (datetime, optional, nullable)
- `resolution` (object, optional, nullable) — Machine-readable next action for an aVenture ProblemDetail. For reviewCandidates, inspect ProblemDetail.details candidates and decide update, create-with-override, or block from those returned records.
  - `action` (enum, required) — Next action category for the client or agent.
    - Allowed values: `setField`, `setParameter`, `removeParameter`, `useEndpoint`, `reviewCandidates`, `authenticate`
  - `acceptedValue` (list of string, optional, nullable) — Accepted values for the field or parameter, when enumerable.
  - `endpoint` (string, optional, nullable) — Endpoint to call for the next action, when applicable.
  - `fieldPath` (string, optional, nullable) — Request-body field path that needs attention, when applicable.
  - `parameter` (string, optional, nullable) — Query parameter that needs attention, when applicable.
  - `retryable` (boolean, optional, nullable) — Whether the same logical request can be retried after the next action.
- `retryAfterSeconds` (long, optional, nullable)
- `spanId` (string, optional, nullable)
- `status` (integer, optional)
- `suggestion` (string, optional, nullable)
- `suggestions` (map from string to string, optional, nullable)
- `suspectedFragment` (string, optional, nullable)
- `title` (string, optional)
- `traceId` (string, optional, nullable)
- `type` (string, optional)
- `unknownParameters` (list of string, optional, nullable)
- `used` (long, optional, nullable)
- `validParameters` (list of string, optional, nullable)
- `value` (string, optional, nullable)
- `windowSeconds` (long, optional, nullable)

## Examples

**Response**

```json
[
  {
    "alreadyJoined": true,
    "classification": {
      "bucket": "string",
      "classificationId": 1,
      "creatable": true,
      "createdAt": "2024-01-15T09:30:00Z",
      "id": 1,
      "isCurrent": true,
      "isPrimary": true,
      "name": "string",
      "slug": "aventure-vc",
      "type": "industry",
      "updatedAt": "2024-01-15T09:30:00Z",
      "writable": true
    },
    "creatable": true,
    "rank": 1,
    "score": 1.1,
    "writable": true
  }
]
```

**SDK Code**

```python
import requests

url = "https://api.aventure.vc/v1/entities/entityId/classifications/suggestions"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.aventure.vc/v1/entities/entityId/classifications/suggestions';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.aventure.vc/v1/entities/entityId/classifications/suggestions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.aventure.vc/v1/entities/entityId/classifications/suggestions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.aventure.vc/v1/entities/entityId/classifications/suggestions")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.aventure.vc/v1/entities/entityId/classifications/suggestions', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.aventure.vc/v1/entities/entityId/classifications/suggestions");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.aventure.vc/v1/entities/entityId/classifications/suggestions")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```