> ## 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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.