Worksheets API

Spreadsheet-style data for your organization: folders, worksheets, typed columns, rows with cell values, saved views with their own row/column access, row attachments backed by managed buckets, CSV/XLSX import and export, cross-zone connections, IAM-delegated access control, and an immutable activity log. Rows are stored in an OLTP layout with per-column read/write optimization, cursor pagination, and structured query filters.

Base URL/api/v1/worksheets

Automation triggers: view every Worksheets event, payload field, and predicate.

Folders

Folders group worksheets within a company and are the primary Worksheets federated-zone root. Permissions are delegated inside org/{company_id}/folder/{folder_id} and inherited by nested worksheets and views. Per-user preferences (favorite, ordering) live alongside the folder list.

POST/api/v1/worksheets/companies/{company_id}/folders

Create Folder

Create a new folder under the given company.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Request Body

Name	Type	Description
`name`*	string	Display name (1–200 characters)
`description`	string \| null	Optional description
`icon`	string \| null	Optional icon key or URL
`color`	string \| null	Hex color; defaults to #3b82f6 if omitted

Response Fields

Name	Type	Description
`id`*	UUID	Folder ID
`company_id`*	UUID	Organization ID
`name`*	string	Folder name
`description`*	string \| null	Description
`icon`*	string \| null	Icon
`color`*	string	Hex color
`created_by`*	UUID \| null	Creator user ID
`created_at`*	datetime	Creation time (UTC)
`worksheet_count`	number	Number of worksheets in the folder
`capabilities`	object	Caller's effective permissions on this folder (can_create_worksheet, can_create_view, can_delete, manage_settings, manage_security, view_activity)

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/companies/{company_id}/folders \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Pipeline",
    "description": "Deals and accounts",
    "icon": "folder-kanban",
    "color": "#2563eb"
  }'

Response

201 Created

{
  "id": "f1111111-2222-3333-4444-555555555555",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Sales Pipeline",
  "description": "Deals and accounts",
  "icon": "folder-kanban",
  "color": "#2563eb",
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-01T14:22:00Z",
  "worksheet_count": 0,
  "capabilities": {
    "can_create_worksheet": true,
    "can_create_view": true,
    "can_delete": true,
    "manage_settings": true,
    "manage_security": true,
    "view_activity": true
  }
}

GET/api/v1/worksheets/companies/{company_id}/folders

List Folders

List folders for a company. Results respect folder-level view permissions.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Response Fields

Name	Type	Description
`[]`*	array	Folder list items (id, name, description, icon, color, created_at, worksheet_count)

curl https://platform.ergondata.ai/api/v1/worksheets/companies/{company_id}/folders \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "f1111111-2222-3333-4444-555555555555",
    "name": "Sales Pipeline",
    "description": "Deals and accounts",
    "icon": "folder-kanban",
    "color": "#2563eb",
    "created_at": "2026-04-01T14:22:00Z",
    "worksheet_count": 3
  }
]

GET/api/v1/worksheets/folders/{folder_id}

Get Folder

Retrieve a single folder including worksheet count and caller capabilities.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

curl https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "f1111111-2222-3333-4444-555555555555",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Sales Pipeline",
  "description": "Deals and accounts",
  "icon": "folder-kanban",
  "color": "#2563eb",
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-01T14:22:00Z",
  "worksheet_count": 3
}

PATCH/api/v1/worksheets/folders/{folder_id}

Update Folder

Update folder fields. Omitted fields are left unchanged.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

Request Body

Name	Type	Description
`name`	string \| null	New name (1–200 characters)
`description`	string \| null	Updated description
`icon`	string \| null	Updated icon
`color`	string \| null	Updated hex color

curl -X PATCH https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales Pipeline v2"}'

Response

200 OK

{
  "id": "f1111111-2222-3333-4444-555555555555",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "name": "Sales Pipeline v2",
  "description": "Deals and accounts",
  "icon": "folder-kanban",
  "color": "#2563eb",
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-01T14:22:00Z",
  "worksheet_count": 3
}

DELETE/api/v1/worksheets/folders/{folder_id}

Delete Folder

Permanently delete a folder and its contents. This action cannot be undone.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/worksheets/companies/{company_id}/folder-prefs

Get Folder Preferences

Return the calling user's personal folder preferences for the company (favorite folder and custom folder ordering).

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Response Fields

Name	Type	Description
`favorite_folder_id`	UUID \| null	Pinned favorite folder, if any
`folder_order`	array of UUID	User-defined ordering of folder IDs

curl https://platform.ergondata.ai/api/v1/worksheets/companies/{company_id}/folder-prefs \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "favorite_folder_id": "f1111111-2222-3333-4444-555555555555",
  "folder_order": [
    "f1111111-2222-3333-4444-555555555555",
    "f2222222-3333-4444-5555-666666666666"
  ]
}

PUT/api/v1/worksheets/companies/{company_id}/folder-prefs

Update Folder Preferences

Replace the calling user's folder preferences. Send only the fields you want to change; null values clear them.

Bearer token required.

Path Parameters

Name	Type	Description
`company_id`*	string (UUID)	Organization ID

Request Body

Name	Type	Description
`favorite_folder_id`	UUID \| null	Folder to pin as favorite
`folder_order`	array of UUID \| null	New folder ordering

curl -X PUT https://platform.ergondata.ai/api/v1/worksheets/companies/{company_id}/folder-prefs \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"favorite_folder_id": "f1111111-2222-3333-4444-555555555555"}'

Response

200 OK

{
  "favorite_folder_id": "f1111111-2222-3333-4444-555555555555",
  "folder_order": [
    "f1111111-2222-3333-4444-555555555555",
    "f2222222-3333-4444-5555-666666666666"
  ]
}

Worksheets

A worksheet is a table scoped to a folder. It owns its columns, rows, and views, and may have a managed attachment bucket. default_optimize_policy sets the read/write index strategy that new columns inherit.

POST/api/v1/worksheets/folders/{folder_id}/worksheets

Create Worksheet

Create a worksheet inside a folder. It is appended after existing worksheets by position.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

Request Body

Name	Type	Description
`name`*	string	Worksheet name (1–200 characters)
`description`	string \| null	Optional description
`default_optimize_policy`	"read" \| "write"	Optimization new columns inherit when their own optimize_for is unset. Defaults to write.Default: `write`

Response Fields

Name	Type	Description
`id`*	UUID	Worksheet ID
`folder_id`*	UUID	Parent folder ID
`name`*	string	Name
`description`	string \| null	Description
`default_optimize_policy`	"read" \| "write"	Default optimize policy inherited by new columnsDefault: `write`
`position`*	number	Sort order within the folder
`created_by`*	UUID \| null	Creator
`created_at`*	datetime	Created at
`column_count`	number	Number of columns
`row_count`	number	Number of rows
`managed_bucket_id`	UUID \| null	Managed attachment bucket backing this worksheet, if provisioned
`principal_id`	UUID \| null	IAM principal representing this worksheet (for connections)
`capabilities`	object	Caller's effective permissions (can_create_columns, can_manage_columns, can_create_rows, can_edit_rows, can_delete_rows, manage_security, view_activity)

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/worksheets \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Deals"}'

Response

201 Created

{
  "id": "w2222222-3333-4444-5555-666666666666",
  "folder_id": "f1111111-2222-3333-4444-555555555555",
  "name": "Deals",
  "description": null,
  "default_optimize_policy": "write",
  "position": 0,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-02T09:15:00Z",
  "column_count": 0,
  "row_count": 0,
  "managed_bucket_id": null,
  "principal_id": "p9999999-8888-7777-6666-555555555555"
}

GET/api/v1/worksheets/folders/{folder_id}/worksheets

List Worksheets

List all worksheets in a folder, ordered by position.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

Response Fields

Name	Type	Description
`[]`*	array	Worksheet list items (id, name, position, created_at, column_count, row_count, managed_bucket_id)

curl https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/worksheets \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "w2222222-3333-4444-5555-666666666666",
    "name": "Deals",
    "position": 0,
    "created_at": "2026-04-02T09:15:00Z",
    "column_count": 5,
    "row_count": 128,
    "managed_bucket_id": null
  }
]

GET/api/v1/worksheets/worksheets/{worksheet_id}

Get Worksheet

Fetch worksheet metadata, aggregate column/row counts, and caller capabilities.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

curl https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "w2222222-3333-4444-5555-666666666666",
  "folder_id": "f1111111-2222-3333-4444-555555555555",
  "name": "Deals",
  "description": null,
  "default_optimize_policy": "write",
  "position": 0,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-02T09:15:00Z",
  "column_count": 5,
  "row_count": 128,
  "managed_bucket_id": null,
  "principal_id": "p9999999-8888-7777-6666-555555555555"
}

PATCH/api/v1/worksheets/worksheets/{worksheet_id}

Update Worksheet

Rename a worksheet, change its ordering within the folder, update its description, or switch its default optimize policy.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`name`	string \| null	New name (1–200 characters)
`description`	string \| null	Updated description
`position`	number \| null	New zero-based position
`default_optimize_policy`	"read" \| "write" \| null	Default optimize policy inherited by future columns

curl -X PATCH https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Deals (EMEA)", "position": 1}'

Response

200 OK

{
  "id": "w2222222-3333-4444-5555-666666666666",
  "folder_id": "f1111111-2222-3333-4444-555555555555",
  "name": "Deals (EMEA)",
  "description": null,
  "default_optimize_policy": "write",
  "position": 1,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-02T09:15:00Z",
  "column_count": 5,
  "row_count": 128,
  "managed_bucket_id": null
}

DELETE/api/v1/worksheets/worksheets/{worksheet_id}

Delete Worksheet

Delete a worksheet and all of its columns, rows, views, and cell values.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

Columns

Columns define field types, validation options, formulas, and references. Each column can be independently optimized for read or write and backed by sort/unique/equality indexes built in the background. Reordering updates display order; bulk endpoints mutate many columns atomically.

GET/api/v1/worksheets/field-types

List Field Types

Return all supported field_type slugs with hints about required options (select, currency, worksheet_ref, attachment, object, etc.).

No authentication required.

curl https://platform.ergondata.ai/api/v1/worksheets/field-types

Response

200 OK

[
  {
    "slug": "text",
    "name": "Text",
    "requires_options": false
  },
  {
    "slug": "select",
    "name": "Select",
    "requires_options": true,
    "options_format": {
      "choices": ["New", "Qualified", "Won"]
    }
  },
  {
    "slug": "currency",
    "name": "Currency",
    "requires_options": true,
    "options_format": {
      "currency": "USD",
      "locale": "en-US"
    }
  }
]

GET/api/v1/worksheets/columns/type-conversions

Get Type Conversions

Return the matrix of allowed field_type conversions used to validate Update Column requests that change a column's type.

No authentication required.

curl https://platform.ergondata.ai/api/v1/worksheets/columns/type-conversions

Response

200 OK

