@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/objects.md

@@ -0,0 +1,1098 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.objects`: Objects
+
+18 operations (7 read, 8 write, 3 destructive).
+
+18 of these also have a hand-written method (`g8.objects`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [objects.d.ts](objects.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`archiveAttribute`](#op-archiveattribute) ★ | `DELETE /api/v1/objects/{object_slug}/attributes/{attr_slug}` | destructive | `objects:manage` | Archive Attribute |
+| [`archiveObject`](#op-archiveobject) ★ | `DELETE /api/v1/objects/{object_slug}` | destructive | `objects:manage` | Archive Object |
+| [`archiveObjectRecord`](#op-archiveobjectrecord) ★ | `DELETE /api/v1/objects/{object_slug}/records/{record_id}` | destructive | `objects:delete` | Archive Object Record |
+| [`createAttribute`](#op-createattribute) ★ | `POST /api/v1/objects/{object_slug}/attributes` | write | `objects:manage` | Create Attribute |
+| [`createObject`](#op-createobject) ★ | `POST /api/v1/objects` | write | `objects:manage` | Create Object |
+| [`createObjectRecord`](#op-createobjectrecord) ★ | `POST /api/v1/objects/{object_slug}/records` | write | `objects:write` | Create Object Record |
+| [`getObject`](#op-getobject) ★ | `GET /api/v1/objects/{object_slug}` | read | `objects:read` | Get Object |
+| [`getObjectRecord`](#op-getobjectrecord) ★ | `GET /api/v1/objects/{object_slug}/records/{record_id}` | read | `objects:read` | Get Object Record |
+| [`getObjectRecordChanges`](#op-getobjectrecordchanges) ★ | `GET /api/v1/objects/{object_slug}/records/{record_id}/changes` | read | `objects:read` | Get Object Record Changes |
+| [`getObjectRecordHistory`](#op-getobjectrecordhistory) ★ | `GET /api/v1/objects/{object_slug}/records/{record_id}/history` | read | `objects:read` | Get Object Record History |
+| [`listObjectAttributes`](#op-listobjectattributes) ★ | `GET /api/v1/objects/{object_slug}/attributes` | read | `objects:read` | List Object Attributes |
+| [`listObjectRecords`](#op-listobjectrecords) ★ | `GET /api/v1/objects/{object_slug}/records` | read | `objects:read` | List Object Records |
+| [`listObjects`](#op-listobjects) ★ | `GET /api/v1/objects` | read | `objects:read` | List Objects |
+| [`restoreObjectRecord`](#op-restoreobjectrecord) ★ | `POST /api/v1/objects/{object_slug}/records/{record_id}/restore` | write | `objects:write` | Restore Object Record |
+| [`updateAttribute`](#op-updateattribute) ★ | `PATCH /api/v1/objects/{object_slug}/attributes/{attr_slug}` | write | `objects:manage` | Update Attribute |
+| [`updateObject`](#op-updateobject) ★ | `PATCH /api/v1/objects/{object_slug}` | write | `objects:manage` | Update Object |
+| [`updateObjectRecord`](#op-updateobjectrecord) ★ | `PATCH /api/v1/objects/{object_slug}/records/{record_id}` | write | `objects:write` | Update Object Record |
+| [`upsertObjectRecord`](#op-upsertobjectrecord) ★ | `POST /api/v1/objects/{object_slug}/records/upsert` | write | `objects:write` | Upsert Object Record |
+
+---
+
+<a id="op-archiveattribute"></a>
+
+### `g8.api.objects.archiveAttribute(input)`
+
+**Archive Attribute**
+
+- HTTP: `DELETE /api/v1/objects/{object_slug}/attributes/{attr_slug}`
+- operationId: `archive_attribute_objects__object_slug__attributes__attr_slug__delete` (also callable as `g8.api.call("archive_attribute_objects__object_slug__attributes__attr_slug__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `objects:manage`
+- ★ Hand-written: [`g8.objects.archiveAttribute()`](../sdk-clients.md#g8-objects-archiveattribute)
+
+Archive a custom field, retaining its values. Restore with PATCH is_archived=false.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `path.attr_slug` | `string` | yes |  |
+
+**Returns** `ApiResponse_AttributeDefinitionResponse_`: the envelope `{ data: AttributeDefinitionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AttributeDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `attribute_type` | `string` | yes | One of the 16 supported attribute types (`text`, `number`, `email_address`, `timestamp`, `select`, `record_reference`, …). Determines how values are validated and canonicalized. |
+| `slug` | `string` | yes | Stable API slug for the attribute, used as a payload key. |
+| `title` | `string` | yes | Customer-facing field label, distinct from its stable API slug. |
+| `config` | `Record<string, unknown>` | no | Type-specific configuration, e.g. select options. Record references require target_object and must resolve to active records in that object within the caller's organization and app. |
+| `default_value` | `unknown` | no | Configured create default. Enabled non-null defaults pass the same validation as explicit values. |
+| `description` | `string \| null` | no | Customer-configured description of the field. |
+| `is_archived` | `boolean` | no | Archived fields retain their values and can be restored. default `false` |
+| `is_default_value_enabled` | `boolean` | no | Apply the configured default when this field is omitted on create. Never applies on PATCH. default `false` |
+| `is_multiselect` | `boolean` | no | Values are a list rather than a scalar. default `false` |
+| `is_required` | `boolean` | no | Required on create. PATCH may omit it, but cannot clear it with null or an empty multivalue list. default `false` |
+| `is_system` | `boolean` | no | Whether this field is protected as a system attribute. default `false` |
+| `is_unique` | `boolean` | no | No two active records may hold the same value for this attribute. A collision is rejected with `409 duplicate_active_value`. default `false` |
+| `sort_order` | `integer` | no | Configured display order; equal values are ordered by API slug. default `0` |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.objects.archiveAttribute({ path: { object_slug: "example", attr_slug: "example" } });
+```
+
+---
+
+<a id="op-archiveobject"></a>
+
+### `g8.api.objects.archiveObject(input)`
+
+**Archive Object**
+
+- HTTP: `DELETE /api/v1/objects/{object_slug}`
+- operationId: `archive_object_objects__object_slug__delete` (also callable as `g8.api.call("archive_object_objects__object_slug__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `objects:manage`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.archive()`](../sdk-clients.md#g8-objects-archive)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Archive a custom object without deleting data; restore with PATCH is_archived=false.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+
+**Returns** `ApiResponse_ObjectDefinitionResponse_`: the envelope `{ data: ObjectDefinitionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `plural_noun` | `string` | yes | Display name for many records, e.g. "Invoices". |
+| `singular_noun` | `string` | yes | Display name for one record, e.g. "Invoice". |
+| `slug` | `string` | yes | Stable API slug for the object type, e.g. `invoices`. |
+| `description` | `string \| null` | no | Customer-configured object description. |
+| `display_attribute_slug` | `string \| null` | no | Active single-value field used to label records; null uses the default. |
+| `icon` | `string \| null` | no | Configured graph8 icon name; null uses the default. |
+| `is_archived` | `boolean` | no | Archived objects are hidden from listings. default `false` |
+| `is_system` | `boolean` | no | True for objects graph8 ships; system objects cannot be deleted. default `false` |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.objects.archiveObject({ path: { object_slug: "example" } });
+```
+
+---
+
+<a id="op-archiveobjectrecord"></a>
+
+### `g8.api.objects.archiveObjectRecord(input)`
+
+**Archive Object Record**
+
+- HTTP: `DELETE /api/v1/objects/{object_slug}/records/{record_id}`
+- operationId: `archive_object_record_objects__object_slug__records__record_id__delete` (also callable as `g8.api.call("archive_object_record_objects__object_slug__records__record_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `objects:delete`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.archiveRecord()`](../sdk-clients.md#g8-objects-archiverecord)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Archive a record.
+
+The record is hidden from listings but stays readable by id, and its history
+and associations are preserved. Nothing is destroyed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `path.record_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_ObjectRecordResponse_`: the envelope `{ data: ObjectRecordResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectRecordResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Opaque record identifier. |
+| `object_slug` | `string` | yes | The object type this record belongs to. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `is_archived` | `boolean` | no | Archived records are excluded from listings. default `false` |
+| `revision` | `integer` | no | Record revision for conditional updates. default `1`, min 1 |
+| `updated_at` | `string (date-time) \| null` | no |  |
+| `values` | `Record<string, unknown>` | no | Currently active values, keyed by attribute slug. Shapes follow each attribute's own type; call `GET /objects/{object_slug}/attributes` for the schema. |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.objects.archiveObjectRecord({ path: { object_slug: "example", record_id: "id" } });
+```
+
+---
+
+<a id="op-createattribute"></a>
+
+### `g8.api.objects.createAttribute(input)`
+
+**Create Attribute**
+
+- HTTP: `POST /api/v1/objects/{object_slug}/attributes`
+- operationId: `create_attribute_objects__object_slug__attributes_post` (also callable as `g8.api.call("create_attribute_objects__object_slug__attributes_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:manage`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.createAttribute()`](../sdk-clients.md#g8-objects-createattribute)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Create a typed CRM field. Requires objects:manage and current Admin access.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `body` | `AttributeCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`AttributeCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.attribute_type` | `AttributeType` | yes |  |
+| `body.slug` | `string` | yes | min length 1, max length 100, pattern `^[a-z][a-z0-9_]*$` |
+| `body.title` | `string` | yes | min length 1, max length 200 |
+| `body.config` | `AttributeConfig \| null` | no |  |
+| `body.default_value` | `unknown \| null` | no |  |
+| `body.description` | `string \| null` | no |  |
+| `body.is_default_value_enabled` | `boolean` | no | default `false` |
+| `body.is_multiselect` | `boolean` | no | default `false` |
+| `body.is_required` | `boolean` | no | default `false` |
+| `body.is_unique` | `boolean` | no | default `false` |
+| `body.sort_order` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_AttributeDefinitionResponse_`: the envelope `{ data: AttributeDefinitionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AttributeDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `attribute_type` | `string` | yes | One of the 16 supported attribute types (`text`, `number`, `email_address`, `timestamp`, `select`, `record_reference`, …). Determines how values are validated and canonicalized. |
+| `slug` | `string` | yes | Stable API slug for the attribute, used as a payload key. |
+| `title` | `string` | yes | Customer-facing field label, distinct from its stable API slug. |
+| `config` | `Record<string, unknown>` | no | Type-specific configuration, e.g. select options. Record references require target_object and must resolve to active records in that object within the caller's organization and app. |
+| `default_value` | `unknown` | no | Configured create default. Enabled non-null defaults pass the same validation as explicit values. |
+| `description` | `string \| null` | no | Customer-configured description of the field. |
+| `is_archived` | `boolean` | no | Archived fields retain their values and can be restored. default `false` |
+| `is_default_value_enabled` | `boolean` | no | Apply the configured default when this field is omitted on create. Never applies on PATCH. default `false` |
+| `is_multiselect` | `boolean` | no | Values are a list rather than a scalar. default `false` |
+| `is_required` | `boolean` | no | Required on create. PATCH may omit it, but cannot clear it with null or an empty multivalue list. default `false` |
+| `is_system` | `boolean` | no | Whether this field is protected as a system attribute. default `false` |
+| `is_unique` | `boolean` | no | No two active records may hold the same value for this attribute. A collision is rejected with `409 duplicate_active_value`. default `false` |
+| `sort_order` | `integer` | no | Configured display order; equal values are ordered by API slug. default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.createAttribute({
+  path: { object_slug: "example" },
+  body: { attribute_type: "text", slug: "example", title: "Example" },
+});
+```
+
+---
+
+<a id="op-createobject"></a>
+
+### `g8.api.objects.createObject(input)`
+
+**Create Object**
+
+- HTTP: `POST /api/v1/objects`
+- operationId: `create_object_objects_post` (also callable as `g8.api.call("create_object_objects_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:manage`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.create()`](../sdk-clients.md#g8-objects-create)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Create a native custom object. Requires objects:manage and Admin access.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ObjectCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`ObjectCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.plural_noun` | `string` | yes | min length 1, max length 100 |
+| `body.singular_noun` | `string` | yes | min length 1, max length 100 |
+| `body.slug` | `string` | yes | min length 1, max length 100, pattern `^[a-z][a-z0-9_]*$` |
+| `body.description` | `string \| null` | no | max length 2000 |
+| `body.icon` | `"box" \| "briefcase" \| "building" \| "calendar" \| "flag" \| "folder" \| "globe" \| "heart" \| … \| null` | no |  |
+
+**Returns** `ApiResponse_ObjectDefinitionResponse_`: the envelope `{ data: ObjectDefinitionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `plural_noun` | `string` | yes | Display name for many records, e.g. "Invoices". |
+| `singular_noun` | `string` | yes | Display name for one record, e.g. "Invoice". |
+| `slug` | `string` | yes | Stable API slug for the object type, e.g. `invoices`. |
+| `description` | `string \| null` | no | Customer-configured object description. |
+| `display_attribute_slug` | `string \| null` | no | Active single-value field used to label records; null uses the default. |
+| `icon` | `string \| null` | no | Configured graph8 icon name; null uses the default. |
+| `is_archived` | `boolean` | no | Archived objects are hidden from listings. default `false` |
+| `is_system` | `boolean` | no | True for objects graph8 ships; system objects cannot be deleted. default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.createObject({
+  body: { plural_noun: "example", singular_noun: "example", slug: "example" },
+});
+```
+
+---
+
+<a id="op-createobjectrecord"></a>
+
+### `g8.api.objects.createObjectRecord(input)`
+
+**Create Object Record**
+
+- HTTP: `POST /api/v1/objects/{object_slug}/records`
+- operationId: `create_object_record_objects__object_slug__records_post` (also callable as `g8.api.call("create_object_record_objects__object_slug__records_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:write`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.createRecord()`](../sdk-clients.md#g8-objects-createrecord)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Create a record.
+
+Every field is validated against the object's attribute definitions. Unknown
+fields are rejected with 422 — they are not dropped — and the response lists
+every problem at once so a client fixes them in one round trip. A collision on
+a unique attribute returns 409.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `body` | `RecordWriteRequest` | yes | Request body; fields below. |
+
+Body fields (`RecordWriteRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.values` | `Record<string, unknown>` | no | Attribute values keyed by slug. Call `GET /objects/{object_slug}/attributes` for active fields. Canonical contacts and companies retain CONTACT_*, COMPANY_* and udo_* field names. Unknown keys are rejected with 422. PATCH preserves omitted fields; required fields cannot be cleared with null or an empty multivalue list. Record references must resolve to active records of their configured target ob… |
+
+**Returns** `ApiResponse_ObjectRecordResponse_`: the envelope `{ data: ObjectRecordResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectRecordResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Opaque record identifier. |
+| `object_slug` | `string` | yes | The object type this record belongs to. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `is_archived` | `boolean` | no | Archived records are excluded from listings. default `false` |
+| `revision` | `integer` | no | Record revision for conditional updates. default `1`, min 1 |
+| `updated_at` | `string (date-time) \| null` | no |  |
+| `values` | `Record<string, unknown>` | no | Currently active values, keyed by attribute slug. Shapes follow each attribute's own type; call `GET /objects/{object_slug}/attributes` for the schema. |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.createObjectRecord({ path: { object_slug: "example" }, body: {} });
+```
+
+---
+
+<a id="op-getobject"></a>
+
+### `g8.api.objects.getObject(input)`
+
+**Get Object**
+
+- HTTP: `GET /api/v1/objects/{object_slug}`
+- operationId: `get_object_objects__object_slug__get` (also callable as `g8.api.call("get_object_objects__object_slug__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.get()`](../sdk-clients.md#g8-objects-get)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Fetch one accessible registered standard or custom object type by its slug.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+
+**Returns** `ApiResponse_ObjectDefinitionResponse_`: the envelope `{ data: ObjectDefinitionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `plural_noun` | `string` | yes | Display name for many records, e.g. "Invoices". |
+| `singular_noun` | `string` | yes | Display name for one record, e.g. "Invoice". |
+| `slug` | `string` | yes | Stable API slug for the object type, e.g. `invoices`. |
+| `description` | `string \| null` | no | Customer-configured object description. |
+| `display_attribute_slug` | `string \| null` | no | Active single-value field used to label records; null uses the default. |
+| `icon` | `string \| null` | no | Configured graph8 icon name; null uses the default. |
+| `is_archived` | `boolean` | no | Archived objects are hidden from listings. default `false` |
+| `is_system` | `boolean` | no | True for objects graph8 ships; system objects cannot be deleted. default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.getObject({ path: { object_slug: "example" } });
+```
+
+---
+
+<a id="op-getobjectrecord"></a>
+
+### `g8.api.objects.getObjectRecord(input)`
+
+**Get Object Record**
+
+- HTTP: `GET /api/v1/objects/{object_slug}/records/{record_id}`
+- operationId: `get_object_record_objects__object_slug__records__record_id__get` (also callable as `g8.api.call("get_object_record_objects__object_slug__records__record_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.getRecord()`](../sdk-clients.md#g8-objects-getrecord)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Fetch one record with its currently active values.
+
+Contacts and companies retain their canonical graph8 IDs; deals retain their
+canonical UUIDs. Deal values include active typed fields and permitted
+company, primary-contact and contact_ids references. Related-record access is checked
+independently of deal access. Generic deal mutations are not yet supported.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `path.record_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_ObjectRecordResponse_`: the envelope `{ data: ObjectRecordResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectRecordResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Opaque record identifier. |
+| `object_slug` | `string` | yes | The object type this record belongs to. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `is_archived` | `boolean` | no | Archived records are excluded from listings. default `false` |
+| `revision` | `integer` | no | Record revision for conditional updates. default `1`, min 1 |
+| `updated_at` | `string (date-time) \| null` | no |  |
+| `values` | `Record<string, unknown>` | no | Currently active values, keyed by attribute slug. Shapes follow each attribute's own type; call `GET /objects/{object_slug}/attributes` for the schema. |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.getObjectRecord({ path: { object_slug: "example", record_id: "id" } });
+```
+
+---
+
+<a id="op-getobjectrecordchanges"></a>
+
+### `g8.api.objects.getObjectRecordChanges(input)`
+
+**Get Object Record Changes**
+
+- HTTP: `GET /api/v1/objects/{object_slug}/records/{record_id}/changes`
+- operationId: `get_object_record_changes_objects__object_slug__records__record_id__changes_get` (also callable as `g8.api.call("get_object_record_changes_objects__object_slug__records__record_id__changes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+- ★ Hand-written: [`g8.objects.changes()`](../sdk-clients.md#g8-objects-changes)
+
+Read recorded mutation authorship and before/after changes with stable cursor pagination.
+
+Custom records include clear and lifecycle actions. Canonical contacts and companies use
+their existing IDs and audit facts, bounded by current record access and
+field privacy; archived records are unavailable through this reader.
+Older writes without recorded mutation facts are not reconstructed here.
+An unavailable audit store returns 503, never an empty success response.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `path.record_id` | `string` | yes |  |
+| `query.limit` | `integer` | no | default `100` |
+| `query.cursor` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_RecordMutationsResponse_`: the envelope `{ data: RecordMutationsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RecordMutationsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `entries` | `Array<RecordMutationEntry>` | yes |  |
+| `record_id` | `string` | yes |  |
+| `next_cursor` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.getObjectRecordChanges({ path: { object_slug: "example", record_id: "id" } });
+```
+
+---
+
+<a id="op-getobjectrecordhistory"></a>
+
+### `g8.api.objects.getObjectRecordHistory(input)`
+
+**Get Object Record History**
+
+- HTTP: `GET /api/v1/objects/{object_slug}/records/{record_id}/history`
+- operationId: `get_object_record_history_objects__object_slug__records__record_id__history_get` (also callable as `g8.api.call("get_object_record_history_objects__object_slug__records__record_id__history_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.history()`](../sdk-clients.md#g8-objects-history)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+A record's value timeline, newest first.
+
+Each entry is one generation of one attribute. An entry whose `active_until`
+is null is the value currently in force.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `path.record_id` | `string` | yes |  |
+| `query.limit` | `integer` | no | Maximum generations to return default `100` |
+
+**Returns** `ApiResponse_RecordHistoryResponse_`: the envelope `{ data: RecordHistoryResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`RecordHistoryResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `record_id` | `string` | yes |  |
+| `entries` | `Array<RecordHistoryEntry>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.getObjectRecordHistory({ path: { object_slug: "example", record_id: "id" } });
+```
+
+---
+
+<a id="op-listobjectattributes"></a>
+
+### `g8.api.objects.listObjectAttributes(input)`
+
+**List Object Attributes**
+
+- HTTP: `GET /api/v1/objects/{object_slug}/attributes`
+- operationId: `list_object_attributes_objects__object_slug__attributes_get` (also callable as `g8.api.call("list_object_attributes_objects__object_slug__attributes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.listAttributes()`](../sdk-clients.md#g8-objects-listattributes)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+List active fields. Archived-field discovery currently applies to custom objects.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `query.include_archived` | `boolean` | no | default `false` |
+
+**Returns** `ApiResponse_list_AttributeDefinitionResponse__`: the envelope `{ data: Array<AttributeDefinitionResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AttributeDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `attribute_type` | `string` | yes | One of the 16 supported attribute types (`text`, `number`, `email_address`, `timestamp`, `select`, `record_reference`, …). Determines how values are validated and canonicalized. |
+| `slug` | `string` | yes | Stable API slug for the attribute, used as a payload key. |
+| `title` | `string` | yes | Customer-facing field label, distinct from its stable API slug. |
+| `config` | `Record<string, unknown>` | no | Type-specific configuration, e.g. select options. Record references require target_object and must resolve to active records in that object within the caller's organization and app. |
+| `default_value` | `unknown` | no | Configured create default. Enabled non-null defaults pass the same validation as explicit values. |
+| `description` | `string \| null` | no | Customer-configured description of the field. |
+| `is_archived` | `boolean` | no | Archived fields retain their values and can be restored. default `false` |
+| `is_default_value_enabled` | `boolean` | no | Apply the configured default when this field is omitted on create. Never applies on PATCH. default `false` |
+| `is_multiselect` | `boolean` | no | Values are a list rather than a scalar. default `false` |
+| `is_required` | `boolean` | no | Required on create. PATCH may omit it, but cannot clear it with null or an empty multivalue list. default `false` |
+| `is_system` | `boolean` | no | Whether this field is protected as a system attribute. default `false` |
+| `is_unique` | `boolean` | no | No two active records may hold the same value for this attribute. A collision is rejected with `409 duplicate_active_value`. default `false` |
+| `sort_order` | `integer` | no | Configured display order; equal values are ordered by API slug. default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.listObjectAttributes({ path: { object_slug: "example" } });
+```
+
+---
+
+<a id="op-listobjectrecords"></a>
+
+### `g8.api.objects.listObjectRecords(input)`
+
+**List Object Records**
+
+- HTTP: `GET /api/v1/objects/{object_slug}/records`
+- operationId: `list_object_records_objects__object_slug__records_get` (also callable as `g8.api.call("list_object_records_objects__object_slug__records_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.listRecords()`](../sdk-clients.md#g8-objects-listrecords)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+List an object's records, newest last, with their active values.
+
+Archived records are excluded. Supports page-number and opaque cursor
+pagination; when `cursor` is supplied it wins. Deals use canonical UUIDs,
+current ownership scope, typed values and independently permitted references.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `query.page` | `integer` | no | Page number (ignored when `cursor` is supplied) default `1` |
+| `query.limit` | `integer` | no | Items per page default `50` |
+| `query.cursor` | `string \| null` | no | Opaque pagination cursor from a prior response's `next_cursor`. When supplied it takes precedence over `page`. |
+
+**Returns** `ApiResponse_list_ObjectRecordResponse__`: the envelope `{ data: Array<ObjectRecordResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectRecordResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Opaque record identifier. |
+| `object_slug` | `string` | yes | The object type this record belongs to. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `is_archived` | `boolean` | no | Archived records are excluded from listings. default `false` |
+| `revision` | `integer` | no | Record revision for conditional updates. default `1`, min 1 |
+| `updated_at` | `string (date-time) \| null` | no |  |
+| `values` | `Record<string, unknown>` | no | Currently active values, keyed by attribute slug. Shapes follow each attribute's own type; call `GET /objects/{object_slug}/attributes` for the schema. |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.listObjectRecords({ path: { object_slug: "example" } });
+```
+
+---
+
+<a id="op-listobjects"></a>
+
+### `g8.api.objects.listObjects(input?)`
+
+**List Objects**
+
+- HTTP: `GET /api/v1/objects`
+- operationId: `list_objects_objects_get` (also callable as `g8.api.call("list_objects_objects_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `objects:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.list()`](../sdk-clients.md#g8-objects-list)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+List accessible registered standard and custom objects; optionally include archived custom definitions.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.include_archived` | `boolean` | no | default `false` |
+
+**Returns** `ApiResponse_list_ObjectDefinitionResponse__`: the envelope `{ data: Array<ObjectDefinitionResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `plural_noun` | `string` | yes | Display name for many records, e.g. "Invoices". |
+| `singular_noun` | `string` | yes | Display name for one record, e.g. "Invoice". |
+| `slug` | `string` | yes | Stable API slug for the object type, e.g. `invoices`. |
+| `description` | `string \| null` | no | Customer-configured object description. |
+| `display_attribute_slug` | `string \| null` | no | Active single-value field used to label records; null uses the default. |
+| `icon` | `string \| null` | no | Configured graph8 icon name; null uses the default. |
+| `is_archived` | `boolean` | no | Archived objects are hidden from listings. default `false` |
+| `is_system` | `boolean` | no | True for objects graph8 ships; system objects cannot be deleted. default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.listObjects();
+```
+
+---
+
+<a id="op-restoreobjectrecord"></a>
+
+### `g8.api.objects.restoreObjectRecord(input)`
+
+**Restore Object Record**
+
+- HTTP: `POST /api/v1/objects/{object_slug}/records/{record_id}/restore`
+- operationId: `restore_object_record_objects__object_slug__records__record_id__restore_post` (also callable as `g8.api.call("restore_object_record_objects__object_slug__records__record_id__restore_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:write`
+- ★ Hand-written: [`g8.objects.restoreRecord()`](../sdk-clients.md#g8-objects-restorerecord)
+
+Restore the archived values under current constraints, preserving identity and history.
+
+Unique-value conflicts return 409. Invalid schema/references or an ambiguous
+legacy archive snapshot return 422. Retrying an already restored record is a
+read with no additional revision or history generation.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `path.record_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_ObjectRecordResponse_`: the envelope `{ data: ObjectRecordResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectRecordResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Opaque record identifier. |
+| `object_slug` | `string` | yes | The object type this record belongs to. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `is_archived` | `boolean` | no | Archived records are excluded from listings. default `false` |
+| `revision` | `integer` | no | Record revision for conditional updates. default `1`, min 1 |
+| `updated_at` | `string (date-time) \| null` | no |  |
+| `values` | `Record<string, unknown>` | no | Currently active values, keyed by attribute slug. Shapes follow each attribute's own type; call `GET /objects/{object_slug}/attributes` for the schema. |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.restoreObjectRecord({ path: { object_slug: "example", record_id: "id" } });
+```
+
+---
+
+<a id="op-updateattribute"></a>
+
+### `g8.api.objects.updateAttribute(input)`
+
+**Update Attribute**
+
+- HTTP: `PATCH /api/v1/objects/{object_slug}/attributes/{attr_slug}`
+- operationId: `update_attribute_objects__object_slug__attributes__attr_slug__patch` (also callable as `g8.api.call("update_attribute_objects__object_slug__attributes__attr_slug__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:manage`
+- ★ Hand-written: [`g8.objects.updateAttribute()`](../sdk-clients.md#g8-objects-updateattribute)
+
+Edit or restore a field; omitted values remain unchanged. Type and slug are immutable.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `path.attr_slug` | `string` | yes |  |
+| `body` | `AttributeUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`AttributeUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.config` | `AttributeConfig \| null` | no |  |
+| `body.default_value` | `unknown \| null` | no |  |
+| `body.description` | `string \| null` | no |  |
+| `body.is_archived` | `boolean \| null` | no |  |
+| `body.is_default_value_enabled` | `boolean \| null` | no |  |
+| `body.is_multiselect` | `boolean \| null` | no |  |
+| `body.is_required` | `boolean \| null` | no |  |
+| `body.is_unique` | `boolean \| null` | no |  |
+| `body.sort_order` | `integer \| null` | no |  |
+| `body.title` | `string \| null` | no | min length 1, max length 200 |
+
+**Returns** `ApiResponse_AttributeDefinitionResponse_`: the envelope `{ data: AttributeDefinitionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AttributeDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `attribute_type` | `string` | yes | One of the 16 supported attribute types (`text`, `number`, `email_address`, `timestamp`, `select`, `record_reference`, …). Determines how values are validated and canonicalized. |
+| `slug` | `string` | yes | Stable API slug for the attribute, used as a payload key. |
+| `title` | `string` | yes | Customer-facing field label, distinct from its stable API slug. |
+| `config` | `Record<string, unknown>` | no | Type-specific configuration, e.g. select options. Record references require target_object and must resolve to active records in that object within the caller's organization and app. |
+| `default_value` | `unknown` | no | Configured create default. Enabled non-null defaults pass the same validation as explicit values. |
+| `description` | `string \| null` | no | Customer-configured description of the field. |
+| `is_archived` | `boolean` | no | Archived fields retain their values and can be restored. default `false` |
+| `is_default_value_enabled` | `boolean` | no | Apply the configured default when this field is omitted on create. Never applies on PATCH. default `false` |
+| `is_multiselect` | `boolean` | no | Values are a list rather than a scalar. default `false` |
+| `is_required` | `boolean` | no | Required on create. PATCH may omit it, but cannot clear it with null or an empty multivalue list. default `false` |
+| `is_system` | `boolean` | no | Whether this field is protected as a system attribute. default `false` |
+| `is_unique` | `boolean` | no | No two active records may hold the same value for this attribute. A collision is rejected with `409 duplicate_active_value`. default `false` |
+| `sort_order` | `integer` | no | Configured display order; equal values are ordered by API slug. default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.updateAttribute({ path: { object_slug: "example", attr_slug: "example" }, body: {} });
+```
+
+---
+
+<a id="op-updateobject"></a>
+
+### `g8.api.objects.updateObject(input)`
+
+**Update Object**
+
+- HTTP: `PATCH /api/v1/objects/{object_slug}`
+- operationId: `update_object_objects__object_slug__patch` (also callable as `g8.api.call("update_object_objects__object_slug__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:manage`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.update()`](../sdk-clients.md#g8-objects-update)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Rename, archive or restore a custom object while retaining its slug and data.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `body` | `ObjectUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`ObjectUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.description` | `string \| null` | no | max length 2000 |
+| `body.display_attribute_slug` | `string \| null` | no | min length 1, max length 100, pattern `^[a-z][a-z0-9_]*$` |
+| `body.icon` | `"box" \| "briefcase" \| "building" \| "calendar" \| "flag" \| "folder" \| "globe" \| "heart" \| … \| null` | no |  |
+| `body.is_archived` | `boolean \| null` | no |  |
+| `body.plural_noun` | `string \| null` | no | min length 1, max length 100 |
+| `body.singular_noun` | `string \| null` | no | min length 1, max length 100 |
+
+**Returns** `ApiResponse_ObjectDefinitionResponse_`: the envelope `{ data: ObjectDefinitionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectDefinitionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `plural_noun` | `string` | yes | Display name for many records, e.g. "Invoices". |
+| `singular_noun` | `string` | yes | Display name for one record, e.g. "Invoice". |
+| `slug` | `string` | yes | Stable API slug for the object type, e.g. `invoices`. |
+| `description` | `string \| null` | no | Customer-configured object description. |
+| `display_attribute_slug` | `string \| null` | no | Active single-value field used to label records; null uses the default. |
+| `icon` | `string \| null` | no | Configured graph8 icon name; null uses the default. |
+| `is_archived` | `boolean` | no | Archived objects are hidden from listings. default `false` |
+| `is_system` | `boolean` | no | True for objects graph8 ships; system objects cannot be deleted. default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.updateObject({ path: { object_slug: "example" }, body: {} });
+```
+
+---
+
+<a id="op-updateobjectrecord"></a>
+
+### `g8.api.objects.updateObjectRecord(input)`
+
+**Update Object Record**
+
+- HTTP: `PATCH /api/v1/objects/{object_slug}/records/{record_id}`
+- operationId: `update_object_record_objects__object_slug__records__record_id__patch` (also callable as `g8.api.call("update_object_record_objects__object_slug__records__record_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:write`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.objects.updateRecord()`](../sdk-clients.md#g8-objects-updaterecord)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Update a record's values. Only the supplied attributes are touched.
+
+A partial update, so required attributes you do not send are left alone rather
+than reported missing. Sending an explicit `null` CLEARS that attribute.
+Values are versioned rather than overwritten, so the previous value stays
+readable through the history endpoint.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `path.record_id` | `string` | yes |  |
+| `body` | `RecordUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`RecordUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.append_values` | `Record<string, Array<unknown>>` | no | Append canonical non-duplicate values to multivalue fields. Fields must not overlap values or remove_values. |
+| `body.expected_revision` | `integer \| null` | no | Required for canonical contact or company PATCH. Apply only if the record still has this revision; otherwise return 409. min 1 |
+| `body.remove_values` | `Record<string, Array<unknown>>` | no | Remove all canonical matches from multivalue fields. Fields must not overlap values or append_values. |
+| `body.values` | `Record<string, unknown>` | no | Attribute values keyed by slug. Call `GET /objects/{object_slug}/attributes` for active fields. Canonical contacts and companies retain CONTACT_*, COMPANY_* and udo_* field names. Unknown keys are rejected with 422. PATCH preserves omitted fields; required fields cannot be cleared with null or an empty multivalue list. Record references must resolve to active records of their configured target ob… |
+
+**Returns** `ApiResponse_ObjectRecordResponse_`: the envelope `{ data: ObjectRecordResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectRecordResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Opaque record identifier. |
+| `object_slug` | `string` | yes | The object type this record belongs to. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `is_archived` | `boolean` | no | Archived records are excluded from listings. default `false` |
+| `revision` | `integer` | no | Record revision for conditional updates. default `1`, min 1 |
+| `updated_at` | `string (date-time) \| null` | no |  |
+| `values` | `Record<string, unknown>` | no | Currently active values, keyed by attribute slug. Shapes follow each attribute's own type; call `GET /objects/{object_slug}/attributes` for the schema. |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.updateObjectRecord({ path: { object_slug: "example", record_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-upsertobjectrecord"></a>
+
+### `g8.api.objects.upsertObjectRecord(input)`
+
+**Upsert Object Record**
+
+- HTTP: `POST /api/v1/objects/{object_slug}/records/upsert`
+- operationId: `upsert_object_record_objects__object_slug__records_upsert_post` (also callable as `g8.api.call("upsert_object_record_objects__object_slug__records_upsert_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `objects:write`
+- ★ Hand-written: [`g8.objects.upsertRecord()`](../sdk-clients.md#g8-objects-upsertrecord)
+
+Create (201) or update (200) by a unique key, preserving omitted fields.
+
+A revision requires an existing matching record; a stale or absent match
+returns 409. Validation, matching, and mutation share one transaction.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.object_slug` | `string` | yes |  |
+| `body` | `RecordUpsertRequest` | yes | Request body; fields below. |
+
+Body fields (`RecordUpsertRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.matching_attribute` | `string` | yes | Active single-value unique attribute. Its nonempty value must be supplied in values. min length 1, max length 100, pattern `^[a-z][a-z0-9_]*$` |
+| `body.expected_revision` | `integer \| null` | no | min 1 |
+| `body.values` | `Record<string, unknown>` | no | Attribute values keyed by slug. Call `GET /objects/{object_slug}/attributes` for active fields. Canonical contacts and companies retain CONTACT_*, COMPANY_* and udo_* field names. Unknown keys are rejected with 422. PATCH preserves omitted fields; required fields cannot be cleared with null or an empty multivalue list. Record references must resolve to active records of their configured target ob… |
+
+**Returns** `ApiResponse_ObjectRecordResponse_`: the envelope `{ data: ObjectRecordResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ObjectRecordResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes | Opaque record identifier. |
+| `object_slug` | `string` | yes | The object type this record belongs to. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `is_archived` | `boolean` | no | Archived records are excluded from listings. default `false` |
+| `revision` | `integer` | no | Record revision for conditional updates. default `1`, min 1 |
+| `updated_at` | `string (date-time) \| null` | no |  |
+| `values` | `Record<string, unknown>` | no | Currently active values, keyed by attribute slug. Shapes follow each attribute's own type; call `GET /objects/{object_slug}/attributes` for the schema. |
+
+**Example**
+
+```ts
+const result = await g8.api.objects.upsertObjectRecord({
+  path: { object_slug: "example" },
+  body: { matching_attribute: "example" },
+});
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-attributeconfig"></a>
+
+### `AttributeConfig`
+
+Configuration for specific attribute types.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `currency_code` | `string \| null` | no |  |
+| `max_value` | `integer \| null` | no |  |
+| `options` | `Array<Record<string, unknown>> \| null` | no |  |
+| `referenced_object` | `string \| null` | no |  |
+| `target_object` | `string \| null` | no |  |
+
+<a id="type-attributetype"></a>
+
+### `AttributeType`
+
+Valid attribute types for the Custom Objects type system.
+
+Type: `"text" | "number" | "currency" | "date" | "timestamp" | "checkbox" | "select" | "status" | …`.
+
+<a id="type-recordhistoryentry"></a>
+
+### `RecordHistoryEntry`
+
+One generation of one attribute's value. Values are TEMPORAL rather than mutable: setting a new value closes the previous generation and opens a new one, so history is the natural reading of the store rather than a separate log that could drift from it. An entry with a null `active_until` is the value currently in force.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `attribute` | `string` | yes | Attribute slug this generation belongs to. |
+| `active_from` | `string (date-time) \| null` | no | When this value took effect. |
+| `active_until` | `string (date-time) \| null` | no | When it was superseded. Null means it is still in force. |
+| `actor_id` | `string \| null` | no | Opaque id of whoever set it. |
+| `value` | `unknown` | no | The value held during this generation. |
+
+<a id="type-recordmutationentry"></a>
+
+### `RecordMutationEntry`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `"created" \| "updated" \| "archived" \| "restored"` | yes |  |
+| `actor_id` | `string \| null` | yes |  |
+| `actor_type` | `"user" \| "api" \| "app" \| "integration" \| "system"` | yes |  |
+| `changes` | `Record<string, RecordMutationValueChange>` | yes |  |
+| `id` | `string` | yes |  |
+| `is_archived` | `boolean` | yes |  |
+| `occurred_at` | `string (date-time)` | yes |  |
+| `revision` | `integer` | yes | min 1 |
+| `source` | `string` | yes |  |
+| `was_archived` | `boolean` | yes |  |
+| `app_id` | `string \| null` | no |  |