REST API

The REST API provides a lightweight HTTP interface for querying Altertable. It's designed for:

• Quick queries from command-line tools
• Applications that prefer HTTP over database protocols

This interface is ideal when you need simplicity over raw performance, or when working in environments where database protocol connections are restricted.

Authentication

Authentication uses HTTP Basic Auth encoded as a Bearer token. Create the token by base64-encoding your credentials in the format username:password:

# Generate your token
echo -n "your_username:your_password" | base64

Include the token in the Authorization header for all requests:

Authorization: Bearer <ALTERTABLE_BASIC_AUTH_TOKEN>

Examples

Query

Execute SQL queries and retrieve results in streaming JSONL format.

Request:

curl https://api.altertable.ai/query \
  -H "Authorization: Bearer $ALTERTABLE_BASIC_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statement": "SELECT ..."}'

Response: Returns JSONL (JSON Lines) format:

• First line: Query metadata
• Second line: Column names and types
• Remaining lines: Result rows, one JSON object per line

Upload

Upload data files to create or update tables. Supports CSV, JSON, and Parquet formats.

Request:

curl https://api.altertable.ai/upload \
  -H "Authorization: Bearer $ALTERTABLE_BASIC_AUTH_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @data.csv \
  "?catalog=my_catalog&schema=public&table=users&format=csv&mode=create"

Query Parameters:

• catalog, schema, table (required): Target location
• format (required): csv, json, or parquet
• mode (required): create, append, upsert, or overwrite
• primary_key (optional): Required for upsert mode

Response: Returns 200 OK on successful upload. Supports files up to 100 GB.

For detailed API reference including request/response formats, examples, and upload modes, see the Lakehouse API Reference.