{
  "text": ["select", "number", "currency"],
  "number": ["text", "currency"],
  "select": ["text"]
}

GET/api/v1/worksheets/worksheets/{worksheet_id}/columns

List Columns

Return all columns for a worksheet ordered by position.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Response Fields

Name	Type	Description
`id`*	UUID	Column ID
`worksheet_id`*	UUID	Worksheet ID
`name`*	string	Column header
`description`*	string \| null	Help text
`field_type`*	string	Field type slug
`required`*	boolean	Required flag
`is_list`*	boolean	Whether the column holds a list of values
`options`*	object \| null	Type-specific options
`position`*	number	Display order
`width`*	number \| null	UI width
`frozen`*	boolean	Pinned in grid
`formula_expression`*	string \| null	Formula source for formula columns
`reference_config`*	object \| null	Cross-sheet reference config
`optimize_for`*	"read" \| "write"	Effective read/write optimization
`sortable`*	boolean	Sort index present
`unique`*	boolean	Uniqueness enforced
`indexed`*	boolean	Equality index present
`created_at`*	datetime	Created at

curl https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/columns \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "c1111111-1111-1111-1111-111111111111",
    "worksheet_id": "w2222222-3333-4444-5555-666666666666",
    "name": "Account",
    "description": null,
    "field_type": "text",
    "required": true,
    "is_list": false,
    "options": null,
    "position": 0,
    "width": 240,
    "frozen": true,
    "formula_expression": null,
    "reference_config": null,
    "optimize_for": "read",
    "sortable": true,
    "unique": true,
    "indexed": false,
    "created_at": "2026-04-02T10:00:00Z"
  }
]

POST/api/v1/worksheets/worksheets/{worksheet_id}/columns

Create Column

Add a column to a worksheet. field_type must be a valid slug from List Field Types.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`name`*	string	Column header (1–200 characters)
`description`	string \| null	Optional help text
`field_type`	string	Field slug; default textDefault: `text`
`required`	boolean	Whether values are requiredDefault: `false`
`is_list`	boolean	Allow multiple entries (lists, multi-refs, etc.)Default: `false`
`options`	object \| null	Type-specific configuration (choices, currency, schema, …)
`width`	number \| null	Optional UI width
`frozen`	boolean	Pin column in grid UIDefault: `false`
`formula_expression`	string \| null	For formula columns
`reference_config`	object \| null	For worksheet_ref / cross-sheet links
`optimize_for`	"read" \| "write" \| null	Read-optimized columns get a value index built asynchronously for fast filter/sort. null inherits the worksheet's default_optimize_policy.
`sortable`	boolean	Build a type-aware sort index for this column (background).Default: `false`
`unique`	boolean	Enforce value uniqueness and back it with a unique index.Default: `false`
`indexed`	boolean	Build a plain equality index for this column (background).Default: `false`

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/columns \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amount",
    "field_type": "currency",
    "required": true,
    "options": {"currency": "USD", "locale": "en-US"}
  }'

Response

201 Created

{
  "id": "c3333333-4444-5555-6666-777777777777",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "name": "Amount",
  "description": null,
  "field_type": "currency",
  "required": true,
  "is_list": false,
  "options": {
    "currency": "USD",
    "locale": "en-US"
  },
  "position": 2,
  "width": null,
  "frozen": false,
  "formula_expression": null,
  "reference_config": null,
  "optimize_for": "write",
  "sortable": false,
  "unique": false,
  "indexed": false,
  "created_at": "2026-04-03T11:05:00Z"
}

POST/api/v1/worksheets/worksheets/{worksheet_id}/columns/bulk

Bulk Create Columns

Create several columns in one request. Columns are appended in array order; each entry takes the same fields as Create Column.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`columns`*	array	Column definitions (same shape as Create Column)

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/columns/bulk \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": [
      {"name": "Stage", "field_type": "select", "options": {"choices": ["New", "Won"]}},
      {"name": "Owner", "field_type": "text"}
    ]
  }'

Response

201 Created

[
  {
    "id": "c4444444-5555-6666-7777-888888888888",
    "worksheet_id": "w2222222-3333-4444-5555-666666666666",
    "name": "Stage",
    "field_type": "select",
    "required": false,
    "is_list": false,
    "options": {"choices": ["New", "Won"]},
    "position": 3,
    "frozen": false,
    "optimize_for": "write",
    "sortable": false,
    "unique": false,
    "indexed": false,
    "created_at": "2026-04-03T11:10:00Z"
  }
]

POST/api/v1/worksheets/worksheets/{worksheet_id}/columns/bulk-update

Bulk Update Columns

Patch multiple columns in one call. Each entry must carry the column id plus the fields to change; omitted fields are left unchanged.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`columns`*	array	Per-column patches

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/columns/bulk-update \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": [
      {"id": "c1111111-1111-1111-1111-111111111111", "name": "Account name"},
      {"id": "c3333333-4444-5555-6666-777777777777", "required": false}
    ]
  }'

Response

200 OK

[
  {
    "id": "c1111111-1111-1111-1111-111111111111",
    "worksheet_id": "w2222222-3333-4444-5555-666666666666",
    "name": "Account name",
    "field_type": "text",
    "required": true,
    "position": 0,
    "optimize_for": "read",
    "sortable": true,
    "unique": true,
    "indexed": false,
    "created_at": "2026-04-02T10:00:00Z"
  }
]

POST/api/v1/worksheets/worksheets/{worksheet_id}/columns/bulk-delete

Bulk Delete Columns

Delete several columns and their cell values in one call.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`column_ids`*	array of UUID	Columns to delete

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/columns/bulk-delete \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"column_ids": ["c4444444-5555-6666-7777-888888888888"]}'

Response

204 No Content

PUT/api/v1/worksheets/worksheets/{worksheet_id}/columns/reorder

Reorder Columns

Set column order by listing every column ID in the desired sequence.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`column_ids`*	array of UUID	Ordered list of column IDs belonging to this worksheet

curl -X PUT https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/columns/reorder \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "column_ids": [
      "c1111111-1111-1111-1111-111111111111",
      "c3333333-4444-5555-6666-777777777777"
    ]
  }'

Response

200 OK

[
  {
    "id": "c1111111-1111-1111-1111-111111111111",
    "worksheet_id": "w2222222-3333-4444-5555-666666666666",
    "name": "Account name",
    "field_type": "text",
    "position": 0,
    "created_at": "2026-04-02T10:00:00Z"
  },
  {
    "id": "c3333333-4444-5555-6666-777777777777",
    "worksheet_id": "w2222222-3333-4444-5555-666666666666",
    "name": "Amount",
    "field_type": "currency",
    "options": {"currency": "USD", "locale": "en-US"},
    "position": 1,
    "created_at": "2026-04-03T11:05:00Z"
  }
]

PATCH/api/v1/worksheets/columns/{column_id}

Update Column

Patch column metadata, type, options, or formula. Changing field_type re-validates options against the conversion matrix.

Bearer token required.

Path Parameters

Name	Type	Description
`column_id`*	string (UUID)	Column ID

Request Body

Name	Type	Description
`name`	string \| null	New header
`description`	string \| null	Updated description
`field_type`	string \| null	New field slug
`required`	boolean \| null	Required flag
`is_list`	boolean \| null	List mode
`options`	object \| null	Replaced options when set
`width`	number \| null	Column width
`frozen`	boolean \| null	Frozen state
`formula_expression`	string \| null	Formula source
`reference_config`	object \| null	Reference settings
`optimize_for`	"read" \| "write" \| null	Switch optimization. Flipping write→read schedules a background value-index build; read→write drops it.
`sortable`	boolean \| null	Toggle the background sort index.
`unique`	boolean \| null	Toggle uniqueness. Enabling rejects new duplicates immediately; the backing index is built in the background.
`indexed`	boolean \| null	Toggle the background equality index.

curl -X PATCH https://platform.ergondata.ai/api/v1/worksheets/columns/{column_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Account name", "frozen": false}'

Response

200 OK

{
  "id": "c1111111-1111-1111-1111-111111111111",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "name": "Account name",
  "description": null,
  "field_type": "text",
  "required": true,
  "is_list": false,
  "options": null,
  "position": 0,
  "width": 240,
  "frozen": false,
  "formula_expression": null,
  "reference_config": null,
  "optimize_for": "write",
  "sortable": false,
  "unique": false,
  "indexed": false,
  "created_at": "2026-04-02T10:00:00Z"
}

DELETE/api/v1/worksheets/columns/{column_id}

Delete Column

Remove a column and its cell values from the worksheet.

Bearer token required.

Path Parameters

Name	Type	Description
`column_id`*	string (UUID)	Column ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/columns/{column_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

POST/api/v1/worksheets/worksheets/{worksheet_id}/columns/attachment-pipeline/schemas/generate

Generate Attachment Column Schema (New Column)

Generate the extraction JSON schema for a not-yet-created attachment-pipeline column from a natural-language prompt. Returns a draft schema you can attach to a Create Column request.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`prompt`*	string	Natural-language description of the fields to extract from attachments

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/columns/attachment-pipeline/schemas/generate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Extract invoice number, total, and due date"}'

Response

200 OK

{
  "schema": {
    "type": "object",
    "properties": {
      "invoice_number": {"type": "string"},
      "total": {"type": "number"},
      "due_date": {"type": "string", "format": "date"}
    }
  }
}

POST/api/v1/worksheets/columns/{column_id}/attachment-pipeline/schemas/generate

Generate Attachment Column Schema (Existing Column)

Regenerate the extraction JSON schema for an existing attachment-pipeline column from a natural-language prompt, using the column's current configuration as context.

Bearer token required.

Path Parameters

Name	Type	Description
`column_id`*	string (UUID)	Column ID

Request Body

Name	Type	Description
`prompt`*	string	Natural-language description of the fields to extract

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/columns/{column_id}/attachment-pipeline/schemas/generate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Also capture the vendor name"}'

Response

200 OK

{
  "schema": {
    "type": "object",
    "properties": {
      "invoice_number": {"type": "string"},
      "total": {"type": "number"},
      "due_date": {"type": "string", "format": "date"},
      "vendor_name": {"type": "string"}
    }
  }
}

Rows

Rows hold cell values keyed by column_id. Listing supports limit/offset and keyset (cursor) pagination plus sort by column value. Query adds structured filters; lookup, related, and resolve-refs power worksheet_ref pickers and cascades. Bulk endpoints create, update, or delete many rows per call.

GET/api/v1/worksheets/worksheets/{worksheet_id}/rows

List Rows

Paginated rows with embedded cell values. Sort by column name using column_name:asc|desc. Use cursor for keyset pagination, and set include_total=false to skip the count on large worksheets.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Query Parameters

Name	Type	Description
`sort`	string	e.g. Amount:desc or Account name:asc
`limit`	integer	Page sizeDefault: `100`
`offset`	integer	Rows to skip (ignored when cursor is set)Default: `0`
`cursor`	string	Keyset cursor from a previous page's next_cursor (overrides offset)
`include_total`	boolean	Compute full count(*); set false to skipDefault: `true`

Response Fields

Name	Type	Description
`rows`*	array	Row list items (id, position, created_at, updated_at, cell_values[])
`total`	number \| null	Total rows matching, or null when include_total=false
`limit`*	number	Applied limit
`offset`*	number	Applied offset
`next_cursor`	string \| null	Cursor for the next page, or null at the end

curl "https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows?limit=50&offset=0&sort=Amount:desc" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "rows": [
    {
      "id": "r4444444-5555-6666-7777-888888888888",
      "position": 127,
      "created_at": "2026-04-04T08:40:00Z",
      "updated_at": "2026-04-04T08:40:00Z",
      "cell_values": [
        {
          "column_id": "c1111111-1111-1111-1111-111111111111",
          "column_name": "Account name",
          "value": {"raw": "Acme Corp"}
        }
      ]
    }
  ],
  "total": 128,
  "limit": 50,
  "offset": 0,
  "next_cursor": "eyJzIjoiQWNtZSIsImlkIjoicjQ0NCJ9"
}

