Skip to content
EntryLayer Operational data entry for Snowflake

SQL API Contracts

Use this page before composing VARIANT payloads for SQL API calls. Cortex and other agents should load the same information with CALL ENTRYLAYER.API.HELP('CONTRACTS') before making mutations.

SQL API contracts:

Universal return envelope:

Success:

{
"status": "success",
"data": {},
"message": "string"
}

Error:

{
"status": "error",
"code": "ERR_*",
"message": "string",
"data": {
} optional
}

Guardrail: Never use data unless status = success. On error, report code and message.

Identifiers and enums:

  • project_id input accepts “proj_<numeric_id>” or a numeric string.
  • source_object must be an unquoted fully qualified DB.SCHEMA.OBJECT.
  • role_name must be an unquoted Snowflake role identifier.
  • access_level enum: viewer | user | admin.
  • source_type enum: table | view | semantic_view.

Project contract:

{
"project_id": "proj_123",
"internal_id": 123,
"name": "Name",
"description": "string or null",
"status": "active | archived",
"org_id": 1,
"source_object": "DB.SCHEMA.OBJECT or null",
"source_type": "table | view | semantic_view | null",
"workflow_enabled": false,
"auto_save_enabled": false,
"multi_step_enabled": false,
"notify_on_submission": false,
"notify_on_review": false,
"folder_id": null,
"created_at": "ISO-8601",
"updated_at": "ISO-8601"
}

ProjectListOptions contract:

{
"include_archived": false,
"include_children": false,
"limit": 100
}

ProjectUpdates contract:

{
"name": "string optional",
"description": "string optional",
"workflow_enabled": boolean,
"auto_save_enabled": boolean,
"multi_step_enabled": boolean,
"notify_on_submission": boolean,
"notify_on_review": boolean
}

SourceColumn contract:

{
"name": "COL",
"type": "VARCHAR",
"nullable": true,
"comment": "",
"primary_key": false,
"default": null
}

Semantic view SourceColumn objects are metadata-only values from DESCRIBE SEMANTIC VIEW where object_kind is DIMENSION, FACT, METRIC, or DERIVED_METRIC and property is DATA_TYPE.

SourceObject contract:

{
"name": "ORDERS",
"type": "TABLE | VIEW | SEMANTIC_VIEW"
}

SourceHierarchy contract:

{
"source_object": "DB.SCHEMA.OBJECT",
"source_type": "table | semantic_view",
"tables": [
{
"name": "OBJECT",
"source_object": "DB.SCHEMA.OBJECT",
"columns": [
SourceColumn
]
}
],
"relationships": [
],
"warnings": [
]
}

PreviewLayoutField contract:

{
"field_id": null,
"code": "COLUMN_NAME",
"title": "Column Name",
"field_type": "Text | Numeric | Date | Checkbox | Variant",
"required": false,
"description": "string or null",
"source": "snowflake",
"config": {
"primary_key": false,
"read_only": false
},
"values": []
}

CreateProjectOptions contract:

{
"description": "string optional",
"workflow_enabled": false,
"auto_save_enabled": false,
"multi_step_enabled": false,
"source_type": "table | view | semantic_view"
}

LayoutSummary contract:

{
"version_id": 123,
"version_number": 1,
"status": "published",
"published_at": "ISO-8601 or null",
"field_count": 2,
"section_count": 1,
"structure": {}
}

FormVersion contract:

{
"version_id": 123,
"project_id": "proj_123",
"internal_project_id": 123,
"version_number": 2,
"status": "draft | published | archived",
"structure": DraftStructure,
"created_at": "ISO-8601",
"updated_at": "ISO-8601",
"published_at": "ISO-8601 or null",
"parent_version_id": 122,
"has_draft_changes": true
}

DraftStructure contract:

{
"sections": [
Section
],
"available_fields": [
Field
],
"rules": [
FormRule
]
}

Section contract:

{
"section_id": "sec_abc",
"title": "Section title",
"relationship_id": 123 optional,
"rows": [
Row
]
}

Row contract:

{
"row_id": "row_abc",
"fields": [
Field
]
}

RowUpdate contract:

{
"fields": [
Field
]
}

Field contract:

