> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Overview of CRAFT REST APIs including base URLs, versioning, rate limits, and service endpoints for Governance, Assets, and Utils.

# API Overview

CRAFT exposes RESTful APIs through five services: **Governance** (identity and permissions), **Assets** (data connections and files), **Utils** (scheduling, context packs, and memories), **Talk2Data** (conversational data analytics), and **Data Readiness** (data profiling and governance). All APIs follow consistent conventions for authentication, versioning, and error handling.

## Base URLs

Each platform service runs on a dedicated internal port. In production, services are accessed via path-based routing through a Gateway:

| Service            | Internal Port | Path Prefix       | Responsibility                                |
| ------------------ | ------------- | ----------------- | --------------------------------------------- |
| **Governance**     | 8000          | `/governance`     | Organizations, projects, permissions, secrets |
| **Assets**         | 8000          | `/assets`         | Artifacts, data connections, files            |
| **Utils**          | 8000          | `/utils`          | Scheduling, context packs, memories, metadata |
| **Talk2Data**      | 8080          | `/talk2data`      | Chat sessions, NL-to-SQL, data analysis       |
| **Data Readiness** | 8000          | `/data-readiness` | Profiling workflows, data quality, glossary   |

<Note>
  The URLs above show direct service access. In production deployments behind an ingress controller, services are exposed on a single domain with path-based routing (e.g., `https://api.example.com/governance`, `https://api.example.com/assets`). The ingress rewrites paths to the service-internal prefix.
</Note>

## API Versioning

CRAFT APIs use service-specific prefixes (/governance, /assets, /utils). The platform follows these versioning principles:

* **Path-based versioning**: Each service uses its own prefix (e.g., `/governance/...`, `/assets/...`, `/utils/...`)
* **Backward compatibility**: Minor additions (new fields, new endpoints) are added within the same version
* **Breaking changes**: Changes that remove fields, rename endpoints, or alter behavior require a new version (`/v2`)
* **Deprecation**: Deprecated versions are maintained for at least 6 months with `Sunset` headers

## Common Headers

### Required Headers

| Header          | Description                                                         | Example            |
| --------------- | ------------------------------------------------------------------- | ------------------ |
| `Authorization` | Bearer token for authentication (JWT contains `org_id` for scoping) | `Bearer eyJhbG...` |
| `Content-Type`  | Request body format                                                 | `application/json` |

### Response Headers

| Header                  | Description                           | Example        |
| ----------------------- | ------------------------------------- | -------------- |
| `X-Request-ID`          | Unique request identifier for tracing | `req-a1b2c3d4` |
| `X-RateLimit-Limit`     | Maximum requests allowed in window    | `300`          |
| `X-RateLimit-Remaining` | Requests remaining in current window  | `297`          |
| `X-RateLimit-Reset`     | Unix timestamp when window resets     | `1712150400`   |

## Rate Limits

Rate limits are enforced per authenticated principal using a sliding window algorithm backed by Redis:

| Operation Type                                  | Limit   | Applies To                              |
| ----------------------------------------------- | ------- | --------------------------------------- |
| **Read operations** (GET, POST :search)         | 300/min | Authenticated users                     |
| **Write operations** (POST, PUT, PATCH, DELETE) | 60/min  | Authenticated users                     |
| **Bulk operations**                             | 10/min  | Authenticated users                     |
| **Anonymous reads**                             | 30/min  | Unauthenticated requests (when enabled) |