POST/api/v1/worksheets/worksheets/{worksheet_id}/rows

Create Row

Append a row. Optionally set initial cell values; values are validated per column type.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`cell_values`	array \| null	Cells to write on create

Response Fields

Name	Type	Description
`id`*	UUID	Row ID
`worksheet_id`*	UUID	Worksheet ID
`position`*	number	Row position
`created_by`*	UUID \| null	Creator
`created_at`*	datetime	Created at
`updated_at`*	datetime	Updated at
`cell_values`	array	Hydrated cells (column_id, column_name, value)

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "cell_values": [
      {"column_id": "c1111111-1111-1111-1111-111111111111", "value": {"raw": "Acme Corp"}},
      {"column_id": "c3333333-4444-5555-6666-777777777777", "value": {"raw": "25000"}}
    ]
  }'

Response

201 Created

{
  "id": "r4444444-5555-6666-7777-888888888888",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "position": 127,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-04T08:40:00Z",
  "updated_at": "2026-04-04T08:40:00Z",
  "cell_values": [
    {
      "column_id": "c1111111-1111-1111-1111-111111111111",
      "column_name": "Account name",
      "value": {"raw": "Acme Corp"}
    },
    {
      "column_id": "c3333333-4444-5555-6666-777777777777",
      "column_name": "Amount",
      "value": {"raw": "25000"}
    }
  ]
}

GET/api/v1/worksheets/rows/{row_id}

Get Row

Fetch a row with all hydrated cell values and column names.

Bearer token required.

Path Parameters

Name	Type	Description
`row_id`*	string (UUID)	Row ID

curl https://platform.ergondata.ai/api/v1/worksheets/rows/{row_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "r4444444-5555-6666-7777-888888888888",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "position": 127,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-04T08:40:00Z",
  "updated_at": "2026-04-05T16:10:00Z",
  "cell_values": [
    {
      "column_id": "c1111111-1111-1111-1111-111111111111",
      "column_name": "Account name",
      "value": {"raw": "Acme Corp"}
    }
  ]
}

PATCH/api/v1/worksheets/rows/{row_id}

Update Row

Upsert cell values for the given columns on an existing row.

Bearer token required.

Path Parameters

Name	Type	Description
`row_id`*	string (UUID)	Row ID

Request Body

Name	Type	Description
`cell_values`	array \| null	Cells to upsert

curl -X PATCH https://platform.ergondata.ai/api/v1/worksheets/rows/{row_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"cell_values": [{"column_id": "c3333333-4444-5555-6666-777777777777", "value": {"raw": "27500"}}]}'

Response

200 OK

{
  "id": "r4444444-5555-6666-7777-888888888888",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "position": 127,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-04T08:40:00Z",
  "updated_at": "2026-04-05T16:10:00Z",
  "cell_values": [
    {
      "column_id": "c3333333-4444-5555-6666-777777777777",
      "column_name": "Amount",
      "value": {"raw": "27500"}
    }
  ]
}

DELETE/api/v1/worksheets/rows/{row_id}

Delete Row

Delete a row and its cell values.

Bearer token required.

Path Parameters

Name	Type	Description
`row_id`*	string (UUID)	Row ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/rows/{row_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

POST/api/v1/worksheets/worksheets/{worksheet_id}/rows/bulk

Bulk Create Rows

Create many rows in one request. Each entry may include cell_values.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`rows`*	array	Row payloads

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows/bulk \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {"cell_values": [{"column_id": "c1111111-1111-1111-1111-111111111111", "value": {"raw": "Globex"}}]},
      {"cell_values": [{"column_id": "c1111111-1111-1111-1111-111111111111", "value": {"raw": "Initech"}}]}
    ]
  }'

Response

201 Created

[
  {
    "id": "r5555555-6666-7777-8888-999999999999",
    "worksheet_id": "w2222222-3333-4444-5555-666666666666",
    "position": 128,
    "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-04-06T12:00:00Z",
    "updated_at": "2026-04-06T12:00:00Z",
    "cell_values": [
      {
        "column_id": "c1111111-1111-1111-1111-111111111111",
        "column_name": "Account name",
        "value": {"raw": "Globex"}
      }
    ]
  }
]

POST/api/v1/worksheets/worksheets/{worksheet_id}/rows/bulk-update

Bulk Update Rows

Upsert cell values across many rows in one call. Each entry targets a row_id and a set of cell_values.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`rows`*	array	Per-row updates

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows/bulk-update \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "row_id": "r4444444-5555-6666-7777-888888888888",
        "cell_values": [{"column_id": "c3333333-4444-5555-6666-777777777777", "value": {"raw": "30000"}}]
      }
    ]
  }'

Response

200 OK

[
  {
    "id": "r4444444-5555-6666-7777-888888888888",
    "worksheet_id": "w2222222-3333-4444-5555-666666666666",
    "position": 127,
    "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-04-04T08:40:00Z",
    "updated_at": "2026-04-07T09:00:00Z",
    "cell_values": [
      {
        "column_id": "c3333333-4444-5555-6666-777777777777",
        "column_name": "Amount",
        "value": {"raw": "30000"}
      }
    ]
  }
]

POST/api/v1/worksheets/worksheets/{worksheet_id}/rows/bulk-delete

Bulk Delete Rows

Delete many rows in one call. Only rows that belong to the worksheet are removed.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`row_ids`*	array of UUID	Rows to delete

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows/bulk-delete \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"row_ids": ["r5555555-6666-7777-8888-999999999999"]}'

Response

204 No Content

POST/api/v1/worksheets/worksheets/{worksheet_id}/rows/query

Query Rows

Filtered, paginated row listing with structured filter conditions. Returns the same paginated shape as List Rows.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`filters`	array	Filter conditions
`sort`	string \| null	Sort expression (same as List Rows sort param)
`limit`	integer	Page sizeDefault: `100`
`offset`	integer	Rows to skipDefault: `0`
`cursor`	string \| null	Opaque keyset cursor from a previous page's next_cursor; overrides offset when set
`include_total`	boolean	Compute the full count(*). Set false on large worksheets to skip it.Default: `true`

Response Fields

Name	Type	Description
`rows`*	array	Row list items with cell_values
`total`	number \| null	Total rows matching the filters (null when include_total=false)
`limit`*	number	Applied limit
`offset`*	number	Applied offset
`next_cursor`	string \| null	Cursor for the next page

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows/query \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"column_id": "c3333333-4444-5555-6666-777777777777", "operator": "gte", "value": 10000}
    ],
    "sort": "Amount:desc",
    "limit": 50,
    "offset": 0
  }'

Response

200 OK

{
  "rows": [
    {
      "id": "r4444444-5555-6666-7777-888888888888",
      "position": 127,
      "created_at": "2026-04-04T08:40:00Z",
      "updated_at": "2026-04-04T08:40:00Z",
      "cell_values": [
        {
          "column_id": "c3333333-4444-5555-6666-777777777777",
          "column_name": "Amount",
          "value": {"raw": "25000"}
        }
      ]
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "next_cursor": null
}

GET/api/v1/worksheets/worksheets/{worksheet_id}/rows/lookup

Lookup Rows

Typeahead search for worksheet_ref pickers: match display column values containing the query string. Supports cascade restrictions via row_ids (relationship mode) or filter_column_id + filter_values (attribute mode). Returns paginated results sorted alphabetically.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Query Parameters

Name	Type	Description
`column_id`*	string (UUID)	Display column to search
`q`	string	Search text (case-insensitive substring)Default: `""`
`limit`	integer	Max matches per pageDefault: `50`
`offset`	integer	Rows to skip for paginationDefault: `0`
`row_ids`	string	Comma-separated row IDs to restrict results to (relationship cascade)
`filter_column_id`	string (UUID)	Column to constrain candidates by (attribute cascade)
`filter_values`	string	Comma-separated accepted values for filter_column_id (IN semantics)

Response Fields

Name	Type	Description
`items`*	array	Matches (row_id, display_value)
`total`*	number	Total matches
`has_more`*	boolean	Whether more pages exist

curl "https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows/lookup?column_id={column_id}&q=acme&limit=50&offset=0" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "row_id": "r4444444-5555-6666-7777-888888888888",
      "display_value": {"raw": "Acme Corp"}
    },
    {
      "row_id": "r7777777-8888-9999-aaaa-bbbbbbbbbbbb",
      "display_value": {"raw": "Acme Logistics"}
    }
  ],
  "total": 42,
  "has_more": true
}

GET/api/v1/worksheets/worksheets/{worksheet_id}/rows/related

Resolve candidate rows related to anchor rows by walking a worksheet_ref relationship (relationship-mode cascade). forward returns rows referenced by the anchors; reverse returns rows that reference the anchors. Returns a list of matching row IDs.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Target worksheet of the relationship

Query Parameters

Name	Type	Description
`via_column_id`*	string (UUID)	worksheet_ref column expressing the relationship
`anchor_row_ids`*	string	Comma-separated anchor (parent) row IDs
`direction`	"forward" \| "reverse"	forward: anchors reference candidates; reverse: candidates reference anchorsDefault: `forward`
`limit`	integer	Maximum row IDs to returnDefault: `1000`

curl "https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows/related?via_column_id={column_id}&anchor_row_ids={row_id}&direction=forward" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "row_ids": [
    "r7777777-8888-9999-aaaa-bbbbbbbbbbbb",
    "r8888888-9999-aaaa-bbbb-cccccccccccc"
  ]
}

POST/api/v1/worksheets/worksheets/{worksheet_id}/rows/resolve-refs

Resolve References

Batch-resolve display values for rows referenced by a worksheet_ref column. Returns a mapping of row IDs to their display column values.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID containing the target display column

Request Body