{
"field_id": 123,
"code": "COLUMN_NAME or null",
"title": "Display Label",
"field_type": "Text | Numeric | Date | Checkbox | Select | Label | Variant",
"required": false,
"description": "string or null",
"source": "snowflake | csv | manual | null",
"config": {},
"values": [],
"field_group_id": null,
"parent_field_id": null,
"formula": null
}

Field values input contract: Select values may be

[
"Open",
"Closed"
]

or [{“title”:“Open”,“value”:“O”}]. Before persistence, SQL API normalizes each value to an object with title and value; malformed option objects return ERR_VALIDATION.

VariantPath contract:

{
"path": "customer.name",
"title": "Customer Name optional",
"field_type": "Text | Numeric | Date | Checkbox | Select | Label"
}

Placement contract:

{
"section_id": "sec_abc optional",
"row_id": "row_abc optional",
"section_index": 0 optional,
"row_index": 0 optional,
"field_index": 0 optional,
"available": false optional,
"index": 0 optional for sections
}

FieldValidation contract:

{
"required": true,
"range_min": 0,
"range_max": 100,
"round_precision": 2,
"format": "currency | percentage | plain",
"include_time": false,
"allow_multiple": false,
"default_value": "optional",
"read_only": false,
"values": [],
"lookup": {},
"parent_field_id": null,
"primary_key": false
}

FormRule contract:

{
"id": "rule_abc optional",
"expression": "{Reviewer Comment}.required = {Status}.value == \"Open\"",
"target_field_id": 123,
"target_property": "visible | enabled | required",
"description": "optional",
"enabled": true
}

Rule expressions use exact draft field titles in braces. The assigned left-hand title should be the field identified by target_field_id.

Workflow contract:

{
"states": [
WorkflowState
],
"within_category_modes": {
},
"allow_send_back": true,
"allow_reopen": true
}

WorkflowState contract:

{
"id": 123 optional,
"label": "Submitted",
"category": "editable | in_review | approved | rejected",
"order_in_category": 0,
"color": "#94a3b8",
"is_exit_point": false,
"exit_target_state_ids": [
123
] optional,
"back_edge_target_state_ids": [
122
] optional,
"acl_entries": [
] optional,
"is_locked_down": false
}

WorkflowTemplate contract:

{
"template_id": 123,
"scope": "builtin | org",
"org_id": null,
"source_project_id": null,
"name": "Standard Review",
"description": "string or null",
"config": Workflow
}

Relationship contract:

{
"id": 1,
"parent_project_id": 123,
"child_project_id": 456,
"parent_field_id": 10,
"child_field_id": 11,
"label": "Line Items",
"sort_order": 0,
"parent_project_title": "Invoices",
"child_project_title": "Invoice Lines",
"is_system_managed": false
}

Folder contract:

{
"id": 1,
"name": "Finance",
"project_count": 3,
"created_at": "ISO-8601",
"updated_at": "ISO-8601"
}

EffectiveField contract:

{
"field_id": 123,
"code": "COLUMN_NAME",
"title": "Display Label",
"field_type": "Text | Numeric | Date | Checkbox | Select | Label | Variant",
"required": false,
"description": "string or null",
"source": "snowflake | csv | null",
"config": {},
"values": [],
"field_group_id": null,
"parent_field_id": null
}

AccessPermissions contract:

{
"can_read": true,
"can_submit": false,
"can_edit": false,
"can_delete": false,
"can_manage": false
}

AccessGrant contract:

{
"grant_id": 123,
"project_id": "proj_123",
"subject_type": "role | user",
"subject_key": "ROLE_NAME or account id",
"subject_identifier": "ROLE_NAME or USERNAME",
"subject_label": "display label",
"account_id": null,
"account_name": null,
"account_email": null,
"account_snowflake_username": null,
"role_name": "ROLE_NAME",
"access_level": "viewer | user | admin",
"can_submit": false,
"can_read": true,
"can_edit": false,
"can_delete": false,
"can_manage": false,
"field_groups": [
FieldGroupPermission
]
}

FieldGroupPermission contract:

{
"field_group_id": 3,
"permission": "read | edit"
}

SubmissionGridQuery contract:

