> 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.

# Edit a Research Draft Section

PUT https://api.aventure.vc/v1/research-runs/{runId}/draft/sections/{sectionKey}
Content-Type: application/json

Replace one section of your run's private draft. The section key must equal the path key and an exact research snippet typeValue. A stale expectedVersion returns 409 without changing the draft. Read your draft's latest version before retrying. Editing an existing run uses no additional research allowance.

Reference: https://docs.aventure.vc/api-reference/research-runs/put-research-run-draft-section

## Authentication

- `Authorization` header (bearer token, required) — Your aVenture API key (https://aventure.vc/settings/api-keys) or OAuth access token

## Request

### Path parameters

- `runId` (string, required) — Research run id
- `sectionKey` (string, required) — Exact research snippet typeValue, matching the section body key.

### Query parameters

- `expectedVersion` (integer, required) — Version returned by the draft read; zero before the first edit.

### Body (application/json)

This endpoint expects an EntityAnalysisSection.

- `citation` (list of EntityAnalysisCitation, required) — Stored source documents and verbatim evidence quotes; verification occurs before publication.
- `key` (string, required) — Exact typeValue from GET /v1/entities/research-snippets/types; also the section path key.
- `origin` (string, required) — Author of this edit; the server derives this from the authenticated caller.
- `paragraph` (list of EntityAnalysisParagraph, required) — Paragraphs in catalog order, satisfying paragraphShape and analysisSectionLabel.
- `title` (string, required) — Heading displayed above this section.
- `figure` (list of EntityAnalysisFigure, optional) — At most two figures illustrating this section; each cell excerpts one of its quotes.

## Response

### 200

OK

- `entityId` (string, required) — Entity researched by this run.
- `runId` (string, required) — Run that owns this private draft.
- `section` (list of EntityAnalysisSection, required) — Current sections, each identified by its snippet type key.
- `version` (integer, required) — Latest analysis-section event sequence; zero before the first section.

## Errors

### 400 Bad Request Error

Bad Request

- `allowanceType` (string, optional, nullable) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — 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 describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `disposition` (enum, optional) — Whether a service-unavailable failure can be retried.
  - Allowed values: `TRANSIENT`, `TERMINAL`
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `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` (string, optional, nullable) — Which meter refused the request; names what limit/used/remaining count.
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `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` (string, optional, nullable) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — 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 describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `disposition` (enum, optional) — Whether a service-unavailable failure can be retried.
  - Allowed values: `TRANSIENT`, `TERMINAL`
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `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` (string, optional, nullable) — Which meter refused the request; names what limit/used/remaining count.
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `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` (string, optional, nullable) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — 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 describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `disposition` (enum, optional) — Whether a service-unavailable failure can be retried.
  - Allowed values: `TRANSIENT`, `TERMINAL`
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `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` (string, optional, nullable) — Which meter refused the request; names what limit/used/remaining count.
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `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.

### 404 Not Found Error

Not Found

- `allowanceType` (string, optional, nullable) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — 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 describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `disposition` (enum, optional) — Whether a service-unavailable failure can be retried.
  - Allowed values: `TRANSIENT`, `TERMINAL`
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `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` (string, optional, nullable) — Which meter refused the request; names what limit/used/remaining count.
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `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` (string, optional, nullable) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — 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 describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `disposition` (enum, optional) — Whether a service-unavailable failure can be retried.
  - Allowed values: `TRANSIENT`, `TERMINAL`
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `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` (string, optional, nullable) — Which meter refused the request; names what limit/used/remaining count.
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `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` (string, optional, nullable) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — 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 describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `disposition` (enum, optional) — Whether a service-unavailable failure can be retried.
  - Allowed values: `TRANSIENT`, `TERMINAL`
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `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` (string, optional, nullable) — Which meter refused the request; names what limit/used/remaining count.
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `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` (string, optional, nullable) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — 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 describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `disposition` (enum, optional) — Whether a service-unavailable failure can be retried.
  - Allowed values: `TRANSIENT`, `TERMINAL`
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `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` (string, optional, nullable) — Which meter refused the request; names what limit/used/remaining count.
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `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` (string, optional, nullable) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — 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 describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `disposition` (enum, optional) — Whether a service-unavailable failure can be retried.
  - Allowed values: `TRANSIENT`, `TERMINAL`
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `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` (string, optional, nullable) — Which meter refused the request; names what limit/used/remaining count.
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `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` (string, optional, nullable) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — 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 describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `disposition` (enum, optional) — Whether a service-unavailable failure can be retried.
  - Allowed values: `TRANSIENT`, `TERMINAL`
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `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` (string, optional, nullable) — Which meter refused the request; names what limit/used/remaining count.
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `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` (string, optional, nullable) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — 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 describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `disposition` (enum, optional) — Whether a service-unavailable failure can be retried.
  - Allowed values: `TRANSIENT`, `TERMINAL`
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `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` (string, optional, nullable) — Which meter refused the request; names what limit/used/remaining count.
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `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` (string, optional, nullable) — Which monthly allowance a BILLING_ALLOWANCE refusal exhausted.
- `circuitBreaker` (string, optional, nullable)
- `code` (string, optional, nullable) — 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 describe server-side conditions a caller cannot fix: surface the error and stop rather than retry.
- `conflictingRecord` (CurrentSlugOwner, optional, nullable) — Current slug owner
- `detail` (string, optional)
- `details` (DomainConflictDetails, optional, nullable) — Structured conflict details. A possible duplicate or an ambiguous lookup returns its candidate records; score and threshold rank the candidates and do not prove that the requested record is absent.
- `disposition` (enum, optional) — Whether a service-unavailable failure can be retried.
  - Allowed values: `TRANSIENT`, `TERMINAL`
- `error` (map from string to string, optional, nullable)
- `existingRecordId` (string, optional, nullable) — On a duplicate 409, the id of the stored record the request collided with; read or update that record instead of creating it again. Absent when the conflict names no single stored record.
- `existingRedirect` (RedirectSlugPath, optional, nullable) — Redirect slug path
- `feId` (string, optional, nullable)
- `field` (string, optional, nullable)
- `filedRunId` (list of string, optional, nullable) — Research request ids a batch filed or reused for its other records before returning this error; absent for every other error.
- `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` (string, optional, nullable) — Which meter refused the request; names what limit/used/remaining count.
- `matchedBlocklistKey` (string, optional, nullable)
- `mediaType` (string, optional, nullable)
- `moderationReason` (string, optional, nullable)
- `path` (string, optional, nullable)
- `properties` (map from string to any, optional)
- `proseViolation` (list of ProseViolation, optional, nullable) — Every rejected passage of a PROSE_REJECTED write, once per problem it shows; absent for every other problem.
- `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

### EntityAnalysisCitation

Verbatim evidence from an archived source document.

- `quote` (string, required) — Nonempty verbatim quote to verify against the archived document.
- `sourceDocumentId` (string, required) — Canonical archived source document UUID.

### EntityAnalysisParagraph

A single paragraph of analysis.

- `text` (string, required) — One nonempty paragraph without embedded line breaks.
- `label` (string, optional, nullable) — Catalog analysisSectionLabel at this position; null for ordinary prose.

### EntityAnalysisFigure

One figure illustrating its section; every cell is a verbatim excerpt of a section quote.

- `entry` (list of EntityAnalysisFigureEntry, required) — Entries in display order: 2-8, or 1-8 for METRIC.
- `title` (string, required) — Caption stating what the figure shows.
- `type` (string, required) — Layout that decides how entries and columns render.
- `column` (list of string, optional) — COMPARISON column headings (1-4, each 1-48 characters), one per cell in every entry; empty otherwise.

### EntityAnalysisSection

One unverified analysis section; replace it by its snippet type key.

- `citation` (list of EntityAnalysisCitation, required) — Stored source documents and verbatim evidence quotes; verification occurs before publication.
- `key` (string, required) — Exact typeValue from GET /v1/entities/research-snippets/types; also the section path key.
- `origin` (string, required) — Author of this edit; the server derives this from the authenticated caller.
- `paragraph` (list of EntityAnalysisParagraph, required) — Paragraphs in catalog order, satisfying paragraphShape and analysisSectionLabel.
- `title` (string, required) — Heading displayed above this section.
- `figure` (list of EntityAnalysisFigure, optional) — At most two figures illustrating this section; each cell excerpts one of its quotes.

### 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

Details of an HTTP 409 conflict. conflictType names the shape: URL_DUPLICATE when the URL is already a current URL on another record; STRICT_URL_LOOKUP when an exact URL lookup matches more than one record; DUPLICATE_CREATE_REVIEW when a create or lookup returns candidate records to review; CLASSIFICATION_INACTIVE_TAG when a classification value exists but is inactive; NEWS_SOURCE_URL when another article already has the same publication and URL.

- `conflictType`: `CLASSIFICATION_INACTIVE_TAG` (CLASSIFICATION_INACTIVE_TAG)
  - `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
- `conflictType`: `DUPLICATE_CREATE_REVIEW` (DUPLICATE_CREATE_REVIEW)
  - `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.
- `conflictType`: `NEWS_SOURCE_URL` (NEWS_SOURCE_URL)
  - `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.
- `conflictType`: `STRICT_URL_LOOKUP` (STRICT_URL_LOOKUP)
  - `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.
- `conflictType`: `URL_DUPLICATE` (URL_DUPLICATE)
  - `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 identity and URL ownership checks.
  - `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).