Name	Type	Description
`display_column_id`*	UUID	Column whose values are displayed for referenced rows
`row_ids`*	array of UUID	Row IDs to resolve

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows/resolve-refs \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_column_id": "c1111111-1111-1111-1111-111111111111",
    "row_ids": [
      "r4444444-5555-6666-7777-888888888888",
      "r5555555-6666-7777-8888-999999999999"
    ]
  }'

Response

200 OK

{
  "r4444444-5555-6666-7777-888888888888": {"raw": "Acme Corp"},
  "r5555555-6666-7777-8888-999999999999": {"raw": "Globex"}
}

Row Attachments

Attachment columns store files in a managed bucket. Uploads use a presigned flow: request an upload URL, PUT the bytes to it, then confirm. Downloads return a short-lived presigned URL. Bucket targets enumerate where custom attachment columns may store their files.

POST/api/v1/worksheets/worksheets/{worksheet_id}/rows/{row_id}/attachments/upload-url

Request Upload URL

Request a presigned URL to upload a file for an attachment column cell. PUT the file bytes to upload_url, then call Confirm Upload with the returned object_key.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID
`row_id`*	string (UUID)	Row ID

Request Body

Name	Type	Description
`column_id`*	UUID	Attachment column ID
`filename`*	string	Original filename
`content_type`*	string	MIME type of the file
`size`*	integer	File size in bytes

Response Fields

Name	Type	Description
`upload_url`*	string	Short-lived presigned PUT URL — use it exactly as returned; do not parse, cache, or reconstruct it.
`object_key`*	string	Storage key to pass to Confirm Upload
`expires_in`*	integer	Seconds until the URL expires

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows/{row_id}/attachments/upload-url \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "column_id": "c5555555-6666-7777-8888-999999999999",
    "filename": "contract.pdf",
    "content_type": "application/pdf",
    "size": 482910
  }'

Response

200 OK

{
  "upload_url": "https://ergon-files.s3.us-east-1.amazonaws.com/worksheets/w2222222/rows/r4444444/contract.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=...",
  "object_key": "worksheets/w2222222/rows/r4444444/contract.pdf",
  "expires_in": 900
}

POST/api/v1/worksheets/worksheets/{worksheet_id}/rows/{row_id}/attachments/confirm

Confirm Upload

Confirm that a file was uploaded to the presigned URL and attach it to the column cell. Returns the updated list of attachments on the cell.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID
`row_id`*	string (UUID)	Row ID

Request Body

Name	Type	Description
`column_id`*	UUID	Attachment column ID
`object_key`*	string	Storage key returned by Request Upload URL
`filename`*	string	Original filename
`content_type`*	string	MIME type
`size`*	integer	File size in bytes

Response Fields

Name	Type	Description
`[]`*	array	Attachment metadata (filename, content_type, size, object_key, uploaded_at, bucket_id, buckets_file_id, folder_id)

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows/{row_id}/attachments/confirm \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "column_id": "c5555555-6666-7777-8888-999999999999",
    "object_key": "worksheets/w2222222/rows/r4444444/contract.pdf",
    "filename": "contract.pdf",
    "content_type": "application/pdf",
    "size": 482910
  }'

Response

200 OK

[
  {
    "filename": "contract.pdf",
    "content_type": "application/pdf",
    "size": 482910,
    "object_key": "worksheets/w2222222/rows/r4444444/contract.pdf",
    "uploaded_at": "2026-04-08T15:20:00Z",
    "bucket_id": "b1111111-2222-3333-4444-555555555555",
    "buckets_file_id": "bf222222-3333-4444-5555-666666666666",
    "folder_id": null
  }
]

GET/api/v1/worksheets/worksheets/{worksheet_id}/rows/{row_id}/attachments/download-url

Request Download URL

Return a short-lived presigned URL to download a stored attachment.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID
`row_id`*	string (UUID)	Row ID

Query Parameters

Name	Type	Description
`object_key`*	string	Storage key of the attachment
`buckets_file_id`	string (UUID)	Optional buckets file ID when the attachment lives in a custom bucket

Response Fields

Name	Type	Description
`download_url`*	string	Short-lived presigned GET URL — use it exactly as returned; do not parse, cache, or reconstruct it.
`expires_in`*	integer	Seconds until the URL expires

curl "https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows/{row_id}/attachments/download-url?object_key={object_key}" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "download_url": "https://ergon-files.s3.us-east-1.amazonaws.com/worksheets/w2222222/rows/r4444444/contract.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=300&X-Amz-Signature=...",
  "expires_in": 300
}

DELETE/api/v1/worksheets/worksheets/{worksheet_id}/rows/{row_id}/attachments

Remove Attachment

Remove a single attachment from an attachment column cell, identified by column_id and object_key. Returns the remaining attachments on the cell.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID
`row_id`*	string (UUID)	Row ID

Request Body

Name	Type	Description
`column_id`*	UUID	Attachment column ID
`object_key`*	string	Storage key of the attachment to remove

Response Fields

Name	Type	Description
`[]`*	array	Remaining attachment metadata on the cell

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/rows/{row_id}/attachments \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "column_id": "c5555555-6666-7777-8888-999999999999",
    "object_key": "worksheets/w2222222/rows/r4444444/contract.pdf"
  }'

Response

200 OK

[]

GET/api/v1/worksheets/worksheets/{worksheet_id}/attachment-bucket-targets

List Attachment Bucket Targets

List buckets and folders eligible as custom attachment-column targets. Returns the buckets and folder tree the calling user can view; system-managed buckets and folders are filtered out.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Response Fields

Name	Type	Description
`[]`*	array	Target options (id, name, target_type, bucket_id, bucket_name, folder_id, parent_folder_id, storage_path, depth, nested folders[])

curl https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/attachment-bucket-targets \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "b1111111-2222-3333-4444-555555555555",
    "name": "Shared Documents",
    "target_type": "bucket",
    "bucket_id": "b1111111-2222-3333-4444-555555555555",
    "bucket_name": "Shared Documents",
    "folder_id": null,
    "parent_folder_id": null,
    "storage_path": "",
    "depth": 0,
    "folders": [
      {
        "id": "bf222222-3333-4444-5555-666666666666",
        "name": "Contracts",
        "target_type": "folder",
        "bucket_id": "b1111111-2222-3333-4444-555555555555",
        "bucket_name": "Shared Documents",
        "folder_id": "bf222222-3333-4444-5555-666666666666",
        "parent_folder_id": null,
        "storage_path": "Contracts",
        "depth": 1,
        "folders": []
      }
    ]
  }
]

Views

Saved grid or board layouts with JSON config for filters, grouping, and column visibility. Views are an access boundary in their own right: they expose per-view column configuration and a row sub-API (list/get/create/update/delete, lookup, query, resolve-refs) gated by view-scoped permissions and the view's locked filters.

POST/api/v1/worksheets/worksheets/{worksheet_id}/views

Create View

Create a named view. Set is_default true to mark the preferred layout for new sessions.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`name`*	string	View name (1–200 characters)
`type`	string	Layout discriminatorDefault: `grid`
`config`	object \| null	Serialized UI state (filters, sorts, hidden columns)
`is_default`	boolean	Whether this view opens by defaultDefault: `false`

Response Fields

Name	Type	Description
`id`*	UUID	View ID
`worksheet_id`*	UUID	Worksheet ID
`name`*	string	View name
`type`*	string	Layout type
`config`*	object \| null	Serialized UI state
`is_default`*	boolean	Default flag
`created_by`*	UUID \| null	Creator
`created_at`*	datetime	Created at
`capabilities`	object	Caller's effective per-view permissions

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/views \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Open deals",
    "type": "grid",
    "is_default": true,
    "config": {
      "filters": [{"column_id": "c3333333-4444-5555-6666-777777777777", "op": "gte", "value": 10000}],
      "hidden_columns": []
    }
  }'

Response

201 Created

{
  "id": "v8888888-9999-aaaa-bbbb-cccccccccccc",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "name": "Open deals",
  "type": "grid",
  "config": {
    "filters": [
      {"column_id": "c3333333-4444-5555-6666-777777777777", "op": "gte", "value": 10000}
    ],
    "hidden_columns": []
  },
  "is_default": true,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-07T07:30:00Z"
}

GET/api/v1/worksheets/worksheets/{worksheet_id}/views

List Views

Return all views for a worksheet ordered by creation time.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

curl https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/views \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "v8888888-9999-aaaa-bbbb-cccccccccccc",
    "worksheet_id": "w2222222-3333-4444-5555-666666666666",
    "name": "Open deals",
    "type": "grid",
    "config": {"filters": [], "hidden_columns": []},
    "is_default": true,
    "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-04-07T07:30:00Z"
  }
]

GET/api/v1/worksheets/folders/{folder_id}/views

List Folder Views

Return all views across every worksheet in a folder, ordered by creation time.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

curl https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/views \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "v8888888-9999-aaaa-bbbb-cccccccccccc",
    "worksheet_id": "w2222222-3333-4444-5555-666666666666",
    "name": "Open deals",
    "type": "grid",
    "config": {"filters": [], "hidden_columns": []},
    "is_default": true,
    "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-04-07T07:30:00Z"
  }
]

GET/api/v1/worksheets/views/{view_id}

Get View

Fetch a single view definition.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

curl https://platform.ergondata.ai/api/v1/worksheets/views/{view_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "v8888888-9999-aaaa-bbbb-cccccccccccc",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "name": "Open deals",
  "type": "grid",
  "config": {
    "filters": [],
    "hidden_columns": []
  },
  "is_default": true,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-07T07:30:00Z"
}

PATCH/api/v1/worksheets/views/{view_id}

Update View

Patch any combination of name, type, config, or default flag.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Request Body

Name	Type	Description
`name`	string \| null	Renamed title
`type`	string \| null	Layout type
`config`	object \| null	Replaced configuration JSON
`is_default`	boolean \| null	Default flag

curl -X PATCH https://platform.ergondata.ai/api/v1/worksheets/views/{view_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Open deals (rev 2)", "is_default": false}'

Response

200 OK

{
  "id": "v8888888-9999-aaaa-bbbb-cccccccccccc",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "name": "Open deals (rev 2)",
  "type": "grid",
  "config": {
    "filters": [],
    "hidden_columns": []
  },
  "is_default": false,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-07T07:30:00Z"
}

DELETE/api/v1/worksheets/views/{view_id}

Delete View

Remove a saved view.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/views/{view_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/worksheets/views/{view_id}/columns

List View Columns

Return the view's columns with per-view overrides applied (visibility, ordering, width, and label).

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Response Fields

Name	Type	Description
`[]`*	array	View columns (column fields plus view_label, view_position, visible)

curl https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/columns \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "c1111111-1111-1111-1111-111111111111",
    "worksheet_id": "w2222222-3333-4444-5555-666666666666",
    "name": "Account name",
    "field_type": "text",
    "required": true,
    "is_list": false,
    "options": null,
    "position": 0,
    "frozen": true,
    "width": 240,
    "view_label": "Account",
    "view_position": 0,
    "visible": true
  }
]

