Skip to main content
POST
/
v1
/
tables
const table = await client.tables.create({
  schema_id: "schema_abc123",
  name: "Q1 Product Catalog",
  file_ids: ["file_xyz789"],
  webhook_url: "https://your-server.com/webhooks",
});

console.log(table.id);     // "tbl_..."
console.log(table.status); // "processing"

{
  "id": "tbl_abc123",
  "name": "Q1 Product Catalog",
  "schema_id": "schema_xyz789",
  "status": "processing",
  "progress": 0,
  "total_rows": 0,
  "source_type": "files",
  "additional_context": null,
  "enhancement_context": null,
  "error_message": null,
  "files": [
    { "name": "catalog.pdf", "path": "company_123/file_xyz/catalog.pdf", "size": 1048576 }
  ],
  "created_at": "2025-03-10T14:30:00.000Z",
  "updated_at": "2025-03-10T14:30:00.000Z"
}

​
Request body

​
schema_id
string
required
The ID of the schema to use for extraction.
​
name
string
required
A name for the table.
​
file_ids
string[]
Array of file IDs (from the Files API) to extract data from. Provide exactly one of file_ids, file_urls, or source_text.
​
file_urls
string[]
Array of publicly accessible URLs to extract data from.
​
source_text
string
Raw text content to extract data from.
​
additional_context
string
Extra context to guide the extraction process.
​
enhancement_context
string
Context for AI enhancement of extracted data.
​
webhook_url
string
URL to receive webhook notifications when processing completes.

​
Response

Returns the created table object with status processing.
​
id
string
Unique table identifier.
​
name
string
Table name.
​
schema_id
string
Schema used for extraction.
​
status
string
Always processing for a new table.
​
progress
integer
Extraction progress (0-100).
​
total_rows
integer
Number of rows extracted so far (0 initially).
​
source_type
string
files or text.
​
additional_context
string | null
Extraction context.
​
enhancement_context
string | null
Enhancement context.
​
error_message
string | null
Error message if processing failed.
​
files
array
Uploaded file metadata.
​
created_at
string
ISO 8601 timestamp.
​
updated_at
string
ISO 8601 timestamp.
const table = await client.tables.create({
  schema_id: "schema_abc123",
  name: "Q1 Product Catalog",
  file_ids: ["file_xyz789"],
  webhook_url: "https://your-server.com/webhooks",
});

console.log(table.id);     // "tbl_..."
console.log(table.status); // "processing"

{
  "id": "tbl_abc123",
  "name": "Q1 Product Catalog",
  "schema_id": "schema_xyz789",
  "status": "processing",
  "progress": 0,
  "total_rows": 0,
  "source_type": "files",
  "additional_context": null,
  "enhancement_context": null,
  "error_message": null,
  "files": [
    { "name": "catalog.pdf", "path": "company_123/file_xyz/catalog.pdf", "size": 1048576 }
  ],
  "created_at": "2025-03-10T14:30:00.000Z",
  "updated_at": "2025-03-10T14:30:00.000Z"
}

​
Waiting for completion

Tables are processed asynchronously. Use the SDK’s built-in polling helper or configure a webhook. 
const completed = await client.tables.waitForCompletion(table.id, {
  intervalMs: 3000,
  timeoutMs: 300000,
});

console.log(completed.status);     // "completed"
console.log(completed.total_rows); // 42