> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frogbot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fields Generated by FrogBot

> Understand the system and feature fields FrogBot adds to collections.

FrogBot adds fields when a collection or feature needs them. The exact schema therefore depends on collection settings such as authentication, uploads, drafts, trash, and FrogBot features such as chat, AI usage tracking, board views, and jobs.

Some generated fields can be customized by defining a top-level field with the same `name`. FrogBot merges supported auth, upload, draft, and feature-field overrides with required defaults. ID and timestamp declarations replace their generated field instead.

Do not define undocumented internal field names. Reserved fields protect
authentication, files, jobs, ordering, and other framework invariants.

## Override example

This auth collection adds read access control to the generated `apiKey` field. FrogBot preserves the field's built-in hooks and admin configuration because the declaration is merged into the generated field:

```ts theme={"theme":"tokyo-night"}
import type { CollectionConfig } from 'frogbot'

export const Users: CollectionConfig = {
  slug: 'users',
  auth: {
    useAPIKey: true,
  },
  fields: [
    {
      name: 'apiKey',
      type: 'text',
      access: {
        read: ({ req }) => Boolean(req.user),
      },
    },
  ],
}
```

## Document fields

| Field | Added when | Override behavior |
| - | - | - |
| `id` | Every collection | A top-level Text or Number field replaces the generated ID. |
| `createdAt`, `updatedAt` | Collection timestamps are enabled | Top-level Date fields replace the generated fields. For a record number, add an [Autonumber](https://docs.frogbot.ai/fields/autonumber.md) field. |
| `createdBy`, `updatedBy` | `authorship` isn't `false` | Relationships to every auth collection, set from the signed-in user when a record is created or saved, and hidden in the admin panel. A top-level field with the same name replaces the generated one. Set `authorship: false` on the collection to leave them out. FrogBot's own collections don't have them. |
| `deletedAt` | Trash is enabled | A top-level Date field replaces the generated field. |

Custom IDs should be required or generated by a hook. Text IDs must not contain `/` or `.`.

```ts theme={"theme":"tokyo-night"}
import type { CollectionConfig } from 'frogbot'

export const Products: CollectionConfig = {
  slug: 'products',
  fields: [
    {
      name: 'id',
      type: 'text',
      required: true,
    },
  ],
}
```

## Authentication fields

Authentication-enabled collections receive fields according to their auth configuration.

| Fields | Added when |
| - | - |
| `email`, `password`, `resetPasswordToken`, `resetPasswordExpiration` | Local authentication is enabled. |
| `username` | Username login is enabled. |
| `enableAPIKey`, `apiKey`, `apiKeyIndex` | API-key authentication is enabled. |
| `_verified`, `_verificationToken` | Email verification is enabled. |
| `loginAttempts`, `lockUntil` | Maximum login attempts are configured. |
| `sessions` | Sessions are enabled. |

Matching supported fields are merged into the generated configuration. The `password` override also affects the admin panel's new-password and confirm-password controls. `salt` and `hash` are reserved and cannot be overridden.

## Upload fields

Upload-enabled collections receive file metadata fields from the upload, folder, and trash configuration. A collection marked [`file: true`](https://docs.frogbot.ai/upload/files) enables uploads but does not itself declare these fields.

| Fields | Added when |
| - | - |
| `filename`, `mimeType`, `filesize`, `width`, `height`, `url`, `thumbnailURL` | Uploads are enabled. |
| `original` | Uploads are enabled. A hidden group with the stored original file's name, URL, type, size and dimensions. |
| `focalX`, `focalY` | Uploads are enabled, unless `focalPoint` is `false` and no transformer adds variants or image adjustments. |
| `variants` | A transformer such as [`sharpTransformer`](https://docs.frogbot.ai/upload/overview#image-sizes) declares image sizes as `variants`. |

Matching upload fields are merged recursively where supported. The internal `file` field is reserved. See [Files](https://docs.frogbot.ai/upload/files.md) for FrogBot's file collection behavior.

## Version fields

Draft-enabled collections receive `_status`. A matching top-level `_status` field merges supported customization into the generated field.

## Chat fields

When chat is configured, FrogBot supplies or merges fields into the default or marked chat collections.

| Collection | FrogBot-owned fields |
| - | - |
| Chats | `title`, `user`, `agent`, `channel`, `externalId`, `channelKey`, `lastMessageAt`, `todos` |
| Messages | `id`, `chat`, `role`, `parts`, `metadata`, `usage` |

Message `usage` contains `inputTokens`, `outputTokens`, `totalTokens`, `reasoningTokens`, `cachedInputTokens`, `model`, and `provider`. These fields are present only on collections serving the corresponding chat role. See [Chat](https://docs.frogbot.ai/chat/overview.md).

## AI fields

Enabling `ai` supplies or merges an AI usage collection. Its reserved base fields are:

| Group | Fields |
| - | - |
| Relationships | `user`; `chat` only when a chat collection is available |
| Request identity | `requestId`, `runId`, `model`, `operation` |
| Tokens and cost | `inputTokens`, `outputTokens`, `cachedInputTokens`, `cacheWriteTokens`, `reasoningTokens`, `totalTokens`, `costUSD` |
| Result metadata | `finishReason`, `requestedAt` |

`costUSD` is a USD [Money field](https://docs.frogbot.ai/fields/money.md).

The [AI policy plugin](https://docs.frogbot.ai/plugins/ai-policy.md) adds `models`, `monthlyBudget`, and `spendThisPeriodUSD` to your auth collection.

## Admin view fields

Each board view adds a hidden indexed Text field named `_order_<view>`, where hyphens in the normalized view slug become underscores. FrogBot uses it for fractional board ordering. It is generated only for collections with the corresponding [board view](https://docs.frogbot.ai/admin/collection-board.md).

## Job fields

The jobs collection includes fields used for durable execution and atomic claims:

| Field | Purpose |
| - | - |
| `jobId` | Optional external job identifier, unique among unfinished jobs. |
| `processingUntil`, `processingToken` | The job's lease: when it expires and which run holds it. |
| `waitpoint` | Hidden internal waitpoint state. |

`waitpoint` is not an author input and is hidden from APIs. See [Jobs](https://docs.frogbot.ai/jobs-queue/overview.md).

## Plugin fields

Plugins can add their own fields under explicit plugin configuration. For example, the Roles plugin controls a `roles` field; it is not an unconditional core field. See [Roles](https://docs.frogbot.ai/plugins/roles.md) for its configuration and merge behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.