Skip to content
Try for free
On this page

Tables

Create view

Save a filter, sort, and column layout as a named presentation of a table. OAuth scope: `api:write`.

POST/api/v2/tables/{tableId}/views

Save a filter, sort, and column layout as a named presentation of a table.

OAuth scope: api:write.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:write

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:write.

Path parameters

tableIdstringRequired

Unique table identifier.

minLength
1

Request body

Required

Workspace scope, name, and saved filter, sort, and layout configuration.

object

Workspace scope, name, and saved filter, sort, and layout configuration.

3 fields
workspaceIdstringRequired

Workspace that owns the table.

minLength
1
namestringRequired

Saved-view display name.

minLength
1
configobjectRequired

Saved filter, sort, and column-layout configuration.

6 fields
columnWidthsobject

Column widths keyed by column name or stable column identifier.

Schema details
Additional propertiesnumber
exclusiveMinimum
0
columnOrderarray

Columns in display order, by name or stable identifier.

Schema details
Array itemstring
pinnedColumnsarray

Pinned columns, by name or stable identifier.

Schema details
Array itemstring
hiddenColumnsarray

Hidden columns, by name or stable identifier.

Schema details
Array itemstring
filtervalue

Saved row predicate, or null when the view is unfiltered.

Schema details

Any of

Option 1TablePredicateInput

One condition or a recursive all/any group, normalized to a grouped predicate. Limits: 100 members per group, 10 levels, and 500 nodes. The negating operators include nulls and absent cells, multi-select included; combine with isNotNull or isNotEmpty to exclude them. Pattern operators use * as the only wildcard; %, _, and backslash are literal. Select operators: single-select uses eq/ne/in/nin; multi-select uses contains/ncontains; option names resolve to IDs. Full operand rules are documented on op.

Schema details

Exactly one of

Option 1object

Matches a row when every member matches.

1 field
allarrayRequired

Members combined with AND. An empty group is rejected, because it would compile to no filter at all.

minItems
1
maxItems
100
Schema details
Array itemvalue

A nested group, or a single condition.

Schema details

Any of

Option 1 references recursive schema TablePredicateInput. See the complete schema in the OpenAPI download.

Option 2object

One column comparison.

3 fields
fieldstringRequired

Column name to compare, or one of the system fields id, createdAt, updatedAt.

minLength
1
maxLength
128
opstringRequired

Operators: eq, ne, gt, gte, lt, lte; in/nin take arrays; isEmpty, isNotEmpty, isNull, and isNotNull take no operand. Text operators are contains, ncontains, startsWith, endsWith, like, nlike, ilike, and nilike. Contains variants are case-insensitive and literal; like/nlike are case-sensitive, while ilike/nilike are case-insensitive. * is the only wildcard; %, _, and backslash are literal. For select columns, single-select accepts eq, ne, in, nin; multi-select accepts contains, ncontains. Option names resolve to IDs.

enum
["eq","ne","gt","gte","lt","lte","in","nin","contains","ncontains","startsWith","endsWith","like","ilike","nlike","nilike","isEmpty","isNotEmpty","isNull","isNotNull"]
valuevalue

Operand. A scalar for the comparison operators, an array of at most 1000 entries for in/nin, a pattern for the matching operators, and omitted for isEmpty/isNotEmpty/isNull/isNotNull.

Additional properties are not allowed.

Additional properties are not allowed.

Option 2object

Matches a row when at least one member matches.

1 field
anyarrayRequired

Members combined with OR. An empty group is rejected, because it would compile to no filter at all.

minItems
1
maxItems
100
Schema details
Array itemvalue

A nested group, or a single condition.

Schema details

Any of

Option 1 references recursive schema TablePredicateInput. See the complete schema in the OpenAPI download.

Option 2object

One column comparison.

3 fields
fieldstringRequired

Column name to compare, or one of the system fields id, createdAt, updatedAt.

minLength
1
maxLength
128
opstringRequired

Operators: eq, ne, gt, gte, lt, lte; in/nin take arrays; isEmpty, isNotEmpty, isNull, and isNotNull take no operand. Text operators are contains, ncontains, startsWith, endsWith, like, nlike, ilike, and nilike. Contains variants are case-insensitive and literal; like/nlike are case-sensitive, while ilike/nilike are case-insensitive. * is the only wildcard; %, _, and backslash are literal. For select columns, single-select accepts eq, ne, in, nin; multi-select accepts contains, ncontains. Option names resolve to IDs.

