# Create table import (/api-reference/tables/createTableImport)

`POST /api/v2/tables/imports`

Create a CSV import. Upload sources receive signed transfer instructions; workspace-file sources start processing directly.

OAuth scope: `api:write`.

## Authentication

```json

{
  "requirements": [
    {
      "apiKey": []
    },
    {
      "oauthBearer": [
        "api:write"
      ]
    }
  ],
  "schemes": {
    "apiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "X-API-Key",
      "description": "Send a personal or workspace API key in `X-API-Key`. See [key types and access](https://docs.sim.ai/api-reference/authentication#key-types); operations that reject workspace keys say so in their description."
    },
    "oauthBearer": {
      "type": "oauth2",
      "description": "Send a Sim OAuth access token in `Authorization: Bearer`. See [OAuth authentication and scopes](https://docs.sim.ai/api-reference/authentication#oauth-access-tokens).",
      "flows": {
        "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"
          }
        }
      }
    }
  }
}

```

Required OAuth scope: `api:write`.

## Request examples

### cURL

```bash
curl --request POST 'https://www.sim.ai/api/v2/tables/imports' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
  "source": {
    "type": "upload",
    "name": "customers.csv",
    "contentType": "text/csv",
    "size": 2048
  },
  "target": {
    "type": "new",
    "name": "ImportedCustomers",
    "folderPath": "/Imports"
  },
  "timezone": "America/Los_Angeles"
}'
```

### JavaScript

```javascript
const response = await fetch("https://www.sim.ai/api/v2/tables/imports", {
  "method": "POST",
  "headers": {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  "body": "{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"source\": {\n    \"type\": \"upload\",\n    \"name\": \"customers.csv\",\n    \"contentType\": \"text/csv\",\n    \"size\": 2048\n  },\n  \"target\": {\n    \"type\": \"new\",\n    \"name\": \"ImportedCustomers\",\n    \"folderPath\": \"/Imports\"\n  },\n  \"timezone\": \"America/Los_Angeles\"\n}"
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const result = await response.json();
```

### Python

```python
import requests

response = requests.request(
    "POST",
    "https://www.sim.ai/api/v2/tables/imports",
    headers={
  "X-API-Key": "YOUR_API_KEY",
  "Content-Type": "application/json"
},
    data="{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"source\": {\n    \"type\": \"upload\",\n    \"name\": \"customers.csv\",\n    \"contentType\": \"text/csv\",\n    \"size\": 2048\n  },\n  \"target\": {\n    \"type\": \"new\",\n    \"name\": \"ImportedCustomers\",\n    \"folderPath\": \"/Imports\"\n  },\n  \"timezone\": \"America/Los_Angeles\"\n}",
)
response.raise_for_status()
result = response.json()
```

### Go

```go
package main

import (
  "io"
  "net/http"
  "os"
  "strings"
)

func check(err error) {
  if err != nil { panic(err) }
}

func must[T any](value T, err error) T {
  check(err)
  return value
}

func main() {

  request := must(http.NewRequest("POST", "https://www.sim.ai/api/v2/tables/imports", strings.NewReader("{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"source\": {\n    \"type\": \"upload\",\n    \"name\": \"customers.csv\",\n    \"contentType\": \"text/csv\",\n    \"size\": 2048\n  },\n  \"target\": {\n    \"type\": \"new\",\n    \"name\": \"ImportedCustomers\",\n    \"folderPath\": \"/Imports\"\n  },\n  \"timezone\": \"America/Los_Angeles\"\n}")))
  request.Header.Set("X-API-Key", "YOUR_API_KEY")
  request.Header.Set("Content-Type", "application/json")
  response := must(http.DefaultClient.Do(request))
  defer response.Body.Close()
  if response.StatusCode >= 400 { panic(response.Status) }
  must(io.Copy(os.Stdout, response.Body))
}
```

### Java

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    var builder = HttpRequest.newBuilder(URI.create("https://www.sim.ai/api/v2/tables/imports"));
    builder.header("X-API-Key", "YOUR_API_KEY");
    builder.header("Content-Type", "application/json");
    var request = builder.method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"source\": {\n    \"type\": \"upload\",\n    \"name\": \"customers.csv\",\n    \"contentType\": \"text/csv\",\n    \"size\": 2048\n  },\n  \"target\": {\n    \"type\": \"new\",\n    \"name\": \"ImportedCustomers\",\n    \"folderPath\": \"/Imports\"\n  },\n  \"timezone\": \"America/Los_Angeles\"\n}")).build();
    var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofInputStream());
    try (var body = response.body()) {
      if (response.statusCode() >= 400) throw new IllegalStateException("HTTP " + response.statusCode());
      body.transferTo(System.out);
    }
  }
}
```

### C#

```csharp
using System;
using System.IO;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.sim.ai/api/v2/tables/imports");
request.Content = new StringContent("{\n  \"workspaceId\": \"a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64\",\n  \"source\": {\n    \"type\": \"upload\",\n    \"name\": \"customers.csv\",\n    \"contentType\": \"text/csv\",\n    \"size\": 2048\n  },\n  \"target\": {\n    \"type\": \"new\",\n    \"name\": \"ImportedCustomers\",\n    \"folderPath\": \"/Imports\"\n  },\n  \"timezone\": \"America/Los_Angeles\"\n}", Encoding.UTF8);
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_API_KEY");
request.Content!.Headers.ContentType = System.Net.Http.Headers.MediaTypeHeaderValue.Parse("application/json");
using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);
response.EnsureSuccessStatusCode();
await response.Content.CopyToAsync(Console.OpenStandardOutput());
```

## Request body

```json