{
"startRow": 0,
"endRow": 100,
"sortModel": [
{
"colId": "10",
"sort": "asc | desc"
}
],
"filterModel": {
"10": "Open"
},
"requestedColumns": [
10
],
"search": "optional",
"editedOnly": false,
"archivedOnly": false,
"statusFilter": "all | not_started | state id",
"parentJoinValue": "optional"
}

SubmissionGridRow contract:

{
"row_id": "sub_100 or virtual key",
"row_ref": {
"submission_id": 100,
"sync_config_id": null,
"row_key": null
},
"materialized": true,
"archived": false,
"state_id": 1,
"can_edit": true,
"can_delete": false,
"cells": {
"10": {
"raw": "Open",
"display": "Open",
"field_type": "Select",
"editable": true,
"masked": false
}
},
"child_groups": []
}

SubmissionRead contract:

{
"submission_id": 100,
"project_id": "proj_123",
"internal_project_id": 123,
"archived": false,
"state_id": 1,
"sync_config_id": null,
"row_key": null,
"created_by": 42,
"created_at": "ISO-8601",
"updated_at": "ISO-8601"
}

SubmissionFieldUpdate contract:

{
"field_id": 10 or "code": "STATUS",
"value": "string | scalar | null",
"expected_value": "optional current value for optimistic locking"
}

SubmissionDetail contract:

{
"id": 100,
"project_id": 123,
"workflow_enabled": true,
"can_edit": true,
"can_delete": false,
"can_manage": false,
"can_transition": [
2
],
"workflow_states": [
WorkflowState
],
"fields": [
SubmissionField
],
"structure": {
},
"relationships": [
],
"ancestry": [
],
"breadcrumb": [
]
}

SubmissionField contract:

{
"id": 1,
"field_id": 10,
"value": "Open",
"is_masked": false
}

SubmissionStatusHistory contract:

{
"id": 1,
"submission_id": 100,
"from_state_id": 1,
"to_state_id": 2,
"changed_by": 42,
"changed_by_name": "User",
"comment": "string or null",
"created_at": "ISO-8601"
}

BreadcrumbEntry contract:

{
"kind": "submission | virtual",
"submission_id": 100,
"project_id": 123,
"project_title": "Orders",
"sync_config_id": 5,
"row_key": "optional",
"label": "Order 100"
}

ProjectAccessLogRow contract:

{
"id": 1,
"submission_id": null,
"account_id": 42,
"action": "view",
"details": "string or null",
"created_at": "ISO-8601"
}

ProjectChangeLogRow contract:

{
"id": 1,
"project_id": "proj_123",
"action": "rename_field",
"entity_type": "field",
"entity_name": "Amount",
"old_value": "Old",
"new_value": "New",
"changed_by": 42,
"created_at": "ISO-8601"
}

ProjectAnalytics contract:

{
"status_counts": [
{
"state_id": 1,
"count": 2
}
],
"total": 2,
"submissions_over_time": [
{
"date": "YYYY-MM-DD",
"count": 1
}
],
"recent_created": 1,
"recent_updated": 1
}

SourceConfig contract:

{
"sync_config_id": 123,
"project_id": "proj_123",
"direction": "import",
"source_object": "DB.SCHEMA.TABLE",
"source_type": "table | view | semantic_view",
"enabled": true,
"column_mappings": [
{
"snowflake_column": "COL",
"field_id": 10
}
],
"last_sync_at": "ISO-8601 or null",
"last_sync_status": "string or null",
"last_sync_message": "string or null",
"created_at": "ISO-8601",
"updated_at": "ISO-8601"
}

UserSeat contract:

{
"username": "JSMITH",
"seat_type": "view | act | build | admin"
}

BillingPreviewRow contract:

{
"billing_month": "YYYY-MM",
"event_class": "ACT_SEAT_MONTHLY | BUILD_ADMIN_SEAT_MONTHLY",
"active_seat_count": 0,
"monthly_unit_price_cents": 2400,
"estimated_full_month_cents": 0,
"snapshot_date": "YYYY-MM-DD",
"note": "string"
}

BillingLedgerRow contract:

