API Reference

API Overview

Overview of the Cortex REST API with endpoints and usage patterns.

API Overview

Cortex provides a comprehensive REST API that exposes all functionality through well-structured endpoints. The API follows RESTful conventions and uses FastAPI for automatic OpenAPI/Swagger documentation generation.

Base URL

https://cortex.jointelescope.com/api/v1

Interactive Documentation

The complete API documentation with interactive examples is available at:

https://cortex.jointelescope.com/api/v1/docs

Request/Response Format

Request Format

All requests should include the Content-Type: application/json header for requests with a body.

Example Request

{
  "environment_id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "monthly_revenue",
  "parameters": {
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
  }
}

Response Format

Responses follow the schema definitions defined in the API. Most responses return the requested data directly:

Workspace Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Workspace",
  "description": "Workspace description",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Metric Execution Response

{
  "success": true,
  "metadata": {
    "execution_time": 0.234,
    "query": "SELECT ..."
  },
  "data": [
    {
      "revenue": 100000,
      "month": "2024-01"
    }
  ],
  "errors": null
}

Common HTTP Status Codes

Status Code	Description	Usage
`200`	OK	Successful request
`201`	Created	Resource successfully created
`204`	No Content	Successful request with no response body
`400`	Bad Request	Invalid request parameters
`404`	Not Found	Resource not found
`422`	Unprocessable Entity	Validation error
`500`	Internal Server Error	Server error

API Endpoints Overview

Core Resources

Resource	Description	Base Endpoint
Workspaces	Manage workspaces and environments	`/workspaces`
Environments	Manage environments within workspaces	`/environments`
Consumers	User and consumer group management	`/consumers`
Consumer Groups	Manage consumer groups and memberships	`/consumers/groups`
Data Sources	Configure database connections	`/data/sources`
Data Models	Define business data models	`/data/models`
Metrics	Execute semantic metrics and get results	`/metrics`
Dashboards	Manage dashboards and widgets	`/dashboards`
Query History	Access query execution history	`/query/history`
Pre-aggregations	Manage pre-aggregated data	`/pre-aggregations`

Health Endpoint

Endpoint	Description	Method
`/`	Service health check	`GET`

Request Context

Workspace and Environment Context

Most API requests require workspace and environment context:

Terminal

# Create environment in workspace
curl -X POST "https://cortex.jointelescope.com/api/v1/environments" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "production",
    "description": "Production environment"
  }'

Consumer Context

Some requests support consumer-specific personalization:

Consumer Context

{
  "environment_id": "550e8400-e29b-41d4-a716-446655440001",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "organization": "Acme Corp"
}

Pagination

List endpoints support pagination using page and page_size parameters:

Pagination Example

curl -X GET "https://cortex.jointelescope.com/api/v1/metrics?page=1&page_size=20"

Paginated Response

{
  "metrics": [
    // Array of metric objects
  ],
  "total_count": 150,
  "page": 1,
  "page_size": 20
}

Result Limiting

For metric execution, you can control the number of results returned using limit and offset parameters in the request body:

Metric Execution Request with Limiting

{
  "limit": 50,
  "offset": 0,
  "parameters": {
    "start_date": "2024-01-01",
    "end_date": "2024-12-31"
  },
  "filters": {
    "category": "sales"
  }
}

Query Parameters

Metric Execution Parameters

When executing metrics, you can control result limiting using limit and offset parameters in the request body:

Metric Execution with Limit/Offset

curl -X POST "https://cortex.jointelescope.com/api/v1/metrics/{metric_id}/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 100,
    "offset": 0,
    "parameters": {
      "start_date": "2024-01-01"
    }
  }'

Pagination for List Endpoints

List endpoints support pagination using page and page_size query parameters:

List Pagination Example

curl -X GET "https://cortex.jointelescope.com/api/v1/metrics?page=1&page_size=20"

Filtering and Sorting

Filtering

Some list endpoints support filtering:

Filtering Example

# Filter metrics by data model
curl -X GET "https://cortex.jointelescope.com/api/v1/metrics?data_model_id=550e8400-e29b-41d4-a716-446655440000"

# Filter by public status
curl -X GET "https://cortex.jointelescope.com/api/v1/metrics?public_only=true"

