Skip to content
Try for free
On this page

Tables

Create table

Create a table with a typed column schema and optional folder placement. OAuth scope: `api:write`.

POST/api/v2/tables

Create a table with a typed column schema and optional folder placement.

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.

Request body

Required

Workspace, table metadata, folder placement, and typed columns.

object

Workspace, table metadata, folder placement, and typed columns.

5 fields
namestringRequired

Table name.

minLength
1
maxLength
128
pattern
^[A-Za-z_][A-Za-z0-9_]*$
descriptionstring

Optional table description.

maxLength
500
workspaceIdstringRequired

Unique workspace identifier.

minLength
1
maxLength
128
schemaobjectRequired

Initial table column definitions.

1 field
columnsarrayRequired

Initial table columns.

minItems
1
maxItems
1000
Schema details
Array itemobject
8 fields
idstring

Optional client-provided column identifier.

namestringRequired

Column name.

minLength
1
maxLength
50
pattern
^[A-Za-z_][A-Za-z0-9_]*$
typestringRequired

Column data type.

enum
["string","number","currency","boolean","date","json","select"]
requiredboolean

Whether inserts must supply a value for this column.

uniqueboolean

Whether values in the column must be unique.

optionsarray

Select options for select-type columns.

maxItems
100
Schema details
Array itemobject
2 fields
idstringRequired

Stable select-option identifier.

minLength
1
namestringRequired

Display name of the select option.

minLength
1
maxLength
100
multipleboolean

Whether a select column accepts multiple values.

currencyCodestring

ISO 4217 code for currency columns.

pattern
^[A-Za-z]{3}$

Additional properties are not allowed.

Additional properties are not allowed.

folderPathstring

Folder in which to create the table.

maxLength
4096

Additional properties are not allowed.

Request example 1

json
{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "name": "Customers",
  "description": "Customer accounts and lifecycle state.",
  "schema": {
    "columns": [
      {
        "name": "email",
        "type": "string",
        "unique": true
      },
      {
        "name": "status",
        "type": "string"
      }
    ]
  }
}

Responses

201

The created table.

object

The created table.

1 field
dataobjectRequired

Response data.

13 fields
idstringRequired

Unique table identifier.

webUrlstringRequired

Canonical absolute URL for opening this resource in the Sim web application.

format
uri
namestringRequired

Table name.

descriptionvalueRequired

Table description, or null when none is set.

Schema details

Any of

Option 1string
Option 2null
ownerEmailstringRequired

Current email address of the table owner.

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

Typed table schema.

1 field
columnsarrayRequired

Table column definitions.

Schema details
Array itemobject

A typed column in a table schema.

9 fields
idstring

Stable server-assigned column identifier.

namestringRequired

Column name used as the public row-data key.

minLength
1
maxLength
50
pattern
^[A-Za-z_][A-Za-z0-9_]*$
typestringRequired

Data type of values stored in the column.

enum
["string","number","currency","boolean","date","json","select"]
requiredbooleanRequired

Whether inserts require a value for this column.

default
false
uniquebooleanRequired

Whether values must be unique across table rows.

default
false
workflowGroupIdstring

Workflow group whose output populates this column.

optionsarray

Options declared for a select column.

maxItems
100
Schema details
Array itemobject
2 fields
idstringRequired

Stable select-option identifier.

minLength
1
namestringRequired

Display name of the select option.

minLength
1
maxLength
100

Additional properties are not allowed.

multipleboolean

Whether a select column accepts multiple options.

currencyCodestring

ISO 4217 code for a currency column, normalized to uppercase.

pattern
^[A-Za-z]{3}$

Additional properties are not allowed.

Additional properties are not allowed.

rowCountnumberRequired

Current number of rows in the table.

maxRowsnumberRequired

Maximum rows allowed by the workspace plan.

folderPathstringRequired

Canonical slash-prefixed folder path. / is the workspace root. Segments are percent-encoded, so a folder shown as "New folder" is /New%20folder: everything outside A-Z a-z 0-9 - _ . ~ is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal . or .. segment are rejected. At most 64 segments and 4096 encoded bytes.

maxLength
4096
locksobjectRequired

Read-only table governance locks.

4 fields
schemaLockedbooleanRequired

Whether column-schema changes are locked.

insertLockedbooleanRequired

Whether row insertion is locked.

updateLockedbooleanRequired

Whether row updates are locked.

deleteLockedbooleanRequired

Whether row and table deletion is locked.

Additional properties are not allowed.

jobvalueRequired

Current background job, or null when idle.

Schema details

Any of

Option 1object

Current background work associated with a table.

5 fields
idvalueRequired

Background job identifier, or null when unavailable.

Schema details

Any of

Option 1string
Option 2null
typevalueRequired

Kind of background table work.

Schema details

Any of

Option 1string
enum
["import","delete","export","backfill","update"]
Option 2null
statusstringRequired

Current background job state.

enum
["running","ready","failed","canceled"]
rowsProcessednumberRequired

Number of rows processed by the job.

errorvalueRequired

Failure reason, or null when the job has not failed.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Option 2null
createdAtstringRequired

ISO 8601 timestamp when the table 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 table 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