# Custom Fields API

Eos supports organization-defined custom fields on existing objects. It does not support customer-created object types, so v1 has no Custom Objects API.

Custom fields use the same object endpoints as standard fields. The Custom Fields API provides read-only schema discovery so an integration can understand each organization's effective field definitions before reading, filtering, or writing records.

## Authorization

A custom field never creates a separate authorization path. Access is the intersection of:

- the API Client's license and Eos Roles;
- access to the containing object and operation;
- the field's role visibility and read/write configuration; and
- the object's workflow and validation rules.

Fields the client cannot read are omitted from record responses and schema results. Writes to unknown, read-only, hidden, or Role-forbidden fields fail explicitly; Eos never silently drops them.

## List object schemas

`GET /v1/schemas`

Operation ID: `listObjectSchemas`.

Returns the Eos object types exposed through API v1 and visible to the API Client. This is a catalog of supported existing objects, not a facility for creating object types.

```json
{
  "object": "list",
  "data": [
    {
      "object": "object_schema_summary",
      "object_type": "project",
      "label": "Project",
      "schema_version": 7,
      "custom_field_count": 3
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Get an object schema

`GET /v1/schemas/{object_type}`

Operation ID: `getObjectSchema`.

```json
{
  "object": "object_schema",
  "object_type": "project",
  "schema_version": 7,
  "fields": [
    {
      "api_name": "customer_tier",
      "label": "Customer tier",
      "field_type": "select",
      "custom_field": true,
      "required": false,
      "readable": true,
      "writable": true,
      "filterable": true,
      "options": [
        {"value": "strategic", "label": "Strategic"},
        {"value": "standard", "label": "Standard"}
      ]
    }
  ]
}
```

The schema contains only fields visible to the caller. It declares types, validation, allowed values, relationship targets, and whether each field may be read, written, filtered, sorted, grouped, or used by Skills.

## Read custom field values

Resources expose organization-defined values in a stable `custom_fields` object keyed by the field's `api_name`:

```json
{
  "object": "project",
  "id": "prj_01J8Q8QFXT2Y3QAD6M0MPB75GC",
  "name": "Northwind implementation",
  "custom_fields": {
    "customer_tier": "strategic",
    "implementation_region": "north_america"
  }
}
```

Unknown readable values may be returned after a schema change. Clients must ignore fields they do not understand and refresh the schema when `schema_version` changes.

## Write custom field values

Create and update operations for the containing object accept `custom_fields` alongside standard fields:

```json
{
  "custom_fields": {
    "customer_tier": "strategic"
  }
}
```

`PATCH` changes only the supplied custom fields. A JSON `null` clears a nullable field; omitting a key leaves it unchanged. Validation is atomic with the rest of the object write.

## Configuration is not part of v1

API Clients cannot create, change, hide, reorder, or delete custom-field definitions. Configuration remains an administrator action in Eos Object Designer. API v1 discovers and uses the resulting effective schema.

## Common errors

`OBJECT_SCHEMA_NOT_FOUND`, `CUSTOM_FIELD_NOT_FOUND`, `CUSTOM_FIELD_FORBIDDEN`, `CUSTOM_FIELD_READ_ONLY`, `CUSTOM_FIELD_VALUE_INVALID`, `CUSTOM_FIELD_REQUIRED`, and `OBJECT_SCHEMA_CHANGED`.

Next: [Webhooks API](webhooks.html).