{
"billing_month": "YYYY-MM",
"event_class": "ACT_SEAT_MONTHLY | BUILD_ADMIN_SEAT_MONTHLY",
"observed_count": 0,
"billed_count": 0,
"seat_days": 0,
"days_in_month": 30,
"calculated_amount_cents": 0,
"emitted_amount_cents": 0,
"status": "pending | emitted | failed",
"emitted_at": "ISO-8601 or null",
"last_error": "string or null",
"calculation_version": "string"
}

ExtractSubmissionRow contract:

{
"submission_id": 123,
"project_id": 123,
"project_title": "Invoices",
"status": "Approved",
"created_at": "TIMESTAMP_NTZ",
"updated_at": "TIMESTAMP_NTZ",
"snowflake_row_key": "string or null",
"field_values": {}
}

ExtractFieldMetadataRow contract:

{
"project_id": 123,
"project_title": "Invoices",
"field_id": 10,
"field_key": "AMOUNT",
"field_code": "AMOUNT",
"field_title": "Amount",
"field_type": "Numeric",
"source": "snowflake | manual | null",
"field_order": 1,
"is_hidden": false,
"is_system_managed": false,
"relationship_id": null,
"relationship_role": "none | child_fk | parent_key",
"related_project_id": null,
"related_project_title": null,
"include_in_extract_sql": true,
"projection_sql": "FIELD_VALUES:AMOUNT::STRING AS AMOUNT"
}

