Data model reference
Exhaustive reference for records, schemas, documents, folders, lookups, references, and version history: methods, parameters, field types, validation rules, limits, envelope shape, error codes, and a "Notes & limits" for each area.
This page does not reproduce the raw endpoint reference — the full request/response shapes are in the generated API reference (OpenAPI / Scalar). Method names below are the Node SDK sub-client methods. The spec is currently at 0.50.0. PATCH and create-by-
typeName-alone require SDK 0.26+ — relevant only if your own integration pins an SDK build older than that; every first-party client is well past it.
Conventions
The list envelope
List, lookup, and version endpoints return a paginated envelope:
{ "data": [ /* items */ ], "nextCursor": "opaque-string-or-null" }
Drain it by feeding the verbatim nextCursor you were given back as startFrom,
until nextCursor is null — that is the only end-of-results signal, on every endpoint
that returns this envelope. A page can come back short, or even empty, while more
results remain; never infer completion from page size or fullness. search.content,
the usage endpoint, GET /v1/models and GET /v1/admin/logs are not enveloped (they return their own shapes).
On list and lookup endpoints, the cursor is opaque and encrypted — never construct,
parse, or store one long-term; a caller-constructed startFrom is rejected with 400,
and a cursor is only valid for the exact query parameters it was issued for. Version
history endpoints (get*Versions) resume from a plain row id instead — still echo
nextCursor back rather than building your own, but it is not encrypted, and a
caller-supplied id is the expected shape there rather than a rejected one.
Page size (limit)
limit is capped, not clamped: on every list/lookup method on this page (listRecords,
lookupRecords, listSchemas, listDocuments, listFolders, listUsers, and the
app-context/access-profile list endpoints in the identity & access
reference) the range is 1–100, defaulting to 20 — a
request for limit: 200 is rejected with 400, not silently reduced to 100 and served.
The SDK does not clamp or auto-paginate on your behalf either: request more than 100 and
the call rejects, exactly as the raw HTTP call would. Page in a loop using nextCursor
(above) rather than requesting a single oversized page. (GET /v1/admin/* audit/access-log
endpoints are a different family with a wider 1–500 range, default 200 — not covered by
this convention.)
Identifiers
typeName, field ids, and lookup field names share one grammar: ^[A-Za-z0-9_-]{1,64}$
— letters (any case), digits, underscore, hyphen; 1–64 characters. camelCase,
snake_case, PascalCase, and kebab-case are all valid. The names userId,
scopes, and externalId are reserved and may not be redeclared as lookup fields or
payload keys.
Timestamps
Creation and modification timestamps are returned as ISO-8601 UTC strings.
Optimistic concurrency
Records, documents, and folders accept an optional expectedVersion on update/patch.
Supply the version you last read; the write is rejected with 409 VERSION_CONFLICT if
the entity changed since, leaving it untouched.
A concurrent write conflicts whether or not you send expectedVersion. An update
that meets another change to the same item between the moment the server read it and the
moment it writes is rejected with 409 VERSION_CONFLICT; nothing is written, the other
change is kept, and you re-read and retry. The server reads the item with a strongly
consistent read when the update starts, so a write that had already finished is always
seen. This covers updates and ?upsert=true requests on records, documents (including an
upload that re-uses an existing document), folders, entities, trigger rules, schemas, app
contexts, roles and namespaces, and the resend of an invitation. An update of an item
deleted a moment earlier returns 404 instead of bringing it back, and a delete that
meets another write to the same item returns a retryable 409 instead of 500. Writes
made from inside a script, a trigger execution, or an atomicity: all_or_nothing record
batch are not covered by this and keep their earlier behavior.
Schemas — client.schemas.*
| Method | Purpose |
|---|---|
createSchema(body) | Create a schema. |
getSchema({ id }) | Fetch by id. |
updateSchema({ id, body }) | PUT full-replace (no PATCH). |
deleteSchema({ id }) | Delete. Refused with 409 while records, documents, users or entities bound to the schema, basedOn variants, or trigger rules that fire off it still exist, or if the platform cannot confirm that none are bound. |
listSchemas({ startFrom?, limit?, surface? }) | List (list envelope). |
getSchemaVersions({ id }) | Version history (list envelope). |
republishSchemaPublicView({ id }) | For a schema whose publicView is in projection mode: rewrite every record's public copy in the background (202, with progress). It also runs on its own whenever the public view changes; each copy written is billed as a record write, and a copy that already matches its record is not rewritten. A request within 10 minutes of a completed republish of the same view that skipped no unreadable record returns that one. SDK 0.50+. |
getSchemaRepublish({ id }) | The progress of the latest republish of a projection schema's public copies: copies written, removed and unchanged, records over the public-copy size limit (oversize) and records that could not be read (unreadable), and a failureReason when it ended FAILED. SDK 0.50+. |
Schema fields
| Field | Type | Required | Notes |
|---|---|---|---|
typeName | string | yes on create | Immutable after create; omit on update. Identifier grammar. Unique within your ownership scope — a different owner may declare a schema under the same typeName via basedOn (see below). |
displayName | string | yes on create | Human-readable name. Omit it on update to keep the current one. |
description | string | no | |
fields | FieldDef[] | no | Omit for a bare schema (no validation). |
lookupFields | LookupDef[] | no | Max 10 (declared by you), of which 7 can be equality lookups unless allowOverflow is set; see lookup notes. |
renderHints | map keyed by fieldId | no | UI hints; does not affect storage/validation. |
capabilities | map<string,boolean> | no | auditHistory (default true) and triggersEnabled (default false, 0.43.0+ — the opt-in a schema must declare before a trigger rule may fire on its records; declaring a rule against a schema without it is a 400). The two are independent: turning audit history off does not turn triggers off. Three more flags: validateReferences (default true; set false to skip the write-time check that a reference field's target exists, for example in an order-unsafe bulk import), readAccessLog (opt-in read-access logging for the records, documents, users or entities this schema types; when unset, your app context's default applies, and the platform default is off), and ttlEligible (default false; must be true before a record of this type may carry expiresAt). ⚠️ capabilities is replaced in full when you supply it, so a PUT that sends a partial map to change one flag drops the other — omit the block entirely to preserve it. A PUT that would turn triggersEnabled off while rules still fire off the schema is refused 409, as is a DELETE of the schema. |
indexMode | enum | no | HYBRID | SEMANTIC | TEXT | NONE. Type-level default for instances. Omit it and a record of this type resolves to NONE (stored and retrievable, not searchable); a document with no mode of its own and no schema default is rejected with a 400. |
storageProfile | enum | no | STANDARD (default) | LOW_LATENCY | LARGE_PAYLOAD. |
allowedSurfaces | string[] | yes on create | Non-empty. Omit it on update to keep the current surfaces. Any of record, document, user, entity. Identity entities in every namespace — org, client, or one you register — bind under the single entity surface, and the schema's typeName tells them apart. An entity-surface schema is written by an ordinary scoped credential in its own context, same as record/document. A user-surface schema stays root-key only: your users are tenant-global, so their schema has one tenant-wide home. GET /v1/schemas?surface=entity reads the caller's own context and the tenant-wide home together, newest context first, through a single cursor. |
active | boolean | no | Default true. Inactive schemas reject new record creation. |
userId / scopes | string / string[] | no | Ownership defaults for the schema itself. scopes is <namespace>:<value> entries, max 2. |
basedOn | string | no | Schema id of the lineage base this schema customizes. The first schema created under a typeName has no basedOn and becomes that name's shared base (must be created by a root/unscoped credential with no userId/scopes); every other schema of that name must declare basedOn, pointing directly at the base (one hop — a variant cannot base off another variant). Immutable once set. |
publicView.geoPrecision | map<string, "exact" | integer> | no | projection mode only: for each geo field listed in publicView.fields, "exact" (the location as stored) or a whole number of metres from 100 to 100000, the minimum edge of the grid cell whose centre the public copy holds. Required for every listed geo field; refused in record mode. The record and your own searches keep the exact location. Changing it on a published type, in either direction, counts as making more data public (the cells of two sizes overlap in a smaller area than either). Geo fields are enabled per account on request. 0.50+. |
FieldDef
| Field | Type | Notes |
|---|---|---|
fieldId | string | Required. Identifier grammar. |
fieldType | enum | string | number | boolean | date | enum | array | object | reference | geo | asset | assets. asset and assets hold public-media images (see the documentTypes row in the blueprints reference). A geo field holds a {lat, lon} WGS84 point (a limited pilot: geo fields are refused unless the pilot is enabled for your account). It cannot be sensitive, searchable, an enum, a lookup or a sortBy target, and is not allowed on a user or entity schema. |
required | boolean | Enforced on every write: the payload of a create, a PUT or a PATCH is validated. |
searchable | boolean | Field text enters the full-text search lane. |
filterable | boolean | Field available as a search filter (no relevance influence). |
description | string | |
validation | object | Validation rules (below). |
enumValues | array | Allowed values for enum fields. |
sensitive | boolean | Redact-at-write + search-exclusion + read-masking + blind-indexed lookup. |
inline | boolean | Keep the field on the record row when the payload is stored out of line (≥ 4 KB, or always on LARGE_PAYLOAD): it appears in list/lookup projections without includePayload, and a trigger rule may project it into input.record. Cannot be combined with sensitive. A schema update that would stop keeping a field inline while a trigger rule still projects it is refused (409); a record or document whose inline fields total more than 224 KB is refused (400). |
targetTypeName | string | reference only: the type pointed at (required for references). |
targetField | string | reference only: target lookup field to resolve against (default externalId; must be a unique lookup on the target). |
cardinality | enum | reference only: one (default) | many. |
targetSurface | string | reference only (required for references): surface the target lives on — record, document, user, or the name of an entity-backed namespace (org, client, or one you registered via POST /v1/namespaces). Not a closed enum — the namespace must already be registered and entity-backed, or the schema is rejected at authoring time. |
geocode | object | geo only, record schemas only: {"from": [...]} names the fields of the same schema that hold the address, in order: at most 10, distinct, each string, enum or number, never sensitive, never the geo field itself (400 otherwise, and on a schema whose allowedSurfaces include document). After a write that changes the address and sends no value for the field, the field is cleared and its location is looked up afterwards; a new geo value sent with the address is kept for that address. The field and its from fields are always kept on the record row (as inline is), so a trigger rule may project them. Progress is geocodeStatus on the record. Geocoding a record sends only its address to Amazon Location Service; nothing else about the record is sent. Address geocoding runs on Amazon Location Service under our AWS BAA; the location provider may process the address outside the US. Addresses in Japan are not geocoded. Geo fields are enabled per account on request. 0.50+. |
A geocoded field on a public view. In record mode every field is public as stored, so a geo field filled from an address is public at its exact location, and so are its address fields. A projection view publishes it at its geoPrecision, and an address field only if you list it (vectros blueprint plan flags one listed next to a coarsened location). While its location is unknown (PENDING, NOT_FOUND or FAILED), the public copy carries none, so the record is not found by a public near.* search.
Validation rules (the validation object)
required, minLength, maxLength, min, max, pattern, email, url, phone,
step, multipleOf, minItems, maxItems. Rules are enforced at record write; a
violation returns a 400 with a readable message before the record is persisted.
64-bit number range (platform-wide, independent of any schema min/max). Every JSON
number you write — in any field, whether or not your schema declares it, and in a search
request body as well as a payload — must fall within the signed 64-bit range
(−9223372036854775808 to 9223372036854775807), carry at most 38 significant digits, and be
finite. A value outside that range (or a magnitude below roughly 1e-130) is rejected with a
400 naming the field. Store a large whole number you need to preserve exactly — an external
id, an account number, epoch-nanoseconds — in a string field: it keeps the digits byte-exact
and still supports exact-match lookup, where a number field would round or reject. (A record
written before this rule that holds an out-of-range number may now read back with that field
absent or coerced to a string.)
LookupDef
A lookup declares either a single field or a composite of fields — never both, and
fieldName is optional on LookupDef precisely because a composite entry omits it:
- Single-field: a bare field name string, or
{ fieldName, unique }.unique: trueenforces one record per value per tenant+context. - Composite (
recordsurface only):{ fieldNames: [...] }— two or three field names, in the order they'll be queried; that order is fixed once the schema is live. A composite lookup cannot setuniqueorrangeEnabled. Code that reads or writes a schema'slookupFieldsmust handlefieldNamebeing absent whenfieldNamesis present — this is the one breaking shape change for typed clients this release. sortBy— which field this lookup's results are ordered by:createdAt(the default),lastUpdated, or any other declared field (must not besensitive). This is authored once, on the schema, not chosen per-query — see "Sort order" below for how that interacts with theorderquery parameter.
RenderHintDef
label, widget (text | textarea | select | date | checkbox), order,
section, helpText, displayField (marks the headline field; at most one per schema).
Schema versioning
schemaVersion is a public revision counter: 1 on create, prior + 1 on each update.
Records and documents are stamped with the governing schemaVersion at write and keep
that value even after the schema evolves. getSchemaVersions returns the immutable
version-row history (same envelope and row shape as record versions).
Notes & limits — schemas
- No PATCH. Schemas are PUT-replace only. Collection fields (
fields,lookupFields,renderHints,capabilities) are replaced in full on update — supply the complete intended set; omitted scalar fields are preserved. typeNameis immutable after creation.- Creating a schema is idempotent by
typeName, within your own ownership scope. Re-issuingcreateSchemafor atypeNameyou already own returns your existing schema rather than failing, so re-running your own provisioning step is safe. To change a schema, update it (PUT-replace). - A different owner reusing an existing
typeNamemust declarebasedOn. The first schema created under a name becomes that name's shared base (root/unscoped credential only, nouserId/scopes); every other owner defining a schema under the same name must setbasedOnto the base's schema id, or the create is rejected with a400. A variant stays the same conceptual type as the base for references, listings, and blueprints, while declaring its own fields/validation. - A bare schema runs no payload validation; all string values are still text-indexed for search when its index mode permits.
- An item whose schema no longer exists is not served. Reading such a record, document, entity or user returns an error instead of its content; updating it, reading its version history, and reading a document's text, download or answers are refused; and lists, batch reads and lookups leave it out. Delete the item.
Records — client.records.*
| Method | Purpose |
|---|---|
createRecord(body) | Create. typeName and/or schemaId (see below). |
getRecord({ id }) | Fetch by id (always full payload). |
updateRecord({ id, body }) | PUT — replace mutable fields; payload replaced in full. |
patchRecord({ id, body }) | PATCH (RFC 7386). SDK 0.26+. |
deleteRecord({ id }) | Hard delete (+ tombstone). |
listRecords({ type, userId?, scope?, startFrom?, limit?, includePayload? }) | List (list envelope). scope is one <namespace>:<value> filter (e.g. org:<id>) per call. |
lookupRecords({ type, field, value?+sortFrom?+sortTo? | values?+sortFrom?+sortTo? | from?+to? | prefix?, order?, startFrom?, limit?, includePayload? }) | Lookup, one mode (list envelope). For a composite lookup, field is comma-joined and pairs with values (array, order matches the schema's fieldNames). order (asc|desc) is direction only — see Sort order below; the sorted field itself is the schema's sortBy, not a call-time choice. |
lookupRecordsByBody({ ... }) | Body-based lookup (sensitive-safe). |
getRecordVersions({ id }) | Version history (list envelope). |
getRecordTombstone({ id }) | Tombstone for a deleted record. |
getRecordPublicView({ id }) | For a record whose type's publicView is in projection mode: its public copy (only the listed fields), or published: false (also while its copy does not yet match the record). SDK 0.50+. |
getRecordPublicView → geoPrecision | On the public copy (and on the public record and list responses): the precision of each geo field present in fields, "exact" or the minimum cell edge in metres whose centre the field holds; omitted when no geo field is public. SDK 0.50+. |
Create / update fields (RecordRequest)
| Field | Type | Notes |
|---|---|---|
typeName | string | The record type. See type-identification below. Immutable; ignored on update. |
schemaId | string | Schema to validate against. See below. Immutable; ignored on update. |
payload | object | Validated against the schema. On PUT, replaces the stored payload in full. |
status | string | ACTIVE (default) or ARCHIVED; any other value is a 400. An archived record leaves search and RAG but stays stored; set it back to ACTIVE to restore it. |
folderId | string | Group with a folder. Cannot currently be cleared once set. |
userId | string | Ownership (Vectros user UUID). Subject to token identity auto-assign. |
scopes | string[] | Ownership entity edges, each <namespace>:<value> (org:..., client:..., or a namespace you registered) — at most two. On update, an explicit scopes replaces the full set; omit to leave ownership unchanged; [] clears it. Subject to token identity auto-assign. |
externalId | string | Stable id you assign. Immutable. Unique within tenant+context+typeName (idempotent create). Max 256 chars. |
indexMode | enum | Per-record override: HYBRID/SEMANTIC/TEXT/NONE. Immutable after create. |
expiresAt | string | Optional absolute expiry (ISO-8601 UTC, at least 10 minutes in the future). The record is removed at or shortly after that time. Requires the schema to set capabilities.ttlEligible: true, otherwise the request is rejected. Records have no expiry by default; omit it on update to leave the expiry unchanged. |
expectedVersion | number | Optimistic concurrency. Ignored on create. |
Type identification (SDK 0.26+ either-or): provide typeName or schemaId
(at least one). With only typeName, the server resolves the schema to your own
basedOn variant when one exists, otherwise the shared base — typeName is unique within
an ownership scope, not tenant+context-wide (see basedOn in the schema fields above).
With only schemaId, it resolves the type from the schema. With both, they must agree.
An SDK older than 0.26 always sends both.
RecordResponse (selected fields)
id, typeName, schemaId, schemaVersion, externalId, payload,
payloadExternalized, payloadBytes, status, folderId, userId, scopes,
indexStatus (PENDING_INDEX | INDEXED | SKIPPED | FAILED, null for store-only;
SKIPPED = no indexable text, so nothing was indexed — stored + retrievable, not an error. A record with no indexable text but a readable geo location is indexed by its location and ends INDEXED; a $near search finds it (it has no text for a query to match). This does not apply when its indexMode is SEMANTIC: such a record ends SKIPPED and no search finds it.),
indexFailure (present when indexStatus is FAILED, and with code LOCATION_NOT_INDEXED when indexStatus is INDEXED but a location value could not be read — an object with a stable code
and a human-readable message; see the code table in the operations-trust reference),
geocodeStatus (read-only, present once a field that declares geocode has a state: per geo field id, status SUPPLIED (the location was sent with the address) | PENDING | OK | NOT_FOUND | FAILED, an optional reason, an open string to which values may be added (DAILY_LIMIT: the account's daily geocoding limit is reached, retried on a later day; TEMPORARILY_UNAVAILABLE: retried a limited number of times, then the field stays FAILED until its address changes; ADDRESS_TOO_LONG (an address longer than 200 characters), METADATA_LIMIT, NOT_ENABLED, ADDRESS_REJECTED: not retried until the address changes; editing other fields does not retry it), and once looked up provider, attribution and geocodedAt; 0.50+),
indexMode, createdBy, createdAt, updatedAt, version.
For an externalized (large) payload, list/lookup responses return only the indexed
projection and set payloadExternalized: true; fetch the full payload via by-id GET or
pass includePayload: true on the list/lookup call.
Automatic ownership lookups
Every record is automatically lookup-indexed by userId and by scopes
without declaring them and without counting against the 10-field cap — so
listRecords({ type, userId }) and listRecords({ type, scope: 'org:<id>' }) resolve
directly (scope takes one <namespace>:<value> filter per call).
Notes & limits — records
- PUT replaces the payload in full — it is not deep-merged. Use PATCH (0.26+) for a true partial payload update.
- PATCH patchable keys:
payload,status,folderId,userId,scopes,expectedVersion. Immutable keys (typeName,schemaId,externalId,indexMode) are rejected if present. Withinpayload, a key set tonullis deleted; a top-level patchable field (such asstatusorfolderId) set tonullis not a delete — it is rejected with400. Clearing a top-level field is not supported. typeNameis immutable after creation. To change a record's type, write a new record and delete the old one.folderIdcannot currently be cleared once set.- Delete is hard delete — there is no soft-delete status that lingers in the index.
- Batch write and batch get are implemented; batch lookup is still reserved.
POST /v1/records/batchwrites up to 50 records in one call andPOST /v1/records/batch-getfetches up to 100 by id. Batch write returns HTTP200with a per-itemresultsarray even when items failed, so inspect the results rather than the status code.POST /v1/records/lookup/batchis still reserved and returns501 not_implemented— do not depend on it.
Documents — client.documents.*
| Method | Purpose |
|---|---|
ingestDocument(body) | Inline text ingest. |
uploadDocument(body) | Request a presigned upload URL (file path). |
getDocument({ id }) | Fetch by id. |
getDocumentText({ id, offset?, limit? }) | Retrieve the retained text — always available for text-ingested documents; for file uploads unless uploaded with storeText: false. offset (default 0) and limit (at least 1; omit it to read to the end), both counted in Unicode characters (code points), select a part of a long text. The response carries id, text, offset and totalLength (the length of the whole text) and, while text remains, nextOffset to pass as the next offset. A non-integer or out-of-range offset or limit, or an offset past the end of the text, is a 400. |
getDocumentDownloadUrl({ id }) | Presigned download URL for a file-backed document. |
updateDocument({ id, body }) | PUT — replaces the fields you send and keeps the ones you omit; payload is replaced in full when sent; text re-ingests. |
patchDocument({ id, title?, payload?, status?, ... }) | PATCH (RFC 7386). SDK 0.26+. In the TypeScript and Java SDKs from 0.46.0 the fields sit beside id (in Java, build a DocumentPatchRequest); earlier SDKs take them as patchDocument({ id, body }). Every patch field is optional, and the patch request has no externalId or indexMode. |
deleteDocument({ id }) | Hard delete (+ tombstone). |
listDocuments({ type?, folderId?, userId?, scope?, startFrom?, limit? }) | List (list envelope). type keeps only documents bound to a schema of that type; scope is one <namespace>:<value> filter per call. A page can hold fewer than limit documents (or none) while nextCursor is set: page until it is null. |
lookupDocuments(...) / lookup-by-body | Lookup on a schema-bound document's lookup fields. |
getDocumentVersions({ id }) | Version history (list envelope). |
Upload fields (FileUploadRequest — uploadDocument)
In addition to fileName/fileType/indexMode/ownership/payload/schemaId/externalId (externalId is unique per schema and needs schemaId or the confirmUntyped=true query parameter, as in the table below):
| Field | Type | Notes |
|---|---|---|
fileType | string | Optional. Any media type of the form type/subtype; stored lower case without parameters, and inferred from the extension of fileName when omitted or application/octet-stream. Without size it is a label only: it does not set the stored file's Content-Type (the PUT's header does). With size, uploadUrl is signed for this type in its stored form, and the PUT must send it as given in the response's requiredHeaders. It never decides whether text is extracted. Only a malformed value is a 400. |
size | integer | The exact length of the file in bytes, at least 1, at most 104857600 (100 MiB). When you send it, the upload is bound: the file's media type and this length become part of uploadUrl's signature, so the storage service refuses a PUT whose Content-Type differs from the one in requiredHeaders or whose length differs from size (403 SignatureDoesNotMatch), before anything is stored. Required for a document of a public-media type; optional for every other upload. |
storeText | boolean | Default true: the extracted text is retained — retrievable via getDocumentText and usable by document-ask. Set false to discard the extracted text once indexing completes (search and the original-file download are unaffected; getDocumentText then 404s and document-ask 409s). Fixed at ingest: it cannot be changed later, and a re-upload keeps the original choice. |
Ingest / update fields (DocumentRequest)
Text-ingested documents always retain their body (it IS the document) — there is no retention flag on this path.
| Field | Type | Notes |
|---|---|---|
title | string | Required on create. Omit it on update to keep the current title. |
text | string | Inline ingest body. Required on POST ingest; on PUT/PATCH it re-ingests write-through. |
indexMode | enum | HYBRID/SEMANTIC/TEXT/NONE. Optional if the bound schema sets a default; otherwise required. Fixed at creation. |
folderId | string | Defaults to the context root. Cannot be cleared once set. |
payload | object | Structured data (records parity). Validated + lookup-indexed when schemaId is set; undeclared keys pass through as free-form, filterable in search. Replaced in full on PUT. |
schemaId | string | Optional schema to validate + lookup-index the payload against. |
status | string | Lifecycle status you control: ACTIVE (default) or ARCHIVED. ARCHIVED pulls the document from search and recall but keeps it; set it back to ACTIVE to restore it. Distinct from the read-only indexStatus. Patchable. |
userId | string | Ownership (Vectros user UUID). |
scopes | string[] | Ownership entity edges, each <namespace>:<value>, at most two. Same replace-on-update semantics as records. |
externalId | string | Stable id you assign. Immutable. Unique within tenant+context per schema (idempotent ingest): the same externalId under a different schemaId, or with none, is a different document. Max 256 chars. Supplying it without schemaId is refused with a 400 unless the request also passes confirmUntyped=true. |
confirmUntyped | boolean (query parameter) | Default false. Set true to confirm that an externalId with no schemaId is intended to address the untyped namespace. Has no effect when schemaId is supplied or externalId is omitted. Applies to ingestDocument and uploadDocument. |
expectedVersion | number | Optimistic concurrency. Ignored on create. |
Upload handshake (uploadDocument)
uploadDocument returns uploadUrl, expiresAt (15 minutes), requiredHeaders (every header the PUT
must send, as a map) and, for older clients, requiredHeaderName + requiredHeaderValue (one of those
headers). PUT the raw bytes to uploadUrl without an Authorization header, and send every header in
requiredHeaders exactly. When the request sent size, requiredHeaders includes the Content-Type the URL
is signed for and the body must be exactly size bytes; without size, set Content-Type to the file's media
type yourself (it is stored with the file and served on download; it is not checked). The URL is single-use, enforced by an S3 conditional-write precondition
baked into its signature: these headers are part of that signature, so a PUT that omits one (or changes its
value) fails with a 403 SignatureDoesNotMatch before reaching this service at all — not this API's JSON
error shape. Poll getDocument until indexStatus is INDEXED, SKIPPED, STORED or FAILED. A file with no extractable text ends SKIPPED (INDEXED when its bound schema declares searchable fields): read extraction for the reason.
Any type of file can be uploaded. Text is extracted only from document formats: plain text, CSV, TSV,
Markdown, JSON, YAML, HTML, XML, PDF, RTF, Word, Excel, PowerPoint, Outlook messages, OpenDocument, EPUB,
e-mail messages and mbox exports, WordPerfect, Visio, Publisher, OneNote and Apple iWork. The format is detected from the file's content, not taken from fileType, and the same
rule applies to attachments and embedded objects inside a file. Anything else (audio, video, images,
archives such as zip or rar, Outlook .pst stores, executables, unrecognized formats) is stored and downloadable but not read: its
extraction.outcome is NOT_EXTRACTED and it ends SKIPPED (STORED under indexMode: NONE; indexed on its schema's
declared-searchable fields when it has any). An Office file one of whose larger parts expands more than 500 times its
compressed size, or whose zip structure is damaged, is refused (UNREADABLE); embedded in another file, it is skipped.
DocumentResponse (selected fields)
id, title, externalId, status (the lifecycle state you control: ACTIVE |
ARCHIVED), indexStatus (the read-only processing state: PENDING_UPLOAD | UPLOADED |
EXTRACTING | PENDING_INDEX | INDEXED | SKIPPED | STORED | FAILED; SKIPPED =
there was no indexable text, so nothing was indexed — stored + retrievable, not an error. A schema-typed
document with no indexable text but a readable geo location is indexed by its location and ends INDEXED; a $near
search finds it. This does not apply when its indexMode is SEMANTIC: such a document ends SKIPPED and no search finds it.),
indexFailure (present when indexStatus is FAILED, and with code LOCATION_NOT_INDEXED when indexStatus is INDEXED but a location value could not be read — an object with a stable code and a
human-readable message; see the code table in the operations-trust reference), extraction (file
documents: how text extraction went — outcome OK | TRUNCATED | NO_TEXT | ENCRYPTED |
UNSUPPORTED | TOO_LARGE | UNREADABLE | NOT_EXTRACTED (a type text is not extracted from), truncated, message; for every outcome but OK and
TRUNCATED the file yielded no text, so /text is 404, /ask is 409, and the document is searchable
only by its declared-searchable field values; branch on outcome, not on message), indexMode, storeText,
folderId, payload, payloadExternalized, schemaId, schemaVersion, textBytes,
userId, scopes, fileType (the declared type), detectedType (the type detected from the
file's content at extraction; absent until then), media (a document of a public-media type only: the image's
processing state and desired public state, read-only; absent until the upload is processed, and no upload is
processed in this version), fileSize, createdAt, lastModified, version.
Notes & limits — documents
- PUT replaces the payload in full; PATCH (0.26+) merges. PATCH patchable keys:
title,text,folderId,schemaId,userId,scopes,payload,status,expectedVersion.indexMode,externalId, andstoreText(text retention is fixed at ingest) are immutable and rejected. - An update re-runs the indexing pipeline; old content is removed from the index as the new content is written.
getDocumentTextserves the retained text: always available for text-ingested documents, and for file uploads unless uploaded withstoreText: false(which discards the extracted text once indexing completes — the original file stays downloadable). Returns 404 when the text is not retained or extraction has not completed.- The presigned PUT must omit the Authorization header — the URL itself carries the grant.
- Text extraction limits. Extracted text is kept up to 1,000,000 characters. A longer file, or a file
holding more than 1,000 embedded documents (archive entries, attachments, embedded objects; images are
not counted), is kept as far as it was read and reported
extraction.outcome: TRUNCATEDwithtruncated: true; what was kept is searchable and readable. Embedded documents nested more than 8 levels deep make the fileUNREADABLE. A file that holds no text (a scanned page), is of a type text is not extracted from (an image, for example), is password-protected, is in an unsupported format, is too large to extract or is corrupt is never indexed as text: it has no/text, and itsextraction.outcome(NO_TEXT,NOT_EXTRACTED,ENCRYPTED,UNSUPPORTED,TOO_LARGE,UNREADABLE) says why. The original file stays downloadable. - Reading a long text in parts. Pass
limit(andoffsetfrom the second part on) togetDocumentTextand keep reading from each response'snextOffsetuntil it is absent.offset,limitandtotalLengthcount characters (code points), so a part never splits a character. - Listing by type.
listDocuments({ type })keeps only documents bound to a schema of that type (a document with no schema never matches). The filter applies to each page as it is read, so a page can be short or empty whilenextCursoris set: page until it isnull.
Folders — client.folders.*
| Method | Purpose |
|---|---|
createFolder(body) | Create (optionally under a parent). |
getFolder({ id }) | Fetch by id. |
updateFolder({ id, body }) | PUT — name/description/ownership. |
patchFolder({ id, body }) | PATCH (RFC 7386). SDK 0.26+. |
deleteFolder({ id }) | Delete (rejects non-empty). |
listFolders({ userId?, scope?, startFrom?, limit? }) | List (list envelope). scope is one <namespace>:<value> filter per call. |
getFolderVersions({ id }) | Version history (list envelope). |
Create / update fields (FolderRequest)
| Field | Type | Notes |
|---|---|---|
name | string | Required on create. Omit it on update to keep the current name. |
description | string | Optional. |
parentFolderId | string | Applied at create only; ignored on update. Omit to create under the context root. |
slug | string | Stable, sibling-unique slug; derived from the name when omitted. Lowercase letters/digits/hyphens. Immutable. |
userId | string | Ownership (Vectros user UUID). |
scopes | string[] | Ownership entity edges, each <namespace>:<value>, at most two. |
expectedVersion | number | Optimistic concurrency. Ignored on create. |
FolderResponse (selected fields)
id, name, description, parentFolderId (null only for a true root),
slug, depth (0 at root), isProtected, userId, scopes, createdAt,
lastModified, version.
Notes & limits — folders
- No move / reparent.
parentFolderIdis fixed at creation; there is no operation to relocate a folder in the hierarchy. - Delete rejects a non-empty folder with a 400 — remove children first. "Non-empty" means
ANY of the three things a folder can hold: sub-folders, documents (file-backed and
text-ingested), and records. Enumerate them with
GET /v1/folders?parentFolderId=,GET /v1/documents?folderId=andGET /v1/records?folderId=. The guard counts items your own credential may not be able to read, so a folder in a shared tenant can refuse to delete for a narrowly-scoped credential without that credential being able to see why. Emptying it then needs a credential whose reach covers the whole folder. - The context root folder is protected (
isProtected: true) and created lazily on first folder interaction. Unparented folders are placed under it, so a folder created without a parent still has a non-nullparentFolderId(the root's id). - PATCH patchable keys:
name,description,userId,scopes,expectedVersion.slugandparentFolderIdare immutable and rejected.
Scripts — client.scripts.* and POST /v1/scripts/execute
A script is a stored, versioned JavaScript program (POST /v1/scripts pushes an immutable new
version of a name; GET/DELETE /v1/scripts/{id} manage versions) that the platform runs for you in
a sandbox with the vectros.records, vectros.documents and vectros.folders host functions. Three
things run a script: a trigger rule (asynchronously, when a record event fires it),
POST /v1/scripts/execute (synchronously, as one atomic call), and an agent run, when the agent
offers the script as a tool (see As an agent tool).
Synchronous execution (POST /v1/scripts/execute)
| Field | Type | Notes |
|---|---|---|
scriptRef.name | string | The script's name. |
scriptRef.version | string | A version number ("3") or "latest", resolved at request time: a version you pushed just before the call is the one that runs. |
input | object | Free-form JSON your script receives as input.params. Optional; {} when absent. |
Response: { result, execution: { id, durationMs } }. result is whatever the script returned,
converted as JSON.stringify would; the platform makes no promise about its shape. It is returned
only after the script's writes have committed — on any failure the body is the standard error
envelope and nothing the script staged is committed: rows are written only when the transaction
commits, and a document body or a large payload is decided at that point and written to storage only
after the commit, so an aborted execution leaves nothing behind. (The one residual sits after a
successful commit, outside the response: if storing a body fails then, the row exists and the body
does not until the platform's repair lands — a 200 guarantees the rows; read a document's text
before relying on it.)
Permission. scripts:x — the permission to execute — separate from scripts:c (push). Bare
scripts:x grants every script in the context; scripts:x:<name> grants exactly that name, every
version. Execution discloses no source (scripts:r is not needed), and scripts:x alone can read or
write nothing: inside the script every host call is enforced by your credential's data scopes exactly
as the equivalent REST call would be.
What the script sees. input.event is the literal "execute", input.userId is your
credential's user id (or null), and input.params is your input object verbatim. That is the same
input grammar a trigger rule uses, so one script can serve both by branching on input.event;
input.schemaId, input.recordId and input.scope are absent on this path. When the version
declares an inputSchema (below), your input is checked against it before anything runs: a 400
names every problem, and an optional member sent as null is removed. Otherwise params is not
validated: a script's declaredInputContract is documentation for readers, not an enforced schema
— a script that needs a shape checks for it and throws, which reaches you as a 400 SCRIPT_ERROR
carrying the script's own message.
As an agent tool
A script version can declare an inputSchema when you push it: a JSON Schema object that the
platform enforces on every call that passes it arguments: a script tool's call and POST /v1/scripts/execute
(trigger rules do not use it). It is required to offer the script to an agent as a tool. The root is
{"type": "object"}; every node declares type (string, number, integer, boolean, array or
object) and may add description and enum; an object node may use properties, required and
additionalProperties (false unless you set it to true, and stored with the false written out); an
array node may use items. Nothing else is accepted: at most 5 levels, 16,384 bytes, 100 members per
object and 100 enum values. The model is shown the schema exactly as stored, and every call's arguments
are checked against it before the script runs; an optional member sent as null is treated as absent
and removed.
Run as a tool, the script sees the same input as on POST /v1/scripts/execute: input.event is
"execute", input.userId is the run's caller's user id (or null), and input.params is the checked
arguments. It runs under the run's caller's credential, which must hold scripts:x for it; with read
verbs only unless the agent's tool entry has allowWrites; with a 10-second limit per call; and without
outbound HTTP. Its writes commit as one transaction, as on the synchronous path, and are recorded as made
by the agent run. It is billed at the script execution rate, like the other two paths. See the agents
reference for the tool entry.
Trigger execution — what the script sees
A rule fires on a record event and the script receives the record as an image, not a pointer:
| Key | Present on | Value |
|---|---|---|
input.event | all | "CREATE", "UPDATE" or "DELETE". |
input.schemaId | all | The schema the rule fires off. |
input.recordId | all | The record's id — what vectros.records.get accepts. |
input.userId, input.scope.<ns> | all | The record's stamped ownership (the values the rule's ${{ input.* }} grant resolved against). |
input.record | all | The rule's declared fields, from the row as written — on DELETE, from the deleted row (the only way a script can see it). Absent only for a firing dispatched before this release rolled out. |
input.previous | UPDATE | The same fields from the row before the write. |
fields is required when you declare the rule (POST /v1/triggers), and [] projects nothing
beyond the identity. Every entry must be a field the schema keeps inline — inline: true,
filterable, or a lookup field — and not sensitive; the rule is rejected with a 400 listing the
projectable fields otherwise. A rule that declares fields must also be able to read every record it
fires on: its grant must hold a records:r clause covering the schema's type (a grant with no read at
all is rejected), and that clause may not carry a literal data_scope constraint (a
${{ input.<dim> }} placeholder is fine — it resolves to the firing record) or the rule is rejected; and if
at execution the rule's grant cannot read the firing record, record and previous are delivered as
empty objects. The reason is the storage tier: a payload moves out of the row above
4 KB, only the inline fields ride the change event a trigger fires from, and a field outside that set
would reach a script for small records and silently vanish for large ones. A field the record does not
carry is undefined, never null. record plus previous are capped at 224 KB serialised; an
over-cap firing is not run and is recorded as an INPUT_TOO_LARGE failure naming the size. A record
last written before its schema inlined a field may lack it in previous (or in record on DELETE)
until it is written again.
Reads inside the script. A get sees the script's own staged writes. A list, query or lookup
never shows a row the script has deleted, shows a row it re-saved with the updated content, and does
not show a row it created — you hold that row's id from create(). (The same holds inside a
trigger execution.)
Budget — "seconds of useful work". 15 s of wall clock (never more than 16), a bounded number of
statements and of host calls (a runaway script is stopped early with RESOURCE_LIMIT_EXCEEDED), and
one transaction of at most 100 storage rows after merging — stated in rows because that is the
storage transaction's own limit, not a platform choice:
| Operation | Rows |
|---|---|
folders.create / folders.delete | 3 |
documents.create (text) | 1 + one per range-indexed lookup field + one per reference field |
records.create | 1 + range-indexed fields + references (+ over-budget fallback rows) |
any update via a full save | the same as its create |
So "create a folder and file N plain text documents" holds up to 97 documents (48 with one range
field or one reference each, 32 with both). Over the limit the error is 400 WRITE_BUFFER_CAP_EXCEEDED
with total and limit, and nothing is committed.
Limits and metering. The request takes the write-path limits once, before the script runs —
burst, monthly credit ceiling, principal quota — with no free-read allowance, so an account over its
credit ceiling is refused (402) even for a read-only script. Each read the script performs is
metered as a read and each write as a write; execution time beyond what those operations include is
charged as script execution time (see GET /v1/usage, whose execution section covers both trigger
and synchronous scripts). Concurrent executions per app are bounded; at the limit the response is
429 with Retry-After: 2.
Retries — the Idempotency-Key header. Optional, 1–128 characters of letters, digits, ., _,
: or -. A request repeated under the same key within 24 hours receives the same response as the
first attempt without executing again; a duplicate still in flight is 409 IDEMPOTENCY_IN_PROGRESS;
the same key on a different request is 422 IDEMPOTENCY_KEY_REUSED. If an execution's outcome cannot
be determined — the script did not finish inside the budget while its writes may have committed — the
response is 500 EXECUTION_OUTCOME_UNKNOWN carrying execution.id, and a keyed retry receives that
same answer: inspect what the script would have written, then use a new key for a new attempt.
With a key present the serialised result is capped at 16 KB (256 KB otherwise): a retry-safe
script returns ids, not payloads. Without a key, a lost response cannot be distinguished from a
failed one — re-read before retrying.
Errors (standard envelope, errorCode named): 400 SCRIPT_ERROR · RESOURCE_LIMIT_EXCEEDED ·
WRITE_BUFFER_CAP_EXCEEDED · RESULT_TOO_LARGE; 403 missing scripts:x ·
AUTHORIZATION_DENIED; 404 unknown script; 409 CONCURRENT_MODIFICATION (names the ids to
re-read; never a version) · IDEMPOTENCY_IN_PROGRESS; 413 body over 256 KB; 422
IDEMPOTENCY_KEY_REUSED; 429 burst / concurrency / probe budget; 500 EXECUTION_OUTCOME_UNKNOWN
or an internal error with a correlationId; 503 writes frozen · EXECUTION_NOT_STARTED ·
EXECUTION_CONTAINER_BUSY (retry after Retry-After); 504 TIMEOUT.
Lookups & references
Lookup modes
Exactly one mode per call:
| Mode | Parameters | Constraints |
|---|---|---|
| exact | value (single field), or values (composite — array, order matches fieldNames) | Any lookup field. A single-element values means the same as value. Sensitive fields must use the body variant. May be narrowed with sortFrom/sortTo (below). |
| range | from + to | Both required. Inclusive, ascending. Non-sensitive, single-field lookups only. |
| prefix | prefix | String, non-sensitive, single-field lookups only. Ascending. |
Supplying zero or more than one mode is a 400. Range with only one bound is a 400. Prefix on a non-string field is a 400.
Composite lookups (record surface only)
A LookupDef can name two or three fields together via fieldNames instead of a single
fieldName. Query it with a comma-joined field (field: 'status,area') and a matching
values array in the same order — repeated query params on GET, an array in the body on
POST. Field order is fixed at authoring time and cannot be changed later; you may query a
leading run of the declared fields (the first field alone, the first two, and so on)
but never a later field on its own — declare a separate lookup for that. Supplying fewer
values than declared returns records grouped by the unspecified fields; a requested
sort order then applies within each group, not across the whole result. A composite
lookup cannot be unique or rangeEnabled, and its schema's allowedSurfaces must be
record only.
Sort-key window (sortFrom / sortTo)
An exact-value lookup accepts optional sortFrom/sortTo bounds on the lookup field's
own sort key — inclusive, either given alone, expressed in that field's own units (epoch
milliseconds for a timestamp field such as createdAt/lastUpdated). On a composite
lookup, a sort-key window requires the full tuple of values; it is not available on a
grouped/partial query. Records with no value on the sorted field sort ahead of records
that have one, and are never included in a bounded window. The result still pages with
the standard { data, nextCursor } envelope.
Sort order (order) vs. sort field (sortBy)
An enumeration lookup accepts an order parameter — asc (default) or desc — as a
query param on GET, or the order option on the SDK's lookupRecords. order picks
direction only. Which field the results are ordered by is not a per-query choice — it
is the lookup's sortBy, declared once on the schema (see LookupDef
above; defaults to createdAt). Passing a sortBy query parameter here has no effect —
it is silently ignored, not rejected — because the field it would need to change is fixed
by the schema, not the request. If you need results ordered by a different field, change
the schema's sortBy for that lookup (or declare a second lookup field with a different
sortBy); don't guess a sortBy query parameter and assume it took effect. (Unrelated
same-named field: RenderHintDef.order above is a form-builder display position, not a
query sort — don't confuse the two.)
Unique vs non-unique (enumeration)
- A
uniquelookup field returns at most one record and is enforced unique on write. - A non-unique lookup field is an enumeration — it returns every record sharing the
value, paginated via the
{ data, nextCursor }envelope.
Sensitive-field lookup (body variant)
For a sensitive field, the exact value must not travel in a URL. The GET lookup rejects
value on a sensitive field and directs you to the body-based variant, where the value
travels in the request body and is blind-indexed server-side. Range and prefix are not
available on sensitive fields (a blind-indexed value has no usable order).
References
A reference field links to another record: it declares targetTypeName (required),
targetField (default externalId; must be a unique lookup on the target), cardinality
(one/many), and targetSurface. The platform can additionally maintain per-field
reverse-reference rows (opt-in) to index the inverse direction.
Notes & limits — lookups & references
- Lookup fields you declare are capped at 10 per schema (the three automatic
ownership lookups do not count). A schema has 7 fast equality-lookup slots; an 8th to
10th equality lookup is rejected with a
400unless that lookup setsallowOverflow: true, which accepts a higher-cost secondary index (about twice the storage, transactional writes). Range-enabled lookups do not count against the 7. - There is no reverse-reference list endpoint — you cannot query back-references through the API today.
- References are validated at write time by default: a value that resolves to no target
(or to more than one, when
targetFieldis not a unique lookup) is rejected with a400. A schema can opt out withcapabilities.validateReferences: false.
Version history — getRecordVersions / getDocumentVersions / getSchemaVersions / getFolderVersions
Each returns the { data, nextCursor } list envelope of version rows
(removed only by your retention policy, an erasure request, or tearing down the context or
tenant) for an audited entity.
Version-row fields
| Field | Type | Notes |
|---|---|---|
id | string | Version-row id. |
changeType | enum | CREATE | UPDATE | DELETE. |
previousContent | string | JSON-stringified snapshot of the state prior to this change. Populated on UPDATE/DELETE; null on CREATE. JSON.parse to inspect. |
previousVersion | number | Version number before this change; null on CREATE. |
changeReason | string | Caller-supplied or system-derived reason. |
changedBy | string | Id of the user / key responsible. |
actingVia | object | Present only when the change was made by an agent run on behalf of changedBy: kind (agent-run today; treat an unrecognized value as a kind you do not interpret), actorId (the stored agent's id), runId and tool (the tool the run called). Absent for a change made directly with a credential. It never replaces changedBy: that stays the credential whose authority the change used. |
createdAt | string | ISO-8601 timestamp of the row. |
changedFields | object | Field-level diff: summary, changed field names, count, per-field old→new detail. Never includes the platform's internal index keys. Null on CREATE. |
Audit capability & retention
- Audit history is governed per schema by
capabilities.auditHistory(default true). Setting it false stops recording the change-history trail for that type's data; it never deletes or affects the records/documents themselves. Tombstones on delete are recorded regardless. - Version rows are written asynchronously (typically 1–3 seconds after a write returns) — poll briefly if you read history immediately after a write.
- Audit and version history are retained; heavy historical content is externalized to a retention-locked, retention-governed store, and each version row carries a SHA-256 hash link to the prior state. The full retention and integrity posture lives in ../operations-trust/compliance.md.
Errors
The platform returns a uniform error contract. Common cases for the data model:
| Status | Meaning (data-model context) |
|---|---|
400 | Validation error: schema-field violation, bad identifier, multiple/zero lookup modes, range/prefix on a sensitive field, prefix on a non-string field, delete of a non-empty folder, immutable field present in a PATCH, a top-level field set to null in a PATCH, a number outside signed 64-bit range / with more than 38 significant digits / non-finite, an externalId without a schemaId on document ingest or upload when confirmUntyped=true is not set, an offset or limit on a document text read that is not a whole number in range (or an offset past the end of the text), a reference that resolves to no target, a caller-constructed (non-verbatim) startFrom, or a startFrom used with different query parameters than it was issued for (the error names the field, where applicable). A request body that is not valid JSON, or does not have the expected shape, is also a 400 with a fixed message that names the offending field where there is one, never the JSON parser's own text. |
404 / "not found" | The entity does not exist, or belongs to another tenant/context, or is out of the caller's token scope — a single uniform shape (the message never distinguishes these). An update of an item deleted a moment earlier is also 404. |
409 VERSION_CONFLICT | expectedVersion did not match — the entity changed since you read it; or another write to the same item committed while your update was being applied (with or without expectedVersion); or a delete met another write to the same item. Nothing is written; re-read and retry. |
409 | DELETE /v1/schemas/{id} while records, documents, users, entities, variants or trigger rules still depend on the schema; a schema update that would turn triggersEnabled off or stop keeping an inline field while a trigger rule needs it; a schema update that removes user or entity from allowedSurfaces while users or entities are bound to the schema. When the platform cannot confirm that none are bound (a row could not be read, or the tenant has more users or entities than one check can examine), the delete or update is refused with a 409 that says so and nothing is changed: retry, or contact support if it persists. |
501 not_implemented | A reserved-but-unbuilt operation (batch record lookup). |
Where to go next
- explanation.md — the concepts and the why.
- how-to.md — runnable guides for every operation above.
- ../operations-trust/compliance.md — version history retention, the SHA-256 continuity hashes, and sensitive-data handling.