{
  "required": true,
  "description": "Workspace, CSV source, target table, optional mapping, and timezone.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "workspaceId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Unique workspace identifier."
          },
          "source": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "upload",
                    "description": "Upload-backed import discriminator."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255,
                    "description": "CSV filename."
                  },
                  "contentType": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255,
                    "description": "CSV MIME type."
                  },
                  "size": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5368709120,
                    "description": "Exact CSV file size in bytes."
                  }
                },
                "required": [
                  "type",
                  "name",
                  "contentType",
                  "size"
                ],
                "additionalProperties": false,
                "title": "Upload table import source",
                "description": "CSV file uploaded through signed transfer instructions."
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "workspace_file",
                    "description": "Workspace-file source discriminator."
                  },
                  "fileId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Existing workspace file identifier."
                  }
                },
                "required": [
                  "type",
                  "fileId"
                ],
                "additionalProperties": false,
                "title": "Workspace file table import source",
                "description": "Existing workspace file used as a CSV import source."
              }
            ],
            "description": "CSV source for the import."
          },
          "target": {
            "oneOf": [
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "new",
                    "description": "Create-new-table target discriminator."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128,
                    "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
                    "description": "Name of the table to create."
                  },
                  "folderPath": {
                    "title": "Folder path input",
                    "description": "Folder path. A missing leading slash is normalized before validation. 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,
                    "type": "string"
                  }
                },
                "required": [
                  "type",
                  "name"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "existing",
                    "description": "Existing-table target discriminator."
                  },
                  "tableId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Existing target table identifier."
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "append",
                      "replace"
                    ],
                    "description": "Whether to append rows or replace existing rows."
                  }
                },
                "required": [
                  "type",
                  "tableId",
                  "mode"
                ],
                "additionalProperties": false
              }
            ],
            "description": "New or existing table import target."
          },
          "mapping": {
            "description": "CSV headers mapped to existing table columns.",
            "type": "object",
            "propertyNames": {
              "type": "string",
              "minLength": 1,
              "maxLength": 50
            },
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 50
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "createColumns": {
            "description": "CSV headers for which new columns should be created.",
            "maxItems": 1000,
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 50
            }
          },
          "timezone": {
            "description": "IANA timezone used to interpret local date values.",
            "type": "string"
          }
        },
        "required": [
          "workspaceId",
          "source",
          "target"
        ],
        "additionalProperties": false,
        "title": "Create table import request",
        "description": "Workspace, CSV source, target table, optional mapping, and timezone."
      },
      "examples": {
        "example1": {
          "summary": "Request example 1",
          "value": {
            "workspaceId": "a91c4b2e-6d3f-4e8a-b5c7-0d9e2f1a8c64",
            "source": {
              "type": "upload",
              "name": "customers.csv",
              "contentType": "text/csv",
              "size": 2048
            },
            "target": {
              "type": "new",
              "name": "ImportedCustomers",
              "folderPath": "/Imports"
            },
            "timezone": "America/Los_Angeles"
          }
        }
      }
    }
  }
}

```

## Responses

### 201

```json

