API Reference — Embedding Core

Authentication

The API uses two separate auth schemes depending on the endpoint:

API Key (Bearer token) — used for programmatic access to /v1/ingest and /v1/search. Found in your workspace console after signing in.

JWT Session Token — used for workspace management endpoints (/v1/workspace/*, /v1/admin/*). Obtained from POST /v1/auth/google.

GET /health

Health check endpoint. Returns service status. No authentication required.

curl https://api.embeddingcore.io/health

{"status": "ok", "service": "level1-embedding-core", "version": "1.0.0"}

POST /v1/ingest

🔑 Requires API Key

Fetches a remote document, parses text/tables, splits into chunks, embeds using your BYOK model, and stores vectors in your Qdrant collection.

Parameter	Type	Description
source_url	string	URL of the document to ingest (PDF, HTML, or plain text)
file_type	string	`pdf` \| `html` \| `txt` \| `csv` \| `json`
collection_name	string	Name of the Qdrant collection to store vectors. Created if not exists. Default: `default_collection`
metadata	object	Optional key-value metadata stored alongside each vector chunk payload

curl -X POST https://api.embeddingcore.io/v1/ingest \
  -H "Authorization: Bearer sk-lvl1-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://sec.gov/q3-2025.pdf",
    "file_type": "pdf",
    "collection_name": "q3_reports",
    "metadata": {"company": "AAPL", "quarter": "Q3-2025"}
  }'

import requests

resp = requests.post(
    "https://api.embeddingcore.io/v1/ingest",
    headers={"Authorization": "Bearer sk-lvl1-your-api-key"},
    json={
        "source_url": "https://sec.gov/q3-2025.pdf",
        "file_type": "pdf",
        "collection_name": "q3_reports",
        "metadata": {"company": "AAPL", "quarter": "Q3-2025"},
    }
)
print(resp.json())

{
  "status": "success",
  "doc_id": "a1b2c3d4-e5f6-...",
  "chunks_processed": 142,
  "collection_name": "q3_reports",
  "provider_used": "huggingface"
}

POST /v1/search

🔑 Requires API Key

Embeds your query using your BYOK model and returns semantically similar chunks ranked by cosine similarity.

Parameter	Type	Description
query	string	Natural language search query
collection_name	string	Collection to search. Default: `default_collection`
limit	integer	Max results to return (1–100). Default: 5

curl -X POST https://api.embeddingcore.io/v1/search \
  -H "Authorization: Bearer sk-lvl1-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "revenue growth projections for Q3",
    "collection_name": "q3_reports",
    "limit": 5
  }'

resp = requests.post(
    "https://api.embeddingcore.io/v1/search",
    headers={"Authorization": "Bearer sk-lvl1-your-api-key"},
    json={"query": "revenue growth projections", "collection_name": "q3_reports", "limit": 5}
)
for result in resp.json()["results"]:
    print(f"Score: {result['score']:.4f} — {result['payload']['text'][:100]}")

{
  "query": "revenue growth projections for Q3",
  "collection_name": "q3_reports",
  "total_returned": 3,
  "results": [
    {
      "id": "uuid-here",
      "score": 0.9241,
      "payload": {
        "doc_id": "a1b2...",
        "text": "Total revenue for Q3 2025 reached $94.9B, a 6% year-over-year increase...",
        "company": "AAPL",
        "quarter": "Q3-2025"
      }
    }
  ]
}

POST /v1/auth/google

Exchanges a Google Firebase ID Token for a JWT session token and workspace credentials. Creates a new user + workspace on first login.

POST /v1/auth/google
Authorization: Bearer <google_firebase_id_token>

// First login (user created)
{
  "status": "created",
  "session_token": "eyJhbGciOiJIUzI1NiJ9...",
  "is_admin": false,
  "workspace_id": "wk_abc123def",
  "api_key": "sk-lvl1-xxxx",   // shown ONCE on creation
  "subscription_tier": "free"
}

// Returning user
{
  "status": "existing",
  "session_token": "eyJhbGciOiJIUzI1NiJ9...",
  "is_admin": false,
  "workspace_id": "wk_abc123def",
  "subscription_tier": "free"
}

GET /v1/auth/me

🔐 Requires JWT Session Token

Returns the authenticated user's profile and workspace statistics.

curl https://api.embeddingcore.io/v1/auth/me \
  -H "Authorization: Bearer <session_token>"

PUT /v1/workspace/config

🔐 Requires JWT Session Token

Updates your BYOK (Bring Your Own Key) configuration — embedding provider tokens and Qdrant connection details.

Parameter	Type	Description
huggingface_token	string?	HuggingFace API token (starts with `hf_`)
openai_api_key	string?	OpenAI API key (starts with `sk-`)
qdrant_url	string?	Qdrant Cloud URL or self-hosted URL. Use `memory` for in-process (testing only)
qdrant_api_key	string?	Qdrant Cloud API key (if using Qdrant Cloud)
vector_db_provider	string?	`qdrant` \| `memory`

GET /v1/admin/analytics

👑 Requires Admin JWT

Returns platform-wide analytics: total users/workspaces, API call volumes, tier distribution, 7-day activity breakdown, and top workspaces by usage.

GET /v1/admin/users

👑 Requires Admin JWT

Returns a paginated list of all registered users with their workspace info and usage stats.

Query Param	Type	Description
skip	integer	Pagination offset. Default: 0
limit	integer	Max results. Default: 50

POST /v1/billing/checkout

Creates a Stripe checkout session for upgrading to the Standard or Enterprise plan.

Query Param	Type	Description
workspace_id	string	Your workspace ID
plan	string	`pro` (Standard tier)