# Filter by validation status
curl -X GET "https://cortex.jointelescope.com/api/v1/metrics?valid_only=true"

Data Source Filtering

# Filter data sources by environment
curl -X GET "https://cortex.jointelescope.com/api/v1/environments/{environment_id}/data/sources"

Error Handling

Common Error Codes

Error Code	HTTP Status	Description
`400`	Bad Request	Invalid request parameters
`404`	Not Found	Requested resource not found
`422`	Unprocessable Entity	Validation error
`500`	Internal Server Error	Server error

Error Response Format

The API returns standard HTTP status codes with error details in the response body:

Validation Error Response

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Not Found Error Response

{
  "detail": "Resource not found"
}

Python SDK

import requests

# Base URL for the API
BASE_URL = "https://cortex.jointelescope.com/api/v1"

# Execute metric
def execute_metric(metric_id, parameters=None):
    url = f"{BASE_URL}/metrics/{metric_id}/execute"
    payload = {"parameters": parameters or {}}
    
    response = requests.post(url, json=payload)
    response.raise_for_status()
    return response.json()

# Example usage
result = execute_metric(
    metric_id="550e8400-e29b-41d4-a716-446655440000",
    parameters={
        "start_date": "2024-01-01",
        "end_date": "2024-12-31"
    }
)
print(result)

Best Practices

1. Error Handling

import requests

def safe_api_call(url, method="GET", data=None):
    try:
        if method == "GET":
            response = requests.get(url)
        elif method == "POST":
            response = requests.post(url, json=data)
        elif method == "PUT":
            response = requests.put(url, json=data)
        elif method == "DELETE":
            response = requests.delete(url)
        
        response.raise_for_status()
        return response.json()
    
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 422:
            print(f"Validation error: {e.response.json()}")
        elif e.response.status_code == 404:
            print("Resource not found")
        else:
            print(f"HTTP error: {e.response.status_code}")
        raise
    
    except requests.exceptions.ConnectionError:
        print("Connection error - check network connectivity")
        raise
    
    except requests.exceptions.Timeout:
        print("Request timed out - try again later")
        raise

2. Pagination Handling

def get_all_metrics():
    all_metrics = []
    page = 1
    page_size = 20
    
    while True:
        url = f"{BASE_URL}/metrics?page={page}&page_size={page_size}"
        response = safe_api_call(url)
        
        all_metrics.extend(response['metrics'])
        
        # Check if we've reached the last page
        if len(response['metrics']) < page_size:
            break
        
        page += 1
    
    return all_metrics

3. Connection Management

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

# Configure retry strategy
retry_strategy = Retry(
    total=3,
    status_forcelist=[500, 502, 503, 504],
    method_whitelist=["HEAD", "GET", "POST", "PUT", "DELETE", "OPTIONS", "TRACE"],
    backoff_factor=1
)

# Create HTTP adapter with retry strategy
adapter = HTTPAdapter(max_retries=retry_strategy)

# Create session with adapter
session = requests.Session()
session.mount("http://", adapter)
session.mount("https://", adapter)

# Use session for API calls
def api_call_with_session(url, method="GET", data=None):
    if method == "GET":
        response = session.get(url)
    elif method == "POST":
        response = session.post(url, json=data)
    # ... etc
    
    response.raise_for_status()
    return response.json()

API Versioning

Cortex uses URL-based versioning:

Current Version: v1 (/api/v1/)
Base URL: https://cortex.jointelescope.com/api/v1

Interactive Documentation

Visit the interactive API documentation at:

https://cortex.jointelescope.com/api/v1/docs

The interactive docs provide:

Try It Out: Execute API calls directly from the browser
Schema Explorer: View detailed request/response schemas
Examples: Copy-paste code examples in multiple languages

Support and Resources

Getting Help

API Documentation: Interactive docs at /docs
GitHub Issues: Report bugs and request features
Community Forum: Share ideas and ask questions

This API overview provides a summary of the Cortex REST API structure. For detailed endpoint documentation with request/response schemas, visit the interactive documentation at https://cortex.jointelescope.com/api/v1/docs.

Edit this pageorReport an issue

Refresh

Control when pre-aggregated data is updated to ensure analytics stay current while optimizing performance.

Studio

Overview of the Cortex Studio - an admin interface for configuring semantic metrics, data models, and dashboards.