Complete API Reference

This section provides a comprehensive reference for every REST API endpoint exposed by the MATIH Enterprise Platform. Endpoints are organized by service, grouped into Control Plane and Data Plane categories. Each endpoint listing includes the HTTP method, path, description, authentication requirements, and example request/response payloads.

API Conventions

All MATIH APIs follow consistent conventions across every service.

Base URL Pattern

# Control Plane services (via API Gateway)
https://{domain}/api/v1/{service-prefix}/{resource}

# Data Plane services (via tenant ingress)
https://{tenant}.{domain}/api/v1/{resource}

# Direct service access (within cluster)
http://{service}.{namespace}.svc.cluster.local:{port}/api/v1/{resource}

Authentication

Every API request (except health checks and public endpoints) requires a valid JWT bearer token in the Authorization header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens are obtained from the IAM Service authentication endpoints and contain tenant context, user identity, and role claims.

Common Headers

Pagination

All list endpoints support cursor-based or offset-based pagination:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 145,
    "totalPages": 8,
    "hasNext": true,
    "hasPrevious": false
  }
}

Query parameters: ?page=1&size=20&sort=created_at&order=desc

Standard Error Response

{
  "error": {
    "code": "MATIH-IAM-1001",
    "message": "Authentication token has expired",
    "details": "Token expiry: 2026-02-12T10:00:00Z, Current time: 2026-02-12T12:30:00Z",
    "timestamp": "2026-02-12T12:30:00.000Z",
    "requestId": "req-abc123",
    "path": "/api/v1/users/me"
  }
}

Rate Limiting

All endpoints are subject to rate limiting. Rate limit information is returned in response headers:

Control Plane Services

IAM Service (Port 8081)

The Identity and Access Management Service handles authentication, authorization, user management, multi-factor authentication, OAuth2 provider integration, and SCIM provisioning.

Authentication Endpoints

Login Request Example:

POST /api/v1/auth/login
Content-Type: application/json
 
{
  "email": "admin@acme.matih.ai",
  "password": "********",
  "tenantSlug": "acme"
}

Login Response Example:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "user": {
    "id": "usr-a1b2c3d4",
    "email": "admin@acme.matih.ai",
    "firstName": "Jane",
    "lastName": "Admin",
    "roles": ["TENANT_ADMIN", "DATA_ENGINEER"],
    "tenantId": "tnt-xyz789"
  }
}

Multi-Factor Authentication Endpoints

OAuth2 / SSO Endpoints

SCIM 2.0 Provisioning Endpoints

User Management Endpoints

Role and Permission Endpoints

Tenant Service (Port 8082)

The Tenant Service manages tenant lifecycle, data source connectors, billing integration, tenant settings, and DNS provisioning.

Tenant Lifecycle Endpoints

Create Tenant Request Example:

POST /api/v1/tenants
Content-Type: application/json
 
{
  "name": "Acme Corporation",
  "slug": "acme",
  "plan": "ENTERPRISE",
  "region": "eastus2",
  "adminEmail": "admin@acme.com",
  "settings": {
    "maxUsers": 500,
    "maxConnectors": 50,
    "gpuEnabled": true,
    "dedicatedIngress": true
  }
}

Connector Management Endpoints

Billing and Settings Endpoints

DNS and Ingress Endpoints

Config Service (Port 8888)

The Config Service manages centralized configuration, feature flags, and marketplace definitions.

Audit Service (Port 8086)

The Audit Service captures and queries audit trail events for compliance and forensics.

Audit Event Query Example:

GET /api/v1/audit/events?action=LOGIN&startDate=2026-02-01&endDate=2026-02-12&userId=usr-123&page=1&size=50

Billing Service (Port 8087)

Notification Service (Port 8085)

Observability API (Port 8088)

Infrastructure Service (Port 8089)

Platform Registry (Port 8084)

Data Plane Services

AI Service (Port 8000)

The AI Service is the conversational intelligence engine that powers text-to-SQL, multi-agent orchestration, RAG-based Q&A, and streaming responses.

Conversation and Chat Endpoints

Chat Request Example:

POST /api/v1/chat
Content-Type: application/json
X-Tenant-ID: tnt-xyz789
 
{
  "conversationId": "conv-abc123",
  "message": "Show me total revenue by region for Q4 2025",
  "context": {
    "dataSource": "sales_warehouse",
    "dialect": "trino",
    "enableVisualization": true
  }
}

Chat Response Example:

{
  "messageId": "msg-def456",
  "conversationId": "conv-abc123",
  "response": {
    "text": "Here is the total revenue by region for Q4 2025.",
    "sql": "SELECT region, SUM(revenue) AS total_revenue FROM sales.orders WHERE quarter = 'Q4' AND year = 2025 GROUP BY region ORDER BY total_revenue DESC",
    "data": {
      "columns": ["region", "total_revenue"],
      "rows": [
        ["North America", 4520000],
        ["Europe", 3180000],
        ["Asia Pacific", 2740000]
      ]
    },
    "visualization": {
      "type": "bar",
      "config": { "xAxis": "region", "yAxis": "total_revenue" }
    }
  },
  "agentTrace": {
    "agents": ["intent_classifier", "schema_retriever", "sql_generator", "sql_validator", "executor"],
    "totalDurationMs": 2340,
    "tokensUsed": 1820
  }
}

Agent Orchestration Endpoints

Text-to-SQL Endpoints

Feedback and Evaluation Endpoints

Studio and DNN Builder Endpoints

ML Service (Port 8000)

The ML Service handles model lifecycle management, training, serving, feature engineering, experiments, and monitoring.

Model Management Endpoints

Training and Experiment Endpoints

Model Serving Endpoints

Feature Store Endpoints

Model Monitoring Endpoints

Query Engine (Port 8080)

BI Service (Port 8084)

Catalog Service (Port 8086)

Semantic Layer (Port 8086)

Pipeline Service (Port 8092)

Data Quality Service (Port 8000)

Governance Service (Port 8080)

Ontology Service (Port 8101)

Health Check Endpoints

Every service exposes a standard health check endpoint that does not require authentication:

Health check response format for Spring Boot services:

{
  "status": "UP",
  "components": {
    "db": { "status": "UP" },
    "redis": { "status": "UP" },
    "kafka": { "status": "UP" },
    "diskSpace": { "status": "UP" }
  }
}

Health check response format for Python FastAPI services:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime_seconds": 86400,
  "checks": {
    "database": "connected",
    "redis": "connected",
    "llm_provider": "available"
  }
}

API Versioning

All MATIH APIs are versioned using URL path versioning (e.g., /api/v1/). When breaking changes are introduced, a new version (e.g., /api/v2/) will be created. Previous versions are supported for a minimum of two major platform releases, providing at least six months of overlap for migration.