Procedure success payloads:

  • LIST_SOURCE_DATABASES: {“databases”:[{“name”:“DB”,“kind”:“DATABASE”}]}
  • LIST_SOURCE_SCHEMAS: {“database”:“DB”,“schemas”:[{“name”:“SCHEMA”}]}
  • LIST_SOURCE_OBJECTS: {“database”:“DB”,“schema”:“SCHEMA”,“objects”:[SourceObject]}
  • LIST_SEMANTIC_VIEWS: {“database”:“DB”,“schema”:“SCHEMA”,“semantic_views”:[SourceObject]}
  • DESCRIBE_SOURCE: {“source_object”:“DB.SCHEMA.OBJECT”,“source_type”:“table | semantic_view”,“columns”:[SourceColumn]}
  • DESCRIBE_SOURCE_HIERARCHY: SourceHierarchy
  • PREVIEW_SOURCE_LAYOUT: {“source_object”:“DB.SCHEMA.OBJECT”,“source_type”:“table | semantic_view”,“layout”:{“sections”:[Section]},“fields”:[PreviewLayoutField]}
  • VALIDATE_SOURCE: {“source_object”:“DB.SCHEMA.OBJECT”,“source_type”:“table | semantic_view”,“columns”:[SourceColumn]}
  • CREATE_EMPTY_PROJECT: {“project”:Project,“project_id”:“proj_123”,“draft”:FormVersion}
  • CREATE_PROJECT: {“project”:Project,“project_id”:“proj_123”,“sync_config_id”:123,“layout”:{“field_count”:2,“section_count”:1,“warnings”:[],“fields_matched”:0,“fields_created”:2}}
  • GET_PROJECT: {“project”:Project}
  • GET_PROJECT_LAYOUT: {“project”:Project,“layout”:LayoutSummary,“fields”:[EffectiveField]}
  • LIST_PROJECTS: {“projects”:[Project]}
  • UPDATE_PROJECT, SET_PROJECT_FOLDER: {“project”:Project}
  • ARCHIVE_PROJECT: {“project”:Project,“archived”:true|false}
  • RESTORE_PROJECT: {“project”:Project,“restored”:true|false}
  • GET_PROJECT_DRAFT: {“project”:Project,“draft”:FormVersion}
  • SAVE_PROJECT_DRAFT, REVERT_PROJECT_VERSION: {“draft”:FormVersion}
  • PUBLISH_PROJECT_DRAFT: {“version”:FormVersion}
  • DISCARD_PROJECT_DRAFT: {“project_id”:“proj_123”,“discarded”:true|false}
  • LIST_PROJECT_VERSIONS: {“project_id”:“proj_123”,“versions”:[FormVersion]}
  • CREATE_SECTION, UPDATE_SECTION: {“section”:Section,“draft”:FormVersion}
  • REMOVE_SECTION: {“section”:Section,“moved_to_available”:[field_id],“archived_fields”:[field_id],“draft”:FormVersion}
  • MOVE_SECTION: {“section”:Section,“draft”:FormVersion}
  • CREATE_ROW, UPDATE_ROW, MOVE_ROW: {“row”:Row,“draft”:FormVersion}
  • REMOVE_ROW: {“row”:Row,“moved_to_available”:[field_id],“archived_fields”:[field_id],“draft”:FormVersion}
  • CREATE_FIELD, UPDATE_FIELD, ARCHIVE_FIELD, MOVE_FIELD, SET_FIELD_VALIDATION, CLEAR_FIELD_VALIDATION: {“field”:Field,“draft”:FormVersion}
  • SET_PRIMARY_KEYS: {“project_id”:“proj_123”,“field_ids”:[123],“updated_version_ids”:[123]}
  • EXTRACT_VARIANT_FIELDS: {“source_field_id”:123,“fields”:[Field],“draft”:FormVersion}
  • LIST_FORM_RULES: {“rules”:[FormRule]}
  • GENERATE_FORM_RULE: {“rule”:{“expression”:“string”,“target_field_id”:123 optional,“target_property”:“required optional”,“enabled”:true,“validation_error”:{} optional}}
  • CREATE_FORM_RULE, UPDATE_FORM_RULE, SET_FORM_RULE_ENABLED: {“rule”:FormRule,“draft”:FormVersion}
  • DELETE_FORM_RULE: {“rule_id”:“rule_abc”,“deleted”:true|false,“draft”:FormVersion}
  • GET_WORKFLOW, UPDATE_WORKFLOW, APPLY_WORKFLOW_TEMPLATE, CLONE_WORKFLOW: {“workflow”:Workflow}
  • LIST_WORKFLOW_TEMPLATES: {“templates”:[{“template_id”:123,“scope”:“builtin | org | project”,“org_id”:1,“source_project_id”:null,“name”:“Name”,“description”:“string or null”}]}
  • GET_WORKFLOW_TEMPLATE: {“template”:WorkflowTemplate}
  • PREVIEW_WORKFLOW_TEMPLATE: {“project”:Project,“preview”:{“state_count”:1,“dropped_state_ids”:[],“within_category_modes”:{},“allow_send_back”:true,“allow_reopen”:true,“warnings”:[]}}
  • LIST_WORKFLOW_TEMPLATE_PROJECTS: {“projects”:[{“project_id”:“proj_123”,“name”:“Orders”,“workflow”:Workflow}]}
  • LIST_FIELD_DISTINCT_VALUES: {“project_id”:“proj_123”,“field_id”:10,“source_column”:“STATUS”,“values”:[“Open”]}
  • SET_FIELD_LOOKUP, CLEAR_FIELD_LOOKUP, SET_FIELD_CASCADE, SET_FIELD_GROUP: {“field”:Field,“draft”:FormVersion}
  • SET_ACCESS_FIELD_GROUPS: {“project_id”:“proj_123”,“grant_id”:123,“field_groups”:[FieldGroupPermission]}
  • QUERY_SUBMISSION_GRID, QUERY_RELATIONSHIP_SUBMISSION_GRID: {“grid”:{“rows”:[SubmissionGridRow],“lastRow”:100,“nextStartRow”:100,“warning”:null}}
  • GET_SUBMISSION, GET_VIRTUAL_SUBMISSION: {“submission”:SubmissionDetail}
  • LIST_SUBMISSION_STATUS_HISTORY: {“history”:[SubmissionStatusHistory]}
  • GET_SUBMISSION_BREADCRUMB, GET_VIRTUAL_SUBMISSION_BREADCRUMB: {“breadcrumb”:[BreadcrumbEntry]}
  • CREATE_SUBMISSION, MATERIALIZE_VIRTUAL_SUBMISSION, TRANSITION_SUBMISSION, ARCHIVE_SUBMISSION, RESTORE_SUBMISSION, CREATE_CHILD_SUBMISSION: {“submission”:SubmissionRead}
  • UPDATE_SUBMISSION_FIELDS: {“fields”:[SubmissionField]}
  • LIST_RELATIONSHIPS: {“project_id”:“proj_123”,“relationships”:[Relationship]}
  • CREATE_RELATIONSHIP, UPDATE_RELATIONSHIP, DELETE_RELATIONSHIP: {“relationship”:Relationship}
  • LIST_FOLDERS: {“folders”:[Folder]}
  • CREATE_FOLDER, UPDATE_FOLDER: {“folder”:Folder}
  • DELETE_FOLDER: {“folder_id”:123,“deleted”:true}
  • GRANT_ACCESS: {“project_id”:“proj_123”,“role_name”:“ROLE_NAME”,“access_level”:“viewer | user | admin”,“grant_id”:123}
  • REVOKE_ACCESS: {“project_id”:“proj_123”,“role_name”:“ROLE_NAME”,“revoked”:true}
  • LIST_ACCESS: {“project_id”:“proj_123”,“access”:[AccessGrant]}
  • UPSERT_ACCESS: {“access”:AccessGrant,“operation”:“created | updated”}
  • UPDATE_ACCESS: {“access”:AccessGrant}
  • DELETE_ACCESS: {“project_id”:“proj_123”,“grant_id”:123,“deleted”:true}
  • GET_PROJECT_ANALYTICS: {“project_id”:“proj_123”,“analytics”:ProjectAnalytics}
  • LIST_PROJECT_ACCESS_LOG: {“project_id”:“proj_123”,“items”:[ProjectAccessLogRow],“total”:0}
  • LIST_PROJECT_CHANGELOG: {“project_id”:“proj_123”,“items”:[ProjectChangeLogRow],“total”:0}
  • GET_SOURCE_CONFIG: {“project_id”:“proj_123”,“source_configs”:[SourceConfig]}
  • RECONFIGURE_SOURCE: {“project_id”:“proj_123”,“source_config”:SourceConfig,“layout”:{“version_id”:123,“version_number”:2,“field_count”:3,“section_count”:1,“warnings”:[],“fields_matched”:1,“fields_created”:2}}
  • SET_USER_SEAT: {“username”:“JSMITH”,“seat_type”:“build”,“organization_id”:1,“account_id”:123,“member_id”:456}
  • REVOKE_USER_SEAT: {“username”:“JSMITH”,“seat_type”:“view”,“organization_id”:1,“account_id”:123,“member_id”:456}
  • LIST_USERS: {“users”:[UserSeat]}
  • REPAIR_USER_SEATS: {“organization_id”:1,“archived_count”:0}
  • PREVIEW_BILLING: {“rows”:[BillingPreviewRow]}
  • LIST_BILLING_LEDGER: {“rows”:[BillingLedgerRow]}
  • SUSPEND_APP, RESUME_APP: {“service”:“core.entrylayer_service”,“compute_pool”:“entrylayer_pool”}