PATCH/api/v1/worksheets/views/{view_id}/columns

Update View Columns

Set per-view column configuration (visibility, ordering, width, label). Send the full set of columns you want to configure.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Request Body

Name	Type	Description
`columns`*	array	Per-view column overrides

curl -X PATCH https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/columns \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "columns": [
      {"column_id": "c1111111-1111-1111-1111-111111111111", "visible": true, "position": 0, "label": "Account"},
      {"column_id": "c3333333-4444-5555-6666-777777777777", "visible": false}
    ]
  }'

Response

200 OK

{
  "id": "v8888888-9999-aaaa-bbbb-cccccccccccc",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "name": "Open deals",
  "type": "grid",
  "config": {"filters": [], "hidden_columns": ["c3333333-4444-5555-6666-777777777777"]},
  "is_default": true,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-07T07:30:00Z"
}

POST/api/v1/worksheets/views/{view_id}/rows

Create View Row

Create a row through a view. The new row must satisfy the view's locked filters.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Request Body

Name	Type	Description
`cell_values`	array \| null	Cells to write on create

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/rows \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "cell_values": [
      {"column_id": "c1111111-1111-1111-1111-111111111111", "value": {"raw": "Umbrella Corp"}}
    ]
  }'

Response

201 Created

{
  "id": "r9999999-aaaa-bbbb-cccc-dddddddddddd",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "position": 130,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-09T10:00:00Z",
  "updated_at": "2026-04-09T10:00:00Z",
  "cell_values": [
    {
      "column_id": "c1111111-1111-1111-1111-111111111111",
      "column_name": "Account name",
      "value": {"raw": "Umbrella Corp"}
    }
  ]
}

POST/api/v1/worksheets/views/{view_id}/rows/bulk

Bulk Create View Rows

Create many rows through a view in one request.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Request Body

Name	Type	Description
`rows`*	array	Row payloads

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/rows/bulk \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {"cell_values": [{"column_id": "c1111111-1111-1111-1111-111111111111", "value": {"raw": "Stark Industries"}}]}
    ]
  }'

Response

201 Created

[
  {
    "id": "raaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "worksheet_id": "w2222222-3333-4444-5555-666666666666",
    "position": 131,
    "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-04-09T10:05:00Z",
    "updated_at": "2026-04-09T10:05:00Z",
    "cell_values": [
      {
        "column_id": "c1111111-1111-1111-1111-111111111111",
        "column_name": "Account name",
        "value": {"raw": "Stark Industries"}
      }
    ]
  }
]

GET/api/v1/worksheets/views/{view_id}/rows/lookup

Lookup View Rows

Typeahead search for rows through a view, applying the view's locked filters. Supports the same cascade restrictions as worksheet lookup (row_ids for relationship mode, filter_column_id + filter_values for attribute mode).

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Query Parameters

Name	Type	Description
`column_id`*	string (UUID)	Display column to search
`q`	string	Search textDefault: `""`
`limit`	integer	Max matches per pageDefault: `50`
`offset`	integer	Rows to skipDefault: `0`
`row_ids`	string	Comma-separated row IDs to restrict results to
`filter_column_id`	string (UUID)	Column to constrain candidates by (attribute cascade)
`filter_values`	string	Comma-separated accepted values for filter_column_id

curl "https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/rows/lookup?column_id={column_id}&q=acme" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "row_id": "r4444444-5555-6666-7777-888888888888",
      "display_value": {"raw": "Acme Corp"}
    }
  ],
  "total": 1,
  "has_more": false
}

POST/api/v1/worksheets/views/{view_id}/rows/query

Query View Rows

Filtered, paginated row listing through a view. The supplied filters are applied on top of the view's locked filters.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Request Body

Name	Type	Description
`filters`	array	Filter conditions (same shape as Query Rows)
`sort`	string \| null	Sort expression
`limit`	integer	Page sizeDefault: `100`
`offset`	integer	Rows to skipDefault: `0`
`cursor`	string \| null	Keyset cursor (overrides offset)
`include_total`	boolean	Compute the full count(*)Default: `true`

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/rows/query \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"column_id": "c1111111-1111-1111-1111-111111111111", "operator": "contains", "value": "Acme"}
    ],
    "limit": 25
  }'

Response

200 OK

{
  "rows": [
    {
      "id": "r4444444-5555-6666-7777-888888888888",
      "position": 127,
      "created_at": "2026-04-04T08:40:00Z",
      "updated_at": "2026-04-04T08:40:00Z",
      "cell_values": [
        {
          "column_id": "c1111111-1111-1111-1111-111111111111",
          "column_name": "Account name",
          "value": {"raw": "Acme Corp"}
        }
      ]
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0,
  "next_cursor": null
}

POST/api/v1/worksheets/views/{view_id}/rows/resolve-refs

Resolve View References

Batch-resolve worksheet_ref display values through a view. The view is the access boundary: if you can see the column in the view, you can see its resolved display value.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Request Body

Name	Type	Description
`display_column_id`*	UUID	Column whose values are displayed for referenced rows
`row_ids`*	array of UUID	Row IDs to resolve

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/rows/resolve-refs \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_column_id": "c1111111-1111-1111-1111-111111111111",
    "row_ids": ["r4444444-5555-6666-7777-888888888888"]
  }'

Response

200 OK

{
  "r4444444-5555-6666-7777-888888888888": {"raw": "Acme Corp"}
}

GET/api/v1/worksheets/views/{view_id}/rows/{row_id}

Get View Row

Get a single row through a view, enforcing the view's filters.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID
`row_id`*	string (UUID)	Row ID

curl https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/rows/{row_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "r4444444-5555-6666-7777-888888888888",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "position": 127,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-04T08:40:00Z",
  "updated_at": "2026-04-05T16:10:00Z",
  "cell_values": [
    {
      "column_id": "c1111111-1111-1111-1111-111111111111",
      "column_name": "Account name",
      "value": {"raw": "Acme Corp"}
    }
  ]
}

PATCH/api/v1/worksheets/views/{view_id}/rows/{row_id}

Update View Row

Upsert cell values on a row through a view, enforcing the view's filters.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID
`row_id`*	string (UUID)	Row ID

Request Body

Name	Type	Description
`cell_values`	array \| null	Cells to upsert

curl -X PATCH https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/rows/{row_id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"cell_values": [{"column_id": "c3333333-4444-5555-6666-777777777777", "value": {"raw": "32000"}}]}'

Response

200 OK

{
  "id": "r4444444-5555-6666-7777-888888888888",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "position": 127,
  "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-04T08:40:00Z",
  "updated_at": "2026-04-09T11:00:00Z",
  "cell_values": [
    {
      "column_id": "c3333333-4444-5555-6666-777777777777",
      "column_name": "Amount",
      "value": {"raw": "32000"}
    }
  ]
}

DELETE/api/v1/worksheets/views/{view_id}/rows/{row_id}

Delete View Row

Delete a row through a view, enforcing the view's filters.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID
`row_id`*	string (UUID)	Row ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/rows/{row_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

Import / Export

Upload CSV or XLSX files to append rows, or download the full worksheet as CSV or XLSX.

POST/api/v1/worksheets/worksheets/{worksheet_id}/import

Import Data

Multipart upload. Headers become columns (created if missing). Each data row becomes a new row with text values stored under {"raw": "..."}.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`file`*	file (multipart)	CSV or XLSX file under the form field name file

Response Fields

Name	Type	Description
`imported_rows`*	number	Rows created from the file
`columns`*	string[]	Column names present after import

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/import \
  -H "Authorization: Bearer {token}" \
  -F "file=@./deals.csv"

Response

201 Created

{
  "imported_rows": 42,
  "columns": ["Account", "Stage", "Owner", "Amount"]
}

GET/api/v1/worksheets/worksheets/{worksheet_id}/export

Export Data

Stream the worksheet as CSV (default) or XLSX. Filename uses the worksheet name.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Query Parameters

Name	Type	Description
`format`	string	csv or xlsxDefault: `csv`

curl "https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/export?format=csv" \
  -H "Authorization: Bearer {token}" \
  -o deals.csv

Response

200 OK

Account,Stage,Owner,Amount\nAcme Corp,Qualified,Jane Doe,25000\nGlobex,New,John Smith,9800\n

Event Types

Public metadata describing the event types emitted by Worksheets.

GET/api/v1/worksheets/event-types

List Event Types

Catalog of event types emitted by the Worksheets service. Used by the Automations service for trigger configuration and to filter activity queries.

No authentication required.

Response Fields

Name	Type	Description
`slug`*	string	Event type identifier
`name`*	string	Human-readable label
`description`*	string \| null	What the event represents

curl https://platform.ergondata.ai/api/v1/worksheets/event-types

Response

200 OK

[
  {
    "slug": "worksheets.row.created",
    "name": "Row created",
    "description": "Emitted when a row is inserted"
  },
  {
    "slug": "worksheets.column.updated",
    "name": "Column updated",
    "description": "Column metadata or options changed"
  }
]

Activity

Immutable audit log of worksheet operations with optional correlation identifiers. Activity can be paged at the folder, worksheet, or view scope, or fetched as a single event.

GET/api/v1/worksheets/folders/{folder_id}/activity

List Folder Activity

Page through activity events for a folder, optionally filtered by event type or correlation_id.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

Query Parameters

Name	Type	Description
`event_type`	string	Exact event slug filter
`correlation_id`	string (UUID)	Group related mutations
`page`	integer	1-based page indexDefault: `1`
`limit`	integer	Page size (1–100)Default: `50`

Response Fields

Name	Type	Description
`items`*	array	Activity events
`total`*	number	Total matching events
`page`*	number	Current page
`limit`*	number	Page size

curl "https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/activity?page=1&limit=25&event_type=worksheets.row.created" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "e1010101-2020-3030-4040-505050505050",
      "folder_id": "f1111111-2222-3333-4444-555555555555",
      "worksheet_id": "w2222222-3333-4444-5555-666666666666",
      "row_id": "r4444444-5555-6666-7777-888888888888",
      "event_type": "worksheets.row.created",
      "actor_type": "member",
      "actor_label": "Jane Doe",
      "correlation_id": "b0b0b0b0-b1b1-b2b2-b3b3-b4b4b4b4b4b4",
      "data": {"worksheet_name": "Deals"},
      "created_at": "2026-04-10T13:05:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 25
}

GET/api/v1/worksheets/worksheets/{worksheet_id}/activity

List Worksheet Activity

Page through activity events for a single worksheet (the in-worksheet detail feed).

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Query Parameters

Name	Type	Description
`event_type`	string	Exact event slug filter
`correlation_id`	string (UUID)	Group related mutations
`page`	integer	1-based page indexDefault: `1`
`limit`	integer	Page size (1–100)Default: `50`

curl "https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/activity?page=1&limit=25" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "e1010101-2020-3030-4040-505050505050",
      "folder_id": "f1111111-2222-3333-4444-555555555555",
      "worksheet_id": "w2222222-3333-4444-5555-666666666666",
      "row_id": "r4444444-5555-6666-7777-888888888888",
      "event_type": "worksheets.row.created",
      "actor_type": "member",
      "actor_label": "Jane Doe",
      "correlation_id": "b0b0b0b0-b1b1-b2b2-b3b3-b4b4b4b4b4b4",
      "data": {"worksheet_name": "Deals"},
      "created_at": "2026-04-10T13:05:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 25
}

