HTTP API

Ingest with HTTP API

The HTTP API provides a lightweight interface for ingesting data into Altertable catalogs.

With the HTTP API, you can:

Append event-style JSON records (up to 32 MB per request)
Upload CSV, JSON, and Parquet files via /upload (up to 100 GB per request)
Upsert CSV, JSON, and Parquet files by primary key

For terminal workflows, the CLI wraps these same ingest paths with altertable append, altertable upload, and altertable upsert.

Append

Append is designed for streaming events and operational records without managing ingestion jobs. You can send individual records, but microbatching several records usually gives you much higher throughput. Append records with cURL or SDKs:

cURL

curl -X POST "https://api.altertable.ai/append?catalog=my_catalog&schema=main&table=events" \
  -H "Authorization: Basic $ALTERTABLE_BASIC_AUTH_TOKEN" \
  -d '{"timestamp":"2026-01-01","event":"click","value":42}'

SDKs

import { AltertableLakehouseClient } from '@altertable/lakehouse';

const client = new AltertableLakehouseClient({
  username: 'YOUR_LAKEHOUSE_USERNAME',
  password: 'YOUR_LAKEHOUSE_PASSWORD',
});

await client.append({
  catalog: 'my_catalog',
  schema: 'main',
  table: 'events',
  body: {
    Single: { timestamp: '2026-01-01', event: 'click', value: 42 },
  },
});

Append is eventually consistent. The endpoint returns as soon as the data is acknowledged, and the new rows are queryable in the catalog within a few seconds.

Each request body can be up to 32 MB. For larger file uploads, use /upload with mode=append instead.

If the input data is not compatible with the current table schema, the endpoint returns an error with details about the incompatible field or type.

Append also supports smart migrations:

Input	Behavior
The table does not exist	Altertable infers the schema from the JSON payload and creates the table.
The payload includes a new column	Altertable automatically adds the missing column to the table.

Upload files

/upload uploads CSV, JSON, or Parquet files and supports several ingestion modes via the mode query parameter:

create: Create a new table from the file
append: Append rows to an existing table (no primary_key required)
overwrite: Replace the table with the uploaded data

Use /upload when you want to load a file without matching rows by primary key. The mode parameter is required.

Request bodies can be up to 100 GB, so /upload is the right choice for large file uploads. Use /append for small, event-style JSON payloads.

From the CLI, upload a CSV file with:

altertable upload --catalog my_catalog --schema main --table users --mode create --format csv --file users.csv

Upsert

/upsert updates existing rows and inserts new rows in the same request. Use it when the file has a stable primary key column:

1
2
3
4
5
6
7
8
9
10
11
12
[
  {
    "id": "user_123",
    "email": "[email protected]",
    "plan": "pro"
  },
  {
    "id": "user_456",
    "email": "[email protected]",
    "plan": "team"
  }
]

Upload users.json with the primary_key parameter:

1
2
3
curl "https://api.altertable.ai/upsert?catalog=my_catalog&schema=main&table=users&primary_key=id" \
  -H "Authorization: Basic $ALTERTABLE_BASIC_AUTH_TOKEN" \
  --data-binary @users.json

The same endpoint also accepts Parquet and CSV files. Parquet is usually the best choice for larger batches.

From the CLI, upsert a CSV file by primary key with:

altertable upsert --catalog my_catalog --schema main --table users --primary-key id --format csv --file users.csv

API reference

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

The same reference also covers related query, validation, and task endpoints: