Kimss SDK & API: Production Integration Guide

This is the authoritative reference for integrating Kimss into production. Kimss is a universal AI hub: you integrate both agent-based workloads (orchestrated chat, tools, and functions) and, where enabled for your tenant, model-level access (listing deployable models for routing or automation). This guide covers the Kimss Python SDK, direct REST usage, authentication, and the ownership-based permission model.

Public SDK source and releases: github.com/eyal81/kimss-python-sdk (mirrored from this monorepo’s kimss_sdk/). IDE integration (MCP): see Python SDK: MCP & IDEs.

For credits, plans, and model choice from a product perspective, see Models and Pricing and Usage and Kimss Credits in this documentation.

Foundry 2.x / Responses cutover (public release notes): release_notes_foundry_v2_responses.md.

1. Architecture & integration overview

In a typical production setup:

Management: Agent lifecycle (create/delete) is done in the Kimss web app; model catalog visibility and toggles (where your tenant has them) are also managed in-app or via supported admin and API operations.
Execution: Chat and automation go through the Kimss Python SDK or REST API with long-lived API keys (X-Kimss-Key).
Models: When the universal model gateway is on for your tenant, you can list models the same identity is allowed to use (see § 6.3), alongside existing agent endpoints.
Ownership model: You may chat with any agent you can see, but you can only modify (update instructions, add functions) agents you created—shared agents are read/chat for non-owners, enforced with 403 on update paths.

2. Installation

The Kimss SDK is available via PyPI. It requires Python 3.x and utilizes the requests library for synchronous HTTP communication.

Standard installation

pip install kimss

Optional PyPI extras

The same kimss package on PyPI supports optional dependency groups:

Extra	Command	Purpose
MCP	`pip install 'kimss[mcp]'`	Stdio Model Context Protocol server (`kimss-mcp-server`) for Cursor, Windsurf, and other MCP clients.
Privacy	`pip install 'kimss[privacy]'`	Optional PII redaction (Presidio) for sensitive pipelines.
Types	`pip install 'kimss[types]'`	Reserved for future typed models.
Dev	`pip install 'kimss[dev]'`	Test and lint tooling for contributors.

Full MCP setup (Cursor mcpServers, environment variables, tool list) is documented in Python SDK: MCP & IDEs.

Development / Editable mode

cd kimss_sdk
pip install -e .
# or with MCP + dev tooling:
pip install -e ".[dev,mcp]"

3. Authentication & Configuration

3.1 API Key Provisioning

API access requires a long-lived API key.

Steps

In the Kimss application navigate to:

Developer Settings -> API Keys

Generate a new API key.
Copy the key immediately. The secret is displayed only once.

Security Recommendations

Store keys in environment variables
Use secret managers (Azure Key Vault, AWS Secrets Manager, etc.)
Never commit API keys to version control

3.2 Connectivity

Initialize the client with the canonical Kimss API host. For production, use https://api.kimss.ai with no trailing slash.

from kimss import KimssClient

client = KimssClient(
    api_key="kimss_xxxxxxxxxxxxxxxxxxxxxxxx",
    base_url="https://api.kimss.ai"  # No trailing slash
)

4. Capability & Permission Matrix

Permissions are enforced server-side based on the user identity tied to the API key.

Feature	Scope	SDK Support	REST Endpoint
List Agents	Personal + Shared	REST Only	POST `/assistant_user_list/`
Chat / Inference	All accessible agents	Yes	POST `/v1/agents/run` (preferred); POST `/assistant_chat_stream/` for SSE on the legacy path envelope; POST `/assistant_chat/` for non-streaming JSON `res`
Update Agent	Personal Only	REST Only	POST `/update_assistant/`
Add Functions	Personal Only	Yes	POST `/agent_add_function/`
Create / Delete	Managed via Web UI	No	N/A

5. Detailed Permission Logic

5.1 Visibility (Listing)

The endpoint:

POST /assistant_user_list/

returns a unified list containing:

Personal Agents Agents created by the user (privacy: "personal")
Shared Agents Agents explicitly shared with the user's tenant.
System Agents Global agents provided by Kimss.

5.2 Ownership & Modification (The 403 Rule)

To preserve organizational integrity, Shared agents cannot be modified via API.

Authorized

Updating instructions or adding functions to agents where:

created_by == current_user

Unauthorized

Attempting to modify an agent shared with you will return:

403 Forbidden

Example error:

Editing is only allowed for agents you own. This agent is shared with you; you can view and chat but not modify it.

6. SDK Implementation

6.1 Agent interaction (conversations + Responses)

Kimss executes agents on Foundry 2.x using conversations and the Responses API. The JSON field thread_id is still the wire name for the conversation id returned from Kimss so existing HTTP clients keep working; new Python SDK (v2+) code uses the keyword conversation_id, which maps to thread_id in the POST body.