GET/api/v1/worksheets/views/{view_id}/activity

List View Activity

Activity surfaced on a view: the events of the view's source worksheet, gated by the view-scoped activity permission.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Query Parameters

Name	Type	Description
`event_type`	string	Exact event slug filter
`correlation_id`	string (UUID)	Group related mutations
`page`	integer	1-based page indexDefault: `1`
`limit`	integer	Page size (1–100)Default: `50`

curl "https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/activity?page=1&limit=25" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "e1010101-2020-3030-4040-505050505050",
      "folder_id": "f1111111-2222-3333-4444-555555555555",
      "worksheet_id": "w2222222-3333-4444-5555-666666666666",
      "row_id": "r4444444-5555-6666-7777-888888888888",
      "event_type": "worksheets.row.updated",
      "actor_type": "member",
      "actor_label": "Jane Doe",
      "correlation_id": null,
      "data": {"worksheet_name": "Deals"},
      "created_at": "2026-04-10T13:30:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 25
}

GET/api/v1/worksheets/activity/{event_id}

Get Activity Event

Fetch a single activity event with the same enrichment as list endpoints.

Bearer token required.

Path Parameters

Name	Type	Description
`event_id`*	string (UUID)	Activity log entry ID

curl https://platform.ergondata.ai/api/v1/worksheets/activity/{event_id} \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "e1010101-2020-3030-4040-505050505050",
  "folder_id": "f1111111-2222-3333-4444-555555555555",
  "worksheet_id": "w2222222-3333-4444-5555-666666666666",
  "row_id": "r4444444-5555-6666-7777-888888888888",
  "event_type": "worksheets.row.created",
  "actor_type": "member",
  "actor_label": "Jane Doe",
  "correlation_id": "b0b0b0b0-b1b1-b2b2-b3b3-b4b4b4b4b4b4",
  "data": {"worksheet_name": "Deals"},
  "created_at": "2026-04-10T13:05:00Z"
}

Access Management

IAM-delegated permission grants for folders, worksheets, and views. Each scope exposes the same shape: list eligible principals, grantable permissions, the resource-type tree, and CRUD over grants. Grants on a worksheet or view narrow access inside the folder federated zone.

POST/api/v1/worksheets/folders/access/grants/batch

Create Access Grants Batch (Folder)

Create grants across folder roots with ordered, independent results. Group a subject with resources and permission UUIDs; operations expand resources first and permission IDs second, to at most 200 grants total. Invalid or unauthorized items fail without blocking valid items, and partial success returns 200. Whole-request retries are safe: existing natural grant tuples return already_exists. A side_effect_error means post-write navigation reconciliation failed while the grant exists. ToolDef slug: worksheets.access_grants.create_grants_batch.

Bearer token required. Permission: worksheets:permissions:folders:manage on every target folder root.

Request Body

Name	Type	Description
`operations`*	array	1–200 grouped operations; resources × permission_ids across all operations must expand to at most 200 grants

Response Fields

Name	Type	Description
`results`*	array	One result per expanded grant, ordered by operation, then resource, then permission
`summary`*	object	Outcome counts

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/folders/access/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"client_ref":"folder-reviewers","principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/folder/{folder_id}"],"permission_ids":["{permission_id}"]}]}'

Response

200 OK

{
  "results": [{
    "index": 0,
    "client_ref": "folder-reviewers",
    "status": "created",
    "principal_type": "member",
    "principal_id": "{principal_id}",
    "permission_id": "{permission_id}",
    "resource": "org/{company_id}/folder/{folder_id}",
    "effect": "allow",
    "grant": {"id": "{grant_id}", "permission_id": "{permission_id}", "name": "worksheets:folders:view", "resource": "org/{company_id}/folder/{folder_id}", "effect": "allow", "is_system": false, "granted_at": "2026-07-15T16:30:00Z"},
    "error_status": null,
    "error_detail": null,
    "side_effect_error_status": null,
    "side_effect_error_detail": null
  }],
  "summary": {"created": 1, "already_exists": 0, "failed": 0}
}

POST/api/v1/worksheets/worksheets/access/grants/batch

Create Access Grants Batch (Worksheet)

Apply the grouped BatchCreateGrantsRequest across worksheet roots, with at most 200 expanded grants and results in expansion order. Items are independent, so validation failures and successes can share a 200 response. Retry failed outcomes or the whole request safely; existing tuples return already_exists, and side_effect_error outcomes already hold a grant and may be retried to reconcile navigation. ToolDef slug: worksheets.worksheet_access_grants.create_grants_batch.

Bearer token required. Permission: worksheets:permissions:worksheets:manage on every target worksheet root.

Request Body

Name	Type	Description
`operations`*	array	1–200 grouped operations; resources × permission_ids across all operations must expand to at most 200 grants

Response Fields

Name	Type	Description
`results`*	array	One result per expanded grant, ordered by operation, then resource, then permission
`summary`*	object	Outcome counts

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/access/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"principal_type":"agent","principal_id":"{principal_id}","resources":["org/{company_id}/folder/{folder_id}/worksheet/{worksheet_id}"],"permission_ids":["{permission_id}"]}]}'

Response

200 OK

{"results":[{"index":0,"client_ref":null,"status":"already_exists","principal_type":"agent","principal_id":"{principal_id}","permission_id":"{permission_id}","resource":"org/{company_id}/folder/{folder_id}/worksheet/{worksheet_id}","effect":"allow","grant":{"id":"{grant_id}","permission_id":"{permission_id}","name":"worksheets:worksheets:view","resource":"org/{company_id}/folder/{folder_id}/worksheet/{worksheet_id}","effect":"allow","is_system":false,"granted_at":"2026-07-15T16:30:00Z"},"error_status":null,"error_detail":null,"side_effect_error_status":null,"side_effect_error_detail":null}],"summary":{"created":0,"already_exists":1,"failed":0}}

POST/api/v1/worksheets/views/access/grants/batch

Create Access Grants Batch (View)

Apply the grouped BatchCreateGrantsRequest across saved-view roots, with at most 200 expanded grants and ordered, independent outcomes. Partial success returns 200. Retry failed outcomes or the whole request safely; natural duplicates return already_exists, while side_effect_error identifies a successful grant whose post-write navigation reconciliation should be retried. ToolDef slug: worksheets.view_access_grants.create_grants_batch.

Bearer token required. Permission: worksheets:permissions:views:manage on every target view root.

Request Body

Name	Type	Description
`operations`*	array	1–200 grouped operations; resources × permission_ids across all operations must expand to at most 200 grants

Response Fields

Name	Type	Description
`results`*	array	One result per expanded grant, ordered by operation, then resource, then permission
`summary`*	object	Outcome counts

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/views/access/grants/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"operations":[{"principal_type":"member","principal_id":"{principal_id}","resources":["org/{company_id}/folder/{folder_id}/view/{view_id}"],"permission_ids":["{permission_id}"],"effect":"allow"}]}'

Response

200 OK

{"results":[{"index":0,"client_ref":null,"status":"created","principal_type":"member","principal_id":"{principal_id}","permission_id":"{permission_id}","resource":"org/{company_id}/folder/{folder_id}/view/{view_id}","effect":"allow","grant":{"id":"{grant_id}","permission_id":"{permission_id}","name":"worksheets:views:view","resource":"org/{company_id}/folder/{folder_id}/view/{view_id}","effect":"allow","is_system":false,"granted_at":"2026-07-15T16:30:00Z"},"error_status":null,"error_detail":null,"side_effect_error_status":null,"side_effect_error_detail":null}],"summary":{"created":1,"already_exists":0,"failed":0}}

GET/api/v1/worksheets/folders/{folder_id}/access/eligible

List Eligible Principals (Folder)

Return principals that can be granted permissions on this folder.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

Response Fields

Name	Type	Description
`[]`*	array	Eligible principals (principal_id, principal_type, label)

curl https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/access/eligible \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_id": "u1111111-2222-3333-4444-555555555555",
    "principal_type": "member",
    "label": "Jane Doe"
  },
  {
    "principal_id": "r2222222-3333-4444-5555-666666666666",
    "principal_type": "role",
    "label": "Sales Team"
  }
]

GET/api/v1/worksheets/folders/{folder_id}/access/permissions

List Permissions (Folder)

Return grantable permissions for the folder scope.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

Response Fields

Name	Type	Description
`[]`*	array	Permission options (id, name, friendly_name, description, scope_anchor, display_order, resource_type_id)

curl https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/access/permissions \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "perm-001",
    "name": "worksheets:rows:view",
    "friendly_name": "View rows",
    "description": "Read rows and cell values",
    "scope_anchor": "instance",
    "display_order": 1
  },
  {
    "id": "perm-002",
    "name": "worksheets:rows:edit",
    "friendly_name": "Edit rows",
    "description": "Create, update and delete rows",
    "scope_anchor": "instance",
    "display_order": 2
  }
]

GET/api/v1/worksheets/folders/{folder_id}/access/resource-types

List Resource Types (Folder)

Return the resource-type tree with the permissions associated to each type.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

Response Fields

Name	Type	Description
`resource_types`*	array	Resource type nodes (id, slug, name, parent_id, children[])
`permissions`*	array	Permission options across the tree

curl https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/access/resource-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "resource_types": [
    {"id": "rt-1", "slug": "folder", "name": "Folder", "parent_id": null, "children": []},
    {"id": "rt-2", "slug": "worksheet", "name": "Worksheet", "parent_id": "rt-1", "children": []}
  ],
  "permissions": [
    {"id": "perm-001", "name": "worksheets:rows:view", "resource_type_id": "rt-2"}
  ]
}

GET/api/v1/worksheets/folders/{folder_id}/access/grants

List Access Grants (Folder)

Paginated list of permission grants on the folder.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

Query Parameters

Name	Type	Description
`page`	integer	Page numberDefault: `1`
`limit`	integer	Page sizeDefault: `100`

curl "https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/access/grants?page=1&limit=100" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "g1111111-2222-3333-4444-555555555555",
      "permission_id": "perm-001",
      "name": "worksheets:rows:view",
      "resource": null,
      "effect": "allow",
      "is_system": false,
      "granted_at": "2026-04-10T14:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 100
}

