# 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](/reference/v1/~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:

```json
{
  "agent_id": "6b1f…",
  "agent_name": "Support triage",
  "agent_model": "genai-pro",
  "agent_created": "2026-08-04T15:22:07.412Z"
}
```

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](/pagination), 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](/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](/uploading-files) and
  [delivering assets](/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](/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.