> 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. # Find people with natural language POST https://api.aventure.vc/v1/search/natural/people Content-Type: application/json Translate a plain-English people search into the canonical PersonFilter contract, execute the existing people list engine, and return both the interpretation and ranked people page. Broad role and profile requests use person semantic search. Explicit filter fields are hard constraints: they override planner values, while the planner fills fields left unset. Reference: https://docs.aventure.vc/api-reference/search/natural-people ## Authentication - `Authorization` header (bearer token, required) — User bearer token: Clerk session JWT, Clerk OAuth access token, or Clerk API key ## Request ### Query parameters - `permitMonogram` (boolean, optional) — When false, generated monogram pictures are stripped from person rows. - `includePrivate` (boolean, optional) — Includes hidden or off-sitemap people when the caller has private-visibility authority. Omit to use the caller's default visibility. - `page` (integer, optional, default: 0) — Zero-based page index (0..N) - `size` (integer, optional, default: 40) — The size of the page to be returned - `sort` (list of string, optional) — Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported. ### Body (application/json) This endpoint expects a PersonNaturalSearch. - `search` (NaturalSearch, required) — Canonical plain-English search request and strategy. - `filter` (PersonFilter, optional) — Explicit people constraints. Caller-supplied fields override planner values; the planner fills only fields left at their canonical defaults. ## Response ### 200 Ranked person matches for the interpreted query. - `interpretation` (PersonSearchInterpretation, required) — Structured interpretation used to run the people query. - `result` (PageResultPerson, required) — Person page returned by the canonical person list engine. ## Errors ### 400 Bad Request Error Bad Request - `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted. - Allowed values: `NEW_COMPANY`, `UPDATE`, `NEW_PERSON`, `UPDATE_PERSON`, `ENTITY_VIEW`, `PERSON_VIEW` - `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`, `rate_limited`, `subscription_required`, `subscription_canceled`, `subscription_past_due`, `subscription_paused`, `billing_allowance_exhausted`, `billing_additional_usage_cap_reached`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `suspected_shell_strip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `jobrunr_disabled`, `JOBRUNR_STORAGE_UNAVAILABLE`, `jobrunr_storage_unavailable`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `geocode_provider_error`, `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`, `primary_website_missing`, `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_error`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `inference_provider_response_empty`, `INFERENCE_PROVIDER_INVALID_JSON`, `inference_provider_invalid_json`, `INFERENCE_PROFILES_MISSING`, `inference_profiles_missing`, `INFERENCE_PROFILE_API_KEY_MISSING`, `inference_profile_api_key_missing` - `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner - `detail` (string, optional) - `details` (DomainConflictDetails, 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. - `error` (map from string to string, optional, nullable) - `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path - `feId` (string, optional, nullable) - `field` (string, optional, nullable) - `hammingDistance` (long, optional, nullable) - `hint` (string, optional, nullable) - `instance` (string, optional) - `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period. - `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count. - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`, `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) — Cap minus used for the limitType meter, never negative. - `requiredRole` (string, optional, nullable) - `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again. - `resolution` (ProblemResolution, 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. - `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff. - `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) — Requests already charged against the limitType meter this period. - `validParameters` (list of string, optional, nullable) - `value` (string, optional, nullable) - `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters. ### 401 Unauthorized Error Unauthorized - `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted. - Allowed values: `NEW_COMPANY`, `UPDATE`, `NEW_PERSON`, `UPDATE_PERSON`, `ENTITY_VIEW`, `PERSON_VIEW` - `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`, `rate_limited`, `subscription_required`, `subscription_canceled`, `subscription_past_due`, `subscription_paused`, `billing_allowance_exhausted`, `billing_additional_usage_cap_reached`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `suspected_shell_strip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `jobrunr_disabled`, `JOBRUNR_STORAGE_UNAVAILABLE`, `jobrunr_storage_unavailable`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `geocode_provider_error`, `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`, `primary_website_missing`, `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_error`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `inference_provider_response_empty`, `INFERENCE_PROVIDER_INVALID_JSON`, `inference_provider_invalid_json`, `INFERENCE_PROFILES_MISSING`, `inference_profiles_missing`, `INFERENCE_PROFILE_API_KEY_MISSING`, `inference_profile_api_key_missing` - `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner - `detail` (string, optional) - `details` (DomainConflictDetails, 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. - `error` (map from string to string, optional, nullable) - `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path - `feId` (string, optional, nullable) - `field` (string, optional, nullable) - `hammingDistance` (long, optional, nullable) - `hint` (string, optional, nullable) - `instance` (string, optional) - `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period. - `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count. - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`, `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) — Cap minus used for the limitType meter, never negative. - `requiredRole` (string, optional, nullable) - `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again. - `resolution` (ProblemResolution, 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. - `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff. - `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) — Requests already charged against the limitType meter this period. - `validParameters` (list of string, optional, nullable) - `value` (string, optional, nullable) - `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters. ### 402 Payment Required Error The authenticated caller's subscription does not include this search. - `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted. - Allowed values: `NEW_COMPANY`, `UPDATE`, `NEW_PERSON`, `UPDATE_PERSON`, `ENTITY_VIEW`, `PERSON_VIEW` - `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`, `rate_limited`, `subscription_required`, `subscription_canceled`, `subscription_past_due`, `subscription_paused`, `billing_allowance_exhausted`, `billing_additional_usage_cap_reached`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `suspected_shell_strip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `jobrunr_disabled`, `JOBRUNR_STORAGE_UNAVAILABLE`, `jobrunr_storage_unavailable`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `geocode_provider_error`, `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`, `primary_website_missing`, `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_error`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `inference_provider_response_empty`, `INFERENCE_PROVIDER_INVALID_JSON`, `inference_provider_invalid_json`, `INFERENCE_PROFILES_MISSING`, `inference_profiles_missing`, `INFERENCE_PROFILE_API_KEY_MISSING`, `inference_profile_api_key_missing` - `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner - `detail` (string, optional) - `details` (DomainConflictDetails, 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. - `error` (map from string to string, optional, nullable) - `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path - `feId` (string, optional, nullable) - `field` (string, optional, nullable) - `hammingDistance` (long, optional, nullable) - `hint` (string, optional, nullable) - `instance` (string, optional) - `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period. - `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count. - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`, `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) — Cap minus used for the limitType meter, never negative. - `requiredRole` (string, optional, nullable) - `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again. - `resolution` (ProblemResolution, 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. - `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff. - `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) — Requests already charged against the limitType meter this period. - `validParameters` (list of string, optional, nullable) - `value` (string, optional, nullable) - `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters. ### 403 Forbidden Error Forbidden - `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted. - Allowed values: `NEW_COMPANY`, `UPDATE`, `NEW_PERSON`, `UPDATE_PERSON`, `ENTITY_VIEW`, `PERSON_VIEW` - `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`, `rate_limited`, `subscription_required`, `subscription_canceled`, `subscription_past_due`, `subscription_paused`, `billing_allowance_exhausted`, `billing_additional_usage_cap_reached`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `suspected_shell_strip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `jobrunr_disabled`, `JOBRUNR_STORAGE_UNAVAILABLE`, `jobrunr_storage_unavailable`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `geocode_provider_error`, `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`, `primary_website_missing`, `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_error`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `inference_provider_response_empty`, `INFERENCE_PROVIDER_INVALID_JSON`, `inference_provider_invalid_json`, `INFERENCE_PROFILES_MISSING`, `inference_profiles_missing`, `INFERENCE_PROFILE_API_KEY_MISSING`, `inference_profile_api_key_missing` - `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner - `detail` (string, optional) - `details` (DomainConflictDetails, 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. - `error` (map from string to string, optional, nullable) - `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path - `feId` (string, optional, nullable) - `field` (string, optional, nullable) - `hammingDistance` (long, optional, nullable) - `hint` (string, optional, nullable) - `instance` (string, optional) - `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period. - `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count. - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`, `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) — Cap minus used for the limitType meter, never negative. - `requiredRole` (string, optional, nullable) - `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again. - `resolution` (ProblemResolution, 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. - `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff. - `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) — Requests already charged against the limitType meter this period. - `validParameters` (list of string, optional, nullable) - `value` (string, optional, nullable) - `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters. ### 406 Not Acceptable Error Not Acceptable - `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted. - Allowed values: `NEW_COMPANY`, `UPDATE`, `NEW_PERSON`, `UPDATE_PERSON`, `ENTITY_VIEW`, `PERSON_VIEW` - `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`, `rate_limited`, `subscription_required`, `subscription_canceled`, `subscription_past_due`, `subscription_paused`, `billing_allowance_exhausted`, `billing_additional_usage_cap_reached`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `suspected_shell_strip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `jobrunr_disabled`, `JOBRUNR_STORAGE_UNAVAILABLE`, `jobrunr_storage_unavailable`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `geocode_provider_error`, `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`, `primary_website_missing`, `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_error`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `inference_provider_response_empty`, `INFERENCE_PROVIDER_INVALID_JSON`, `inference_provider_invalid_json`, `INFERENCE_PROFILES_MISSING`, `inference_profiles_missing`, `INFERENCE_PROFILE_API_KEY_MISSING`, `inference_profile_api_key_missing` - `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner - `detail` (string, optional) - `details` (DomainConflictDetails, 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. - `error` (map from string to string, optional, nullable) - `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path - `feId` (string, optional, nullable) - `field` (string, optional, nullable) - `hammingDistance` (long, optional, nullable) - `hint` (string, optional, nullable) - `instance` (string, optional) - `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period. - `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count. - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`, `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) — Cap minus used for the limitType meter, never negative. - `requiredRole` (string, optional, nullable) - `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again. - `resolution` (ProblemResolution, 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. - `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff. - `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) — Requests already charged against the limitType meter this period. - `validParameters` (list of string, optional, nullable) - `value` (string, optional, nullable) - `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters. ### 409 Conflict Error Conflict - `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted. - Allowed values: `NEW_COMPANY`, `UPDATE`, `NEW_PERSON`, `UPDATE_PERSON`, `ENTITY_VIEW`, `PERSON_VIEW` - `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`, `rate_limited`, `subscription_required`, `subscription_canceled`, `subscription_past_due`, `subscription_paused`, `billing_allowance_exhausted`, `billing_additional_usage_cap_reached`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `suspected_shell_strip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `jobrunr_disabled`, `JOBRUNR_STORAGE_UNAVAILABLE`, `jobrunr_storage_unavailable`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `geocode_provider_error`, `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`, `primary_website_missing`, `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_error`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `inference_provider_response_empty`, `INFERENCE_PROVIDER_INVALID_JSON`, `inference_provider_invalid_json`, `INFERENCE_PROFILES_MISSING`, `inference_profiles_missing`, `INFERENCE_PROFILE_API_KEY_MISSING`, `inference_profile_api_key_missing` - `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner - `detail` (string, optional) - `details` (DomainConflictDetails, 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. - `error` (map from string to string, optional, nullable) - `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path - `feId` (string, optional, nullable) - `field` (string, optional, nullable) - `hammingDistance` (long, optional, nullable) - `hint` (string, optional, nullable) - `instance` (string, optional) - `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period. - `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count. - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`, `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) — Cap minus used for the limitType meter, never negative. - `requiredRole` (string, optional, nullable) - `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again. - `resolution` (ProblemResolution, 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. - `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff. - `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) — Requests already charged against the limitType meter this period. - `validParameters` (list of string, optional, nullable) - `value` (string, optional, nullable) - `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters. ### 415 Unsupported Media Type Error Unsupported Media Type - `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted. - Allowed values: `NEW_COMPANY`, `UPDATE`, `NEW_PERSON`, `UPDATE_PERSON`, `ENTITY_VIEW`, `PERSON_VIEW` - `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`, `rate_limited`, `subscription_required`, `subscription_canceled`, `subscription_past_due`, `subscription_paused`, `billing_allowance_exhausted`, `billing_additional_usage_cap_reached`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `suspected_shell_strip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `jobrunr_disabled`, `JOBRUNR_STORAGE_UNAVAILABLE`, `jobrunr_storage_unavailable`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `geocode_provider_error`, `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`, `primary_website_missing`, `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_error`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `inference_provider_response_empty`, `INFERENCE_PROVIDER_INVALID_JSON`, `inference_provider_invalid_json`, `INFERENCE_PROFILES_MISSING`, `inference_profiles_missing`, `INFERENCE_PROFILE_API_KEY_MISSING`, `inference_profile_api_key_missing` - `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner - `detail` (string, optional) - `details` (DomainConflictDetails, 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. - `error` (map from string to string, optional, nullable) - `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path - `feId` (string, optional, nullable) - `field` (string, optional, nullable) - `hammingDistance` (long, optional, nullable) - `hint` (string, optional, nullable) - `instance` (string, optional) - `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period. - `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count. - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`, `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) — Cap minus used for the limitType meter, never negative. - `requiredRole` (string, optional, nullable) - `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again. - `resolution` (ProblemResolution, 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. - `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff. - `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) — Requests already charged against the limitType meter this period. - `validParameters` (list of string, optional, nullable) - `value` (string, optional, nullable) - `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters. ### 422 Unprocessable Entity Error Unprocessable Content - `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted. - Allowed values: `NEW_COMPANY`, `UPDATE`, `NEW_PERSON`, `UPDATE_PERSON`, `ENTITY_VIEW`, `PERSON_VIEW` - `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`, `rate_limited`, `subscription_required`, `subscription_canceled`, `subscription_past_due`, `subscription_paused`, `billing_allowance_exhausted`, `billing_additional_usage_cap_reached`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `suspected_shell_strip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `jobrunr_disabled`, `JOBRUNR_STORAGE_UNAVAILABLE`, `jobrunr_storage_unavailable`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `geocode_provider_error`, `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`, `primary_website_missing`, `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_error`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `inference_provider_response_empty`, `INFERENCE_PROVIDER_INVALID_JSON`, `inference_provider_invalid_json`, `INFERENCE_PROFILES_MISSING`, `inference_profiles_missing`, `INFERENCE_PROFILE_API_KEY_MISSING`, `inference_profile_api_key_missing` - `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner - `detail` (string, optional) - `details` (DomainConflictDetails, 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. - `error` (map from string to string, optional, nullable) - `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path - `feId` (string, optional, nullable) - `field` (string, optional, nullable) - `hammingDistance` (long, optional, nullable) - `hint` (string, optional, nullable) - `instance` (string, optional) - `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period. - `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count. - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`, `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) — Cap minus used for the limitType meter, never negative. - `requiredRole` (string, optional, nullable) - `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again. - `resolution` (ProblemResolution, 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. - `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff. - `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) — Requests already charged against the limitType meter this period. - `validParameters` (list of string, optional, nullable) - `value` (string, optional, nullable) - `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters. ### 429 Too Many Requests Error Too Many Requests - `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted. - Allowed values: `NEW_COMPANY`, `UPDATE`, `NEW_PERSON`, `UPDATE_PERSON`, `ENTITY_VIEW`, `PERSON_VIEW` - `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`, `rate_limited`, `subscription_required`, `subscription_canceled`, `subscription_past_due`, `subscription_paused`, `billing_allowance_exhausted`, `billing_additional_usage_cap_reached`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `suspected_shell_strip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `jobrunr_disabled`, `JOBRUNR_STORAGE_UNAVAILABLE`, `jobrunr_storage_unavailable`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `geocode_provider_error`, `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`, `primary_website_missing`, `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_error`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `inference_provider_response_empty`, `INFERENCE_PROVIDER_INVALID_JSON`, `inference_provider_invalid_json`, `INFERENCE_PROFILES_MISSING`, `inference_profiles_missing`, `INFERENCE_PROFILE_API_KEY_MISSING`, `inference_profile_api_key_missing` - `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner - `detail` (string, optional) - `details` (DomainConflictDetails, 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. - `error` (map from string to string, optional, nullable) - `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path - `feId` (string, optional, nullable) - `field` (string, optional, nullable) - `hammingDistance` (long, optional, nullable) - `hint` (string, optional, nullable) - `instance` (string, optional) - `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period. - `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count. - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`, `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) — Cap minus used for the limitType meter, never negative. - `requiredRole` (string, optional, nullable) - `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again. - `resolution` (ProblemResolution, 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. - `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff. - `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) — Requests already charged against the limitType meter this period. - `validParameters` (list of string, optional, nullable) - `value` (string, optional, nullable) - `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters. ### 500 Internal Server Error Internal Server Error - `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted. - Allowed values: `NEW_COMPANY`, `UPDATE`, `NEW_PERSON`, `UPDATE_PERSON`, `ENTITY_VIEW`, `PERSON_VIEW` - `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`, `rate_limited`, `subscription_required`, `subscription_canceled`, `subscription_past_due`, `subscription_paused`, `billing_allowance_exhausted`, `billing_additional_usage_cap_reached`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `suspected_shell_strip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `jobrunr_disabled`, `JOBRUNR_STORAGE_UNAVAILABLE`, `jobrunr_storage_unavailable`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `geocode_provider_error`, `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`, `primary_website_missing`, `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_error`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `inference_provider_response_empty`, `INFERENCE_PROVIDER_INVALID_JSON`, `inference_provider_invalid_json`, `INFERENCE_PROFILES_MISSING`, `inference_profiles_missing`, `INFERENCE_PROFILE_API_KEY_MISSING`, `inference_profile_api_key_missing` - `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner - `detail` (string, optional) - `details` (DomainConflictDetails, 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. - `error` (map from string to string, optional, nullable) - `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path - `feId` (string, optional, nullable) - `field` (string, optional, nullable) - `hammingDistance` (long, optional, nullable) - `hint` (string, optional, nullable) - `instance` (string, optional) - `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period. - `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count. - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`, `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) — Cap minus used for the limitType meter, never negative. - `requiredRole` (string, optional, nullable) - `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again. - `resolution` (ProblemResolution, 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. - `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff. - `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) — Requests already charged against the limitType meter this period. - `validParameters` (list of string, optional, nullable) - `value` (string, optional, nullable) - `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters. ### 503 Service Unavailable Error Service Unavailable - `allowanceType` (enum, optional) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted. - Allowed values: `NEW_COMPANY`, `UPDATE`, `NEW_PERSON`, `UPDATE_PERSON`, `ENTITY_VIEW`, `PERSON_VIEW` - `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`, `rate_limited`, `subscription_required`, `subscription_canceled`, `subscription_past_due`, `subscription_paused`, `billing_allowance_exhausted`, `billing_additional_usage_cap_reached`, `origin_detail_capacity`, `origin_detail_shutdown`, `suspectedShellStrip`, `suspected_shell_strip`, `url_surface_misclassification`, `JOBRUNR_DISABLED`, `jobrunr_disabled`, `JOBRUNR_STORAGE_UNAVAILABLE`, `jobrunr_storage_unavailable`, `rbac_lookup_unavailable`, `GEOCODE_PROVIDER_ERROR`, `geocode_provider_error`, `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`, `primary_website_missing`, `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_error`, `INFERENCE_PROVIDER_RESPONSE_EMPTY`, `inference_provider_response_empty`, `INFERENCE_PROVIDER_INVALID_JSON`, `inference_provider_invalid_json`, `INFERENCE_PROFILES_MISSING`, `inference_profiles_missing`, `INFERENCE_PROFILE_API_KEY_MISSING`, `inference_profile_api_key_missing` - `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner - `detail` (string, optional) - `details` (DomainConflictDetails, 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. - `error` (map from string to string, optional, nullable) - `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path - `feId` (string, optional, nullable) - `field` (string, optional, nullable) - `hammingDistance` (long, optional, nullable) - `hint` (string, optional, nullable) - `instance` (string, optional) - `limit` (long, optional, nullable) — Cap the limitType meter allows for its current period. - `limitType` (enum, optional) — Which meter refused the request; names what limit/used/remaining count. - Allowed values: `FORM`, `GLOBAL`, `SUBNET`, `IP`, `UNKNOWN`, `RESILIENCE4J`, `WEB_SEARCH`, `NATURAL_SEARCH`, `BILLING_ALLOWANCE`, `BILLING_ADDITIONAL_USAGE`, `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) — Cap minus used for the limitType meter, never negative. - `requiredRole` (string, optional, nullable) - `resetAt` (datetime, optional, nullable) — When the limitType meter refills and the request can succeed again. - `resolution` (ProblemResolution, 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. - `retryAfterSeconds` (long, optional, nullable) — Seconds to wait before the same request can succeed. A BILLING_ALLOWANCE meter resets at the UTC month boundary, so this reaches weeks: read limitType before treating it as a burst backoff. - `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) — Requests already charged against the limitType meter this period. - `validParameters` (list of string, optional, nullable) - `value` (string, optional, nullable) - `windowSeconds` (long, optional, nullable) — Length of a rolling throttle window; absent for period meters. ## Types ### NaturalSearch Plain-English search request. The server plans the query into the target domain filter plus sort, then runs that domain's canonical list engine. - `query` (string, required) — Plain-English search request. - `mode` (enum, optional) — Search strategy to run. Defaults to `auto`: the fast name layer runs first (a single-token query as keyword search, a multiword query as an exact normalized name) and the language-model planner runs only on a miss, so name lookups never pay for planning. Any other value forces exactly that strategy: `exact` and `keyword` skip planner model resolution and its rate limit. Entity and person natural-search take every value; news and federated search accept only `auto` and `keyword`; content search accepts only `auto`. - Allowed values: `auto`, `exact`, `keyword`, `semantic`, `natural` - `model` (string, optional, nullable) — Optional chat model for planning; null uses the configured natural-search default. A caller without admin authority may only choose an allowlisted model; admin callers are unrestricted. ### PersonFilter Canonical person criteria contract for GET/POST/batch endpoints - `arrayFilter` (PersonListArrayFilter, optional) — Array and range filters - `entityId` (string, optional, nullable) — Associated entity UUID. - `entitySlug` (string, optional, nullable) — Associated entity slug. - `firstName` (string, optional, nullable) — Person first name. - `includeAddress` (boolean, optional, nullable) — Include addresses on each person - `includeUrl` (boolean, optional, nullable) — Include URL links on each person - `investorActivity` (InvestorActivityFilter, optional) — Aggregate investor activity filters. - `isCurrent` (boolean, optional, nullable) — Filter current associations. - `lastName` (string, optional, nullable) — Person last name. - `letter` (string, optional, nullable) — First-name initial. - `personId` (list of string, optional) — Restrict results to specific person IDs. Omit or use [] for no ID restriction. - `personName` (list of string, optional) — Exact normalized match against a person's full name or slug. - `role` (string, optional, nullable) — Associated entity role or title. - `search` (string, optional, nullable) — Search keyword or phrase. Single characters valid; stop words rejected. - `semanticQuery` (string, optional, nullable) — Semantic person search phrase. - `status` (string, optional, nullable) — Person workflow status. ### PersonSearchInterpretation Structured interpretation of a natural-language people search: canonical filter, sort, confidence, and any unsupported constraint the planner could not translate exactly. - `confidence` (enum, required) — Planner confidence in the structured interpretation. - Allowed values: `HIGH`, `MEDIUM`, `LOW` - `execution` (SearchModeExecution, required) — Requested and executed search strategy. - `fallbackUsed` (boolean, required) — True when the semantic fallback replaced an unconstrained planner result with a semantic search over the original query. - `filter` (PersonFilter, required) — Canonical person filter generated from the natural-language query. - `interpretation` (string, required) — Human-readable summary of how the query was interpreted. - `sort` (SearchOrderingPersonSortField, required) — Ordering applied to the result page: the relevance rank that ran first, if any, then the sortable-column terms. - `unsupported` (string, optional, nullable) — Constraint the planner could not translate into the canonical PersonFilter contract; null when every material constraint was supported. ### PageResultPerson - `content` (list of Person, required) - `number` (integer, required) - `size` (integer, required) - `totalElements` (long, required) - `totalPages` (integer, required) ### CurrentSlugOwner 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) ### DomainConflictDetails Polymorphic envelope for RFC 9457 ProblemDetail.details on HTTP 409 responses. The concrete variant depends on the conflict kind: URL ownership collisions return UrlDuplicateConflict; ambiguous strict URL lookups return StrictUrlLookupConflict; create-time duplicate review gates return DuplicateCreateReview; classification writes that touch an inactive tag bucket return ClassificationInactiveTagDetails; news publication+URL uniqueness violations return NewsSourceUrlConflict. Inspect ProblemDetail.code/type and the field set present on details to identify the variant. ### RedirectSlugPath 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` ### ProblemResolution 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. ### PersonListArrayFilter Array and range filters for person list endpoints - `amountInvestedRange` (list of DecimalRange, optional, nullable) - `amountRaisedRange` (list of DecimalRange, optional, nullable) - `entityName` (list of string, optional, nullable) — Associated entity names. - `investedCompany` (list of string, optional, nullable) — Invested company names. - `personTitle` (list of string, optional, nullable) — Person titles. - `round` (list of string, optional, nullable) — Fundraise round labels. - `totalInvestmentCount` (list of IntRange, optional, nullable) - `typeRecord` (list of enum, optional, nullable) — Associated entity type scope. Omit or use [] for any associated type. - Allowed values: `Company`, `Investment Firm`, `Fund`, `Nonprofit`, `Government`, `Organization`, `Business Line`, `Product`, `Service` ### InvestorActivityFilter Aggregate investor activity filters from distinct fundraise deals and USD amounts. - `averageAmountInvestedUsdRange` (list of DecimalRange, optional) - `largestAmountInvestedUsdRange` (list of DecimalRange, optional) - `smallestAmountInvestedUsdRange` (list of DecimalRange, optional) - `totalAmountInvestedUsdRange` (list of DecimalRange, optional) - `totalInvestmentRange` (list of IntRange, optional) ### SearchModeExecution Search strategy requested by the caller and executed by the canonical engine. - `modeRequested` (enum, required) — Search mode requested by the caller. - Allowed values: `auto`, `exact`, `keyword`, `semantic`, `natural` - `modeUsed` (enum, required) — Search mode executed by the canonical engine. - Allowed values: `auto`, `exact`, `keyword`, `semantic`, `natural` ### SearchOrderingPersonSortField Ordering applied to a search result page: an optional relevance rank that precedes the sortable-column terms. - `order` (list of SortOrderPersonSortField, required) — Sortable-column terms applied after the relevance rank, highest precedence first. Empty when the relevance rank alone ordered the page. Listing priorities that every list page applies ahead of these terms, such as operating-status and logo priority, are not reported. - `relevance` (enum, optional, nullable) — Relevance rank applied before any column term; absent when no relevance rank ran. - Allowed values: `keyword`, `semantic` ### Person Canonical person core record - `id` (string, required) — Canonical person UUID - `image` (PersonImage, required) — Read projection: person image fields for detail/list responses - `nameAlias` (list of EntityNameAliasPersonAliasType, required) — Display and search aliases for this person - `nameFull` (string, required) - `slug` (string, required) — Canonical lowercase URL slug for the resource - `text` (EntityTextBundle, required) — Grouped person text content - `createdAt` (datetime, optional, nullable) — Record creation timestamp - `gender` (string, optional, nullable) - `lastModifiedAt` (datetime, optional, nullable) — Provenance-grounded last-modified watermark (schema.org dateModified): the latest effective time across all writes attributed to this person. - `nameFirst` (string, optional, nullable) - `nameLast` (string, optional, nullable) - `nameMiddle` (string, optional, nullable) - `nickname` (string, optional, nullable) - `publicId` (string, optional, nullable) — Stable, immutable public handle (e.g. `pV1StGXR8Z5ab`). Never changes once assigned, unlike the slug. Null on projections that do not select it and on rows still awaiting handle backfill. - `semanticMatch` (ContentEmbeddingMatch, optional, nullable) — Semantic embedding match evidence populated only for semantic people reads. - `suffix` (string, optional, nullable) - `updatedAt` (datetime, optional, nullable) — Last modification timestamp ### UrlDuplicateConflict Typed extension on ProblemDetail.details for HTTP 409 when a create/update attempts to set a URL with urlType=website (or another exclusive urlType) that is already a current URL on a different entity or person. The existingJoin list names every current owner of the normalized URL; resolve by demoting the existing owner (isCurrent=false, isPrimary=false) before promoting the new owner. - `existingJoin` (list of UrlDuplicateJoin, required) — Every current owner that already holds the normalized URL with this urlType. Non-empty when this conflict is emitted. - `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` (EntityPersonOwner, required) — Owner the caller attempted to attach the URL to. - `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 Typed extension on ProblemDetail.details for HTTP 409 when a strict URL lookup (GET /v1/entities/lookup?url=...) resolves to more than one current owner. The candidate lists return every current owner that matches the normalized URL key; the caller must add disambiguating signals (urlType, typeRecord, slug) to resolve to a single owner. - `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 Candidate-review conflict details returned in ProblemDetail.details for create gates and deterministic lookup ambiguity. The returned candidates are the decision surface: update the matching candidate, create with duplicate override only when every candidate is distinct from the source-backed target, or block when identity is unresolved. score and threshold rank review priority; they are not proof that the requested record is absent. - `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 SearchDuplicateCandidateScore, 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. - `newsCandidate` (list of NewsCandidateScore, 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. - `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 ProblemDetail.details for HTTP 409 when a classification value exists but is inactive. - `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 Typed extension on ProblemDetail.details for HTTP 409 when a news mutation's publication + newsUrlOriginal pair already belongs to another article. The returned fields identify the existing article so the caller can read/update it instead of creating a duplicate. - `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/lookup?slug= to fetch the conflicting article. - `conflictingArticleTitle` (string, required) — Existing article title for human-readable diagnostics. ### DecimalRange Decimal range for monetary and numeric filter criteria - `max` (double, optional, nullable) — Inclusive maximum decimal number, such as 220000 or 123456.78. - `min` (double, optional, nullable) — Inclusive minimum decimal number, such as 220000 or 123456.78. ### IntRange Integer range for count-based filter criteria - `max` (integer, optional, nullable) — Inclusive maximum integer. - `min` (integer, optional, nullable) — Inclusive minimum integer. ### SortOrderPersonSortField Single sort term: which enumerated sort field to use and whether direction is descending. - `descending` (boolean, required) — true for descending (DESC), false for ascending (ASC) - `field` (enum, required) — Sort field for this resource (entity list uses EntityFilter.Sortable / published sort keys). - Allowed values: `ID`, `FIRST_NAME`, `LAST_NAME`, `FULL_NAME`, `SLUG`, `CREATED_AT`, `UPDATED_AT`, `STATUS`, `GENDER`, `AMOUNT_INVESTED`, `TOTAL_INVESTMENTS` ### PersonImage Read projection: person image fields for detail/list responses - `isMonogram` (boolean, required) — Whether person image monogram - `picture` (string, optional, nullable) ### EntityNameAliasPersonAliasType Alternate name used for search and display - `name` (string, required) — Alternate name text - `displayable` (boolean, optional, nullable) — Show this alias in public name displays. - `type` (enum, optional, nullable) — Alias type classification - Allowed values: `nickname`, `maidenName`, `formerName`, `stageName` ### EntityTextBundle Grouped entity/person text content - `expanded` (string, optional, nullable) — Expanded summary text - `generatedDescription` (string, optional, nullable) — Generated SEO meta description text - `short` (string, optional, nullable) — Short summary text ### ContentEmbeddingMatch Nearest-neighbor content embedding match evidence. - `computedAt` (datetime, required) — Timestamp when the embedding row was computed. - `cosineDistance` (double, required) — pgvector cosine distance where lower is closer. - `cosineScore` (double, required) — Cosine similarity score where higher is closer. - `modelVersion` (string, required) — Embedding model/profile version for this row. - `rank` (integer, required) — One-based semantic rank within the returned ANN candidate set. - `sourceHash` (string, required) — SHA-256 hash of the source content. - `sourceId` (string, required) — Content embedding source identifier. - `sourceJson` (string, required) — Serialized JSONB source document stored for the embedding row. - `sourceText` (string, required) — Source text used to compute the stored embedding. - `sourceType` (enum, required) — Stored content embedding source partition. - Allowed values: `entity`, `person`, `newsArticle`, `blogPost`, `text`, `classificationTag`, `classificationCode`, `product`, `service`, `agentHelpDoc` ### UrlDuplicateJoin URL ownership join row identifying which entity or person currently owns a normalized URL. - `owner` (EntityPersonOwner, 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. - `urlId` (integer, required) — Internal URL row id (res_weburl.id) — opaque to API clients. ### EntityPersonOwner Exactly one of entityId or personId is set; ids only, no name fields. Resolve display names with GET /v1/entities/detail or GET /v1/people/\{personId}. - `entityId` (string, optional, nullable) — Canonical entity UUID - `personId` (string, optional, nullable) — Canonical person UUID ### SearchDuplicateCandidateScore Duplicate candidate scoring result. Use id/name/slug/typeRecord/reason to decide whether the candidate is the requested record. score ranks review priority; it does not prove absence. - `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-current, url-type, or precomputed-similarity. url-match proves the supplied URL/domain matched; url-current additionally proves the candidate still holds that address today, so a candidate with url-match but no url-current matched only through a URL it no longer uses, such as an acquisition redirect. 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` ### NewsCandidateScore Duplicate candidate scoring result for news articles. Use id/slug/externalId/reason to decide whether the candidate is the requested article. score ranks review priority; it does not prove absence. - `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. ## Examples **Request** ```json { "search": { "query": "Companies founded in the last year that raised venture capital" } } ``` **Response** ```json { "interpretation": { "confidence": "HIGH", "execution": { "modeRequested": "auto", "modeUsed": "auto" }, "fallbackUsed": true, "filter": { "arrayFilter": { "amountInvestedRange": [ { "max": 1.1, "min": 1.1 } ], "amountRaisedRange": [ { "max": 1.1, "min": 1.1 } ], "entityName": [ "string" ], "investedCompany": [ "string" ], "personTitle": [ "string" ], "round": [ "string" ], "totalInvestmentCount": [ { "max": 1, "min": 1 } ], "typeRecord": [ "Company" ] }, "entityId": "string", "entitySlug": "string", "firstName": "string", "includeAddress": true, "includeUrl": true, "investorActivity": { "averageAmountInvestedUsdRange": [ { "max": 1.1, "min": 1.1 } ], "largestAmountInvestedUsdRange": [ { "max": 1.1, "min": 1.1 } ], "smallestAmountInvestedUsdRange": [ { "max": 1.1, "min": 1.1 } ], "totalAmountInvestedUsdRange": [ { "max": 1.1, "min": 1.1 } ], "totalInvestmentRange": [ { "max": 1, "min": 1 } ] }, "isCurrent": true, "lastName": "string", "letter": "A", "personId": [ "string" ], "personName": [ "string" ], "role": "string", "search": "AI", "semanticQuery": "string", "status": "string" }, "interpretation": "string", "sort": { "order": [ { "descending": true, "field": "ID" } ], "relevance": "keyword" }, "unsupported": "string" }, "result": { "content": [ { "id": "string", "image": { "isMonogram": true, "picture": "string" }, "nameAlias": [ { "name": "Bun", "displayable": true, "type": "nickname" } ], "nameFull": "string", "slug": "aventure-vc", "text": { "expanded": "Canonical expanded summary for grouped text assertions.", "generatedDescription": "Acme AI builds AI copilots for growth teams.", "short": "Canonical short summary" }, "createdAt": "2024-01-15T09:30:00Z", "gender": "string", "lastModifiedAt": "2024-01-15T09:30:00Z", "nameFirst": "string", "nameLast": "string", "nameMiddle": "string", "nickname": "string", "publicId": "pV1StGXR8Z5ab", "semanticMatch": { "computedAt": "2024-01-15T09:30:00Z", "cosineDistance": 1.1, "cosineScore": 1.1, "modelVersion": "string", "rank": 1, "sourceHash": "string", "sourceId": "string", "sourceJson": "string", "sourceText": "string", "sourceType": "entity" }, "suffix": "string", "updatedAt": "2024-01-15T09:30:00Z" } ], "number": 1, "size": 1, "totalElements": 1, "totalPages": 1 } } ``` **SDK Code** ```python import requests url = "https://api.aventure.vc/v1/search/natural/people" payload = { "search": { "query": "Companies founded in the last year that raised venture capital" } } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.aventure.vc/v1/search/natural/people'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"search":{"query":"Companies founded in the last year that raised venture capital"}}' }; 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" "strings" "net/http" "io" ) func main() { url := "https://api.aventure.vc/v1/search/natural/people" payload := strings.NewReader("{\n \"search\": {\n \"query\": \"Companies founded in the last year that raised venture capital\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") 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/search/natural/people") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"search\": {\n \"query\": \"Companies founded in the last year that raised venture capital\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.aventure.vc/v1/search/natural/people") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"search\": {\n \"query\": \"Companies founded in the last year that raised venture capital\"\n }\n}") .asString(); ``` ```php request('POST', 'https://api.aventure.vc/v1/search/natural/people', [ 'body' => '{ "search": { "query": "Companies founded in the last year that raised venture capital" } }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.aventure.vc/v1/search/natural/people"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"search\": {\n \"query\": \"Companies founded in the last year that raised venture capital\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = ["search": ["query": "Companies founded in the last year that raised venture capital"]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.aventure.vc/v1/search/natural/people")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data 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() ```