Preferred — Python (kimss ≥ 2.0)

from kimss import KimssClient

client = KimssClient(api_key="...", base_url="https://api.kimss.ai")

# First turn: omit conversation_id
res = client.agents.run("asst_xxxx", "Summarize Q1 risks.", stream=False)
cid = res.conversation_id  # may be None if the service omits it for this tenant

# Next turn: continue the same Foundry conversation
follow = client.agents.run(
    "asst_xxxx",
    "Compare to Q4.",
    stream=False,
    conversation_id=cid,
)

# Streaming: iterate SSE JSON chunks (same route)
for chunk in client.agents.run("asst_xxxx", "Stream this answer.", stream=True):
    ...  # handle dict events from Kimss / model stream

Legacy envelope (non-stream) — POST /assistant_chat/ remains available; execution still uses the modern runtime internally. Prefer /v1/agents/run for gateway-aligned routing and telemetry.

6.1b Custom JavaScript (embedded / white-label)

Use fetch against POST https://api.kimss.ai/v1/agents/run with "stream": true and parse text/event-stream lines. The example below is self-contained (no Kimss npm package): keep your API key on the server in production; shown inline only for clarity.

<!doctype html>
<html lang="en">
<head><meta charset="utf-8"/><title>Kimss stream demo</title></head>
<body>
  <pre id="out"></pre>
  <script>
    const API_KEY = "kimss_xxx";       // do not ship production keys to browsers
    const ASSISTANT_ID = "asst_xxx";
    let conversationId = null;

    async function send(usrChat) {
      const body = {
        assistant_id: ASSISTANT_ID,
        usr_chat: usrChat,
        stream: true,
        chat_type: "user_chat",
      };
      if (conversationId) body.thread_id = conversationId;

      const resp = await fetch("https://api.kimss.ai/v1/agents/run", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-Kimss-Key": API_KEY,
        },
        body: JSON.stringify(body),
      });
      const reader = resp.body.getReader();
      const dec = new TextDecoder();
      let buf = "";
      while (true) {
        const { value, done } = await reader.read();
        if (done) break;
        buf += dec.decode(value, { stream: true });
        let idx;
        while ((idx = buf.indexOf("\n\n")) >= 0) {
          const block = buf.slice(0, idx);
          buf = buf.slice(idx + 2);
          for (const line of block.split("\n")) {
            if (!line.startsWith("data:")) continue;
            const payload = line.slice(5).trim();
            if (payload === "[DONE]") continue;
            try {
              const evt = JSON.parse(payload);
              if (evt.thread_id) conversationId = evt.thread_id;
              document.getElementById("out").textContent += JSON.stringify(evt) + "\n";
            } catch (_) { /* ignore parse errors */ }
          }
        }
      }
    }
    send("Hello — stream a short reply.");
  </script>
</body>
</html>

Alternative SSE route: POST /assistant_chat_stream/ accepts the same assistant/message fields as /assistant_chat/ and streams events for integrations that already target that path.

Key behavior

First request without thread_id / conversation_id starts a new Foundry conversation.
Returning the thread_id from res (or SSE events) on the next call continues context.
Kimss does not expose classic Foundry run polling for standard chat; use streaming or wait for the full res on non-stream calls.

6.2 Extending Capability (Functions)

Available for Personal agents only.

This registers a tool definition that the agent can invoke during execution.

agent.add_function(
    name="get_order_status",
    description="Retrieve status for a specific order ID.",
    parameters={
        "type": "object",
        "properties": {
            "order_id": {
                "type": "string"
            }
        },
        "required": ["order_id"]
    }
)

Functions must follow a JSON schema structure describing:

function name
description
parameter definitions

6.3 Models and gateway (list / catalog)

When universal gateway v2 is enabled for your tenant, you can query which models are available to the current principal for routing, UI, or automation. If these return 404 with feature_disabled, the feature is not active for that environment or tenant.

List models (JSON body, authenticated)

POST /v1/models/list

or the alternate path (same behavior):

POST /v1/models/list/

Response shape (simplified): a JSON object whose res.models field contains a list of model records (ids, display metadata, and tenant enablement as implemented by the service). Use the response your tenant actually returns to drive dropdowns or server-side model selection.

Model settings catalog (browser or server-side with session / cookie auth as used by the app)

GET /api/v1/settings/models/catalog

Returns catalog rows for the Model Catalog / settings experiences; admin flows may also use POST /api/v1/settings/models/toggle to change tenant enablement where your role allows it (see product UI and your organization’s policy).

Note Base URL: call these on the canonical Kimss API host, https://api.kimss.ai, the same base_url used by KimssClient. Public GET /api/v1/settings/models/catalog is intended for authenticated browser or service patterns that already work with your Kimss session or approved integration model—API key traffic for model listing should use POST /v1/models/list as documented above.

