Altertable

REST API

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

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

Quick queries from backend applications or 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.

With the REST API, you can:

Run SQL queries over HTTPS
Stream results as JSONL
Upload CSV, JSON, and Parquet files
Append event-style JSON records
Validate SQL and manage running queries

SDK and CLI quick starts

These clients use the same REST authentication model and endpoint family:

from altertable_lakehouse import Client
from altertable_lakehouse.models import QueryRequest

client = Client(
    username="your_username",
    password="your_password",
)

# Run a SQL query
req = QueryRequest(statement="""
    SELECT
        date_trunc('day', timestamp) AS day,
        COUNT(DISTINCT user_id)      AS dau
    FROM   events
    WHERE  event = 'Event Name'
    AND    timestamp >= NOW() - INTERVAL '30 days'
    GROUP  BY 1
    ORDER  BY 1 DESC
""")

# Accumulate all rows in memory
result = client.query_all(req)
for row in result.rows:
    print(row)

# Append data to a table
client.append(
    catalog="my_catalog",
    schema="my_schema",
    table="users",
    data={"user_id": 1, "plan": "pro"}
)

Authentication

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

echo -n "your_username:your_password" | base64

Include the token in the Authorization header for all requests:

Authorization: Basic <ALTERTABLE_BASIC_AUTH_TOKEN>

SDKs handle authentication automatically when you pass your username and password during initialization.

Endpoint reference

Use the reference page for endpoint details, payload shapes, and full examples: