Principio Primitives API

Quick overview

Base URL

https://primitives.byte-genie.com

Interactive API docs are available at /docs and /redoc.

Request model

Every request includes a source object that identifies the profile and connection details for the backend (SQL or object storage).

Source objects

SQL source

profile (required) - profile name for credentials.
engine (default: postgres).
database, project, dataset (optional).
connection_uri (optional DSN).
extras (free-form settings).

Object storage source

profile (required) - profile name for credentials.
provider (default: s3).
bucket, prefix (optional).
project, region, connection_uri (optional).
extras (free-form settings).

Supported endpoints

SQL primitives

POST /sql/query - run a SQL query with optional parameters/limit.
POST /sql/table - fetch rows from a table with optional limit.
POST /sql/tables - list tables in the database.
POST /sql/schema - fetch column metadata for a table.
POST /sql/indexes - list indexes, optionally filtered by table.
POST /sql/index/create - create an index.
POST /sql/index/delete - delete an index.
POST /sql/index/full-text - create a full-text index.
POST /sql/table/create - create a table.
POST /sql/table/alter - alter table schema.
POST /sql/table/delete - delete a table.
POST /sql/table/delete-rows - delete rows by conditions.
POST /sql/table/update-column - update a column by conditions.
POST /sql/table/write - insert or upsert rows.

Object storage primitives

POST /storage/buckets - list available buckets.
POST /storage/objects - list objects in a bucket/prefix.
POST /storage/object/text - read an object as text.
POST /storage/object/bytes - read an object as base64 bytes.
POST /storage/object/download - download an object as raw bytes (no parsing).
POST /storage/object/put_text - write text to an object key.
POST /storage/object/delete - delete an object key.
POST /storage/object/read_file - read a file and return parsed data.
POST /storage/sync_files - sync files from one storage source to another without parsing.

Examples

Run a SQL query

{
  "source": {
    "profile": "prod",
    "engine": "postgres",
    "database": "analytics"
  },
  "query": "SELECT * FROM users WHERE created_at > :since",
  "parameters": {"since": "2024-01-01"},
  "limit": 100
}

Read an object as text

{
  "source": {
    "profile": "prod",
    "provider": "s3",
    "bucket": "app-data"
  },
  "key": "exports/report.csv"
}

All endpoints respond with JSON and include status or payload fields specific to the operation.

Principio Python Primitives API