{
  "description": "The created table import and optional transfer instructions.",
  "headers": {
    "X-RateLimit-Limit": {
      "description": "Maximum requests allowed in the current window.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Rate limit",
        "description": "Maximum requests allowed in the current window."
      }
    },
    "X-RateLimit-Remaining": {
      "description": "Requests remaining in the current window.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Rate limit remaining",
        "description": "Requests remaining in the current window."
      }
    },
    "X-RateLimit-Reset": {
      "description": "ISO 8601 timestamp when the current rate-limit window resets.",
      "schema": {
        "type": "string",
        "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))$",
        "title": "Rate limit reset",
        "description": "ISO 8601 timestamp when the current rate-limit window resets."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "data": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "session": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Unique table-import identifier."
                      },
                      "workspaceId": {
                        "type": "string",
                        "description": "Workspace that owns the import."
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "uploading",
                          "processing",
                          "completed",
                          "failed",
                          "canceled",
                          "expired"
                        ],
                        "description": "Current import lifecycle state."
                      },
                      "source": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "const": "upload",
                            "description": "Upload-backed import discriminator."
                          },
                          "name": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 255,
                            "description": "CSV filename."
                          },
                          "contentType": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 255,
                            "description": "CSV MIME type."
                          },
                          "size": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 5368709120,
                            "description": "Exact CSV file size in bytes."
                          }
                        },
                        "required": [
                          "type",
                          "name",
                          "contentType",
                          "size"
                        ],
                        "additionalProperties": false,
                        "title": "Upload table import source",
                        "description": "Uploaded CSV source for this import."
                      },
                      "target": {
                        "oneOf": [
                          {
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string",
                                "const": "new",
                                "description": "Create-new-table target discriminator."
                              },
                              "name": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 128,
                                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
                                "description": "Name of the table to create."
                              },
                              "folderPath": {
                                "title": "Folder path input",
                                "description": "Folder path. A missing leading slash is normalized before validation. 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,
                                "type": "string"
                              }
                            },
                            "required": [
                              "type",
                              "name"
                            ],
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string",
                                "const": "existing",
                                "description": "Existing-table target discriminator."
                              },
                              "tableId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "Existing target table identifier."
                              },
                              "mode": {
                                "type": "string",
                                "enum": [
                                  "append",
                                  "replace"
                                ],
                                "description": "Whether to append rows or replace existing rows."
                              }
                            },
                            "required": [
                              "type",
                              "tableId",
                              "mode"
                            ],
                            "additionalProperties": false
                          }
                        ],
                        "description": "New or existing table import target."
                      },
                      "tableId": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Resulting or target table identifier."
                      },
                      "rowsProcessed": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 9007199254740991,
                        "description": "Rows processed so far."
                      },
                      "rowsRejected": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 9007199254740991,
                        "description": "Minimum number of source records dropped by parser failures. One failure can discard multiple records, such as an unterminated quote consuming the rest of the file. A non-zero value means partial import even with `completed` status; zero does not guarantee no loss."
                      },
                      "cellsRejected": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 9007199254740991,
                        "description": "Non-empty cell values the target column type could not represent. Their rows were imported with the cell left blank."
                      },
                      "rejectedSamples": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "string",
                              "description": "CSV parser error code, e.g. CSV_QUOTE_NOT_CLOSED."
                            },
                            "line": {
                              "anyOf": [
                                {
                                  "type": "integer",
                                  "minimum": 0,
                                  "maximum": 9007199254740991
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "1-based source line the parser had reached when it gave up, or null."
                            },
                            "message": {
                              "type": "string",
                              "description": "Parser message for the dropped record."
                            }
                          },
                          "required": [
                            "code",
                            "line",
                            "message"
                          ],
                          "additionalProperties": false,
                          "title": "Rejected import record",
                          "description": "One source record a table import could not read."
                        },
                        "description": "Bounded sample of the dropped records, for locating them in the source file."
                      },
                      "error": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Terminal failure reason, or null."
                      },
                      "createdAt": {
                        "type": "string",
                        "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))$",
                        "description": "ISO 8601 creation timestamp."
                      },
                      "updatedAt": {
                        "type": "string",
                        "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))$",
                        "description": "ISO 8601 last-update timestamp."
                      },
                      "completedAt": {
                        "anyOf": [
                          {
                            "type": "string",
                            "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))$"
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "ISO 8601 completion timestamp, or null."
                      }
                    },
                    "required": [
                      "id",
                      "workspaceId",
                      "status",
                      "source",
                      "target",
                      "tableId",
                      "rowsProcessed",
                      "rowsRejected",
                      "cellsRejected",
                      "rejectedSamples",
                      "error",
                      "createdAt",
                      "updatedAt",
                      "completedAt"
                    ],
                    "additionalProperties": false,
                    "title": "Upload-backed table import",
                    "description": "Created upload-backed import session."
                  },
                  "uploadToken": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Signed token for upload control requests."
                  },
                  "transfer": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "method": {
                            "type": "string",
                            "const": "put",
                            "description": "Upload strategy discriminator."
                          },
                          "url": {
                            "type": "string",
                            "format": "uri",
                            "description": "Signed URL to which the file bytes are uploaded. Upload bytes with `PUT` and exactly the supplied headers; never construct or modify the signed URL. Treat any `2xx` as success. Sim-hosted URLs return an empty `204` and v2 JSON errors. Object-storage URLs may return `200` or `201` and provider-specific errors, often XML."
                          },
                          "headers": {
                            "type": "object",
                            "propertyNames": {
                              "type": "string"
                            },
                            "additionalProperties": {
                              "type": "string"
                            },
                            "description": "Headers that must be included with the upload request."
                          },
                          "expiresAt": {
                            "type": "string",
                            "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))$",
                            "description": "ISO 8601 expiration time for this signed URL. This is the URL's own expiry and is normally earlier than the upload session's expiresAt: the session stays open for later part, status, completion, and abort requests, but the bytes must be uploaded before this time. Once it passes, the storage provider rejects the upload and a new upload session must be created."
                          }
                        },
                        "required": [
                          "method",
                          "url",
                          "headers",
                          "expiresAt"
                        ],
                        "additionalProperties": false,
                        "title": "Direct upload transfer",
                        "description": "Instructions for uploading bytes to one signed URL."
                      },
                      {
                        "type": "object",
                        "properties": {
                          "method": {
                            "type": "string",
                            "const": "multipart",
                            "description": "Upload strategy discriminator."
                          },
                          "partSize": {
                            "type": "integer",
                            "exclusiveMinimum": 0,
                            "maximum": 9007199254740991,
                            "description": "Required size of each non-final part in bytes."
                          },
                          "partCount": {
                            "type": "integer",
                            "exclusiveMinimum": 0,
                            "maximum": 640,
                            "description": "Total number of upload parts."
                          }
                        },
                        "required": [
                          "method",
                          "partSize",
                          "partCount"
                        ],
                        "additionalProperties": false,
                        "title": "Multipart upload transfer",
                        "description": "Instructions for splitting bytes into a multipart upload."
                      }
                    ],
                    "description": "Signed CSV upload instructions."
                  }
                },
                "required": [
                  "session",
                  "uploadToken",
                  "transfer"
                ],
                "additionalProperties": false
              },
              {
                "type": "object",
                "properties": {
                  "session": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Unique table-import identifier."
                      },
                      "workspaceId": {
                        "type": "string",
                        "description": "Workspace that owns the import."
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "uploading",
                          "processing",
                          "completed",
                          "failed",
                          "canceled",
                          "expired"
                        ],
                        "description": "Current import lifecycle state."
                      },
                      "source": {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "const": "workspace_file",
                            "description": "Workspace-file source discriminator."
                          },
                          "fileId": {
                            "type": "string",
                            "minLength": 1,
                            "description": "Existing workspace file identifier."
                          }
                        },
                        "required": [
                          "type",
                          "fileId"
                        ],
                        "additionalProperties": false,
                        "title": "Workspace file table import source",
                        "description": "Workspace-file CSV source for this import."
                      },
                      "target": {
                        "oneOf": [
                          {
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string",
                                "const": "new",
                                "description": "Create-new-table target discriminator."
                              },
                              "name": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 128,
                                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
                                "description": "Name of the table to create."
                              },
                              "folderPath": {
                                "title": "Folder path input",
                                "description": "Folder path. A missing leading slash is normalized before validation. 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,
                                "type": "string"
                              }
                            },
                            "required": [
                              "type",
                              "name"
                            ],
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "properties": {
                              "type": {
                                "type": "string",
                                "const": "existing",
                                "description": "Existing-table target discriminator."
                              },
                              "tableId": {
                                "type": "string",
                                "minLength": 1,
                                "description": "Existing target table identifier."
                              },
                              "mode": {
                                "type": "string",
                                "enum": [
                                  "append",
                                  "replace"
                                ],
                                "description": "Whether to append rows or replace existing rows."
                              }
                            },
                            "required": [
                              "type",
                              "tableId",
                              "mode"
                            ],
                            "additionalProperties": false
                          }
                        ],
                        "description": "New or existing table import target."
                      },
                      "tableId": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Resulting or target table identifier."
                      },
                      "rowsProcessed": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 9007199254740991,
                        "description": "Rows processed so far."
                      },
                      "rowsRejected": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 9007199254740991,
                        "description": "Minimum number of source records dropped by parser failures. One failure can discard multiple records, such as an unterminated quote consuming the rest of the file. A non-zero value means partial import even with `completed` status; zero does not guarantee no loss."
                      },
                      "cellsRejected": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 9007199254740991,
                        "description": "Non-empty cell values the target column type could not represent. Their rows were imported with the cell left blank."
                      },
                      "rejectedSamples": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "string",
                              "description": "CSV parser error code, e.g. CSV_QUOTE_NOT_CLOSED."
                            },
                            "line": {
                              "anyOf": [
                                {
                                  "type": "integer",
                                  "minimum": 0,
                                  "maximum": 9007199254740991
                                },
                                {
                                  "type": "null"
                                }
                              ],
                              "description": "1-based source line the parser had reached when it gave up, or null."
                            },
                            "message": {
                              "type": "string",
                              "description": "Parser message for the dropped record."
                            }
                          },
                          "required": [
                            "code",
                            "line",
                            "message"
                          ],
                          "additionalProperties": false,
                          "title": "Rejected import record",
                          "description": "One source record a table import could not read."
                        },
                        "description": "Bounded sample of the dropped records, for locating them in the source file."
                      },
                      "error": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "Terminal failure reason, or null."
                      },
                      "createdAt": {
                        "type": "string",
                        "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))$",
                        "description": "ISO 8601 creation timestamp."
                      },
                      "updatedAt": {
                        "type": "string",
                        "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))$",
                        "description": "ISO 8601 last-update timestamp."
                      },
                      "completedAt": {
                        "anyOf": [
                          {
                            "type": "string",
                            "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))$"
                          },
                          {
                            "type": "null"
                          }
                        ],
                        "description": "ISO 8601 completion timestamp, or null."
                      }
                    },
                    "required": [
                      "id",
                      "workspaceId",
                      "status",
                      "source",
                      "target",
                      "tableId",
                      "rowsProcessed",
                      "rowsRejected",
                      "cellsRejected",
                      "rejectedSamples",
                      "error",
                      "createdAt",
                      "updatedAt",
                      "completedAt"
                    ],
                    "additionalProperties": false,
                    "title": "Workspace-file table import",
                    "description": "Created workspace-file import session."
                  },
                  "uploadToken": {
                    "type": "null",
                    "description": "Always null; a workspace-file import has no upload to authorize."
                  },
                  "transfer": {
                    "type": "null",
                    "description": "Always null; a workspace-file import has no bytes to transfer."
                  }
                },
                "required": [
                  "session",
                  "uploadToken",
                  "transfer"
                ],
                "additionalProperties": false
              }
            ],
            "title": "Create table import data",
            "description": "Response data."
          }
        },
        "required": [
          "data"
        ],
        "additionalProperties": false,
        "title": "Create table import response",
        "description": "The import session and upload instructions when transfer is required."
      }
    }
  }
}