6.4 MCP, streaming, Entra, and Usage Hub metadata

MCP (IDE tools): Install kimss[mcp] (package 2.x for conversation_id tool args) and run kimss-mcp-server (or uvx --with kimss[mcp] kimss-mcp-server). Exposes non-streaming tools for chat, v1 agent run/create, model completions, file upload, vector stores, and add-function. Configure KIMSS_API_KEY, optional KIMSS_BASE_URL and KIMSS_WORKSPACE_ID. See Python SDK: MCP & IDEs.
Streaming (library only): KimssClient.agents.run(..., stream=True) and KimssClient.models.create(..., stream=True) return an SSE iterator. MCP v1 tools do not stream.
Microsoft Entra ID: Headless workers can use KimssClient(credential=DefaultAzureCredential(), token_scope="api://<app-id>/.default", workspace_id=...) instead of an API key. See the public SDK README.
Usage Hub: The Python SDK may send X-Kimss-SDK-Context (base64url JSON) on agent/model routes for attribution in Product integrations. Remove it with before_request_hooks if your policy forbids sending caller paths. See Product integrations & execution logs.

7. Direct REST Patterns (Non-SDK)

Developers can integrate Kimss using standard HTTP requests.

Authentication uses the header:

X-Kimss-Key: <your_api_key>

List Agents

Endpoint

POST /assistant_user_list/

Body

{}

Chat / Inference (preferred)

Endpoint

POST /v1/agents/run

Use the Kimss Python SDK (client.agents.run(...)) when possible. POST /assistant_chat/ remains for older JSON integrations; both paths use the Responses-backed runtime.

Example request body (non-stream, simplified — Universal AI Gateway v2 must be enabled for /v1/agents/run):

{
  "assistant_id": "asst_xxx",
  "usr_chat": "Analyze this dataset",
  "stream": false,
  "chat_type": "user_chat"
}

Optional continuation: set thread_id to the conversation id returned in the previous res (same field name the SDK maps from conversation_id).

Update Agent (Personal Only)

Endpoint

POST /update_assistant/

Example request:

{
  "id": "asst_xxx",
  "instructions": "New system persona...",
  "model": "gpt-4-turbo"
}

8. Error Reference

Code	Status	Context
401	Unauthorized	Invalid, missing, or revoked `X-Kimss-Key` (or session bearer where applicable)
403	Forbidden	Attempted modification of a shared agent you do not own, or role insufficient for the route
404	Not Found	Invalid `assistant_id`, unknown conversation / `thread_id`, or feature disabled for the tenant (`feature_disabled` in body)
429	Too Many Requests	Often credits exhausted, rate limit, or subscription required — the Python SDK maps many cases to typed exceptions (`KimssCreditExhausted`, `KimssRateLimited`, `KimssSubscriptionRequired`); honor `Retry-After` when present
451	Unavailable For Legal Reasons	Trust & safety block—do not retry the same harmful payload; see Trust & safety
500	Server Error	Infrastructure anomaly; check system status

Streaming and gateway responses may wrap errors in an envelope (detail, message, or nested JSON). Parse defensively and map 401 / 451 to user-safe messages.

9. Production Best Practices

Environment Isolation

Use separate API keys for:

Development
Staging
Production

Stateless vs conversational automation

Prefer client.agents.run(..., stream=False) (or stream=True when you consume SSE) for one-shot and interactive flows. Use conversation_id (Python SDK ≥ 2) or JSON thread_id to continue a Foundry conversation.

Use client.chat / agent.query only when you intentionally target the /assistant_chat/ envelope; new integrations should standardize on /v1/agents/run.

Timeout Management

The standard chat timeout is:

120 seconds

Ensure your application properly handles long-running reasoning tasks.

Key Rotation

Periodically rotate API keys via:

Developer Settings -> API Keys

This mitigates the risk of credential leaks or compromise.

10. Support & Troubleshooting

If you encounter issues integrating with Kimss:

Verify your API key is valid and active.
Confirm your base_url is https://api.kimss.ai for production (or the documented staging host for staging).
Ensure your request headers include:

X-Kimss-Key: <your_api_key>

Check returned HTTP status codes using the error reference table above.
See Troubleshooting for browser cache, SSO, and common API codes.

For platform issues or infrastructure anomalies (HTTP 500 responses), consult the Kimss system status dashboard or contact platform support.

11. SDK versioning

The Kimss SDK follows semantic versioning:

MAJOR.MINOR.PATCH

MAJOR — Breaking API changes (e.g. 2.0.0: thread_id kwargs → conversation_id, Foundry conversation semantics; see release notes).
MINOR — New features without breaking compatibility
PATCH — Bug fixes and performance improvements

Upgrade recommendations:

pip install --upgrade kimss

When 2.0.0 is on PyPI, pin major version in production requirements (kimss>=2,<3) until you have migrated call sites.