Objects and fields
Every endpoint that returns something returns one of a small set of named objects (a
File, an Agent, a Thread) or a page of them. The reference lists all of them
under Schemas, and each operation's response links to the
object it answers with rather than describing it again.
This page covers what is true of all of them.
Field naming
Every field of an object is prefixed with the object it belongs to:
Code
An Agent has agent_name, a File has file_name, an Album has album_name. The
prefix is not decoration: it keeps a field unambiguous when objects are embedded in one
another or returned side by side, and filter and sort parameters use the same spelling.
You filter ?agent_name=… and sort ?sort=-agent_created with the same names you read
back.
A few fields are deliberately unprefixed. They belong to the response rather than to the
object: data, has_more and next_cursor in the collection
envelope, and computed values a particular endpoint joins on, such as
similarity on a search result.
Identifiers, timestamps and types
| Convention | |
|---|---|
<prefix>_id | The object's identifier. A UUID, unless the reference says otherwise. |
<prefix>_created, <prefix>_updated | RFC 3339 timestamps in UTC, to the millisecond. |
<prefix>_metadata, <prefix>_config | Free-form JSON objects. The API stores and returns them; it does not validate their contents. |
| Money and credits | Numbers, never formatted strings. |
Fields holding an id name what they point at rather than repeating it:
thread_agent is an agent's id, file_added_by is a user's id.
What objects never contain
Three things are absent from every object by construction rather than by filtering:
- Workspace columns. Rows carry the workspace they belong to, and the API never publishes it. Isolation is enforced in the database (see security and tenancy), so there is nothing for a caller to check.
- Access-control data. Who may read a row is stored on the row and read through that resource's own access endpoint, not as a field on the object.
- Storage internals. Buckets, folders and provider ids are not part of the contract. Bytes are reached through signed URLs. See uploading files and delivering assets.
Objects only gain fields
An object may gain fields at any time within a version, so ignore fields you do not recognize rather than rejecting them. A field is never removed or repurposed inside a version; that requires a new version. Versioning covers the full commitment and the deprecation timeline behind it.
An absent field is therefore not the same as an empty one. Fields that apply only in
some cases, such as similarity on a file that was not matched against anything or
download_url on a job that has not finished, are omitted rather than returned as
null.
Objects that share a record
A few objects describe the same underlying row from different angles. They are listed separately because they carry different fields, not because the data is duplicated:
| Object | |
|---|---|
File | The canonical file. |
MediaFile | A file as the media library lists it, with the albums it sits in and a match score when the request searched by image or face. |
PersonPhoto | A photo a person appears in, with the face detection that matched them. |
Infographic | A generated data graphic, which is stored as a file. |
They share the file_ prefix because they share the record, so an id read from one can
always be used against the endpoints of another.