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 Basic token. Create the token by base64-encoding your credentials in the format username:password:

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

Include the token in the Authorization header for all requests:

Authorization: Basic <ALTERTABLE_BASIC_AUTH_TOKEN>

Examples

Query

Execute SQL queries and retrieve results in streaming JSONL format.

Request:

1
2
3
4
curl https://api.altertable.ai/query \
  -H "Authorization: Basic $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:

1
2
3
4
5
curl https://api.altertable.ai/upload \
  -H "Authorization: Basic $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.

Append

Append JSON records to a table. The schema is inferred from the payload — the table is created automatically if it doesn't exist, and new fields trigger automatic schema migrations. Records are queued internally and become available for querying within ~5 seconds (eventual consistency). Ideal for logs, events, and other streaming data.

Request:

1
2
3
4
curl -X POST "https://api.altertable.ai/append?catalog=my_catalog&schema=public&table=logs" \
  -H "Authorization: Basic $ALTERTABLE_BASIC_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level": "info", "message": "User logged in", "timestamp": "2024-01-01T00:00:00Z"}'

Query Parameters:

• catalog, schema, table (required): Target location

Request body: A single JSON object or an array of JSON objects.

Response: Returns 200 OK on success.

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