# Overview & Authentication

***

## Base URL

```
https://{your-telmai-domain}/api
```

***

## Authentication

All endpoints (except `/api/health` and `/api/features`) require a Bearer JWT:

```
Authorization: Bearer <entra-jwt>
```

The JWT is an Entra ID token obtained from the Microsoft Fabric SDK:

```javascript
const token = await workloadClient.auth.acquireAccessToken();
```

Tokens expire after \~1 hour. The Fabric SDK handles refresh automatically.

For service-to-service calls (Data Plane / Scheduler), a service principal JWT is used with the same header format.

***

## Response Envelope

Every endpoint returns a standard JSON envelope:

```json
{
  "data": <response payload or null>,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {}
  },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2026-03-24T10:00:00Z",
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "total": 100,
      "totalPages": 4
    }
  }
}
```

On success: `data` is populated, `error` is `null`. On error: `data` is `null`, `error` is populated.

***

## Standard Query Parameters

All list endpoints support:

| Parameter   | Type            | Description                            |
| ----------- | --------------- | -------------------------------------- |
| `page`      | number          | Page number (1-indexed, default: 1)    |
| `pageSize`  | number          | Items per page (default: 25, max: 100) |
| `search`    | string          | Text search filter                     |
| `sortBy`    | string          | Field to sort by                       |
| `sortOrder` | `asc` \| `desc` | Sort direction                         |

***

## Error Codes

| Code                 | HTTP Status | Cause                                  |
| -------------------- | ----------- | -------------------------------------- |
| `UNAUTHORIZED`       | 401         | JWT missing, expired, or invalid       |
| `FORBIDDEN`          | 403         | Insufficient Fabric workspace role     |
| `TENANT_NOT_ACTIVE`  | 403         | Tenant hasn't completed Entra consent  |
| `VALIDATION_ERROR`   | 400         | Request body failed validation         |
| `RESOURCE_NOT_FOUND` | 404         | Entity not found                       |
| `CONFLICT`           | 409         | Constraint violation (e.g., duplicate) |
| `METRICS_ERROR`      | 502         | Metrics query failure                  |
| `CATALOG_ERROR`      | 502         | Fabric REST API error                  |
| `AI_SERVICE_ERROR`   | 503         | LLM service error                      |
| `INTERNAL_ERROR`     | 500         | Unhandled exception                    |

***

## Roles and Permissions

| Fabric Role           | App Role  | Capabilities                                                                           |
| --------------------- | --------- | -------------------------------------------------------------------------------------- |
| Workspace Admin       | `admin`   | Full access: all CRUD, deploy monitors, manage integrations, AI Copilot, trigger scans |
| Workspace Member      | `editor`  | Create/edit monitors and incidents, manage integrations, AI Copilot, trigger scans     |
| Workspace Contributor | `editor`  | Same as Member                                                                         |
| Workspace Viewer      | `viewer`  | Read-only: assets, monitors, incidents, metrics                                        |
| Service Principal     | `service` | `monitors:read`, `metrics:read`, `metrics:write` — data plane only                     |

***

## Utility Endpoints

### GET /api/health

Health check. No authentication required.

```json
{
  "status": "healthy",
  "checks": {
    "uptime": 3600,
    "timestamp": "2026-03-24T10:00:00Z",
    "telmai": "ok",
    "database": "ok"
  }
}
```

### GET /api/features

Feature flags. No authentication required.

```json
{
  "data": { "dqReport": true, "lineage": true },
  "error": null,
  "meta": {}
}
```

### GET /api/tenants/current

Returns the current tenant's registration status. Requires authentication.

```json
{
  "data": {
    "id": "internal-uuid",
    "entra_tenant_id": "entra-uuid",
    "name": "Contoso",
    "status": "active",
    "created_at": "2026-01-15T10:00:00Z"
  }
}
```

***

## API Sections

| Section                                    | Description                                   |
| ------------------------------------------ | --------------------------------------------- |
| [Catalog](/api-reference/catalog.md)       | Browse Fabric domains, workspaces, and tables |
| [Assets](/api-reference/assets.md)         | Register and manage monitored Fabric tables   |
| [Monitors](/api-reference/monitors.md)     | Create, update, and deploy DQ monitors        |
| [Incidents](/api-reference/incidents.md)   | List, update, and correlate incidents         |
| [Scan Runs](/api-reference/scan-runs.md)   | Trigger on-demand scans and track progress    |
| [Metrics](/api-reference/metrics.md)       | Query time-series DQ metric history           |
| [Copilot Chat](/api-reference/copilot.md)  | Streaming AI chat API                         |
| [MCP Server](/api-reference/mcp-server.md) | Use Telmai from Claude Desktop                |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fabric-docs.telm.ai/api-reference/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.