Public API v1

Public API v1 is the read-only part of the DataForge public API: RMD content, the data model and data marts. Authentication, common conventions and error codes are described on the API page.

1 Public DF API — RMD content (df-api/v1)

Base path: /df-api/v1. Auth: X-Api-Key. All endpoints are read-only and gated by company license (section 5 of the API page). This group covers access to projects, versions, and RMD content (measures, dimensions, facts); the data-model and data-mart endpoints are described in section 9.8. The RMD content endpoints are mounted directly under the version — …/versions/{version_id}/measures, with no intermediate /rmd/ segment.

Common to every endpoint of the group: only projects the key owner can access are visible (section 2.2 of the API page); page and pageSize are not capped on this group (section 3.2 of the API page); format=xlsx answers { "downloadUrl": "<signed URL valid for 15 minutes>" } instead of the JSON body (section 3.5 of the API page).

1.1 List projects

Request

GET /df-api/v1/projects

Parameter	In	Type	Required	Description
page	query	integer	no	Page number, 1-indexed. Default 1
pageSize	query	integer	no	Items per page. Default 20; not capped
format	query	json | xlsx	no	Output format. Default json; xlsx produces a one-sheet workbook Projects

Details

The list is filtered to the projects the key owner can access; inaccessible projects are excluded from the page and from total. The language parameter is not accepted — no field of the response is localized.

Response

200 OK

{
  "projects": [
    { "id": 12, "name": "Sales Analytics", "description": "Production sales warehouse" }
  ],
  "pagination": { "total": 1, "page": 1, "pageSize": 20, "totalPages": 1 }
}

Field	Type	Description
projects[].id	integer	Project identifier
projects[].name	string	Project name
projects[].description	string | null	Project description
pagination	object	total, page, pageSize, totalPages (section 3.2 of the API page)

Errors. Common errors only (section 4 of the API page).

1.2 List versions

Request

GET /df-api/v1/projects/{id}/versions

Parameter	In	Type	Required	Description
id	path	integer	yes	Project identifier
page	query	integer	no	Page number, 1-indexed. Default 1
pageSize	query	integer	no	Items per page. Default 20; not capped
format	query	json | xlsx	no	Output format. Default json; xlsx produces a one-sheet workbook Versions

Details

Soft-deleted versions are not returned. A project the key owner cannot access answers 404 — existence is not disclosed.

Response

200 OK

{
  "versions": [ { "id": 33, "name": "Q4 2025", "is_global": true } ],
  "pagination": { "total": 1, "page": 1, "pageSize": 20, "totalPages": 1 }
}

Field	Type	Description
versions[].id	integer	Version identifier
versions[].name	string	Version name
versions[].is_global	boolean	true for the project's published (global) version
pagination	object	total, page, pageSize, totalPages

Errors. Common errors only (section 4 of the API page).

1.3 Get measures

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/measures

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
language	query	ru | en	no	Language of the select-type labels. Default: Accept-Language, then en
format	query	json | xlsx	no	Output format. Default json
page	query	integer	no	Page number, 1-indexed. Default 1
pageSize	query	integer	no	Items per page. Default 20; not capped

Details

The set of returned keys reflects the RMD column layout of the measures table: every row carries all columns, empty ones as null. Select-type fields (measure_type, display_data_type, status, relevance, …) are returned as localized labels (Base / Calculated, Number, …), not as slugs. Formula fields have measure references substituted from numeric IDs to human-readable names. original_source and original_object are free text from the RMD.

Response

200 OK

{
  "measures": [
    {
      "row_number": 1,
      "group": "Revenue",
      "block": "Sales",
      "measure_name": "Total revenue",
      "measure_description": "Gross revenue across all channels",
      "original_source_type": "Database",
      "original_source": "ERP",
      "original_object": "sales.amount",
      "display_data_type": "Number",
      "measure_type": "Base",
      "restrictions": null,
      "formula": null,
      "report_for_verification": null,
      "comment": null,
      "status": "Active",
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null,
      "variation": null
    }
  ],
  "pagination": { "total": 42, "page": 1, "pageSize": 20, "totalPages": 3 }
}

Field	Type	Description
measures[].row_number	integer	Position of the row in the RMD table
measures[].group, block	string | null	Grouping columns of the RMD
measures[].measure_name	string	Measure name
measures[].measure_description	string | null	Description
measures[].original_source_type, original_source, original_object	string | null	Provenance columns; free text
measures[].display_data_type	string | null	Localized data type label (Number, Text, Date, …)
measures[].measure_type	string	Localized label: Base or Calculated
measures[].restrictions	string | null	Restrictions column
measures[].formula	string | null	Formula of a calculated measure with references rendered as [Name]
measures[].report_for_verification, comment, responsible_for_data, variation	string | null	Free-text columns
measures[].status, relevance, required, visibility	string | null	Localized select labels
pagination	object	total, page, pageSize, totalPages

Errors. Common errors only (section 4 of the API page).

1.4 Get dimensions

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/dimensions

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
language	query	ru | en	no	Language of the select-type labels
format	query	json | xlsx	no	Output format. Default json
page	query	integer	no	Page number, 1-indexed. Default 1
pageSize	query	integer	no	Items per page. Default 20; not capped

Details

Every row carries all columns of the dimensions table of the RMD, empty ones as null; select-type fields (dimension_type, display_data_type, status, …) are returned as localized labels, formula references as human-readable names. source_data_type is derived from connected_source: the API parses the source object (db, schema, table, column) and resolves the column type from the cached schema of the referenced connection. The value is null when the connected source is absent, cannot be resolved to a column, or when no row in the version has a connected_source. connected_source is the source object of section 3.6 of the API page without connection (v1).

Response

200 OK

{
  "dimensions": [
    {
      "row_number": 1,
      "group": "Customer",
      "block": "Profile",
      "dimension_name": "Customer name",
      "dimension_description": "Full customer name",
      "original_source_type": null,
      "original_source": null,
      "original_object": null,
      "dimension_group": "Customers",
      "display_data_type": "Text",
      "source_data_type": "VARCHAR(255)",
      "dimension_type": "Primary",
      "formula": null,
      "connected_source": { "db": "analytics_db", "schema": "public", "table": "dim_customer", "column": "customer_name" },
      "comment": null,
      "value_options": null,
      "status": "Active",
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null
    }
  ],
  "pagination": { "total": 18, "page": 1, "pageSize": 20, "totalPages": 1 }
}