enum
["eq","ne","gt","gte","lt","lte","in","nin","contains","ncontains","startsWith","endsWith","like","ilike","nlike","nilike","isEmpty","isNotEmpty","isNull","isNotNull"]
valuevalue

Operand. A scalar for the comparison operators, an array of at most 1000 entries for in/nin, a pattern for the matching operators, and omitted for isEmpty/isNotEmpty/isNull/isNotNull.

Additional properties are not allowed.

Additional properties are not allowed.

Option 3object

One column comparison.

3 fields
fieldstringRequired

Column name to compare, or one of the system fields id, createdAt, updatedAt.

minLength
1
maxLength
128
opstringRequired

Operators: eq, ne, gt, gte, lt, lte; in/nin take arrays; isEmpty, isNotEmpty, isNull, and isNotNull take no operand. Text operators are contains, ncontains, startsWith, endsWith, like, nlike, ilike, and nilike. Contains variants are case-insensitive and literal; like/nlike are case-sensitive, while ilike/nilike are case-insensitive. * is the only wildcard; %, _, and backslash are literal. For select columns, single-select accepts eq, ne, in, nin; multi-select accepts contains, ncontains. Option names resolve to IDs.

enum
["eq","ne","gt","gte","lt","lte","in","nin","contains","ncontains","startsWith","endsWith","like","ilike","nlike","nilike","isEmpty","isNotEmpty","isNull","isNotNull"]
valuevalue

Operand. A scalar for the comparison operators, an array of at most 1000 entries for in/nin, a pattern for the matching operators, and omitted for isEmpty/isNotEmpty/isNull/isNotNull.

Additional properties are not allowed.

Option 2null
sortvalue

Saved ordered sort specification, or null for default ordering.

Schema details

Any of

Option 1array
maxItems
16
Schema details
Array itemobject
2 fields
fieldstringRequired

Column name to sort by.

minLength
1
maxLength
128
directionstringRequired

Sort direction for this column.

enum
["asc","desc"]

Additional properties are not allowed.

Option 2null

Additional properties are not allowed.

Additional properties are not allowed.

Request example 1

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "name": "Active customers",
  "config": {
    "filter": {
      "all": [
        {
          "field": "status",
          "op": "eq",
          "value": "active"
        }
      ]
    },
    "sort": [
      {
        "field": "createdAt",
        "direction": "desc"
      }
    ]
  }
}

Responses

201

The created table view.

object

The created saved view.

1 field
dataobjectRequired

Response data.

8 fields
idstringRequired

Unique saved-view identifier.

tableIdstringRequired

Table to which the view belongs.

namestringRequired

Saved-view display name.

configobjectRequired

Saved filter, sort, and column-layout configuration.

6 fields
columnWidthsobject

Column widths keyed by column name.

Schema details
Additional propertiesnumber
exclusiveMinimum
0
columnOrderarray

Column names in display order.

Schema details
Array itemstring
pinnedColumnsarray

Names of pinned columns.

Schema details
Array itemstring
hiddenColumnsarray

Names of hidden columns.

Schema details
Array itemstring
filtervalue

Saved row predicate, or null when the view is unfiltered.

Schema details

Any of

Option 1value

Recursive saved predicate tree. Runtime validation uses the canonical predicate schema.

Option 2null
sortvalue

Saved ordered sort specification, or null for default ordering.

Schema details

Any of

Option 1array
maxItems
16
Schema details
Array itemobject
2 fields
fieldstringRequired

Column name to sort by.

minLength
1
maxLength
128
directionstringRequired

Sort direction for this column.

enum
["asc","desc"]

Additional properties are not allowed.

Option 2null

Additional properties are not allowed.

isDefaultbooleanRequired

Whether this is the table default view.

createdByEmailvalueRequired

Current author email, or null when removed.

Schema details

Any of

Option 1string
format
email
pattern
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
Option 2null
createdAtstringRequired

ISO 8601 timestamp when the view was created.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAtstringRequired

ISO 8601 timestamp when the view was last modified.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Additional properties are not allowed.

Additional properties are not allowed.

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit