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

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.

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:

{
  "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.

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

Service Endpoints Summary

Governance API (Port 8001)

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://<host>:8001/docs (Swagger UI) or https://<host>:8001/openapi.json
Assets: https://<host>:8002/docs or https://<host>:8002/openapi.json
Utils: https://<host>:8003/docs or https://<host>:8003/openapi.json

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

SDKs

Auto-generated SDKs are available for programmatic access:

Python
TypeScript

pip install em-runtime-governance-sdk-python
pip install em-runtime-assets-sdk-python
pip install em-runtime-utils-sdk-python

from em_runtime_governance_sdk import GovernanceClient

client = GovernanceClient(
    base_url="https://<host>:8001",
    token=access_token
)
orgs = await client.organizations.list()

npm install @emergence/em-runtime-governance-sdk
npm install @emergence/em-runtime-assets-sdk
npm install @emergence/em-runtime-utils-sdk

import { GovernanceClient } from '@emergence/em-runtime-governance-sdk';

const client = new GovernanceClient({
  baseUrl: 'https://<host>:8001',
  token: accessToken
});
const orgs = await client.organizations.list();

Pagination

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

# First page
GET /assets/artifacts?limit=20&page=1

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

The limit parameter controls page size (default varies by endpoint). The page parameter is 1-indexed.

Next Steps

API Authentication

Learn how to obtain and use JWT tokens for API access.

Error Codes

Understand error response formats and troubleshooting.

Python SDK

Use the auto-generated Python SDK for programmatic access.

TypeScript SDK

Use the auto-generated TypeScript SDK for frontend integration.

Overview

Platform APIs

Solution APIs

SDKs & Client Libraries

API Overview

API Overview

Base URLs

API Versioning

Common Headers

Required Headers

Response Headers

Rate Limits

Service Endpoints Summary

Governance API (Port 8001)

Assets API

Utils API

Talk2Data API (Data Insights)

Data Readiness API (Data Governance)

OpenAPI Specifications

SDKs

Next Steps

API Authentication

Error Codes

Python SDK

TypeScript SDK

Overview

Platform APIs

Solution APIs

SDKs & Client Libraries

Documentation Index

​API Overview

​Base URLs

​API Versioning

​Common Headers

​Required Headers

​Response Headers

​Rate Limits

​Service Endpoints Summary

​Governance API (Port 8001)

​Assets API

​Utils API

​Talk2Data API (Data Insights)

​Data Readiness API (Data Governance)

​OpenAPI Specifications

​SDKs

​Pagination

​Next Steps

API Authentication

Error Codes

Python SDK

TypeScript SDK

API Overview

Base URLs

API Versioning

Common Headers

Required Headers

Response Headers

Rate Limits

Service Endpoints Summary

Governance API (Port 8001)

Assets API

Utils API

Talk2Data API (Data Insights)

Data Readiness API (Data Governance)

OpenAPI Specifications

SDKs

Pagination

Next Steps