aVenture APIEntity Research

Replace research detail

View as Markdown

Replaces a specific catalog-governed research detail row for an entity. Use replace to correct a row believed wrong, not to refresh time-series history; create a new row for a new dated observation. Use entities relationships join for acceleratorParticipant rows.

Authentication

AuthorizationBearer

User bearer token: Supabase or Clerk session JWT, Clerk OAuth access token, or Clerk personal API key

OR
X-API-Keystring

Admin API key for system-to-system write operations

Path parameters

entityIdstringRequiredformat: "uuid"
Canonical entity UUID.
detailIdintegerRequired
Research detail id.

Query parameters

sourceTypeenumRequired
Write provenance source type.
sourceDetailstringRequired
Source detail or reviewer reference for the write.
sourceProviderstringOptional

Provider name for provider-native IDs or slugs.

sourceProviderIdstringOptional

Provider-native source ID.

sourceProviderSlugstringOptional

Provider-native source slug.

actorTypeenumOptional

Actor type; inferred as agent when agentChassis and agentModel are supplied, or as employee from an authenticated user JWT session.

Allowed values:
agentChassisstringOptional

Agent chassis token for agent-authored writes.

agentModelstringOptional

Agent model id for agent-authored writes.

Request

This endpoint expects an object.
typeResearchDetailstringRequired

Research detail type token. Run GET /v1/entities/research/details/types (CLI: entities research details types list) for the token inventory and each token’s value shape.

asOfDatedatetime or nullOptional
Observation timestamp for dated detail shapes.
creatorstring or nullOptional
Creator identifier for the research detail.
dataConfidenceenum or nullOptional

Confidence tier for the research detail: low, medium, or high. Omitting it persists NULL — no default is fabricated.

discreteValuedouble or nullOptional

Numeric value for monetary, ratio, score, count, and growth-rate details. numericGrowthRate uses percentage points: send 80 for 80%, not 0.8; use the selected detail type’s range.

sourcestring or nullOptional
Legacy source display text. Prefer provenance query parameters.
textValuestring or nullOptional

Text value for free-text or employee-range details. Generic research details reject acceleratorParticipation writes; use entities relationships join. Write ’$’ literally in currency text — escaped forms such as ‘$1M’ are rejected as shell artifacts; monetary amounts belong in discreteValue, not textValue.

valueResearchDetailstring or nullOptional

String value for token, currency, period, date-interval, or target-duration shapes. monetaryFlow packs “CURRENCY|PERIOD” (e.g. “USD|P1Y”); monetaryFlowOverPeriod packs “CURRENCY|START/END” as an ISO-8601 date interval (e.g. “USD|2021-01-01/2025-12-31”), with asOfDate holding the separate report date.

Response

OK
entityIdstringformat: "uuid"
Canonical entity UUID
idinteger
typeResearchDetailstring
valueTypeenum
Output kind for governed research detail values
asOfDatedatetime or nullOptional
createdAtdatetime or nullOptional
creatorstring or nullOptional
dataConfidenceenum or nullOptional

Confidence tier stored verbatim in res_entity_detail.data_confidence.

derivedRangeobject or nullOptionalRead-only

Read-only range derived only for targetDateAbsolute detail rows

discreteValuedouble or nullOptional
textValuestring or nullOptional
updatedAtdatetime or nullOptional
valueResearchDetailstring or nullOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
406
Not Acceptable Error
409
Conflict Error
415
Unsupported Media Type Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error