POST/api/v1/worksheets/folders/{folder_id}/access/grants

Create Access Grant (Folder)

Grant a permission to a principal on this folder.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

Request Body

Name	Type	Description
`principal_type`*	string	Grant target type (e.g. member, role, api_key, agent)
`principal_id`*	UUID	Principal ID
`permission_id`*	string	Permission identifier from List Permissions
`resource`	string \| null	Optional resource scope
`effect`	string	Grant effectDefault: `allow`

Response Fields

Name	Type	Description
`id`*	UUID	Grant ID
`permission_id`*	string	Permission identifier
`name`*	string	Permission name
`resource`*	string	Resource scope
`effect`*	string	Grant effect
`is_system`*	boolean	Whether this is a system-managed grant
`granted_at`*	datetime	When the grant was created

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "member",
    "principal_id": "u1111111-2222-3333-4444-555555555555",
    "permission_id": "perm-001",
    "effect": "allow"
  }'

Response

201 Created

{
  "id": "g2222222-3333-4444-5555-666666666666",
  "permission_id": "perm-001",
  "name": "worksheets:rows:view",
  "resource": null,
  "effect": "allow",
  "is_system": false,
  "granted_at": "2026-04-11T10:30:00Z"
}

DELETE/api/v1/worksheets/folders/{folder_id}/access/grants/{grant_id}

Delete Access Grant (Folder)

Revoke a permission grant from the folder.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID
`grant_id`*	string (UUID)	Grant ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/worksheets/worksheets/{worksheet_id}/access/eligible

List Eligible Principals (Worksheet)

Return principals that can be granted permissions on this worksheet.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

curl https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/access/eligible \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_id": "u1111111-2222-3333-4444-555555555555",
    "principal_type": "member",
    "label": "Jane Doe"
  }
]

GET/api/v1/worksheets/worksheets/{worksheet_id}/access/permissions

List Permissions (Worksheet)

Return grantable permissions for the worksheet scope.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

curl https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/access/permissions \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "perm-001",
    "name": "worksheets:rows:view",
    "friendly_name": "View rows",
    "description": "Read rows and cell values",
    "scope_anchor": "instance",
    "display_order": 1
  }
]

GET/api/v1/worksheets/worksheets/{worksheet_id}/access/resource-types

List Resource Types (Worksheet)

Return the resource-type tree with associated permissions for the worksheet.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

curl https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/access/resource-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "resource_types": [
    {"id": "rt-2", "slug": "worksheet", "name": "Worksheet", "parent_id": "rt-1", "children": []}
  ],
  "permissions": [
    {"id": "perm-001", "name": "worksheets:rows:view", "resource_type_id": "rt-2"}
  ]
}

GET/api/v1/worksheets/worksheets/{worksheet_id}/access/grants

List Access Grants (Worksheet)

Paginated list of permission grants on the worksheet.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Query Parameters

Name	Type	Description
`page`	integer	Page numberDefault: `1`
`limit`	integer	Page sizeDefault: `100`

curl "https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/access/grants?page=1&limit=100" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "g3333333-4444-5555-6666-777777777777",
      "permission_id": "perm-002",
      "name": "worksheets:rows:edit",
      "resource": null,
      "effect": "allow",
      "is_system": false,
      "granted_at": "2026-04-11T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 100
}

POST/api/v1/worksheets/worksheets/{worksheet_id}/access/grants

Create Access Grant (Worksheet)

Grant a permission to a principal on this worksheet.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`principal_type`*	string	Grant target type (e.g. member, role, api_key, agent)
`principal_id`*	UUID	Principal ID
`permission_id`*	string	Permission identifier
`resource`	string \| null	Optional resource scope
`effect`	string	Grant effectDefault: `allow`

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "member",
    "principal_id": "u1111111-2222-3333-4444-555555555555",
    "permission_id": "perm-002",
    "effect": "allow"
  }'

Response

201 Created

{
  "id": "g3333333-4444-5555-6666-777777777777",
  "permission_id": "perm-002",
  "name": "worksheets:rows:edit",
  "resource": null,
  "effect": "allow",
  "is_system": false,
  "granted_at": "2026-04-11T12:00:00Z"
}

DELETE/api/v1/worksheets/worksheets/{worksheet_id}/access/grants/{grant_id}

Delete Access Grant (Worksheet)

Revoke a permission grant from the worksheet.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID
`grant_id`*	string (UUID)	Grant ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/worksheets/views/{view_id}/access/eligible

List Eligible Principals (View)

Return principals that can be granted permissions on this view.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

curl https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/access/eligible \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "principal_id": "u1111111-2222-3333-4444-555555555555",
    "principal_type": "member",
    "label": "Jane Doe"
  }
]

GET/api/v1/worksheets/views/{view_id}/access/permissions

List Permissions (View)

Return grantable permissions for the view scope.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

curl https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/access/permissions \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "perm-010",
    "name": "worksheets:views:rows:view",
    "friendly_name": "View rows in view",
    "description": "Read rows visible through this view",
    "scope_anchor": "instance",
    "display_order": 1
  }
]

GET/api/v1/worksheets/views/{view_id}/access/resource-types

List Resource Types (View)

Return the resource-type tree with associated permissions for the view.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

curl https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/access/resource-types \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "resource_types": [
    {"id": "rt-3", "slug": "view", "name": "View", "parent_id": "rt-2", "children": []}
  ],
  "permissions": [
    {"id": "perm-010", "name": "worksheets:views:rows:view", "resource_type_id": "rt-3"}
  ]
}

GET/api/v1/worksheets/views/{view_id}/access/grants

List Access Grants (View)

Paginated list of permission grants on the view.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Query Parameters

Name	Type	Description
`page`	integer	Page numberDefault: `1`
`limit`	integer	Page sizeDefault: `100`

curl "https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/access/grants?page=1&limit=100" \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "g4444444-5555-6666-7777-888888888888",
      "permission_id": "perm-010",
      "name": "worksheets:views:rows:view",
      "resource": null,
      "effect": "allow",
      "is_system": false,
      "granted_at": "2026-04-11T13:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 100
}

POST/api/v1/worksheets/views/{view_id}/access/grants

Create Access Grant (View)

Grant a permission to a principal on this view.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Request Body

Name	Type	Description
`principal_type`*	string	Grant target type (e.g. member, role, api_key, agent)
`principal_id`*	UUID	Principal ID
`permission_id`*	string	Permission identifier
`resource`	string \| null	Optional resource scope
`effect`	string	Grant effectDefault: `allow`

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/access/grants \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "principal_type": "member",
    "principal_id": "u1111111-2222-3333-4444-555555555555",
    "permission_id": "perm-010",
    "effect": "allow"
  }'

Response

201 Created

{
  "id": "g4444444-5555-6666-7777-888888888888",
  "permission_id": "perm-010",
  "name": "worksheets:views:rows:view",
  "resource": null,
  "effect": "allow",
  "is_system": false,
  "granted_at": "2026-04-11T13:00:00Z"
}

DELETE/api/v1/worksheets/views/{view_id}/access/grants/{grant_id}

Delete Access Grant (View)

Revoke a permission grant from the view.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID
`grant_id`*	string (UUID)	Grant ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/access/grants/{grant_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

Connections

Cross-zone sharing between an external principal (e.g. another service or agent) and a worksheet resource. A worksheet owner connects out to a target service/resource; the receiving folder, worksheet, or view zone reviews inbound connection requests, approves or rejects them, and lists or revokes established connections.

GET/api/v1/worksheets/worksheets/{worksheet_id}/connections

List Worksheet Connections

List this worksheet's outbound connections and its pending outbound requests (requester side).

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Response Fields

Name	Type	Description
`connections`*	array	Established connections
`pending_requests`*	array	Outstanding outbound requests awaiting approval

curl https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/connections \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "connections": [
    {
      "id": "cn111111-2222-3333-4444-555555555555",
      "principal_id": "p9999999-8888-7777-6666-555555555555",
      "target_service": "agents",
      "target_resource": "agent:a1111111-2222-3333-4444-555555555555",
      "label": "Sales assistant",
      "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2026-04-12T09:00:00Z"
    }
  ],
  "pending_requests": []
}

POST/api/v1/worksheets/worksheets/{worksheet_id}/connections

Connect Worksheet

Request or establish a connection from this worksheet to a target service/resource. Returns either an active connection or a pending request, depending on whether the target auto-approves.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Request Body

Name	Type	Description
`target_service`*	string	Service to connect to (e.g. agents, workflows)
`target_resource`*	string	Target resource identifier within the service
`label`	string \| null	Human-readable connection label
`message`	string \| null	Optional message for the approver
`permissions`	array of string \| null	Requested permissions

Response Fields

Name	Type	Description
`status`*	string	connected or pending
`connection`	object \| null	The established connection when status is connected
`request`	object \| null	The pending request when status is pending

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/connections \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "target_service": "agents",
    "target_resource": "agent:a1111111-2222-3333-4444-555555555555",
    "label": "Sales assistant",
    "permissions": ["worksheets:rows:view"]
  }'

Response

201 Created

{
  "status": "pending",
  "connection": null,
  "request": {
    "id": "cr111111-2222-3333-4444-555555555555",
    "principal_id": "p9999999-8888-7777-6666-555555555555",
    "target_service": "agents",
    "target_resource": "agent:a1111111-2222-3333-4444-555555555555",
    "status": "pending",
    "requested_permissions": ["worksheets:rows:view"],
    "created_at": "2026-04-12T09:05:00Z"
  }
}

DELETE/api/v1/worksheets/worksheets/{worksheet_id}/connections/{connection_id}

Revoke Worksheet Connection

Revoke an outbound connection from this worksheet.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/connections/{connection_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

POST/api/v1/worksheets/worksheets/{worksheet_id}/connection-requests/{request_id}/withdraw

Withdraw Connection Request

Withdraw a pending outbound connection request from this worksheet.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID
`request_id`*	string (UUID)	Connection request ID

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/connection-requests/{request_id}/withdraw \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "id": "cr111111-2222-3333-4444-555555555555",
  "principal_id": "p9999999-8888-7777-6666-555555555555",
  "target_service": "agents",
  "target_resource": "agent:a1111111-2222-3333-4444-555555555555",
  "status": "withdrawn",
  "requested_permissions": ["worksheets:rows:view"],
  "decided_at": "2026-04-12T09:10:00Z",
  "created_at": "2026-04-12T09:05:00Z"
}

GET/api/v1/worksheets/folders/{folder_id}/connections

List Folder Connections

List IAM principal connections across all worksheets in a folder.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

Response Fields

Name	Type	Description
`items`	array	Principal connections within the folder

curl https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/connections \
  -H "Authorization: Bearer {token}"

Response

200 OK

