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.

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

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

Development / Editable mode

cd kimss_sdk
pip install -e .

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 `/assistant_chat/`
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 (Chat)

The SDK supports stateful conversations through thread persistence.

from kimss import KimssClient, Agent

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

# Initialize agent handle
agent = client.get_agent(agent_id="asst_xxxx")

# Execute query (creates new thread)
result = agent.query("Analyze our current Q1 trajectory.")

# Continue conversation in the same thread
follow_up = agent.query(
    "Compare this to Q4.",
    thread_id=result.get("thread_id")
)

Key behavior

First query automatically creates a thread
thread_id enables conversation continuation
Context is preserved across turns

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.

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

Endpoint

POST /assistant_chat/

Example request:

{
  "assistant_id": "asst_xxx",
  "message": "Analyze this dataset"
}

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`, `thread_id`, or feature disabled for the tenant (`feature_disabled` in body)
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 Logic

Prefer:

client.chat()

for one-off automated tasks.

Use:

agent.query(thread_id=...)

for user-facing conversational interfaces.

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
MINOR - New features without breaking compatibility
PATCH - Bug fixes and performance improvements

Upgrade recommendations:

pip install --upgrade kimss