API reference

API quickstart

Mint a key, generate your first rows, push them into a database. About five minutes.

Everything below is a real request against the live API. Copy, paste, run.

1. Get an API key

API access is available on Platinum and Enterprise. Sign in, open Settings → API Keys, and create one.

The key is shown once. Copy it immediately: only a SHA-256 hash is stored, so it cannot be recovered or re-displayed. If you lose it, revoke and mint a new one.

export SEEDQL_KEY="sk_live_..."
export SEEDQL_API="https://seedql-production.up.railway.app"

2. Confirm it works

curl -s "$SEEDQL_API/api/auth/me" -H "Authorization: Bearer $SEEDQL_KEY"

{
  "id": "a94ba11c-...",
  "email": "you@example.com",
  "tier": "platinum",
  "role": "admin",
  "display_name": "your-name"
}

A 401 means the key is wrong, revoked, or expired. Those three cases return an identical response on purpose, so an attacker cannot probe which keys exist.

3. Read your target schema

SeedQL never guesses your structure. It introspects the database you point it at and derives table order from the real foreign keys.

curl -s "$SEEDQL_API/api/introspect" \
  -H "Authorization: Bearer $SEEDQL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection": {
      "db_type": "postgresql",
      "connection_string": "postgresql://user:pass@host:5432/mydb",
      "schema_name": "public"
    }
  }'

You get back tables, columns, types, nullability and the foreign keys between them.

4. Generate rows

curl -s "$SEEDQL_API/api/generate" \
  -H "Authorization: Bearer $SEEDQL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection": {
      "db_type": "postgresql",
      "connection_string": "postgresql://user:pass@host:5432/mydb"
    },
    "tables": [
      { "table_name": "users",  "row_count": 500,  "enabled": true },
      { "table_name": "orders", "row_count": 5000, "enabled": true }
    ],
    "seed": 42
  }'

{
  "total_rows": 5500,
  "per_table": { "users": 500, "orders": 5000 },
  "elapsed_seconds": 0.42,
  "seed": 42
}

orders referencing users resolves correctly because parents are generated before children. You do not declare the order; it is computed from the schema.

5. Push into the database

curl -s "$SEEDQL_API/api/generate/push" \
  -H "Authorization: Bearer $SEEDQL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection": { "db_type": "postgresql", "connection_string": "postgresql://..." },
    "tables": [{ "table_name": "users", "row_count": 500, "enabled": true }],
    "truncate_first": false,
    "seed": 42
  }'

{
  "tables_processed": 1,
  "total_rows": 500,
  "requested_rows": 500,
  "per_table": { "users": 500 },
  "pushed_to_db": true,
  "errors": []
}

Read pushed_to_db rather than assuming success from the status code. It is derived from tables actually written, so a run where every row failed a primary-key conflict reports false with the reasons in errors. Compare total_rows against requested_rows to detect partial writes.

Next