{
  "items": [
    {
      "id": "cn111111-2222-3333-4444-555555555555",
      "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
      "principal_id": "p9999999-8888-7777-6666-555555555555",
      "target_service": "agents",
      "target_resource": "agent:a1111111-2222-3333-4444-555555555555",
      "label": "Sales assistant",
      "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2026-04-12T09:00:00Z"
    }
  ]
}

DELETE/api/v1/worksheets/folders/{folder_id}/connections/{connection_id}

Revoke Folder Connection

Revoke a principal connection that belongs to a worksheet in this folder.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/connections/{connection_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/worksheets/folders/{folder_id}/access/connection-requests

List Inbound Connection Requests (Folder)

List inbound connection requests targeting this folder zone.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

Query Parameters

Name	Type	Description
`status`	string	Filter by request status (pending, approved, rejected)Default: `pending`

curl "https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/access/connection-requests?status=pending" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "cr111111-2222-3333-4444-555555555555",
    "principal_id": "p8888888-7777-6666-5555-444444444444",
    "target_service": "worksheets",
    "target_resource": "folder:f1111111-2222-3333-4444-555555555555",
    "status": "pending",
    "message": "Requesting read access",
    "requested_permissions": ["worksheets:rows:view"],
    "requested_by": "u3333333-4444-5555-6666-777777777777",
    "created_at": "2026-04-12T10:00:00Z"
  }
]

POST/api/v1/worksheets/folders/{folder_id}/access/connection-requests/{request_id}/approve

Approve Connection Request (Folder)

Approve an inbound connection request for this folder, optionally granting permissions and a label.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`grant`	boolean	Whether to create the permission grant on approvalDefault: `true`
`label`	string \| null	Label for the resulting connection
`permissions`	array of string \| null	Permissions to grant (defaults to the requested set)

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/access/connection-requests/{request_id}/approve \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"grant": true, "permissions": ["worksheets:rows:view"]}'

Response

200 OK

{
  "id": "cr111111-2222-3333-4444-555555555555",
  "principal_id": "p8888888-7777-6666-5555-444444444444",
  "target_service": "worksheets",
  "target_resource": "folder:f1111111-2222-3333-4444-555555555555",
  "status": "approved",
  "connection_id": "cn222222-3333-4444-5555-666666666666",
  "requested_permissions": ["worksheets:rows:view"],
  "decided_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "decided_at": "2026-04-12T10:30:00Z",
  "created_at": "2026-04-12T10:00:00Z"
}

POST/api/v1/worksheets/folders/{folder_id}/access/connection-requests/{request_id}/reject

Reject Connection Request (Folder)

Reject an inbound connection request for this folder.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`reason`	string \| null	Optional rejection reason

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/access/connection-requests/{request_id}/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Not needed"}'

Response

200 OK

{
  "id": "cr111111-2222-3333-4444-555555555555",
  "principal_id": "p8888888-7777-6666-5555-444444444444",
  "target_service": "worksheets",
  "target_resource": "folder:f1111111-2222-3333-4444-555555555555",
  "status": "rejected",
  "decided_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "decided_at": "2026-04-12T10:30:00Z",
  "created_at": "2026-04-12T10:00:00Z"
}

GET/api/v1/worksheets/folders/{folder_id}/access/connections

List Inbound Connections (Folder)

List established inbound connections on this folder zone.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID

curl https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/access/connections \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "cn222222-3333-4444-5555-666666666666",
    "principal_id": "p8888888-7777-6666-5555-444444444444",
    "principal_type": "agent",
    "principal_label": "Sales assistant",
    "target_service": "worksheets",
    "target_resource": "folder:f1111111-2222-3333-4444-555555555555",
    "label": "Inbound read access",
    "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2026-04-12T10:30:00Z"
  }
]

DELETE/api/v1/worksheets/folders/{folder_id}/access/connections/{connection_id}

Revoke Inbound Connection (Folder)

Revoke an established inbound connection on this folder zone.

Bearer token required.

Path Parameters

Name	Type	Description
`folder_id`*	string (UUID)	Folder ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/folders/{folder_id}/access/connections/{connection_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/worksheets/worksheets/{worksheet_id}/access/connection-requests

List Inbound Connection Requests (Worksheet)

List inbound connection requests targeting this worksheet zone.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

Query Parameters

Name	Type	Description
`status`	string	Filter by request statusDefault: `pending`

curl "https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/access/connection-requests?status=pending" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "cr222222-3333-4444-5555-666666666666",
    "principal_id": "p8888888-7777-6666-5555-444444444444",
    "target_service": "worksheets",
    "target_resource": "worksheet:w2222222-3333-4444-5555-666666666666",
    "status": "pending",
    "requested_permissions": ["worksheets:rows:view"],
    "created_at": "2026-04-12T11:00:00Z"
  }
]

POST/api/v1/worksheets/worksheets/{worksheet_id}/access/connection-requests/{request_id}/approve

Approve Connection Request (Worksheet)

Approve an inbound connection request for this worksheet.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`grant`	boolean	Whether to create the permission grant on approvalDefault: `true`
`label`	string \| null	Label for the resulting connection
`permissions`	array of string \| null	Permissions to grant

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/access/connection-requests/{request_id}/approve \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"grant": true}'

Response

200 OK

{
  "id": "cr222222-3333-4444-5555-666666666666",
  "principal_id": "p8888888-7777-6666-5555-444444444444",
  "target_service": "worksheets",
  "target_resource": "worksheet:w2222222-3333-4444-5555-666666666666",
  "status": "approved",
  "connection_id": "cn333333-4444-5555-6666-777777777777",
  "decided_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "decided_at": "2026-04-12T11:15:00Z",
  "created_at": "2026-04-12T11:00:00Z"
}

POST/api/v1/worksheets/worksheets/{worksheet_id}/access/connection-requests/{request_id}/reject

Reject Connection Request (Worksheet)

Reject an inbound connection request for this worksheet.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`reason`	string \| null	Optional rejection reason

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/access/connection-requests/{request_id}/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Out of scope"}'

Response

200 OK

{
  "id": "cr222222-3333-4444-5555-666666666666",
  "principal_id": "p8888888-7777-6666-5555-444444444444",
  "target_service": "worksheets",
  "target_resource": "worksheet:w2222222-3333-4444-5555-666666666666",
  "status": "rejected",
  "decided_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "decided_at": "2026-04-12T11:15:00Z",
  "created_at": "2026-04-12T11:00:00Z"
}

GET/api/v1/worksheets/worksheets/{worksheet_id}/access/connections

List Inbound Connections (Worksheet)

List established inbound connections on this worksheet zone.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID

curl https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/access/connections \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "cn333333-4444-5555-6666-777777777777",
    "principal_id": "p8888888-7777-6666-5555-444444444444",
    "principal_type": "agent",
    "principal_label": "Sales assistant",
    "target_service": "worksheets",
    "target_resource": "worksheet:w2222222-3333-4444-5555-666666666666",
    "label": "Inbound read access",
    "created_at": "2026-04-12T11:15:00Z"
  }
]

DELETE/api/v1/worksheets/worksheets/{worksheet_id}/access/connections/{connection_id}

Revoke Inbound Connection (Worksheet)

Revoke an established inbound connection on this worksheet zone.

Bearer token required.

Path Parameters

Name	Type	Description
`worksheet_id`*	string (UUID)	Worksheet ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/worksheets/{worksheet_id}/access/connections/{connection_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content

GET/api/v1/worksheets/views/{view_id}/access/connection-requests

List Inbound Connection Requests (View)

List inbound connection requests targeting this view zone.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

Query Parameters

Name	Type	Description
`status`	string	Filter by request statusDefault: `pending`

curl "https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/access/connection-requests?status=pending" \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "cr333333-4444-5555-6666-777777777777",
    "principal_id": "p8888888-7777-6666-5555-444444444444",
    "target_service": "worksheets",
    "target_resource": "view:v8888888-9999-aaaa-bbbb-cccccccccccc",
    "status": "pending",
    "requested_permissions": ["worksheets:views:rows:view"],
    "created_at": "2026-04-12T12:00:00Z"
  }
]

POST/api/v1/worksheets/views/{view_id}/access/connection-requests/{request_id}/approve

Approve Connection Request (View)

Approve an inbound connection request for this view.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`grant`	boolean	Whether to create the permission grant on approvalDefault: `true`
`label`	string \| null	Label for the resulting connection
`permissions`	array of string \| null	Permissions to grant

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/access/connection-requests/{request_id}/approve \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"grant": true, "permissions": ["worksheets:views:rows:view"]}'

Response

200 OK

{
  "id": "cr333333-4444-5555-6666-777777777777",
  "principal_id": "p8888888-7777-6666-5555-444444444444",
  "target_service": "worksheets",
  "target_resource": "view:v8888888-9999-aaaa-bbbb-cccccccccccc",
  "status": "approved",
  "connection_id": "cn444444-5555-6666-7777-888888888888",
  "decided_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "decided_at": "2026-04-12T12:15:00Z",
  "created_at": "2026-04-12T12:00:00Z"
}

POST/api/v1/worksheets/views/{view_id}/access/connection-requests/{request_id}/reject

Reject Connection Request (View)

Reject an inbound connection request for this view.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID
`request_id`*	string (UUID)	Connection request ID

Request Body

Name	Type	Description
`reason`	string \| null	Optional rejection reason

curl -X POST https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/access/connection-requests/{request_id}/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Denied"}'

Response

200 OK

{
  "id": "cr333333-4444-5555-6666-777777777777",
  "principal_id": "p8888888-7777-6666-5555-444444444444",
  "target_service": "worksheets",
  "target_resource": "view:v8888888-9999-aaaa-bbbb-cccccccccccc",
  "status": "rejected",
  "decided_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "decided_at": "2026-04-12T12:15:00Z",
  "created_at": "2026-04-12T12:00:00Z"
}

GET/api/v1/worksheets/views/{view_id}/access/connections

List Inbound Connections (View)

List established inbound connections on this view zone.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID

curl https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/access/connections \
  -H "Authorization: Bearer {token}"

Response

200 OK

[
  {
    "id": "cn444444-5555-6666-7777-888888888888",
    "principal_id": "p8888888-7777-6666-5555-444444444444",
    "principal_type": "agent",
    "principal_label": "Sales assistant",
    "target_service": "worksheets",
    "target_resource": "view:v8888888-9999-aaaa-bbbb-cccccccccccc",
    "label": "Inbound view access",
    "created_at": "2026-04-12T12:15:00Z"
  }
]

DELETE/api/v1/worksheets/views/{view_id}/access/connections/{connection_id}

Revoke Inbound Connection (View)

Revoke an established inbound connection on this view zone.

Bearer token required.

Path Parameters

Name	Type	Description
`view_id`*	string (UUID)	View ID
`connection_id`*	string (UUID)	Connection ID

curl -X DELETE https://platform.ergondata.ai/api/v1/worksheets/views/{view_id}/access/connections/{connection_id} \
  -H "Authorization: Bearer {token}"

Response

204 No Content