aVenture APIEntity Research

Create research snippet

View as Markdown
Creates a research snippet for an entity. Snippets are an append-only time series: creating a row defaults isCurrent/isPrimary to true and demotes the prior current/primary row of the same textType to inactive history, so refresh by creating a new row rather than overwriting. Pass a textType listed by GET /v1/entities/research/snippets/types: those are validated against the type's length and paragraph rules and are visible by default. An unrecognized textType is still saved but defaults to visible=false (hidden from default reads). The response returns a NOT_VISIBLE warning header whenever the saved row is hidden (visible=false), and no warning when it is visible; send visible=true to publish an unrecognized type anyway.

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.

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

Snippet body text. Recognized types enforce the length and paragraph rules returned by the types endpoint. Write ’$’ literally in currency amounts — escaped forms such as ‘$95 million’ are rejected as shell artifacts; in a shell, pass the text via ANSI-C $’…’ quoting or —from-file.

textTypestringRequired

Research snippet type token. Use one listed by GET /v1/entities/research/snippets/types for validation and default visibility; an unrecognized token is saved hidden (visible=false) unless visible=true is sent.

allowSuspectedShellStripboolean or nullOptional

Override suspected shell-strip rejection for intentional prose that looks like a money phrase without a currency marker, or that intentionally contains an escape sequence before ’$’. Prefer fixing shell quotes or using —from-file; set true only after confirming the value is intentional.

creatorstring or nullOptional
Creator identifier for the snippet write.
isCurrentboolean or nullOptional

Create defaults to true and appends a NEW current row, demoting the prior current row of this type to inactive history. Set false to write a non-current historical row.

isPrimaryboolean or nullOptional

Primary row among current snippets of this type. Defaults to true when the row is current; promoting demotes the prior primary.

visibleboolean or nullOptional

Whether the snippet appears in default reads. Omit to use the type default (recognized types visible, unrecognized types hidden); set explicitly to override.

Response

OK
entityIdstringformat: "uuid"
Canonical entity UUID
idinteger
isCurrentboolean

Current row. The live snippet for its type; demoted historical rows read only with includePrivate.

isPrimaryboolean
Primary row among the current snippets of its type.
textstring
textTypestring
visibleboolean

Whether the snippet appears in default reads. Admin/private reads (includePrivate) also return hidden rows.

complianceobject or nullOptional

Derived character/word counts and governed-contract compliance for this snippet row; null when not evaluated.

createdAtdatetime or nullOptional
updatedAtdatetime 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