When a rate limit is exceeded, the API returns:

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 42 seconds.",
    "status": 429
  }
}
```

The `Retry-After` response header indicates when the client can retry.

<Tip>
  Rate limits are configurable per tenant by administrators. Contact your platform admin if the default limits are insufficient for your workload.
</Tip>

## Service Endpoints Summary

### Governance API

| Method | Endpoint                             | Description                      |
| ------ | ------------------------------------ | -------------------------------- |
| GET    | `/governance/organizations`          | List organizations               |
| GET    | `/governance/organizations/{org_id}` | Get organization details         |
| POST   | `/governance/projects`               | Create a project                 |
| GET    | `/governance/projects`               | List projects                    |
| GET    | `/governance/projects/{project_id}`  | Get project details              |
| GET    | `/governance/permissions/check`      | Check if a user has a permission |
| POST   | `/governance/permissions/grant`      | Grant a permission               |
| POST   | `/governance/permissions/revoke`     | Revoke a permission              |
| \*     | `/governance/resources/.../secrets`  | Secret management (CRUD)         |

### Assets API

| Method | Endpoint                                    | Description                 |
| ------ | ------------------------------------------- | --------------------------- |
| POST   | `/assets/artifacts`                         | Create an artifact          |
| GET    | `/assets/artifacts/{resource_uri}`          | Get artifact details        |
| GET    | `/assets/artifacts/{resource_uri}/preview`  | Preview artifact content    |
| GET    | `/assets/artifacts/{resource_uri}/download` | Download artifact           |
| POST   | `/assets/data`                              | Register a data connection  |
| GET    | `/assets/data/{resource_uri}`               | Get data connection details |
| POST   | `/assets/data/{resource_uri}/verify`        | Verify a data connection    |
| POST   | `/assets/files`                             | Upload a file               |
| GET    | `/assets/files/{resource_uri}`              | Get file metadata           |
| GET    | `/assets/files/{resource_uri}/download`     | Download file               |

### Utils API

| Method | Endpoint                                         | Description                |
| ------ | ------------------------------------------------ | -------------------------- |
| POST   | `/utils/schedules`                               | Create a schedule          |
| GET    | `/utils/schedules/{schedule_id}`                 | Get schedule details       |
| PUT    | `/utils/schedules/{schedule_id}`                 | Update a schedule          |
| DELETE | `/utils/schedules/{schedule_id}`                 | Delete a schedule          |
| POST   | `/utils/context-packs`                           | Create a context pack      |
| GET    | `/utils/context-packs`                           | List context packs         |
| POST   | `/utils/memories`                                | Create a memory            |
| GET    | `/utils/memories`                                | List memories              |
| POST   | `/utils/search/metadata`                         | Search metadata catalog    |
| \*     | `/utils/{resource_type}/{resource_uri}/metadata` | Metadata management (CRUD) |

### Talk2Data API (Data Insights)

| Method | Endpoint                                                                | Description             |
| ------ | ----------------------------------------------------------------------- | ----------------------- |
| POST   | `/talk2data/chat/sessions`                                              | Create a chat session   |
| GET    | `/talk2data/chat/sessions`                                              | List chat sessions      |
| GET    | `/talk2data/chat/sessions/{session_id}`                                 | Get session details     |
| PATCH  | `/talk2data/chat/sessions/{session_id}`                                 | Rename a session        |
| DELETE | `/talk2data/chat/sessions/{session_id}`                                 | Delete a session        |
| POST   | `/talk2data/chat/sessions/{session_id}/turns`                           | Create a new turn       |
| GET    | `/talk2data/chat/sessions/{session_id}/turns`                           | List turns in a session |
| GET    | `/talk2data/chat/sessions/{session_id}/turns/{turn_id}`                 | Get turn details        |
| GET    | `/talk2data/chat/sessions/{session_id}/turns/{turn_id}/artifacts`       | Get turn artifacts      |
| POST   | `/talk2data/chat/sessions/{session_id}/turns/{turn_id}/feedback`        | Submit feedback         |
| POST   | `/talk2data/chat/messages/sessions/{session_id}/turns/{turn_id}/stream` | Stream message (SSE)    |
| POST   | `/talk2data/chat/messages/{task_id}/cancel`                             | Cancel a running task   |

### Data Readiness API (Data Governance)

| Method | Endpoint                                            | Description                     |
| ------ | --------------------------------------------------- | ------------------------------- |
| GET    | `/data-readiness/workflows`                         | List workflow configurations    |
| POST   | `/data-readiness/workflows`                         | Create a workflow configuration |
| GET    | `/data-readiness/workflows/{configuration_id}`      | Get workflow details            |
| POST   | `/data-readiness/workflows/{configuration_id}/runs` | Trigger a workflow run          |
| GET    | `/data-readiness/workflows/{configuration_id}/runs` | List runs for a workflow        |
| \*     | `/data-readiness/data-assets/...`                   | Data asset catalog management   |
| \*     | `/data-readiness/metrics/...`                       | Quality metrics and scorecards  |
| \*     | `/data-readiness/violations`                        | Data quality violation tracking |
| \*     | `/data-readiness/glossary/terms`                    | Business glossary management    |

## OpenAPI Specifications

Each service generates an OpenAPI 3.0 specification accessible at:

* Governance: `https://<platform-host>/api/governance/docs` (Swagger UI) or `https://<platform-host>/api/governance/openapi.json`
* Assets: `https://<platform-host>/api/assets/docs` or `https://<platform-host>/api/assets/openapi.json`
* Utils: `https://<platform-host>/api/utils/docs` or `https://<platform-host>/api/utils/openapi.json`

The OpenAPI specs are used to auto-generate Python and TypeScript SDKs.

## SDKs

Auto-generated SDKs are available for programmatic access:

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install em-runtime-governance-sdk-python
    pip install em-runtime-assets-sdk-python
    pip install em-runtime-utils-sdk-python
    ```

    ```python theme={null}
    from em_runtime_governance_sdk import AuthenticatedClient
    from em_runtime_governance_sdk.api.organizations import list_organizations

    client = AuthenticatedClient(
        base_url="https://<platform-host>/api/governance",
        token=access_token,
    )
    orgs = await list_organizations.asyncio(client=client)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install @emergence-ai/em-runtime-governance-sdk
    npm install @emergence-ai/em-runtime-assets-sdk
    npm install @emergence-ai/em-runtime-utils-sdk
    ```

    ```typescript theme={null}
    import { Client } from '@emergence-ai/em-runtime-governance-sdk';
    import { listOrganizations } from '@emergence-ai/em-runtime-governance-sdk/api';

    const client = new Client({
      BASE: 'https://<platform-host>/api/governance',
      TOKEN: accessToken,
    });
    const orgs = await listOrganizations({ client });
    ```
  </Tab>
</Tabs>

## Pagination

List endpoints support offset-based pagination using `page` and `limit` parameters:

```bash theme={null}
# First page
GET /assets/artifacts?limit=20&page=1

# Next page
GET /assets/artifacts?limit=20&page=2
```

<Note>
  The `limit` parameter controls page size (default varies by endpoint). The `page` parameter is 1-indexed.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Authentication" icon="lock" href="/api-reference/authentication">
    Learn how to obtain and use JWT tokens for API access.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/errors">
    Understand error response formats and troubleshooting.
  </Card>

  <Card title="Python SDK" icon="python" href="/sdks/python">
    Use the auto-generated Python SDK for programmatic access.
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdks/typescript">
    Use the auto-generated TypeScript SDK for frontend integration.
  </Card>
</CardGroup>