Skip to main content

Data Types

Tags: collections, data

Endpoints​

List​

GET /api/v2/w/{workspace_uuid}/data-types

Description:

Custom data type management

List all data types in the workspace.

Retrieves all custom data type definitions created in the workspace, including their field schemas, record counts, and configuration. Data types define structured data models that can be used to store and organize workspace information.

Query Parameters:

  • archived: Filter by archived status (boolean, default: false)

Response: Returns an array of DataTypeResponse objects, each containing the data type's ID, name, slug, description, fields (with types and validation rules), and record count.

Permissions: Requires authenticated member session. All workspace members can list data types.

Error Responses:

  • 401 Unauthorized: Missing or invalid authentication

Related Endpoints:

  • POST /data-types - Create a new data type
  • GET /data-types/{data_type_id} - Get a specific data type
  • GET /data-types/{data_type_id}/records - List records for a data type

Authorization: Requires datatypes:read scope

Parameters:

  • archived (Boolean)
  • sortBy (DataTypeSortField)
  • sortOrder (SortOrder)

Response: List of DataTypeResponse

Create​

POST /api/v2/w/{workspace_uuid}/data-types

Description:

Custom data type management

Create a new custom data type.

Defines a new structured data model in the workspace with custom fields and validation rules. Data types can represent any entity (customers, products, tickets, etc.) and are used by assistants to store and retrieve structured information.

Request Body:

  • name: Display name for the data type
  • slug: URL-friendly identifier (auto-generated if not provided)
  • description: Optional description of the data type's purpose
  • fields: Array of field definitions with name, type, validation, and indexing options

Response: Returns the created DataTypeResponse object with all field definitions and configuration.

Permissions: Requires appropriate admin scope to create data types.

Error Responses:

  • 400 Bad Request: Invalid request parameters or duplicate slug
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: User lacks appropriate admin scope
  • 500 Internal Server Error: Database error during creation

Related Endpoints:

  • GET /data-types - List all data types
  • PUT /data-types/{data_type_id} - Update data type definition
  • POST /data-types/{data_type_id}/records - Create records of this type

Authorization: Requires datatypes:write scope

Parameters:

  • data_type (CreateDataTypeRequest)

Response: See DataTypeResponse

Slug​

GET /api/v2/w/{workspace_uuid}/data-types/slug/{slug}

Description:

Custom data type management

Get a data type by its slug identifier.

Retrieves complete data type details using its URL-friendly slug identifier. Returns the full schema including all field definitions, types, and validation rules.

Path Parameters:

  • slug: URL-friendly slug identifier for the data type

Response: Returns a DataTypeResponse object with complete field schema and configuration.

Permissions: Requires authenticated member session.

Error Responses:

  • 401 Unauthorized: Missing or invalid authentication
  • 404 Not Found: Data type with specified slug not found

Related Endpoints:

  • GET /data-types/{data_type_id} - Get data type by numeric ID
  • GET /data-types - List all data types
  • GET /data-types/{data_type_id}/records - Get records for this data type

Authorization: Requires datatypes:read scope

Parameters:

  • slug (String)

Response: See DataTypeResponse

Validate Slug​

POST /api/v2/w/{workspace_uuid}/data-types/validate-slug

Description:

Custom data type management

Validate if a data type slug is available.

Checks if the given slug conflicts with existing data types and suggests a unique alternative if needed.

Request Body:

  • slug: The slug to validate
  • excludeId: Optional data type ID to exclude (for updates)

Response:

  • available: Whether the slug is available
  • suggestedSlug: A suggested unique slug if the original is taken

Permissions: Requires valid workspace membership.

Authorization: Requires datatypes:write scope

Parameters:

Response: See ValidateSlugResponse

Delete Data Type Id​

DELETE /api/v2/w/{workspace_uuid}/data-types/{data_type_id}

Description:

Custom data type management

Permanently delete a data type and all its records.

Removes a data type definition along with all associated records and field indexes. This operation is irreversible and will delete all data stored in records of this type. Field indexes are removed via background tasks.

Path Parameters:

  • id: Data type ID to delete

Response: Returns a status object with "deleted" confirmation.

Permissions: Requires appropriate admin scope to delete data types.

Error Responses:

  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: User lacks appropriate admin scope
  • 404 Not Found: Data type not found
  • 500 Internal Server Error: Database error during deletion

Related Endpoints:

  • GET /data-types - List remaining data types
  • POST /data-types/{data_type_id}/export - Export data before deletion
  • GET /data-types/{data_type_id}/records - View records that will be deleted

Authorization: Requires datatypes:admin scope

Parameters:

  • data_type_id (Integer)

Get Data Type Id​

GET /api/v2/w/{workspace_uuid}/data-types/{data_type_id}

Description:

Custom data type management

Get detailed information about a specific data type.

Retrieves complete data type configuration including all field definitions, record count, and metadata. Includes field types, validation rules, and indexing status. This endpoint accepts either the numeric data type ID or stable UUID.

Path Parameters:

  • data_type_id: Data type numeric ID or UUID to retrieve

Response: Returns a DataTypeResponse object with complete field schema, record count, and all configuration details.

Permissions: Requires authenticated member session.

Error Responses:

  • 401 Unauthorized: Missing or invalid authentication
  • 404 Not Found: Data type not found

Related Endpoints:

  • GET /data-types/slug/{slug} - Get data type by slug
  • PUT /data-types/{data_type_id} - Update data type
  • GET /data-types/{data_type_id}/records - List records for this data type

Authorization: Requires datatypes:read scope

Parameters:

  • data_type_id (String)

Response: See DataTypeResponse

Update Data Type Id​

PUT /api/v2/w/{workspace_uuid}/data-types/{data_type_id}

Description:

Custom data type management

Update an existing data type definition.

Modifies a data type's metadata, field definitions, or configuration. Can add new fields, update field properties, or modify validation rules. Existing records are preserved and automatically adapt to schema changes.

Path Parameters:

  • id: Data type ID to update

Request Body:

  • name: Updated display name (optional)
  • description: Updated description (optional)
  • fields: Updated field definitions array (optional)

Response: Returns the updated DataTypeResponse object with refreshed schema and configuration.

Permissions: Requires appropriate admin scope to update data types.

Error Responses:

  • 400 Bad Request: Invalid update parameters or validation error
  • 401 Unauthorized: Missing or invalid authentication
  • 403 Forbidden: User lacks appropriate admin scope
  • 404 Not Found: Data type not found
  • 500 Internal Server Error: Database error during update

Related Endpoints:

  • GET /data-types/{data_type_id} - Get current data type definition
  • DELETE /data-types/{data_type_id} - Delete the data type
  • GET /data-types/{data_type_id}/records - View records affected by schema changes

Authorization: Requires datatypes:write scope

Parameters:

  • data_type_id (Integer)
  • data_type (UpdateDataTypeRequest)

Response: See DataTypeResponse