```

### 400

```json

{
  "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "BAD_REQUEST",
          "message": "Invalid request"
        }
      }
    }
  }
}

```

### 401

```json

{
  "description": "The API credential is missing or invalid.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "UNAUTHORIZED",
          "message": "Authentication required"
        }
      }
    }
  }
}

```

### 403

```json

{
  "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "FORBIDDEN",
          "message": "Insufficient workspace permissions",
          "details": {
            "code": "INSUFFICIENT_WORKSPACE_ROLE"
          }
        }
      }
    }
  }
}

```

### 404

```json

{
  "description": "The requested resource was not found.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "NOT_FOUND",
          "message": "Not found"
        }
      }
    }
  }
}

```

### 409

```json

{
  "description": "The request conflicts with current resource state.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "CONFLICT",
          "message": "The request conflicts with current table state"
        }
      }
    }
  }
}

```

### 413

```json

{
  "description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "PAYLOAD_TOO_LARGE",
          "message": "Request body is too large"
        }
      }
    }
  }
}

```

### 415

```json

{
  "description": "The request uses an unsupported media type.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "UNSUPPORTED_MEDIA_TYPE",
          "message": "Request body must be sent as application/json"
        }
      }
    }
  }
}

```

### 423

```json

{
  "description": "The resource is temporarily locked or unavailable; retry the request.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "LOCKED",
          "message": "A table lock prevents this operation.",
          "details": {
            "lock": "insert"
          }
        }
      }
    }
  }
}

```

### 429

```json

{
  "description": "The caller exceeded the request rate limit.",
  "headers": {
    "Retry-After": {
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Retry after",
        "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "RATE_LIMITED",
          "message": "API rate limit exceeded",
          "details": {
            "retryAfter": "2026-01-01T00:00:30.000Z"
          }
        }
      }
    }
  }
}

```

### 500

```json

{
  "description": "An unexpected server error occurred.",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "INTERNAL_ERROR",
          "message": "Internal server error"
        }
      }
    }
  }
}

```

### 503

```json

