---
title: "Infer and return the structural schema of data sources"
method: POST
path: "/v1/sources/schema"
tags: ["Semantic Query", "Semantic Query"]
---

# Infer and return the structural schema of data sources

`POST /v1/sources/schema`

## Request

- Base URL: `https://api.algenta.ai`
- URL: `https://api.algenta.ai/v1/sources/schema`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

**Call this once when a user connects a data source.**

Returns the full Algenta structural schema: column roles, detected formulas, cardinality, and `query_hints` the LLM should use when calling `POST /v1/query`.

The schema is also embedded as Arrow metadata in the returned Parquet bytes (`parquet_b64`), which the LLM agent can store and reuse — no re-profiling on subsequent queries.

**Flow:**
1. User connects data source
2. Call `POST /v1/sources/schema` — ~1-2s, runs once
3. LLM reads `schema` JSON and `query_hints`
4. User asks questions → LLM produces structured intent → `POST /v1/query` (~200ms, cached)

## Request body

- SchemaRequest
  - `sources` DataSource[]: Data sources to profile. Pass an empty list (or omit) to return schemas for ALL sources registered for this org via POST /v1/sources/register.
    - `name` string, required: Label for this source (e.g., 'sales', 'orders')
    - `dataset_id` string, nullable: Public dataset ID alias for a registered source.
    - `source_id` string, nullable: Registered source ID; fastest path and avoids re-uploading data.
    - `records` object[], nullable: Inline JSON records
    - `csv` string, nullable: Raw CSV text
    - `json_str` string, nullable: Raw JSON array/object text (nested auto-flattened)
    - `url` string, nullable: HTTP URL — format auto-detected
    - `excel_b64` string, nullable: Excel .xlsx file, base64-encoded
    - `parquet_b64` string, nullable: Parquet file, base64-encoded
    - `connection` object, nullable: Connector config dict — see DataSource docstring for all types
    - `table` string, nullable: Legacy field — use connection instead

## Response `200`

Successful Response

- object

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/codna/apis/algenta-api.md) · [All operations](https://skmtc.dev/codna/apis/algenta-api/llms.txt) · [OpenAPI document](https://skmtc.dev/codna/apis/algenta-api/revisions/35d30f84a5df?raw)