### 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`

### ProseViolation

One rejected passage and one problem it shows; a passage with several problems appears once per problem.

- `overridable` (boolean, required) — Whether proseOverrideReason can accept this problem; ProblemDetail.hint says when an override is allowed.
- `passage` (string, required) — The rejected sentence, the whole text for a text-contract violation, or the source URL for a legal-page source.
- `problem` (string, required) — The problem this passage shows.
- `reason` (string, required) — Why the passage was rejected and how to fix it.

### 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 or path parameter that needs attention, when applicable.
- `retryable` (boolean, optional, nullable) — Whether the same logical request can be retried after the next action.

### EntityAnalysisFigureEntry

One labeled entry of excerpt cells.

- `cell` (list of EntityAnalysisFigureCell, required) — One cell per COMPARISON column; exactly one cell for every other type.
- `label` (string, required) — Entry heading: the party (COMPARISON), the date as its quote states it (TIMELINE), the step (FLOW), or the measure and period (METRIC).

### 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.
- `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.
- `score` (integer, optional) — 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.
- `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.
- `publicationScore` (integer, required) — Portion of score contributed by the publication match alone; 0 when the publication did not match. A candidate whose score minus publicationScore falls below the review threshold matched only on its outlet, not its story.
- `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.

### UrlDuplicateJoin

Entity or person that 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) — Identifier of the existing URL record that already holds this address.

### 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) — Owning entity id; set only when personId is absent.
- `personId` (string, optional, nullable) — Owning person id; set only when entityId is absent.

### EntityAnalysisFigureCell

A verbatim excerpt of one section citation's quote.

- `citation` (integer, required) — Position of the cited quote in the section's citation list, from 1.
- `excerpt` (string, required) — Exact text copied from that quote; the figure displays it as is.

## Examples

**Request**

```json
{
  "citation": [
    {
      "quote": "string",
      "sourceDocumentId": "string"
    }
  ],
  "key": "string",
  "origin": "string",
  "paragraph": [
    {
      "text": "string"
    }
  ],
  "title": "string"
}
```

**Response**

```json
{
  "entityId": "string",
  "runId": "string",
  "section": [
    {
      "citation": [
        {
          "quote": "string",
          "sourceDocumentId": "string"
        }
      ],
      "key": "string",
      "origin": "string",
      "paragraph": [
        {
          "text": "string",
          "label": "string"
        }
      ],
      "title": "string",
      "figure": [
        {
          "entry": [
            {
              "cell": [
                {
                  "citation": 1,
                  "excerpt": "string"
                }
              ],
              "label": "string"
            }
          ],
          "title": "string",
          "type": "string",
          "column": [
            "string"
          ]
        }
      ]
    }
  ],
  "version": 1
}
```

**SDK Code**

```python
import requests

