---
title: "Instantly map any dataset — no schema, no ETL"
method: POST
path: "/v1/map"
tags: ["Data Mapping"]
---

# Instantly map any dataset — no schema, no ETL

`POST /v1/map`

## Request

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

**Connect and understand any dataset instantly.**

Drop in CSV files, JSON records, or table names from multiple sources. Get back a unified schema with every field mapped, explained, and ready to run decisions on.

**What it detects:**
- Matching fields across sources (revenue ↔ sales, qty ↔ quantity)
- Value distributions (lognormal for prices, triangular for ranges)
- Polarity (cost → negative, revenue → positive)
- Join keys between tables (background if slow)
- Derived formulas A×B≈C (background if slow)
- Confidence and plain-English reasoning for every mapping

**Two-speed pipeline:** Phase 1 (schema + column matches) returns in <300ms. Phase 2 (join detection + relation detection) is embedded in the response if it finishes within 200ms, otherwise `deep_analysis_pending: true` is set and results can be retrieved via `GET /v1/map/{map_id}`.

**The data funnel:** Upload → Map → Query → Decide → Optimize

## Request body

- MapRequest: Drop in any data sources. Get back semantic field mappings and a unified schema. No configuration required. The engine auto-detects: - Which fields represent the same concept across sources - Distribution shapes for numeric fields - Polarity (revenue → positive, cost → negative) - Primary/foreign keys for joins - Confidence and reasoning for every mapping
  - `sources` DataSource[], required: Data sources to map (CSV, JSON records, or table name)
    - `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
  - `min_confidence` number: Minimum confidence threshold for mappings (default: 0.5)
  - `include_statistics` boolean: Include value distribution statistics in response

## Response `200`

Successful Response

- MapResponse
  - `map_id` string, required
  - `sources_analyzed` integer, required
  - `total_fields` integer, required
  - `mappings` FieldMapping[], required
    - `source_field` string, required
    - `source` string, required
    - `target_field` string, required
    - `target` string, required
    - `confidence` number, required
    - `reason` string[], required
    - `match_type` string, required
  - `unified_schema` SchemaField[], required
    - `name` string, required
    - `sources` string[], required
    - `distribution` string, nullable
    - `unit` string, nullable
    - `polarity` integer, nullable
    - `sample_values` unknown[]
      - unknown
  - `join_keys` object[], required
  - `derived_relationships` object[], required
  - `simulation_ready` boolean, required
  - `simulation_payload` object, nullable, required
  - `deep_analysis_pending` boolean
  - `latency_ms` number, required

## 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)