Lakehouse API

HTTP API

Use the Altertable HTTP API to run SQL, estimate query scans, upload files, upsert by primary key, append event-style JSON records, validate SQL, and request autocomplete suggestions without opening a database protocol connection.

If you are working from a terminal, the CLI wraps the query, upload, upsert, and append endpoints with profile-based authentication.

API endpoint

Hostname	Port
`api.altertable.ai`	443 (HTTPS)

Authentication

Authenticate every request with HTTP Basic Auth. Base64-encode your credentials in the format lakehouse_username:lakehouse_password:

echo -n "YOUR_LAKEHOUSE_USERNAME:YOUR_LAKEHOUSE_PASSWORD" | base64

Then send the encoded value in the Authorization header:


Authorization: Basic <ALTERTABLE_BASIC_AUTH_TOKEN>

The Python and Ruby SDKs handle this for you when you pass your lakehouse username and lakehouse password during client initialization.

POST/query

Execute SQL and stream the result as JSON Lines.

Authentication: HTTP Basic Auth
Permission: Query access to referenced catalogs

Parameters

statementstring· body · Required: The SQL statement to execute.
catalogstring· body · Optional: Catalog to use for unqualified table names.
schemastring· body · Optional: Schema to use for unqualified table names.
session_idstring· body · Optional: Reuse an existing query session.
timezonestring· body · Optional: IANA timezone for the session. Defaults to UTC.
compute_sizeXS | S | M | L | XL | AUTO· body · Optional: Choose a compute tier or infer one from the SQL. AUTO cannot be combined with session_id.
dialectstring· body · Optional: Source SQL dialect to transpile to DuckDB before execution.
limitinteger· body · Optional: Limit the number of returned rows.
offsetinteger· body · Optional: Skip this many rows before returning results.
formatdefault | csv | jsonl | parquet· body · Optional: Choose the streamed output format. Defaults to the Altertable metadata, schema, and row stream.
query_idUUID· body · Optional: Assign a query identifier instead of generating one.

Response format

The default response uses JSONL (JSON Lines) for efficient streaming:

First line: query metadata, including the session, query, and Worker identifiers
Second line: an array of column names
Remaining lines: one JSON array per result row, in column order

Set format to csv, jsonl, or parquet when you need a standard data stream without the Altertable metadata and schema lines. The jsonl format emits one JSON object per row.

POST/upload

Upload a CSV, JSON, or Parquet file to create, append to, or replace a table.

Authentication: HTTP Basic Auth
Permission: Write access to the destination catalog

Parameters

catalogstring· query · Required: Catalog to ingest data into.
schemastring· query · Required: Schema within the catalog.
tablestring· query · Required: Table to create or insert into.
modecreate | append | overwrite· query · Required: How the uploaded data changes the destination table.

Request body

Binary file data. The server infers CSV, JSON, or Parquet from the Content-Type header when present, otherwise from magic bytes in the payload:

CSV: Comma-separated values with header row
JSON: JSON array of objects or JSONL (one JSON object per line)
Parquet: Apache Parquet columnar format (most efficient)

Ingestion modes

create: Create a new table with the uploaded data (fails if the table already exists)
append: Append the uploaded data to an existing table (preserves existing data)
overwrite: Drop the existing table and recreate it with the uploaded data (replaces all data)

Request bodies can contain up to 100 GB.

Example: Upload CSV file


curl "https://api.altertable.ai/upload?catalog=my_catalog&schema=main&table=users&mode=create" \
  -H "Authorization: Basic $ALTERTABLE_BASIC_AUTH_TOKEN" \
  --data-binary @users.csv

Example: Append JSON file


curl "https://api.altertable.ai/upload?catalog=my_catalog&schema=main&table=events&mode=append" \
  -H "Authorization: Basic $ALTERTABLE_BASIC_AUTH_TOKEN" \
  --data-binary @events.json

POST/upsert

Merge uploaded CSV, JSON, or Parquet rows into a table by primary key.

Authentication: HTTP Basic Auth
Permission: Write access to the destination catalog