Table/scalar function return payloads:

  • EXTRACT_PROJECT_SUBMISSIONS: TABLE rows matching ExtractSubmissionRow; this function does not return the VARIANT envelope.
  • EXTRACT_PROJECT_FIELD_METADATA: TABLE rows matching ExtractFieldMetadataRow; this function does not return the VARIANT envelope.
  • GET_PROJECT_EXTRACT_SQL: VARCHAR containing generated SELECT text; this scalar function does not return the VARIANT envelope.

Automation guardrails:

  • Call VALIDATE_SOURCE before CREATE_PROJECT when creating from a Snowflake object.
  • Use GET_PROJECT for lightweight metadata and GET_PROJECT_LAYOUT for form fields.
  • Treat GET_PROJECT_LAYOUT data.fields as the canonical parsed field list for automation.
  • For draft edits, use GET_PROJECT_DRAFT, mutate with targeted procedures, then PUBLISH_PROJECT_DRAFT before users can see changes.
  • Read procedures are safe to retry. GRANT_ACCESS upserts role access. UPSERT_ACCESS upserts role or user access. REVOKE_ACCESS is idempotent.
  • CREATE_PROJECT is not idempotent and creates a new project on each successful call.
  • CREATE_PROJECT and create-style draft commands are not idempotent and create new resources on each successful call.
  • Submission procedures are admin-only but still require explicit project data permissions such as can_read, can_submit, can_edit, and can_delete.
  • Submission values are procedure-only. No APP_PUBLIC view exposes submission values.
  • Do not infer or request broad source row samples from this API; source-backed calls must stay tied to documented grid/virtual-row workflows.
  • Do not call removed procedures such as DESCRIBE_PROJECT.