---
title: Contract
description: Contract protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

Standard Create Request

<Callout type="info">
**Source:** `packages/spec/src/api/contract.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { ApiError, BaseResponse, BatchLoadingStrategy, BulkRequest, BulkResponse, CreateRequest, DataLoaderConfig, DeleteResponse, ExportRequest, IdRequest, ListRecordResponse, ModificationResult, QueryOptimizationConfig, RecordData, SingleRecordResponse, UpdateRequest } from '@objectstack/spec/api';
import type { ApiError, BaseResponse, BatchLoadingStrategy, BulkRequest, BulkResponse, CreateRequest, DataLoaderConfig, DeleteResponse, ExportRequest, IdRequest, ListRecordResponse, ModificationResult, QueryOptimizationConfig, RecordData, SingleRecordResponse, UpdateRequest } from '@objectstack/spec/api';

// Validate data
const result = ApiError.parse(data);
```

---

## ApiError

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **code** | `string` | ✅ | Error code (e.g. validation_error) |
| **message** | `string` | ✅ | Readable error message |
| **category** | `string` | optional | Error category (e.g. validation, authorization) |
| **details** | `any` | optional | Additional error context (e.g. field validation errors) |
| **requestId** | `string` | optional | Request ID for tracking |


---

## BaseResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |


---

## BatchLoadingStrategy

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **strategy** | `Enum<'dataloader' \| 'windowed' \| 'prefetch'>` | ✅ | Batch loading strategy type |
| **windowMs** | `number` | optional | Collection window duration in milliseconds (for windowed strategy) |
| **prefetchDepth** | `integer` | optional | Depth of relation prefetching (for prefetch strategy) |
| **associationLoading** | `Enum<'lazy' \| 'eager' \| 'batch'>` | ✅ | How to load related associations |


---

## BulkRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **records** | `Record<string, any>[]` | ✅ | Array of records to process |
| **allOrNone** | `boolean` | ✅ | If true, rollback entire transaction on any failure |


---

## BulkResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Object[]` | ✅ | Results for each item in the batch |


---

## CreateRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **data** | `Record<string, any>` | ✅ | Record data to insert |


---

## DataLoaderConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **maxBatchSize** | `integer` | ✅ | Maximum number of keys per batch load |
| **batchScheduleFn** | `Enum<'microtask' \| 'timeout' \| 'manual'>` | ✅ | Scheduling strategy for collecting batch keys |
| **cacheEnabled** | `boolean` | ✅ | Enable per-request result caching |
| **cacheKeyFn** | `string` | optional | Name or identifier of the cache key function |
| **cacheTtl** | `number` | optional | Cache time-to-live in seconds (0 = no expiration) |
| **coalesceRequests** | `boolean` | ✅ | Deduplicate identical requests within a batch window |
| **maxConcurrency** | `integer` | optional | Maximum parallel batch requests |


---

## DeleteResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **id** | `string` | ✅ | ID of the deleted record |


---

## ExportRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **object** | `string` | ✅ | Object name (e.g. account) |
| **fields** | `[__schema1](./__schema1)[]` | optional | Fields to retrieve |
| **where** | `[__schema2](./__schema2)` | optional | Filtering criteria (WHERE) |
| **search** | `Object` | optional | Full-text search configuration ($search parameter) |
| **orderBy** | `Object[]` | optional | Sorting instructions (ORDER BY) |
| **limit** | `number` | optional | Max records to return (LIMIT) |
| **offset** | `number` | optional | Records to skip (OFFSET) |
| **top** | `number` | optional | Alias for limit (OData compatibility) |
| **cursor** | `Record<string, any>` | optional | Cursor for keyset pagination |
| **joins** | `Object[]` | optional | Explicit Table Joins |
| **aggregations** | `Object[]` | optional | Aggregation functions |
| **groupBy** | `string \| Object[]` | optional | GROUP BY targets (strings or `{field, dateGranularity?}` objects for date bucketing) |
| **having** | `[__schema2](./__schema2)` | optional | HAVING clause for aggregation filtering |
| **windowFunctions** | `Object[]` | optional | Window functions with OVER clause |
| **distinct** | `boolean` | optional | SELECT DISTINCT flag |
| **expand** | `Record<string, [__schema0](./__schema0)>` | optional | Recursive relation loading map. Keys are lookup/master_detail field names; values are nested QueryAST objects that control select, filter, sort, and further expansion on the related object. The engine resolves expand via batch $in queries (driver-agnostic) with a default max depth of 3. |


---

## IdRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | ✅ | Record ID |


---

## ListRecordResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Record<string, any>[]` | ✅ | Array of matching records |
| **pagination** | `Object` | ✅ | Pagination info |


---

## ModificationResult

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **id** | `string` | optional | Record ID if processed |
| **success** | `boolean` | ✅ |  |
| **errors** | `Object[]` | optional |  |
| **index** | `number` | optional | Index in original request |
| **data** | `any` | optional | Result data (e.g. created record) |


---

## QueryOptimizationConfig

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **preventNPlusOne** | `boolean` | ✅ | Enable N+1 query detection and prevention |
| **dataLoader** | `Object` | optional | DataLoader batch loading configuration |
| **batchStrategy** | `Object` | optional | Batch loading strategy configuration |
| **maxQueryDepth** | `integer` | ✅ | Maximum depth for nested relation queries |
| **queryComplexityLimit** | `number` | optional | Maximum allowed query complexity score |
| **enableQueryPlan** | `boolean` | ✅ | Log query execution plans for debugging |


---


---

## SingleRecordResponse

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **success** | `boolean` | ✅ | Operation success status |
| **error** | `Object` | optional | Error details if success is false |
| **meta** | `Object` | optional | Response metadata |
| **data** | `Record<string, any>` | ✅ | The requested or modified record |


---

## UpdateRequest

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **data** | `Record<string, any>` | ✅ | Partial record data to update |


---