Parameters

catalogstring· query · Required: Catalog to ingest data into.
schemastring· query · Required: Schema within the catalog.
tablestring· query · Required: Table to merge rows into.
primary_keystring· query · Required: Column used to match and update existing rows.

The request body contains binary CSV, JSON, or Parquet data and can be up to 100 GB. Matching rows are updated and new rows are inserted.

POST/append

Append one JSON object or a batch of objects without managing pipelines or offsets.

Authentication: HTTP Basic Auth
Permission: Write access to the destination catalog

Parameters

catalogstring· query · Required: Catalog to append data to.
schemastring· query · Required: Schema within the catalog.
tablestring· query · Required: Table to append data to.
syncboolean· query · Optional: Wait for processing to finish before returning.

The request body can be one JSON object or an array of objects, up to 32 MB. For larger files, use /upload with mode=append.

Use task_id with GET /tasks/{task_id} to poll asynchronous processing. When sync=true, the response waits until the append task finishes.

The response confirms that Altertable accepted the records for asynchronous processing. Rows that still fail after retries are written to altertable.main.quarantined_appends with the destination catalog, schema, table, error, original payload, and retry count.

Automatic table management

Infer column types from JSON values
Create the table when it does not exist
Add columns when later payloads contain new fields
Make accepted data queryable within seconds

Numbers become BIGINT or DOUBLE, strings become VARCHAR, booleans become BOOLEAN, arrays and objects become JSON, and RFC3339 timestamps become TIMESTAMP.

You can also create the table manually when you need explicit types, constraints, or defaults. Append respects the existing schema and only adds missing columns.

POST/explain

Estimate the files, bytes, and rows a SQL statement will scan without running it.

Authentication: HTTP Basic Auth
Permission: Query access to referenced catalogs

Parameters

statementstring· body · Required: SQL statement to estimate.
catalogstring· body · Optional: Catalog to use for unqualified table names.
schemastring· body · Optional: Schema to use for unqualified table names.
session_idstring· body · Optional: Existing session to use for the estimate.
include_planboolean· body · Optional: Include the raw EXPLAIN plan in the response.

The response reports per-table row estimates and, when available, file and byte estimates after filter pruning. It also returns totals across all scanned tables and connection errors for catalogs that could not be attached.

POST/validate

Check a SQL statement for syntax and semantic issues without executing it.

Authentication: HTTP Basic Auth
Permission: Query access to referenced catalogs

Parameters

statementstring· body · Required: SQL statement to validate.
catalogstring· body · Optional: Catalog to use for validation.
schemastring· body · Optional: Schema to use for validation.
session_idstring· body · Optional: Existing session to use for validation.

POST/autocomplete

Return ranked SQL completions for a partial statement.

Authentication: HTTP Basic Auth
Permission: Query access to referenced catalogs

Parameters

statementstring· body · Required: Partial SQL statement.
catalogstring· body · Optional: Catalog used to scope suggestions.
schemastring· body · Optional: Schema used to scope suggestions.
session_idstring· body · Optional: Existing session used for catalog context.
max_suggestionsinteger· body · Optional: Maximum suggestions to return. Defaults to 20 and cannot exceed 200.

The response includes the original statement, connection errors by catalog when present, and suggestions with their type, score, and replacement start position.

GET/query/{query_id}

Inspect a running or completed query.

Authentication: HTTP Basic Auth
Permission: Access to the query

Parameters

query_idUUID· path · Required: Query identifier returned when execution started.

DELETE/query/{query_id}

Cancel a running query.

Authentication: HTTP Basic Auth
Permission: Access to the query

Parameters

query_idUUID· path · Required: Query identifier to cancel.
session_idstring· query · Required: Session identifier returned when execution started.

GET/tasks/{task_id}

Inspect an asynchronous task returned by the append API.

Authentication: HTTP Basic Auth
Permission: Access to the task

Parameters

task_idUUID· path · Required: Task identifier returned by an asynchronous request.

Task status is pending or completed.