API primitives
Base URL & Auth
- Hosted (Showdown tier): base URL
https://gimmelowdown.com, endpoints under /api/v1. Get a key at gimmelowdown.com/dashboard/api_keys.
- Self-hosted appliance: base URL is your own appliance, endpoints under
/v1 (same shapes, plus admin-only operations).
- Auth: Include the header
Authorization: Bearer <api_key> or use our clients.
- Roles: globally permissioned admin vs single customer scoped keys. On the hosted tier every key is scoped to its own customer slice.
- Identity Check:
GET /v1/whoami (appliance) · Health Check: GET /v1/health
Hosted endpoint map (Showdown)
- Ingest:
POST /api/v1/media - up to 32 base64 items per call, or a public Hugging Face dataset as a background job.
curl https://gimmelowdown.com/api/v1/media -H "Authorization: Bearer $LOWDOWN_API_KEY" -H "Content-Type: application/json" -d '{"media": [{"data": "<base64>", "filename": "x.png"}]}'
curl https://gimmelowdown.com/api/v1/media -H "Authorization: Bearer $LOWDOWN_API_KEY" -H "Content-Type: application/json" -d '{"hf_dataset": "jxie/flickr8k", "hf_split": "train"}'
- Embeddings:
POST /api/v1/embeddings - raw vectors; target_res max 256, batches of 32.
curl https://gimmelowdown.com/api/v1/embeddings -H "Authorization: Bearer $LOWDOWN_API_KEY" -H "Content-Type: application/json" -d '{"input": "a red dress on a runway"}'
- Search:
POST /api/v1/search - text or image, plus k, min_score.
curl https://gimmelowdown.com/api/v1/search -H "Authorization: Bearer $LOWDOWN_API_KEY" -H "Content-Type: application/json" -d '{"text": "a red dress on a runway", "k": 10}'
- SQL console:
POST /api/v1/query - one read-only SELECT over your slice; see the SQL rules (1000-row cap, 15s timeout).
curl https://gimmelowdown.com/api/v1/query -H "Authorization: Bearer $LOWDOWN_API_KEY" -H "Content-Type: application/json" -d '{"sql": "SELECT id, external_ref FROM as_blobs ORDER BY created_at DESC", "row_limit": 200}'
- Duplicates:
POST /api/v1/duplicates - near-duplicate clusters at a cosine threshold (default 0.92).
curl https://gimmelowdown.com/api/v1/duplicates -H "Authorization: Bearer $LOWDOWN_API_KEY" -H "Content-Type: application/json" -d '{"threshold": 0.92}'
- Corpus:
GET /api/v1/corpus - per-kind counts and top tags for your slice.
- Jobs:
GET /api/v1/jobs/{id} · POST /api/v1/jobs/{id}/cancel - ingest job progress (only your jobs are visible).
- Datasets:
GET /api/v1/datasets · POST /api/v1/datasets ({"name": "...", "blob_ids": [...]}) · GET /api/v1/datasets/{id} · POST /api/v1/datasets/{id}/items · DELETE /api/v1/datasets/{id}/items · DELETE /api/v1/datasets/{id}.
- Exports:
POST /api/v1/exports ({"format": "ndjson"} with vectors, or "parquet" metadata-only; optional tag/dataset_id) · GET /api/v1/exports lists files with time-limited download URLs.
- Wipe:
DELETE /api/v1/data - deletes everything you ingested; keys, usage, account, and billing are untouched.
Appliance endpoint map
- Ingest:
POST /v1/media · GET /v1/media/formats · GET /v1/jobs/{job_id} · POST /v1/jobs/{job_id}/cancel
- Read:
GET /v1/media/{blob_id} · /bytes · /frames · /transcript
- Search:
POST /v1/search - text or image
- Duplicates:
GET /v1/duplicates/suggested-threshold · POST /v1/duplicates
- SQL console:
POST /v1/query
- Keys:
POST /v1/keys · GET /v1/keys · POST /v1/keys/{key_id}/revoke
- Export / Import:
POST /v1/export · POST /v1/import
- Maintenance:
POST /v1/customers/reassign-bulk · GET /v1/corpus
Conventions
- Async by default. Ingest supports one or many items at will.
- Errors: 401 missing/bad key · 403 role/scope violation, free tier exhausted, or asset cap reached · 400 bad query/SQL · 404 unknown blob/job (or another customer's resource) · 413 asset over 25MB · 422 validation · 429 rate limited · 504 SQL timeout
- Hosted rate limits: 200 requests/minute per key on embeddings; 600/minute per IP across the API.
- OpenAPI spec is live here:
GET /openapi.json which you can interact with for more documentation or to generate your own clients.
See It Working