Field	Type	Description
dimensions[].row_number	integer	Position of the row in the RMD table
dimensions[].group, block	string | null	Grouping columns of the RMD
dimensions[].dimension_name, dimension_description	string / string | null	Name and description
dimensions[].original_source_type, original_source, original_object	string | null	Provenance columns; free text
dimensions[].dimension_group	string | null	Name of the dimension group the dimension belongs to
dimensions[].display_data_type	string | null	Localized data type label
dimensions[].source_data_type	string | null	Physical column type resolved from the connection's cached schema
dimensions[].dimension_type	string	Localized label: Primary or Derived
dimensions[].formula	string | null	Formula of a derived dimension
dimensions[].connected_source	object | null	Source object { db, schema, table, column } (section 3.6 of the API page)
dimensions[].comment, responsible_for_data	string | null	Free-text columns
dimensions[].value_options	string | null	Allowed values column
dimensions[].status, relevance, required, visibility	string | null	Localized select labels
pagination	object	total, page, pageSize, totalPages

Errors. Common errors only (section 4 of the API page).

1.5 Get facts

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/facts

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
language	query	ru | en	no	Language of the select-type labels
format	query	json | xlsx	no	Output format. Default json
page	query	integer	no	Page number, 1-indexed. Default 1
pageSize	query	integer	no	Items per page. Default 20; not capped

Details

Every row carries all columns of the facts table of the RMD, empty ones as null; select-type fields are returned as localized labels, formula references as human-readable names. source_data_type is resolved from connected_source through the cached schema of the referenced connection and is null when the connected source is absent or cannot be resolved.

Response

200 OK

{
  "facts": [
    {
      "row_number": 1,
      "group": "Sales",
      "block": "Orders",
      "fact_name": "Order line",
      "fact_description": "An individual line item on a sales order",
      "original_source_type": null,
      "original_source": null,
      "original_object": null,
      "source_data_type": "DECIMAL(18,2)",
      "fact_type": "Primary",
      "formula": null,
      "connected_source": { "db": "analytics_db", "schema": "public", "table": "fact_order_line", "column": "amount" },
      "report_for_verification": null,
      "comment": null,
      "status": null,
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null
    }
  ],
  "pagination": { "total": 6, "page": 1, "pageSize": 20, "totalPages": 1 }
}

Field	Type	Description
facts[].row_number	integer	Position of the row in the RMD table
facts[].group, block	string | null	Grouping columns of the RMD
facts[].fact_name, fact_description	string / string | null	Name and description
facts[].original_source_type, original_source, original_object	string | null	Provenance columns; free text
facts[].source_data_type	string | null	Physical column type resolved from the connection's cached schema
facts[].fact_type	string	Localized label: Primary or Derived
facts[].formula	string | null	Formula of a derived fact
facts[].connected_source	object | null	Source object { db, schema, table, column } (section 3.6 of the API page)
facts[].report_for_verification, comment, responsible_for_data	string | null	Free-text columns
facts[].status, relevance, required, visibility	string | null	Localized select labels
pagination	object	total, page, pageSize, totalPages

Errors. Common errors only (section 4 of the API page).

1.6 Get full RMD (content)

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/rmd

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
language	query	ru | en	no	Language of the select-type labels
format	query	json | xlsx	no	Output format. Default json

Details

On df-api/v1 this path is the combined RMD export: measures, dimensions and facts together with the data model (dimension groups, fact tables, relationships), not paginated. It returns a complete metadata snapshot of the version with an exported_at timestamp and is designed for downstream catalogs and full-state synchronization.

Response

200 OK