{
  "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
  "headers": {
    "Retry-After": {
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "title": "Retry after",
        "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
      }
    }
  },
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error."
              },
              "details": {
                "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "code": {
                        "type": "string",
                        "enum": [
                          "INSUFFICIENT_WORKSPACE_ROLE",
                          "PERSONAL_API_KEYS_DISABLED",
                          "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
                          "PRINCIPAL_KIND_NOT_PERMITTED",
                          "ORGANIZATION_MEMBERSHIP_REQUIRED",
                          "ORGANIZATION_ADMIN_REQUIRED",
                          "ENTERPRISE_PLAN_REQUIRED",
                          "SSO_DISABLED",
                          "SSO_DOMAIN_NOT_VERIFIED",
                          "SSO_PROVIDER_LIMIT_REACHED",
                          "ORGANIZATION_PLAN_REQUIRED",
                          "AUDIT_LOGS_DISABLED",
                          "ACCESS_REQUESTS_DISABLED",
                          "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
                          "SKILL_EDITOR_ACCESS_REQUIRED",
                          "SECRET_ADMIN_ACCESS_REQUIRED",
                          "WORKSPACE_RESOURCE_LIMIT_REACHED",
                          "PUBLIC_SHARING_NOT_ALLOWED",
                          "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
                          "MCP_SERVER_URL_NOT_ALLOWED",
                          "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
                          "CHAT_AUTH_MODE_NOT_PERMITTED",
                          "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
                          "PERMISSION_GROUP_CAPABILITY_BLOCKED",
                          "INTEGRATION_NOT_ALLOWED",
                          "INSUFFICIENT_SCOPE",
                          "SCIM_MANAGED_MEMBERSHIP"
                        ],
                        "title": "Forbidden detail code",
                        "description": "Stable cause code for an actionable `403` response."
                      }
                    },
                    "required": [
                      "code"
                    ],
                    "additionalProperties": {
                      "description": "Additional context for this refusal."
                    },
                    "title": "Actionable forbidden details",
                    "description": "Machine-readable cause and optional context for an actionable `403` response."
                  },
                  {
                    "description": "Other structured context defined by the specific error."
                  }
                ]
              }
            },
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "description": "Canonical error details."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false,
        "title": "v2 error response",
        "description": "Canonical error envelope returned by the public v2 API.",
        "examples": [
          {
            "error": {
              "code": "BAD_REQUEST",
              "message": "The request is invalid."
            }
          }
        ]
      },
      "example": {
        "error": {
          "code": "SERVICE_UNAVAILABLE",
          "message": "Service temporarily unavailable"
        }
      }
    }
  }
}

```

## Referenced schemas

The following definitions preserve recursive references and composition exactly.

```json