url = "https://api.aventure.vc/v1/research-runs/runId/draft/sections/sectionKey"

querystring = {"expectedVersion":"1"}

payload = {
    "citation": [
        {
            "quote": "string",
            "sourceDocumentId": "string"
        }
    ],
    "key": "string",
    "origin": "string",
    "paragraph": [{ "text": "string" }],
    "title": "string"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.aventure.vc/v1/research-runs/runId/draft/sections/sectionKey?expectedVersion=1';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"citation":[{"quote":"string","sourceDocumentId":"string"}],"key":"string","origin":"string","paragraph":[{"text":"string"}],"title":"string"}'
};

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/research-runs/runId/draft/sections/sectionKey?expectedVersion=1"

	payload := strings.NewReader("{\n  \"citation\": [\n    {\n      \"quote\": \"string\",\n      \"sourceDocumentId\": \"string\"\n    }\n  ],\n  \"key\": \"string\",\n  \"origin\": \"string\",\n  \"paragraph\": [\n    {\n      \"text\": \"string\"\n    }\n  ],\n  \"title\": \"string\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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/research-runs/runId/draft/sections/sectionKey?expectedVersion=1")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"citation\": [\n    {\n      \"quote\": \"string\",\n      \"sourceDocumentId\": \"string\"\n    }\n  ],\n  \"key\": \"string\",\n  \"origin\": \"string\",\n  \"paragraph\": [\n    {\n      \"text\": \"string\"\n    }\n  ],\n  \"title\": \"string\"\n}"

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.put("https://api.aventure.vc/v1/research-runs/runId/draft/sections/sectionKey?expectedVersion=1")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"citation\": [\n    {\n      \"quote\": \"string\",\n      \"sourceDocumentId\": \"string\"\n    }\n  ],\n  \"key\": \"string\",\n  \"origin\": \"string\",\n  \"paragraph\": [\n    {\n      \"text\": \"string\"\n    }\n  ],\n  \"title\": \"string\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.aventure.vc/v1/research-runs/runId/draft/sections/sectionKey?expectedVersion=1', [
  'body' => '{
  "citation": [
    {
      "quote": "string",
      "sourceDocumentId": "string"
    }
  ],
  "key": "string",
  "origin": "string",
  "paragraph": [
    {
      "text": "string"
    }
  ],
  "title": "string"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.aventure.vc/v1/research-runs/runId/draft/sections/sectionKey?expectedVersion=1");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"citation\": [\n    {\n      \"quote\": \"string\",\n      \"sourceDocumentId\": \"string\"\n    }\n  ],\n  \"key\": \"string\",\n  \"origin\": \"string\",\n  \"paragraph\": [\n    {\n      \"text\": \"string\"\n    }\n  ],\n  \"title\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "citation": [
    [
      "quote": "string",
      "sourceDocumentId": "string"
    ]
  ],
  "key": "string",
  "origin": "string",
  "paragraph": [["text": "string"]],
  "title": "string"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.aventure.vc/v1/research-runs/runId/draft/sections/sectionKey?expectedVersion=1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
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()
```