Project Endpoints

For Data Analysts

The project endpoints allow you to load, compile, and inspect your Olytix Core project structure and dependencies.

POST /api/v1/unified/load

Load a unified project from the filesystem. This parses all sources, models, cubes, and metrics and builds the dependency graph.

Request

curl -X POST http://localhost:8000/api/v1/unified/load \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/your/olytix-core-project",
    "strict": true
  }'

Request Body

Field	Type	Required	Description
project_path	string	No	Path to the project root. Uses configured default if not specified.
strict	boolean	No	Raise errors for missing dependencies if true (default: true).

Response

{
  "success": true,
  "project_name": "ecommerce_analytics",
  "source_count": 5,
  "model_count": 12,
  "cube_count": 4,
  "metric_count": 8,
  "graph_nodes": 29,
  "graph_edges": 35,
  "errors": [],
  "warnings": [],
  "load_time_ms": 142.5
}

Response Fields

Field	Type	Description
success	boolean	Whether the project loaded successfully
project_name	string	Name of the loaded project
source_count	number	Number of data sources discovered
model_count	number	Number of transformation models
cube_count	number	Number of semantic cubes
metric_count	number	Number of metrics defined
graph_nodes	number	Total nodes in the dependency graph
graph_edges	number	Total edges in the dependency graph
errors	string[]	List of errors encountered
warnings	string[]	List of warnings
load_time_ms	number	Time taken to load the project in milliseconds

POST /api/v1/unified/compile

Compile the unified project. This compiles SQL models, registers cubes in the semantic layer, and builds column-level lineage.

Request

curl -X POST http://localhost:8000/api/v1/unified/compile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/path/to/your/olytix-core-project",
    "full": false
  }'

Compile Specific Models

curl -X POST http://localhost:8000/api/v1/unified/compile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["stg_orders", "fct_orders"],
    "full": true
  }'

Request Body

Field	Type	Required	Description
project_path	string	No	Path to the project root.
models	string[]	No	Specific models to compile. Compiles all if not specified.
full	boolean	No	Force full compilation even if cached (default: false).

Response

{
  "success": true,
  "models": [
    {
      "name": "stg_orders",
      "unique_id": "model.ecommerce.stg_orders",
      "compiled_sql": "SELECT\n  order_id,\n  customer_id,\n  order_date,\n  total_amount\nFROM raw.orders",
      "success": true,
      "errors": [],
      "compile_time_ms": 12.3
    },
    {
      "name": "fct_orders",
      "unique_id": "model.ecommerce.fct_orders",
      "compiled_sql": "SELECT\n  o.order_id,\n  o.customer_id,\n  c.customer_name,\n  o.order_date,\n  o.total_amount\nFROM stg_orders o\nJOIN stg_customers c ON o.customer_id = c.customer_id",
      "success": true,
      "errors": [],
      "compile_time_ms": 15.7
    }
  ],
  "cubes": [
    {
      "name": "orders",
      "cube_id": "cube.ecommerce.orders",
      "measure_count": 5,
      "dimension_count": 8,
      "success": true,
      "errors": []
    }
  ],
  "model_count": 12,
  "cube_count": 4,
  "metric_count": 8,
  "errors": [],
  "warnings": [],
  "compile_time_ms": 523.8
}

Response Fields

Field	Type	Description
success	boolean	Whether compilation succeeded
models	ModelResult[]	Compilation results for each model
cubes	CubeResult[]	Registration results for each cube
model_count	number	Total models compiled
cube_count	number	Total cubes registered
metric_count	number	Total metrics registered
errors	string[]	Compilation errors
warnings	string[]	Compilation warnings
compile_time_ms	number	Total compilation time

GET /api/v1/unified/graph

Get the unified dependency graph. Returns nodes, edges, execution order, and parallel batches for all artifacts in the project.

Request

curl -X GET "http://localhost:8000/api/v1/unified/graph" \
  -H "Authorization: Bearer YOUR_API_KEY"

With Project Path

curl -X GET "http://localhost:8000/api/v1/unified/graph?project_path=/path/to/project" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Required	Description
project_path	string	No	Path to the project root. Uses loaded project if not specified.

Response

{
  "success": true,
  "nodes": [
    {
      "unique_id": "source.ecommerce.raw.orders",
      "node_type": "source",
      "name": "orders",
      "compiled": true,
      "error": null
    },
    {
      "unique_id": "model.ecommerce.stg_orders",
      "node_type": "model",
      "name": "stg_orders",
      "compiled": true,
      "error": null
    },
    {
      "unique_id": "model.ecommerce.fct_orders",
      "node_type": "model",
      "name": "fct_orders",
      "compiled": true,
      "error": null
    },
    {
      "unique_id": "cube.ecommerce.orders",
      "node_type": "cube",
      "name": "orders",
      "compiled": true,
      "error": null
    },
    {
      "unique_id": "metric.ecommerce.monthly_revenue",
      "node_type": "metric",
      "name": "monthly_revenue",
      "compiled": true,
      "error": null
    }
  ],
  "edges": [
    {"from": "source.ecommerce.raw.orders", "to": "model.ecommerce.stg_orders"},
    {"from": "model.ecommerce.stg_orders", "to": "model.ecommerce.fct_orders"},
    {"from": "model.ecommerce.fct_orders", "to": "cube.ecommerce.orders"},
    {"from": "cube.ecommerce.orders", "to": "metric.ecommerce.monthly_revenue"}
  ],
  "execution_order": [
    "source.ecommerce.raw.orders",
    "model.ecommerce.stg_orders",
    "model.ecommerce.fct_orders",
    "cube.ecommerce.orders",
    "metric.ecommerce.monthly_revenue"
  ],
  "parallel_batches": [
    ["source.ecommerce.raw.orders", "source.ecommerce.raw.customers"],
    ["model.ecommerce.stg_orders", "model.ecommerce.stg_customers"],
    ["model.ecommerce.fct_orders"],
    ["cube.ecommerce.orders"],
    ["metric.ecommerce.monthly_revenue"]
  ],
  "node_count": 5,
  "edge_count": 4
}

Node Types

Type	Description
source	Raw data source definition
source_table	Specific table within a source
model	SQL transformation model
cube	Semantic cube definition
measure	Measure within a cube
dimension	Dimension within a cube
metric	Business metric

Error Responses

400 Bad Request

{
  "error": {
    "code": "INVALID_PROJECT_PATH",
    "message": "Project path does not exist: /invalid/path",
    "details": {}
  }
}

422 Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required model reference",
    "details": {
      "model": "fct_orders",
      "missing_ref": "stg_products"
    }
  }
}

500 Internal Server Error

{
  "error": {
    "code": "COMPILATION_ERROR",
    "message": "Failed to compile model: syntax error in SQL",
    "details": {
      "model": "fct_orders",
      "line": 15,
      "column": 32
    }
  }
}

Next Steps

• Explore lineage endpoints
• Query the semantic layer
• Discover metadata