{
  "#/components/schemas/CreateTableImportRequest": {
    "type": "object",
    "properties": {
      "workspaceId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128,
        "description": "Unique workspace identifier."
      },
      "source": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/V2TableUploadImportSource"
          },
          {
            "$ref": "#/components/schemas/V2TableWorkspaceFileImportSource"
          }
        ],
        "description": "CSV source for the import."
      },
      "target": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "new",
                "description": "Create-new-table target discriminator."
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
                "description": "Name of the table to create."
              },
              "folderPath": {
                "$ref": "#/components/schemas/FolderPathInput"
              }
            },
            "required": [
              "type",
              "name"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "existing",
                "description": "Existing-table target discriminator."
              },
              "tableId": {
                "type": "string",
                "minLength": 1,
                "description": "Existing target table identifier."
              },
              "mode": {
                "type": "string",
                "enum": [
                  "append",
                  "replace"
                ],
                "description": "Whether to append rows or replace existing rows."
              }
            },
            "required": [
              "type",
              "tableId",
              "mode"
            ],
            "additionalProperties": false
          }
        ],
        "description": "New or existing table import target."
      },
      "mapping": {
        "description": "CSV headers mapped to existing table columns.",
        "type": "object",
        "propertyNames": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50
        },
        "additionalProperties": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 50
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "createColumns": {
        "description": "CSV headers for which new columns should be created.",
        "maxItems": 1000,
        "type": "array",
        "items": {
          "type": "string",
          "minLength": 1,
          "maxLength": 50
        }
      },
      "timezone": {
        "description": "IANA timezone used to interpret local date values.",
        "type": "string"
      }
    },
    "required": [
      "workspaceId",
      "source",
      "target"
    ],
    "additionalProperties": false,
    "title": "Create table import request",
    "description": "Workspace, CSV source, target table, optional mapping, and timezone."
  },
  "#/components/schemas/V2TableUploadImportSource": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "const": "upload",
        "description": "Upload-backed import discriminator."
      },
      "name": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255,
        "description": "CSV filename."
      },
      "contentType": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255,
        "description": "CSV MIME type."
      },
      "size": {
        "type": "integer",
        "minimum": 1,
        "maximum": 5368709120,
        "description": "Exact CSV file size in bytes."
      }
    },
    "required": [
      "type",
      "name",
      "contentType",
      "size"
    ],
    "additionalProperties": false,
    "title": "Upload table import source",
    "description": "CSV file uploaded through signed transfer instructions."
  },
  "#/components/schemas/V2TableWorkspaceFileImportSource": {
    "type": "object",
    "properties": {
      "type": {
        "type": "string",
        "const": "workspace_file",
        "description": "Workspace-file source discriminator."
      },
      "fileId": {
        "type": "string",
        "minLength": 1,
        "description": "Existing workspace file identifier."
      }
    },
    "required": [
      "type",
      "fileId"
    ],
    "additionalProperties": false,
    "title": "Workspace file table import source",
    "description": "Existing workspace file used as a CSV import source."
  },
  "#/components/schemas/FolderPathInput": {
    "title": "Folder path input",
    "description": "Folder path. A missing leading slash is normalized before validation. 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,
    "type": "string"
  },
  "#/components/headers/X-RateLimit-Limit": {
    "description": "Maximum requests allowed in the current window.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Rate limit",
      "description": "Maximum requests allowed in the current window."
    }
  },
  "#/components/headers/X-RateLimit-Remaining": {
    "description": "Requests remaining in the current window.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Rate limit remaining",
      "description": "Requests remaining in the current window."
    }
  },
  "#/components/headers/X-RateLimit-Reset": {
    "description": "ISO 8601 timestamp when the current rate-limit window resets.",
    "schema": {
      "type": "string",
      "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))$",
      "title": "Rate limit reset",
      "description": "ISO 8601 timestamp when the current rate-limit window resets."
    }
  },
  "#/components/schemas/V2CreateTableImportResponse": {
    "type": "object",
    "properties": {
      "data": {
        "description": "Response data.",
        "$ref": "#/components/schemas/V2CreateTableImportData"
      }
    },
    "required": [
      "data"
    ],
    "additionalProperties": false,
    "title": "Create table import response",
    "description": "The import session and upload instructions when transfer is required."
  },
  "#/components/schemas/V2CreateTableImportData": {
    "anyOf": [
      {
        "type": "object",
        "properties": {
          "session": {
            "description": "Created upload-backed import session.",
            "$ref": "#/components/schemas/V2UploadBackedTableImport"
          },
          "uploadToken": {
            "type": "string",
            "minLength": 1,
            "description": "Signed token for upload control requests."
          },
          "transfer": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/V2PutUploadTransfer"
              },
              {
                "$ref": "#/components/schemas/V2MultipartUploadTransfer"
              }
            ],
            "description": "Signed CSV upload instructions."
          }
        },
        "required": [
          "session",
          "uploadToken",
          "transfer"
        ],
        "additionalProperties": false
      },
      {
        "type": "object",
        "properties": {
          "session": {
            "description": "Created workspace-file import session.",
            "$ref": "#/components/schemas/V2WorkspaceFileTableImport"
          },
          "uploadToken": {
            "type": "null",
            "description": "Always null; a workspace-file import has no upload to authorize."
          },
          "transfer": {
            "type": "null",
            "description": "Always null; a workspace-file import has no bytes to transfer."
          }
        },
        "required": [
          "session",
          "uploadToken",
          "transfer"
        ],
        "additionalProperties": false
      }
    ],
    "title": "Create table import data",
    "description": "Response data."
  },
  "#/components/schemas/V2UploadBackedTableImport": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Unique table-import identifier."
      },
      "workspaceId": {
        "type": "string",
        "description": "Workspace that owns the import."
      },
      "status": {
        "type": "string",
        "enum": [
          "uploading",
          "processing",
          "completed",
          "failed",
          "canceled",
          "expired"
        ],
        "description": "Current import lifecycle state."
      },
      "source": {
        "description": "Uploaded CSV source for this import.",
        "$ref": "#/components/schemas/V2TableUploadImportSource"
      },
      "target": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "new",
                "description": "Create-new-table target discriminator."
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
                "description": "Name of the table to create."
              },
              "folderPath": {
                "$ref": "#/components/schemas/FolderPathInput"
              }
            },
            "required": [
              "type",
              "name"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "existing",
                "description": "Existing-table target discriminator."
              },
              "tableId": {
                "type": "string",
                "minLength": 1,
                "description": "Existing target table identifier."
              },
              "mode": {
                "type": "string",
                "enum": [
                  "append",
                  "replace"
                ],
                "description": "Whether to append rows or replace existing rows."
              }
            },
            "required": [
              "type",
              "tableId",
              "mode"
            ],
            "additionalProperties": false
          }
        ],
        "description": "New or existing table import target."
      },
      "tableId": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Resulting or target table identifier."
      },
      "rowsProcessed": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Rows processed so far."
      },
      "rowsRejected": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Minimum number of source records dropped by parser failures. One failure can discard multiple records, such as an unterminated quote consuming the rest of the file. A non-zero value means partial import even with `completed` status; zero does not guarantee no loss."
      },
      "cellsRejected": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Non-empty cell values the target column type could not represent. Their rows were imported with the cell left blank."
      },
      "rejectedSamples": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/V2TableImportRejectedSample"
        },
        "description": "Bounded sample of the dropped records, for locating them in the source file."
      },
      "error": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Terminal failure reason, or null."
      },
      "createdAt": {
        "type": "string",
        "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))$",
        "description": "ISO 8601 creation timestamp."
      },
      "updatedAt": {
        "type": "string",
        "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))$",
        "description": "ISO 8601 last-update timestamp."
      },
      "completedAt": {
        "anyOf": [
          {
            "type": "string",
            "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))$"
          },
          {
            "type": "null"
          }
        ],
        "description": "ISO 8601 completion timestamp, or null."
      }
    },
    "required": [
      "id",
      "workspaceId",
      "status",
      "source",
      "target",
      "tableId",
      "rowsProcessed",
      "rowsRejected",
      "cellsRejected",
      "rejectedSamples",
      "error",
      "createdAt",
      "updatedAt",
      "completedAt"
    ],
    "additionalProperties": false,
    "title": "Upload-backed table import",
    "description": "Created upload-backed import session."
  },
  "#/components/schemas/V2TableImportRejectedSample": {
    "type": "object",
    "properties": {
      "code": {
        "type": "string",
        "description": "CSV parser error code, e.g. CSV_QUOTE_NOT_CLOSED."
      },
      "line": {
        "anyOf": [
          {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          {
            "type": "null"
          }
        ],
        "description": "1-based source line the parser had reached when it gave up, or null."
      },
      "message": {
        "type": "string",
        "description": "Parser message for the dropped record."
      }
    },
    "required": [
      "code",
      "line",
      "message"
    ],
    "additionalProperties": false,
    "title": "Rejected import record",
    "description": "One source record a table import could not read."
  },
  "#/components/schemas/V2PutUploadTransfer": {
    "type": "object",
    "properties": {
      "method": {
        "type": "string",
        "const": "put",
        "description": "Upload strategy discriminator."
      },
      "url": {
        "type": "string",
        "format": "uri",
        "description": "Signed URL to which the file bytes are uploaded. Upload bytes with `PUT` and exactly the supplied headers; never construct or modify the signed URL. Treat any `2xx` as success. Sim-hosted URLs return an empty `204` and v2 JSON errors. Object-storage URLs may return `200` or `201` and provider-specific errors, often XML."
      },
      "headers": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "string"
        },
        "description": "Headers that must be included with the upload request."
      },
      "expiresAt": {
        "type": "string",
        "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))$",
        "description": "ISO 8601 expiration time for this signed URL. This is the URL's own expiry and is normally earlier than the upload session's expiresAt: the session stays open for later part, status, completion, and abort requests, but the bytes must be uploaded before this time. Once it passes, the storage provider rejects the upload and a new upload session must be created."
      }
    },
    "required": [
      "method",
      "url",
      "headers",
      "expiresAt"
    ],
    "additionalProperties": false,
    "title": "Direct upload transfer",
    "description": "Instructions for uploading bytes to one signed URL."
  },
  "#/components/schemas/V2MultipartUploadTransfer": {
    "type": "object",
    "properties": {
      "method": {
        "type": "string",
        "const": "multipart",
        "description": "Upload strategy discriminator."
      },
      "partSize": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991,
        "description": "Required size of each non-final part in bytes."
      },
      "partCount": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 640,
        "description": "Total number of upload parts."
      }
    },
    "required": [
      "method",
      "partSize",
      "partCount"
    ],
    "additionalProperties": false,
    "title": "Multipart upload transfer",
    "description": "Instructions for splitting bytes into a multipart upload."
  },
  "#/components/schemas/V2WorkspaceFileTableImport": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "Unique table-import identifier."
      },
      "workspaceId": {
        "type": "string",
        "description": "Workspace that owns the import."
      },
      "status": {
        "type": "string",
        "enum": [
          "uploading",
          "processing",
          "completed",
          "failed",
          "canceled",
          "expired"
        ],
        "description": "Current import lifecycle state."
      },
      "source": {
        "description": "Workspace-file CSV source for this import.",
        "$ref": "#/components/schemas/V2TableWorkspaceFileImportSource"
      },
      "target": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "new",
                "description": "Create-new-table target discriminator."
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 128,
                "pattern": "^[A-Za-z_][A-Za-z0-9_]*$",
                "description": "Name of the table to create."
              },
              "folderPath": {
                "$ref": "#/components/schemas/FolderPathInput"
              }
            },
            "required": [
              "type",
              "name"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "existing",
                "description": "Existing-table target discriminator."
              },
              "tableId": {
                "type": "string",
                "minLength": 1,
                "description": "Existing target table identifier."
              },
              "mode": {
                "type": "string",
                "enum": [
                  "append",
                  "replace"
                ],
                "description": "Whether to append rows or replace existing rows."
              }
            },
            "required": [
              "type",
              "tableId",
              "mode"
            ],
            "additionalProperties": false
          }
        ],
        "description": "New or existing table import target."
      },
      "tableId": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Resulting or target table identifier."
      },
      "rowsProcessed": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Rows processed so far."
      },
      "rowsRejected": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Minimum number of source records dropped by parser failures. One failure can discard multiple records, such as an unterminated quote consuming the rest of the file. A non-zero value means partial import even with `completed` status; zero does not guarantee no loss."
      },
      "cellsRejected": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Non-empty cell values the target column type could not represent. Their rows were imported with the cell left blank."
      },
      "rejectedSamples": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/V2TableImportRejectedSample"
        },
        "description": "Bounded sample of the dropped records, for locating them in the source file."
      },
      "error": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "null"
          }
        ],
        "description": "Terminal failure reason, or null."
      },
      "createdAt": {
        "type": "string",
        "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))$",
        "description": "ISO 8601 creation timestamp."
      },
      "updatedAt": {
        "type": "string",
        "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))$",
        "description": "ISO 8601 last-update timestamp."
      },
      "completedAt": {
        "anyOf": [
          {
            "type": "string",
            "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))$"
          },
          {
            "type": "null"
          }
        ],
        "description": "ISO 8601 completion timestamp, or null."
      }
    },
    "required": [
      "id",
      "workspaceId",
      "status",
      "source",
      "target",
      "tableId",
      "rowsProcessed",
      "rowsRejected",
      "cellsRejected",
      "rejectedSamples",
      "error",
      "createdAt",
      "updatedAt",
      "completedAt"
    ],
    "additionalProperties": false,
    "title": "Workspace-file table import",
    "description": "Created workspace-file import session."
  },
  "#/components/responses/BadRequest": {
    "description": "The request is invalid. This includes a query parameter sent with no value (`?limit=`, `?search=`), which is rejected rather than read as zero, empty, or the parameter default — omit the parameter instead.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "BAD_REQUEST",
            "message": "Invalid request"
          }
        }
      }
    }
  },
  "#/components/schemas/V2Error": {
    "type": "object",
    "properties": {
      "error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code."
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation of the error."
          },
          "details": {
            "description": "Structured error context whose keys depend on the error. Actionable `403` responses use the `V2ActionableForbiddenDetails` shape; validation failures may return issue arrays instead.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/V2ActionableForbiddenDetails"
              },
              {
                "description": "Other structured context defined by the specific error."
              }
            ]
          }
        },
        "required": [
          "code",
          "message"
        ],
        "additionalProperties": false,
        "description": "Canonical error details."
      }
    },
    "required": [
      "error"
    ],
    "additionalProperties": false,
    "title": "v2 error response",
    "description": "Canonical error envelope returned by the public v2 API.",
    "examples": [
      {
        "error": {
          "code": "BAD_REQUEST",
          "message": "The request is invalid."
        }
      }
    ]
  },
  "#/components/schemas/V2ActionableForbiddenDetails": {
    "type": "object",
    "properties": {
      "code": {
        "$ref": "#/components/schemas/V2ForbiddenDetailCode"
      }
    },
    "required": [
      "code"
    ],
    "additionalProperties": {
      "description": "Additional context for this refusal."
    },
    "title": "Actionable forbidden details",
    "description": "Machine-readable cause and optional context for an actionable `403` response."
  },
  "#/components/schemas/V2ForbiddenDetailCode": {
    "type": "string",
    "enum": [
      "INSUFFICIENT_WORKSPACE_ROLE",
      "PERSONAL_API_KEYS_DISABLED",
      "WORKSPACE_KEY_OPERATION_NOT_PERMITTED",
      "PRINCIPAL_KIND_NOT_PERMITTED",
      "ORGANIZATION_MEMBERSHIP_REQUIRED",
      "ORGANIZATION_ADMIN_REQUIRED",
      "ENTERPRISE_PLAN_REQUIRED",
      "SSO_DISABLED",
      "SSO_DOMAIN_NOT_VERIFIED",
      "SSO_PROVIDER_LIMIT_REACHED",
      "ORGANIZATION_PLAN_REQUIRED",
      "AUDIT_LOGS_DISABLED",
      "ACCESS_REQUESTS_DISABLED",
      "ACCESS_REQUEST_ORGANIZATION_REQUIRED",
      "SKILL_EDITOR_ACCESS_REQUIRED",
      "SECRET_ADMIN_ACCESS_REQUIRED",
      "WORKSPACE_RESOURCE_LIMIT_REACHED",
      "PUBLIC_SHARING_NOT_ALLOWED",
      "CREDENTIAL_ADMIN_ACCESS_REQUIRED",
      "MCP_SERVER_URL_NOT_ALLOWED",
      "WORKSPACE_PLAN_CAPABILITY_REQUIRED",
      "CHAT_AUTH_MODE_NOT_PERMITTED",
      "CONNECTOR_MANAGED_RESOURCE_READ_ONLY",
      "PERMISSION_GROUP_CAPABILITY_BLOCKED",
      "INTEGRATION_NOT_ALLOWED",
      "INSUFFICIENT_SCOPE",
      "SCIM_MANAGED_MEMBERSHIP"
    ],
    "title": "Forbidden detail code",
    "description": "Stable cause code for an actionable `403` response."
  },
  "#/components/responses/Unauthorized": {
    "description": "The API credential is missing or invalid.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "UNAUTHORIZED",
            "message": "Authentication required"
          }
        }
      }
    }
  },
  "#/components/responses/Forbidden": {
    "description": "The caller lacks the rights this operation requires. When the cause is one a caller can act on, `error.details.code` names it. A resource in a workspace the caller cannot reach at all answers `404` instead, so absence and denial are indistinguishable.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "FORBIDDEN",
            "message": "Insufficient workspace permissions",
            "details": {
              "code": "INSUFFICIENT_WORKSPACE_ROLE"
            }
          }
        }
      }
    }
  },
  "#/components/responses/NotFound": {
    "description": "The requested resource was not found.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "NOT_FOUND",
            "message": "Not found"
          }
        }
      }
    }
  },
  "#/components/responses/Conflict": {
    "description": "The request conflicts with current resource state.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "CONFLICT",
            "message": "The request conflicts with current table state"
          }
        }
      }
    }
  },
  "#/components/responses/PayloadTooLarge": {
    "description": "The request, or a resource collection it must materialize, exceeds the allowed size: an oversized request body, a generated artifact past the download ceiling, or a workspace folder tree too large to load in full.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "PAYLOAD_TOO_LARGE",
            "message": "Request body is too large"
          }
        }
      }
    }
  },
  "#/components/responses/UnsupportedMediaType": {
    "description": "The request uses an unsupported media type.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "UNSUPPORTED_MEDIA_TYPE",
            "message": "Request body must be sent as application/json"
          }
        }
      }
    }
  },
  "#/components/responses/Locked": {
    "description": "The resource is temporarily locked or unavailable; retry the request.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "LOCKED",
            "message": "A table lock prevents this operation.",
            "details": {
              "lock": "insert"
            }
          }
        }
      }
    }
  },
  "#/components/responses/RateLimited": {
    "description": "The caller exceeded the request rate limit.",
    "headers": {
      "Retry-After": {
        "$ref": "#/components/headers/Retry-After"
      }
    },
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "RATE_LIMITED",
            "message": "API rate limit exceeded",
            "details": {
              "retryAfter": "2026-01-01T00:00:30.000Z"
            }
          }
        }
      }
    }
  },
  "#/components/headers/Retry-After": {
    "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset.",
    "schema": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "title": "Retry after",
      "description": "Seconds to wait before retrying, sent on `429` and `503`. Add jitter rather than retrying at exactly this offset."
    }
  },
  "#/components/responses/InternalError": {
    "description": "An unexpected server error occurred.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "INTERNAL_ERROR",
            "message": "Internal server error"
          }
        }
      }
    }
  },
  "#/components/responses/ServiceUnavailable": {
    "description": "A required service is temporarily unavailable. When present, `Retry-After` gives the minimum seconds to wait; add jitter before retrying. Check operation-specific guidance before repeating a change after an uncertain response.",
    "headers": {
      "Retry-After": {
        "$ref": "#/components/headers/Retry-After"
      }
    },
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/V2Error"
        },
        "example": {
          "error": {
            "code": "SERVICE_UNAVAILABLE",
            "message": "Service temporarily unavailable"
          }
        }
      }
    }
  }
}

```

[Download OpenAPI specification](/openapi.json)

Source: `openapi-v2-tables.json`, operation `createTableImport`.