{
  "project": {
    "id": "12",
    "name": "Sales Analytics",
    "description": "Production sales warehouse"
  },
  "version": {
    "id": "33",
    "name": "Q4 2025",
    "is_global": true
  },
  "measures": [
    {
      "row_number": 1,
      "group": "Revenue",
      "block": "Sales",
      "measure_name": "Total revenue",
      "measure_description": "Gross revenue across all channels",
      "original_source_type": "Database",
      "original_source": "ERP",
      "original_object": "sales.amount",
      "display_data_type": "Number",
      "measure_type": "Base",
      "restrictions": null,
      "formula": null,
      "report_for_verification": null,
      "comment": null,
      "status": "Active",
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null,
      "variation": null
    }
  ],
  "dimensions": [
    {
      "row_number": 1,
      "group": "Customer",
      "block": "Profile",
      "dimension_name": "Customer name",
      "dimension_description": "Full customer name",
      "original_source_type": null,
      "original_source": null,
      "original_object": null,
      "dimension_group": "Customers",
      "display_data_type": "Text",
      "source_data_type": "VARCHAR(255)",
      "dimension_type": "Primary",
      "formula": null,
      "connected_source": { "db": "analytics_db", "schema": "public", "table": "dim_customer", "column": "customer_name" },
      "comment": null,
      "value_options": null,
      "status": "Active",
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null
    }
  ],
  "facts": [
    {
      "row_number": 1,
      "group": "Sales",
      "block": "Orders",
      "fact_name": "Order line",
      "fact_description": "An individual line item on a sales order",
      "original_source_type": null,
      "original_source": null,
      "original_object": null,
      "source_data_type": "DECIMAL(18,2)",
      "fact_type": "Primary",
      "formula": null,
      "connected_source": { "db": "analytics_db", "schema": "public", "table": "fact_order_line", "column": "amount" },
      "report_for_verification": null,
      "comment": null,
      "status": null,
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null
    }
  ],
  "dimension_groups": [
    {
      "id": "9",
      "name": "Geography",
      "description": "Geographic regions and countries",
      "primary_key": {
        "db": "analytics_db",
        "schema": "public",
        "table": "dim_geography",
        "column": "region_id"
      },
      "dimensions": [
        { "id": "722", "name": "Region", "level": 1, "data_type": "Text", "physical_column": "region_name" },
        { "id": "723", "name": "Country", "level": 2, "data_type": "Text", "physical_column": "country_code" }
      ],
      "related_fact_tables": ["11", "14"],
      "created_at": null
    }
  ],
  "fact_tables": [
    {
      "id": "11",
      "name": "fact_sales",
      "description": "Primary sales facts",
      "owner": "Pavel Shalavin",
      "created_at": "2026-04-15T08:30:00Z",
      "measures_count": 5,
      "dimensions_count": 3,
      "facts_count": 2,
      "verification_filters_count": 2,
      "related_dimension_groups_count": 1
    }
  ],
  "relationships": [
    {
      "id": "1101",
      "source_fact_table": { "id": "11", "name": "fact_sales" },
      "target_dimension_group": { "id": "9", "name": "Geography" },
      "foreign_key": { "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
      "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
      "relationship_type": "Many-to-one",
      "created_at": null
    }
  ],
  "exported_at": "2026-05-05T08:30:00Z"
}

Field	Type	Description
project	object	id, name, description of the project (id as a string)
version	object	id, name, is_global of the version
measures[].row_number	integer	Position of the row in the RMD table
measures[].group, block	string | null	Grouping columns of the RMD
measures[].measure_name	string	Measure name
measures[].measure_description	string | null	Description
measures[].original_source_type, original_source, original_object	string | null	Provenance columns; free text
measures[].display_data_type	string | null	Localized data type label (Number, Text, Date, …)
measures[].measure_type	string	Localized label: Base or Calculated
measures[].restrictions	string | null	Restrictions column
measures[].formula	string | null	Formula of a calculated measure with references rendered as [Name]
measures[].report_for_verification, comment, responsible_for_data, variation	string | null	Free-text columns
measures[].status, relevance, required, visibility	string | null	Localized select labels
dimensions[].row_number	integer	Position of the row in the RMD table
dimensions[].group, block	string | null	Grouping columns of the RMD
dimensions[].dimension_name, dimension_description	string / string | null	Name and description
dimensions[].original_source_type, original_source, original_object	string | null	Provenance columns; free text
dimensions[].dimension_group	string | null	Name of the dimension group the dimension belongs to
dimensions[].display_data_type	string | null	Localized data type label
dimensions[].source_data_type	string | null	Physical column type resolved from the connection's cached schema
dimensions[].dimension_type	string	Localized label: Primary or Derived
dimensions[].formula	string | null	Formula of a derived dimension
dimensions[].connected_source	object | null	Source object { db, schema, table, column } (section 3.6 of the API page)
dimensions[].comment, responsible_for_data	string | null	Free-text columns
dimensions[].value_options	string | null	Allowed values column
dimensions[].status, relevance, required, visibility	string | null	Localized select labels
facts[].row_number	integer	Position of the row in the RMD table
facts[].group, block	string | null	Grouping columns of the RMD
facts[].fact_name, fact_description	string / string | null	Name and description
facts[].original_source_type, original_source, original_object	string | null	Provenance columns; free text
facts[].source_data_type	string | null	Physical column type resolved from the connection's cached schema
facts[].fact_type	string	Localized label: Primary or Derived
facts[].formula	string | null	Formula of a derived fact
facts[].connected_source	object | null	Source object { db, schema, table, column } (section 3.6 of the API page)
facts[].report_for_verification, comment, responsible_for_data	string | null	Free-text columns
facts[].status, relevance, required, visibility	string | null	Localized select labels
dimension_groups[].id, name, description	string / string / string | null	Identity
dimension_groups[].primary_key	object | null	Source object { db, schema, table, column }
dimension_groups[].dimensions[]	array	Members ordered by hierarchy level; data_type is the localized display data type, physical_column the column in the source table
dimension_groups[].related_fact_tables[]	string	IDs of fact tables that reference the group; their configuration is available through the fact table endpoints
dimension_groups[].created_at	null	Not populated in v1
fact_tables[].id, name, description, owner, created_at	—	Identity; owner is the creator's name
fact_tables[].measures_count, dimensions_count, facts_count	integer	Elements assigned directly to the fact table
fact_tables[].verification_filters_count	integer	Per-fact-table verification filters
fact_tables[].related_dimension_groups_count	integer	Dimension groups assigned to the fact table
relationships[].id	string	Relationship identifier
relationships[].source_fact_table	object	id, name of the fact table holding the foreign key
relationships[].target_dimension_group	object	id, name of the dimension group holding the primary key
relationships[].foreign_key, primary_key	object | null	Source objects of the join
relationships[].relationship_type	string	Localized cardinality label
relationships[].created_at	null	Not populated in v1
exported_at	string	When the snapshot was taken, ISO 8601

Errors. Common errors only (section 4 of the API page).

2 Public DF API — data model and data marts (df-api/v1)

Base path: /df-api/v1. Auth: X-Api-Key. All endpoints are read-only.

This group is organized into six logical areas: data marts, connections, dimension groups, fact tables, relationships, and a combined RMD export. The data-marts and connections endpoints return JSON only; the dimension-groups, fact-tables, relationships, and RMD-export endpoints additionally support ?format=xlsx (see section 3.5 of the API page). The RMD content endpoints (projects, versions, measures, dimensions, facts) are documented in section 9.7.

Common to every endpoint of the group: {project_id} and {version_id} are required path parameters (integers); a project the key owner cannot access answers 404; list endpoints refuse pageSize above 100 with 400 DF_API.PAGE_SIZE_EXCEEDED and paginate with total_pages (not totalPages, section 3.2 of the API page). Source objects (primary_key, foreign_key) carry db, schema, table, column and no connection field (section 3.6 of the API page).

2.1 List data marts

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/data-marts

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
page	query	integer	no	Page number, 1-indexed. Default 1
pageSize	query	integer	no	Items per page. Default 20, maximum 100
language	query	ru | en	no	Language of the type label
type	query	string	no	Filter by mart type: with_grouping, without_grouping, with_grouping_and_pivoting
merge_type	query	string	no	Filter by merge type: union, join
search	query	string	no	Case-insensitive substring search across name and description

Details

type is returned as a localized label (depends on language / Accept-Language), e.g. "With grouping" for en, while the filter takes the raw slug. merge_type is always the raw slug (union / join), never localized. When a mart has no description the description key is absent (v2 returns null). JSON only — format is not accepted.

Response

200 OK

{
  "data_marts": [
    {
      "id": "57",
      "name": "Monthly Sales Mart",
      "description": "Aggregated by month and region",
      "owner": "Pavel Shalavin",
      "created_at": "2026-04-15T08:30:00Z",
      "type": "With grouping",
      "merge_type": "union",
      "source_fact_table_count": 2,
      "has_physical_view": true
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 45, "total_pages": 3 }
}

Field	Type	Description
data_marts[].id	string	Data mart identifier
data_marts[].name	string	Display name
data_marts[].description	string	Description; the key is omitted when unset
data_marts[].owner	string	Owner's name, or the e-mail when no name is set
data_marts[].created_at	string	Creation timestamp, ISO 8601
data_marts[].type	string	Localized mart type label
data_marts[].merge_type	string | null	union / join; null for marts built on a single fact table
data_marts[].source_fact_table_count	integer	Number of distinct source fact tables
data_marts[].has_physical_view	boolean	Whether a physical object has been materialized for the mart
pagination	object	page, pageSize, total, total_pages

Errors

Code	HTTP	Condition
DF_API.INVALID_TYPE	400	type is outside the allowed set
DF_API.INVALID_MERGE_TYPE	400	merge_type is outside the allowed set
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize above 100
Common errors	—	Section 4 of the API page

2.2 Get data mart details

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/data-marts/{data_mart_id}

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
data_mart_id	path	integer	yes	Data mart identifier
language	query	ru | en	no	Language of the localized labels (type, data_type)

Details

Returns the full configuration of a data mart. For pivoted (transposed) marts (type = with_grouping_and_pivoting) the response additionally includes selected_measure_attributes, where the implicit pivot key Measure name is always prepended to any explicitly stored attributes:

"selected_measure_attributes": [
  { "attribute_id": "3",  "attribute_name": "Measure name" },
  { "attribute_id": "27", "attribute_name": "Measure description" }
]

Response

200 OK

{
  "id": "57",
  "name": "Monthly Sales Mart",
  "description": "Aggregated by month and region",
  "owner": "Pavel Shalavin",
  "created_at": "2026-04-15T08:30:00Z",
  "type": "with_grouping",
  "merge_type": "union",
  "source_fact_tables": [
    { "id": "11", "name": "fact_sales", "description": "Primary sales facts" }
  ],
  "selected_measures": [
    {
      "instance_id": "204",
      "measure_id": "501",
      "measure_name": "Total revenue",
      "description": "Gross revenue",
      "formula": "SUM([Amount])",
      "data_type": "Numeric",
      "display_name": "Revenue",
      "aggregation_configuration": { "type": "default", "group_by_fields": [] },
      "source_fact_table_id": "11"
    }
  ],
  "selected_facts": [
    {
      "fact_id": "611",
      "fact_name": "Order line",
      "data_type": "Numeric",
      "display_name": "Order line",
      "include_in_result": true,
      "filter_condition": null,
      "source_fact_table_id": "11"
    }
  ],
  "selected_dimensions": [
    {
      "dimension_id": "722",
      "dimension_name": "Region",
      "description": "Geographic region",
      "data_type": "Text",
      "display_name": "Region",
      "include_in_result": true,
      "filter_condition": null,
      "source_fact_table_id": "11",
      "source_dimension_group_id": "9",
      "source_dimension_group_name": "Geography"
    }
  ],
  "physical_view": {
    "exists": false,
    "type": null, "database": null, "schema": null, "name": null, "created_at": null
  }
}

Field	Type	Description
id	string	Data mart identifier
name	string	Display name
description	string	Description; the key is omitted when unset
owner	string	Owner's name, or the e-mail when no name is set
created_at	string	Creation timestamp, ISO 8601
type	string	Localized mart type label
merge_type	string | null	union / join; null for marts built on a single fact table
source_fact_tables[]	array	Fact tables the mart draws from: id, name, description
selected_measures[].instance_id	string	Unique identifier of the measure instance inside the mart (the same measure may appear several times with different aggregation settings)
selected_measures[].measure_id	string	Identifier of the measure in the RMD
selected_measures[].formula	string | null	Formula of a calculated measure
selected_measures[].data_type	string	Localized data type label
selected_measures[].display_name	string	Column name in the mart
selected_measures[].aggregation_configuration.type	string	default, none, custom, or global
selected_measures[].aggregation_configuration.group_by_fields	array	Column-value IDs of the fields the measure is grouped by
selected_facts[], selected_dimensions[]	array	Facts and dimensions used by the mart
…include_in_result	boolean	false means the element is used only for filtering and is not projected into the result
…filter_condition	string | null	Filter expression with column-value references replaced by names; null if no filter
selected_dimensions[].source_dimension_group_id / source_dimension_group_name	string | null	Resolved from the data model even if the dimension group is not explicitly listed in the mart's attributes
physical_view	object	Metadata of the materialized object: exists, type (localized label of the object kind), database (raw slug), schema, name, created_at; the connection field is not included here

Errors

Code	HTTP	Condition
DF_API.DATA_MART_NOT_FOUND	404	The mart does not exist in the given version
Common errors	—	Section 4 of the API page

2.3 Get physical view metadata

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/data-marts/{data_mart_id}/view

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
data_mart_id	path	integer	yes	Data mart identifier
language	query	ru | en	no	Language of the type label

Details

Returns metadata of the physical object DataForge has materialized for the data mart. No connection to the target database is performed — only what the platform already knows is returned. When no view has been materialized, exists is false and every other field is null:

{ "exists": false, "type": null, "database": null, "schema": null, "name": null, "created_at": null, "connection": null }

Response

200 OK

{
  "exists": true,
  "type": "materialized_view",
  "database": "postgresql",
  "schema": "marts",
  "name": "monthly_sales",
  "created_at": "2026-04-21T09:00:00Z",
  "connection": { "id": "3", "name": "Production PostgreSQL", "db_type": "postgres" }
}

Field	Type	Description
exists	boolean	Whether the object is materialized
type	string | null	Localized label for the physical object kind (depends on language); raw slugs are regular_view, materialized_view, table
database	string | null	Raw database-type slug: postgresql, clickhouse, sqlserver (not localized)
schema	string | null	Schema of the object. For ClickHouse v1 returns the database name here; v2 returns null
name	string | null	Object name in the database
created_at	string | null	When the object was created, ISO 8601
connection	object | null	id, name, db_type of the connection the object lives in; no credentials

Errors

Code	HTTP	Condition
DF_API.DATA_MART_NOT_FOUND	404	The mart does not exist in the given version
Common errors	—	Section 4 of the API page

2.4 Generate SQL script

Request

POST /df-api/v1/projects/{project_id}/versions/{version_id}/data-marts/{data_mart_id}/generate-sql

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
data_mart_id	path	integer	yes	Data mart identifier
limit	body	integer > 0	no	Appends a row limit using dialect-appropriate syntax: LIMIT n OFFSET m for PostgreSQL/ClickHouse, OFFSET m ROWS FETCH NEXT n ROWS ONLY for MS SQL
offset	body	integer ≥ 0	no	Row offset; effective only together with limit. offset alone is ignored

Request body (optional):

{ "limit": 100, "offset": 0 }

Details

Generates the SQL SELECT statement of the mart. SQL is only generated and returned — it is not executed, and nothing is persisted. For MS SQL, if the generated SQL has no ORDER BY, the service appends ORDER BY (SELECT NULL) to make OFFSET … FETCH NEXT syntactically valid.

The endpoint answers 201 Created — the default POST status in v1; the same endpoint in v2 answers 200 and takes limit / offset from the query string.

If SQL generation fails (broken metric formulas or missing source mappings), the response is still successful (the same 201) and carries the failure in validation_errors. This lets clients distinguish "the mart cannot currently produce SQL" from "the mart does not exist" (404). In v1 the message field carries the raw key of the cause (e.g. FORMULA.SOURCE_NOT_FOUND_FOR_METRIC); only v2 returns localized text.

Response

201 Created

{
  "sql_script": "SELECT ...\nFROM ...\nGROUP BY ...\nLIMIT 100 OFFSET 0",
  "target_db_type": "postgres",
  "validation_errors": []
}

On a generation failure:

{
  "sql_script": "",
  "target_db_type": null,
  "validation_errors": [
    { "code": "SQL_GENERATION_FAILED", "message": "FORMULA.SOURCE_NOT_FOUND_FOR_METRIC" }
  ]
}

Field	Type	Description
sql_script	string	The generated SELECT; empty string on failure
target_db_type	string | null	Target database type (postgres, clickhouse, sqlserver); null on failure
validation_errors[]	array	Empty on success
validation_errors[].code	string	Always SQL_GENERATION_FAILED
validation_errors[].message	string	Raw key of the cause (v1)

Errors

Code	HTTP	Condition
DF_API.DATA_MART_NOT_FOUND	404	The mart does not exist in the given version
Common errors	—	Section 4 of the API page

2.5 List connections

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/connections

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
page	query	integer	no	Page number, 1-indexed. Default 1
pageSize	query	integer	no	Items per page. Default 20, maximum 100
language	query	ru | en	no	Accepted for contract parity; no field of the response is localized
db_type	query	string	no	Filter by database type: postgresql, clickhouse, sqlserver
status	query	string	no	Filter by status: active, inactive, never_verified, failed

Details

Credentials are never returned (section 6 of the API page). schema is only returned for PostgreSQL: for MS SQL Server it is folded into the table name elsewhere, for ClickHouse the database name is used in lieu of a schema — null in both cases. Connections whose database type the public API does not expose (MySQL, for instance) are omitted from the list and from total.

status is mapped from the internal connection state: never_verified takes priority — without a successful update timestamp the system cannot claim a state; failed corresponds to internal UPDATE_ERROR; inactive corresponds to DISABLED; otherwise the status is active.

Response

200 OK

{
  "connections": [
    {
      "id": "1",
      "name": "Production PostgreSQL",
      "db_type": "postgresql",
      "host": "db.production.company.com",
      "port": 5432,
      "database": "analytics_db",
      "schema": "public",
      "username": "analytics_user",
      "status": "active",
      "last_updated_at": "2026-04-15T08:30:00Z"
    },
    {
      "id": "2",
      "name": "Legacy SQL Server",
      "db_type": "sqlserver",
      "host": "sqlserver.legacy.company.com",
      "port": 1433,
      "database": "legacy_warehouse",
      "schema": null,
      "username": "etl_service",
      "status": "active",
      "last_updated_at": "2026-04-14T10:00:00Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 8, "total_pages": 1 }
}

Field	Type	Description
connections[].id	string	Connection identifier
connections[].name	string	Display name (unique within the version)
connections[].db_type	string	Raw slug: postgresql, clickhouse, sqlserver
connections[].host, port, database	string / integer / string	Network coordinates
connections[].schema	string | null	Connection schema; PostgreSQL only
connections[].username	string	Database user name (not a secret)
connections[].status	string	active, inactive, never_verified, failed
connections[].last_updated_at	string | null	When the schema snapshot was last refreshed successfully
pagination	object	page, pageSize, total, total_pages

Errors

Code	HTTP	Condition
DF_API.INVALID_DB_TYPE	400	db_type is outside the allowed set
DF_API.INVALID_STATUS	400	status is outside the allowed set
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize above 100
Common errors	—	Section 4 of the API page

2.6 Get connection details

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/connections/{connection_id}

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
connection_id	path	integer	yes	Connection identifier
language	query	ru | en	no	Accepted for contract parity; no field is localized
include_db_schema	query	boolean	no	Default false. When true, replaces the lightweight db_tables array with the full db_schema object

Details

db_tables[] carries name only. db_schema.tables[] carries table_name, schema (the table's own schema; null for ClickHouse, which has no schemas) and columns[] of column_name and data_type. The same structure object is called db_schema in this endpoint and schema in the schema endpoint (GET …/connections/{connection_id}/schema); the table contents are identical in both. In v1 the container carries no connection field — only v2 adds it. The schema is a cached snapshot taken at connection setup or during a manual refresh; last_updated_at records when it was taken.

Response

200 OK — include_db_schema=false:

{
  "id": "1",
  "name": "Production PostgreSQL",
  "db_type": "postgresql",
  "host": "db.production.company.com",
  "port": 5432,
  "database": "analytics_db",
  "schema": "public",
  "username": "analytics_user",
  "status": "active",
  "last_updated_at": "2026-04-15T08:30:00Z",
  "db_tables": [ { "name": "fact_sales" }, { "name": "dim_customer" } ]
}

200 OK — include_db_schema=true:

{
  "id": "1",
  "name": "Production PostgreSQL",
  "db_type": "postgresql",
  "host": "db.production.company.com",
  "port": 5432,
  "database": "analytics_db",
  "schema": "public",
  "username": "analytics_user",
  "status": "active",
  "last_updated_at": "2026-04-15T08:30:00Z",
  "db_schema": {
    "tables": [
      {
        "table_name": "fact_sales",
        "schema": "public",
        "columns": [
          { "column_name": "sale_id", "data_type": "int" },
          { "column_name": "sale_date", "data_type": "datetime" },
          { "column_name": "amount", "data_type": "decimal(18,2)" }
        ]
      }
    ]
  }
}

Field	Type	Description
id	string	Connection identifier
name	string	Display name (unique within the version)
db_type	string	Raw slug: postgresql, clickhouse, sqlserver
host, port, database	string / integer / string	Network coordinates
schema	string | null	Connection schema; PostgreSQL only
username	string	Database user name (not a secret)
status	string	active, inactive, never_verified, failed
last_updated_at	string | null	When the schema snapshot was last refreshed successfully
db_tables[].name	string	Table name; present when include_db_schema is not set
db_schema	object	Full structure; present instead of db_tables when include_db_schema=true
db_schema.tables[].table_name	string	Table name
db_schema.tables[].schema	string | null	The table's schema; null for ClickHouse
db_schema.tables[].columns[].column_name, data_type	string	Column name and type as read from the database

Errors

Code	HTTP	Condition
DF_API.CONNECTION_NOT_FOUND	404	The connection does not exist in the given version
Common errors	—	Section 4 of the API page

2.7 Get connection schema

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/connections/{connection_id}/schema

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
connection_id	path	integer	yes	Connection identifier

Details

Returns only the cached schema (tables and columns) of a connection, without the network coordinates. The top-level key is schema (the connection details endpoint calls the same object db_schema); its contents are identical: tables[] with table_name, the table's schema (null for ClickHouse) and columns[] of column_name and data_type.

The schema returned is a cached snapshot taken at connection setup or during a manual refresh. It does not reflect real-time changes in the target database; last_updated_at records when the snapshot was taken.

Response

200 OK

{
  "id": "1",
  "name": "Production PostgreSQL",
  "db_type": "postgresql",
  "last_updated_at": "2026-04-15T08:30:00Z",
  "schema": {
    "tables": [
      { "table_name": "fact_sales", "schema": "public",
        "columns": [
          { "column_name": "sale_id", "data_type": "int" },
          { "column_name": "sale_date", "data_type": "datetime" }
        ]
      }
    ]
  }
}

Field	Type	Description
id, name, db_type	string	Connection identity
last_updated_at	string | null	When the snapshot was taken
schema.tables[].table_name	string	Table name
schema.tables[].schema	string | null	The table's schema; null for ClickHouse
schema.tables[].columns[].column_name, data_type	string	Column name and type as read from the database

Errors

Code	HTTP	Condition
DF_API.CONNECTION_NOT_FOUND	404	The connection does not exist in the given version
Common errors	—	Section 4 of the API page

2.8 List dimension groups

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/dimension-groups

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
page	query	integer	no	Page number, 1-indexed. Default 1
pageSize	query	integer	no	Items per page. Default 20, maximum 100
language	query	ru | en	no	Language of the data_type labels
format	query	json | xlsx	no	Default json. xlsx produces a one-sheet workbook Dimension Groups

Details

Returns the dimension groups (справочники) defined in the project version, with their primary key, member dimensions, and the IDs of fact tables that reference them. primary_key is the source object of section 3.6 of the API page without connection, or null when the group has no resolved physical key; v1 answers the schema stored on the row as-is. created_at is present but not populated for dimension groups — returned as null.

Response

200 OK

{
  "dimension_groups": [
    {
      "id": "9",
      "name": "Geography",
      "description": "Geographic regions and countries",
      "primary_key": {
        "db": "analytics_db",
        "schema": "public",
        "table": "dim_geography",
        "column": "region_id"
      },
      "dimensions": [
        { "id": "722", "name": "Region", "level": 1, "data_type": "Text", "physical_column": "region_name" },
        { "id": "723", "name": "Country", "level": 2, "data_type": "Text", "physical_column": "country_code" }
      ],
      "related_fact_tables": ["11", "14"],
      "created_at": null
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 12, "total_pages": 1 }
}

Field	Type	Description
dimension_groups[].id, name, description	string / string / string | null	Identity
dimension_groups[].primary_key	object | null	Source object { db, schema, table, column }
dimension_groups[].dimensions[]	array	Members ordered by hierarchy level; data_type is the localized display data type, physical_column the column in the source table
dimension_groups[].related_fact_tables[]	string	IDs of fact tables that reference the group; their configuration is available through the fact table endpoints
dimension_groups[].created_at	null	Not populated in v1
pagination	object	page, pageSize, total, total_pages

Errors

Code	HTTP	Condition
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize above 100
Common errors	—	Section 4 of the API page

2.9 Get dimension group details

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/dimension-groups/{dimension_group_id}

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
dimension_group_id	path	integer	yes	Dimension group identifier
language	query	ru | en	no	Localization
format	query	json | xlsx	no	Default json

Details

Returns the full configuration of a single dimension group, including the related fact tables with their foreign key columns. Unlike the list endpoint, the v1 details do not include the dimensions array (v2 does). created_at / updated_at are present but null.

Response

200 OK

{
  "id": "9",
  "name": "Geography",
  "description": "Geographic regions and countries",
  "primary_key": {
    "db": "analytics_db",
    "schema": "public",
    "table": "dim_geography",
    "column": "region_id"
  },
  "related_fact_tables": [
    { "fact_table_id": "11", "fact_table_name": "fact_sales", "foreign_key_column": "region_id" },
    { "fact_table_id": "14", "fact_table_name": "fact_inventory", "foreign_key_column": "region_id" }
  ],
  "created_at": null,
  "updated_at": null
}

Field	Type	Description
id, name, description	string / string / string | null	Identity
primary_key	object | null	Source object { db, schema, table, column }
related_fact_tables[]	array	fact_table_id, fact_table_name, foreign_key_column of every fact table joined to the group
created_at, updated_at	null	Not populated in v1

Errors

Code	HTTP	Condition
DF_API.DIMENSION_GROUP_NOT_FOUND	404	The dimension group does not exist in the version
Common errors	—	Section 4 of the API page

2.10 List fact tables

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/fact-tables

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
page	query	integer	no	Page number, 1-indexed. Default 1
pageSize	query	integer	no	Items per page. Default 20, maximum 100
language	query	ru | en	no	Accepted; the list has no localized field
format	query	json | xlsx	no	Default json. xlsx produces a one-sheet workbook Fact Tables

Details

dimensions_count counts only dimensions added directly to the fact table (not part of any dimension group). Dimensions inherited via dimension groups are accessible through related_dimension_groups_count and through the detail endpoint.

Response

200 OK

{
  "fact_tables": [
    {
      "id": "11",
      "name": "fact_sales",
      "description": "Primary sales facts",
      "owner": "Pavel Shalavin",
      "created_at": "2026-04-15T08:30:00Z",
      "measures_count": 5,
      "dimensions_count": 3,
      "facts_count": 2,
      "verification_filters_count": 2,
      "related_dimension_groups_count": 1
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 6, "total_pages": 1 }
}

Field	Type	Description
fact_tables[].id, name, description, owner, created_at	—	Identity; owner is the creator's name
fact_tables[].measures_count, dimensions_count, facts_count	integer	Elements assigned directly to the fact table
fact_tables[].verification_filters_count	integer	Per-fact-table verification filters
fact_tables[].related_dimension_groups_count	integer	Dimension groups assigned to the fact table
pagination	object	page, pageSize, total, total_pages

Errors

Code	HTTP	Condition
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize above 100
Common errors	—	Section 4 of the API page

2.11 Get fact table details

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/fact-tables/{fact_table_id}

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
fact_table_id	path	integer	yes	Fact table identifier
language	query	ru | en	no	Language of the data_type labels and invalid_reason
include_dependencies	query	boolean	no	Default false. When true, every measure carries a recursive dependencies tree resolving formula references to their target measures
format	query	json | xlsx	no	Default json. xlsx produces five sheets: Measures, Dimensions, Facts, Dimension Groups, Verification Filters

Details

Returns the full configuration of a fact table — its measures, dimensions, facts, dimension groups (with primary and foreign keys), and verification filters. measure_type and fact_type are raw slugs here (base / calculated, primary / derived / constant). In v1 the element data type field is called data_type (v2: display_data_type, section 1 of the Public API v2 page).

Response

200 OK

{
  "id": "11",
  "name": "fact_sales",
  "description": "Primary sales facts",
  "owner": "Pavel Shalavin",
  "created_at": "2026-04-15T08:30:00Z",
  "updated_at": "2026-04-21T09:00:00Z",
  "measures": [
    {
      "id": "501",
      "name": "Total revenue",
      "description": "Gross revenue",
      "formula": "SUM([Amount])",
      "data_type": "Numeric",
      "measure_type": "base",
      "dependencies": null
    }
  ],
  "dimensions": [
    {
      "id": "801",
      "name": "Sale date",
      "description": "Calendar date of the sale",
      "data_type": "Date",
      "physical_column": "sale_date",
      "is_from_dimension_group": false,
      "dimension_group_id": null
    }
  ],
  "facts": [
    {
      "id": "611",
      "name": "Order line",
      "description": null,
      "data_type": "Numeric",
      "fact_type": "primary",
      "formula": null,
      "physical_column": "amount"
    }
  ],
  "dimension_groups": [
    {
      "id": "9",
      "name": "Geography",
      "description": "Geographic regions and countries",
      "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
      "foreign_key": { "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" }
    }
  ],
  "verification_filters": [
    {
      "id": "301",
      "name": "Valid sales only",
      "description": "Excludes test and cancelled orders",
      "conditions": "[Status] != 'cancelled'",
      "is_valid": true,
      "invalid_reason": null
    }
  ]
}

Field	Type	Description
measures[].measure_type	string	base (sourced directly) or calculated (derived from a formula)
measures[].dependencies	array | null	Present and populated only when include_dependencies=true; each node has id, name, type, formula and a recursive dependencies array
dimensions[].is_from_dimension_group	boolean	true for dimensions inherited from a linked dimension group; false for dimensions defined directly on the fact table
dimensions[].dimension_group_id	string | null	The group an inherited dimension comes from
facts[].fact_type	string	primary, derived, or constant
…physical_column	string | null	Column bound to the element in the source table
dimension_groups[].primary_key, foreign_key	object | null	Source objects of the join (section 3.6 of the API page)
verification_filters[].is_valid	boolean	false when the filter expression cannot be resolved (missing reference, syntax error); invalid_reason carries the localized explanation

Errors

Code	HTTP	Condition
DF_API.FACT_TABLE_NOT_FOUND	404	The fact table does not exist in the version
Common errors	—	Section 4 of the API page

2.12 List relationships

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/relationships

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
page	query	integer	no	Page number, 1-indexed. Default 1
pageSize	query	integer	no	Items per page. Default 20, maximum 100
language	query	ru | en	no	Language of the relationship_type label
fact_table_id	query	integer	no	Only relationships whose source is the given fact table
dimension_group_id	query	integer	no	Only relationships whose target is the given dimension group
format	query	json | xlsx	no	Default json

Details

Returns foreign-key relationships between fact tables and dimension groups in the project version. relationship_type describes the cardinality from source fact table to target dimension group; in v1 it is a localized label (Many-to-one / Многие-к-одному depending on language) — only v2 returns the slug many_to_one. created_at is not populated in v1 (null). foreign_key and primary_key may be null if the underlying mapping is incomplete; in that case the relationship is exposed for visibility but cannot be used to build SQL joins.

Response

200 OK

{
  "relationships": [
    {
      "id": "1101",
      "source_fact_table": { "id": "11", "name": "fact_sales" },
      "target_dimension_group": { "id": "9", "name": "Geography" },
      "foreign_key": { "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
      "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
      "relationship_type": "Many-to-one",
      "created_at": null
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 4, "total_pages": 1 }
}

Field	Type	Description
relationships[].id	string	Relationship identifier
relationships[].source_fact_table	object	id, name of the fact table holding the foreign key
relationships[].target_dimension_group	object	id, name of the dimension group holding the primary key
relationships[].foreign_key, primary_key	object | null	Source objects of the join
relationships[].relationship_type	string	Localized cardinality label
relationships[].created_at	null	Not populated in v1
pagination	object	page, pageSize, total, total_pages

Errors

Code	HTTP	Condition
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize above 100
Common errors	—	Section 4 of the API page

2.13 Get relationship details

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/relationships/{relationship_id}

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
relationship_id	path	integer	yes	Relationship identifier
language	query	ru | en	no	Language of the relationship_type label
format	query	json | xlsx	no	Default json

Details

Returns a single relationship with descriptive fields on both sides; the target dimension group additionally carries its primary_key.

Response

200 OK

{
  "id": "1101",
  "source_fact_table": {
    "id": "11",
    "name": "fact_sales",
    "description": "Primary sales facts"
  },
  "target_dimension_group": {
    "id": "9",
    "name": "Geography",
    "description": "Geographic regions and countries",
    "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" }
  },
  "foreign_key": { "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
  "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
  "relationship_type": "Many-to-one",
  "created_at": null,
  "updated_at": null
}

Field	Type	Description
source_fact_table, target_dimension_group	object	Both sides with description; the group side repeats its primary_key
id	string	Relationship identifier
foreign_key, primary_key	object | null	Source objects of the join
relationship_type	string	Localized cardinality label
created_at, updated_at	null	Not populated in v1

Errors

Code	HTTP	Condition
DF_API.RELATIONSHIP_NOT_FOUND	404	The relationship does not exist in the version
Common errors	—	Section 4 of the API page

2.14 Combined RMD export

Request

GET /df-api/v1/projects/{project_id}/versions/{version_id}/rmd

Parameter	In	Type	Required	Description
project_id	path	integer	yes	Project identifier
version_id	path	integer	yes	Version identifier
language	query	ru | en	no	Language of the select-type labels
format	query	json | xlsx	no	Default json. xlsx produces six sheets: Measures, Dimensions, Facts, Dimension Groups, Fact Tables, Relationships

Details

Returns a complete metadata snapshot of the project version — the RMD content (measures, dimensions, facts) plus the data model (dimension groups, fact tables, relationships) — in a single, non-paginated payload with an exported_at timestamp. Designed for downstream catalogs and full-state synchronization. Use the section 1 endpoints for individual, paginated RMD sections.

Response

200 OK

{
  "project": {
    "id": "12",
    "name": "Sales Analytics",
    "description": "Production sales warehouse"
  },
  "version": {
    "id": "33",
    "name": "Q4 2025",
    "is_global": true
  },
  "measures": [
    {
      "row_number": 1,
      "group": "Revenue",
      "block": "Sales",
      "measure_name": "Total revenue",
      "measure_description": "Gross revenue across all channels",
      "original_source_type": "Database",
      "original_source": "ERP",
      "original_object": "sales.amount",
      "display_data_type": "Number",
      "measure_type": "Base",
      "restrictions": null,
      "formula": null,
      "report_for_verification": null,
      "comment": null,
      "status": "Active",
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null,
      "variation": null
    }
  ],
  "dimensions": [
    {
      "row_number": 1,
      "group": "Customer",
      "block": "Profile",
      "dimension_name": "Customer name",
      "dimension_description": "Full customer name",
      "original_source_type": null,
      "original_source": null,
      "original_object": null,
      "dimension_group": "Customers",
      "display_data_type": "Text",
      "source_data_type": "VARCHAR(255)",
      "dimension_type": "Primary",
      "formula": null,
      "connected_source": { "db": "analytics_db", "schema": "public", "table": "dim_customer", "column": "customer_name" },
      "comment": null,
      "value_options": null,
      "status": "Active",
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null
    }
  ],
  "facts": [
    {
      "row_number": 1,
      "group": "Sales",
      "block": "Orders",
      "fact_name": "Order line",
      "fact_description": "An individual line item on a sales order",
      "original_source_type": null,
      "original_source": null,
      "original_object": null,
      "source_data_type": "DECIMAL(18,2)",
      "fact_type": "Primary",
      "formula": null,
      "connected_source": { "db": "analytics_db", "schema": "public", "table": "fact_order_line", "column": "amount" },
      "report_for_verification": null,
      "comment": null,
      "status": null,
      "relevance": null,
      "required": null,
      "visibility": null,
      "responsible_for_data": null
    }
  ],
  "dimension_groups": [
    {
      "id": "9",
      "name": "Geography",
      "description": "Geographic regions and countries",
      "primary_key": {
        "db": "analytics_db",
        "schema": "public",
        "table": "dim_geography",
        "column": "region_id"
      },
      "dimensions": [
        { "id": "722", "name": "Region", "level": 1, "data_type": "Text", "physical_column": "region_name" },
        { "id": "723", "name": "Country", "level": 2, "data_type": "Text", "physical_column": "country_code" }
      ],
      "related_fact_tables": ["11", "14"],
      "created_at": null
    }
  ],
  "fact_tables": [
    {
      "id": "11",
      "name": "fact_sales",
      "description": "Primary sales facts",
      "owner": "Pavel Shalavin",
      "created_at": "2026-04-15T08:30:00Z",
      "measures_count": 5,
      "dimensions_count": 3,
      "facts_count": 2,
      "verification_filters_count": 2,
      "related_dimension_groups_count": 1
    }
  ],
  "relationships": [
    {
      "id": "1101",
      "source_fact_table": { "id": "11", "name": "fact_sales" },
      "target_dimension_group": { "id": "9", "name": "Geography" },
      "foreign_key": { "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
      "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
      "relationship_type": "Many-to-one",
      "created_at": null
    }
  ],
  "exported_at": "2026-05-05T08:30:00Z"
}

Field	Type	Description
project	object	id, name, description of the project (id as a string)
version	object	id, name, is_global of the version
measures[].row_number	integer	Position of the row in the RMD table
measures[].group, block	string | null	Grouping columns of the RMD
measures[].measure_name	string	Measure name
measures[].measure_description	string | null	Description
measures[].original_source_type, original_source, original_object	string | null	Provenance columns; free text
measures[].display_data_type	string | null	Localized data type label (Number, Text, Date, …)
measures[].measure_type	string	Localized label: Base or Calculated
measures[].restrictions	string | null	Restrictions column
measures[].formula	string | null	Formula of a calculated measure with references rendered as [Name]
measures[].report_for_verification, comment, responsible_for_data, variation	string | null	Free-text columns
measures[].status, relevance, required, visibility	string | null	Localized select labels
dimensions[].row_number	integer	Position of the row in the RMD table
dimensions[].group, block	string | null	Grouping columns of the RMD
dimensions[].dimension_name, dimension_description	string / string | null	Name and description
dimensions[].original_source_type, original_source, original_object	string | null	Provenance columns; free text
dimensions[].dimension_group	string | null	Name of the dimension group the dimension belongs to
dimensions[].display_data_type	string | null	Localized data type label
dimensions[].source_data_type	string | null	Physical column type resolved from the connection's cached schema
dimensions[].dimension_type	string	Localized label: Primary or Derived
dimensions[].formula	string | null	Formula of a derived dimension
dimensions[].connected_source	object | null	Source object { db, schema, table, column } (section 3.6 of the API page)
dimensions[].comment, responsible_for_data	string | null	Free-text columns
dimensions[].value_options	string | null	Allowed values column
dimensions[].status, relevance, required, visibility	string | null	Localized select labels
facts[].row_number	integer	Position of the row in the RMD table
facts[].group, block	string | null	Grouping columns of the RMD
facts[].fact_name, fact_description	string / string | null	Name and description
facts[].original_source_type, original_source, original_object	string | null	Provenance columns; free text
facts[].source_data_type	string | null	Physical column type resolved from the connection's cached schema
facts[].fact_type	string	Localized label: Primary or Derived
facts[].formula	string | null	Formula of a derived fact
facts[].connected_source	object | null	Source object { db, schema, table, column } (section 3.6 of the API page)
facts[].report_for_verification, comment, responsible_for_data	string | null	Free-text columns
facts[].status, relevance, required, visibility	string | null	Localized select labels
dimension_groups[].id, name, description	string / string / string | null	Identity
dimension_groups[].primary_key	object | null	Source object { db, schema, table, column }
dimension_groups[].dimensions[]	array	Members ordered by hierarchy level; data_type is the localized display data type, physical_column the column in the source table
dimension_groups[].related_fact_tables[]	string	IDs of fact tables that reference the group; their configuration is available through the fact table endpoints
dimension_groups[].created_at	null	Not populated in v1
fact_tables[].id, name, description, owner, created_at	—	Identity; owner is the creator's name
fact_tables[].measures_count, dimensions_count, facts_count	integer	Elements assigned directly to the fact table
fact_tables[].verification_filters_count	integer	Per-fact-table verification filters
fact_tables[].related_dimension_groups_count	integer	Dimension groups assigned to the fact table
relationships[].id	string	Relationship identifier
relationships[].source_fact_table	object	id, name of the fact table holding the foreign key
relationships[].target_dimension_group	object	id, name of the dimension group holding the primary key
relationships[].foreign_key, primary_key	object | null	Source objects of the join
relationships[].relationship_type	string	Localized cardinality label
relationships[].created_at	null	Not populated in v1
exported_at	string	When the snapshot was taken, ISO 8601

Errors. Common errors only (section 4 of the API page).