Update Table

Rename a table, edit its description, or move it to a canonical folder. At least one mutable field is required; lock flags remain read-only.

This operation is NOT atomic. The name, description, and folder changes are written independently in that order, so a failure part-way through leaves the earlier writes committed — a 4xx does NOT mean nothing changed. When at least one field landed before the failure, the error body carries details.applied: the list of fields (name, description, folderPath) that were successfully written. Re-read the table, or retry with only the fields missing from details.applied.

A workspace whose folder tree exceeds 10,000 folders is a 413, because the response needs the whole tree to render folder paths.

PATCH/api/v2/tables/{tableId}

Authorization

apiKey
X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one from the Sim dashboard under Settings > API Keys. A workspace API key is not accepted everywhere: operations that act on behalf of a specific human — administrative reads, secret access, and irreversible or governance-affecting writes — always reject it, whatever role the key carries. Each such operation says so in its own description, and the rejection surfaces as 403 unless the operation conceals unauthorized resources, in which case it is reported as 404. Use a personal API key for those.

In: header

Path Parameters

tableId*string

Unique table identifier.

Length1 <= length

Request Body

application/json

Workspace scope and one or more table metadata or placement changes.

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://www.sim.ai/api/v2/tables/string" \  -H "Content-Type: application/json" \  -d '{    "workspaceId": "string"  }'
{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "ownerEmail": "owner@example.com",
    "schema": {
      "columns": [
        {
          "id": "string",
          "name": "string",
          "type": "string",
          "required": false,
          "unique": false,
          "workflowGroupId": "string",
          "options": [
            {
              "id": "string",
              "name": "string"
            }
          ],
          "multiple": true,
          "currencyCode": "string"
        }
      ]
    },
    "rowCount": 0,
    "maxRows": 0,
    "folderPath": "string",
    "locks": {
      "schemaLocked": true,
      "insertLocked": true,
      "updateLocked": true,
      "deleteLocked": true
    },
    "job": {
      "id": "string",
      "type": "import",
      "status": "running",
      "rowsProcessed": 0,
      "error": "string"
    },
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}