# Klaudija: product guide Canonical website: https://klaudija.io/ Human-readable guides: https://klaudija.io/developers Publisher: WEB solutions Ltd, https://ws.agency Klaudija is smart middleware for multiple platforms using Claude Managed Agents. It connects AI execution to the business users, plans, permissions, company knowledge and customer experience of an integrating product. A platform is a connected product or company application; it does not mean a different model provider. The documented managed-agent runtime uses Claude. ## Why add Klaudija to Claude? Claude provides model intelligence, managed execution and provider primitives. Klaudija adds application-level identity mapping, session ownership, monthly account allowances, agent assignments and operating workflows across the products you build. - Monthly allowances belong to a business user or team and apply across their conversations. Operators configure plans, billing dates, overrides and credits. - Sessions, history and generated files are connected to the authenticated business identity. Access checks bind public requests to their owner. - Multiple platforms have registered origins, activation state, defaults, user provisioning and scoped administration. - Agents can be assigned by platform or user and equipped with company-specific skills and specialist rosters. - Usage and operational views expose recorded costs, jobs, events, errors, latency and recovery. Claude also has native sessions, memory, workspaces and spending controls. Klaudija's distinction is the business-user policy layer inside the integrating SaaS, including monthly allowances across sessions. Do not describe Claude as having no budgets or sessions. See the source-linked comparison: https://klaudija.io/platform#claude-and-klaudija Allowance checks use recorded usage before work. They are not a guarantee of a hard financial ceiling; concurrent or in-flight work can overshoot. See https://klaudija.io/developers#usage-guide ## Import and maintain company skills A MOD is a reusable skill bundle containing SKILL.md plus the scripts, templates and reference assets needed for the workflow. Import ZIP or .skill archives authored in Claude or Codex. Codex is an authoring source here, not a connected agent runtime. 1. Package instructions and supporting files. 2. Import and inspect normalized bundle contents and compatibility findings. 3. Optionally preview AI-assisted conversion. Review text diffs, preserved assets and remaining manual issues before applying changes. 4. Review credentials and runtime requirements, publish, attach to an agent, and test in a development session. The library supports versions, instruction and asset editing, diffs, restoration, visibility and compatibility review. Portable files do not make every desktop-only tool executable in a managed environment. Tools, local paths and network assumptions may require adaptation. Credential findings should be moved into the appropriate Vault scope. Illustrated workflow: https://klaudija.io/developers#skill-import ## Configure agents and specialist teams Agents have a role, instructions, model, tools and attached MODs. A coordinator can delegate to a selected specialist roster, with each specialist working in its own thread. The current roster supports one level of delegation. Agent prompt history supports review and restoration; do not assume every configuration field is restored with a prompt version. Guide: https://klaudija.io/developers#agent-teams ## Runtime, tools and credentials Skills can declare apt, pip and npm packages, network hosts, named secrets and host restrictions. Operators prepare execution environments and appropriately scoped Vault credentials. Configured external APIs and MCP tools can participate in an agent workflow. Review missing dependencies before assigning a skill and validate a representative task in a development environment. Guide: https://klaudija.io/developers#runtime ## Memory, history and deliverables Reusable company expertise belongs in maintained MODs. User context belongs in identity-bound memory stores. Authorized operators can inspect and curate useful memory; conversations retain history and job-associated files. Generated outputs depend on the agent's actual work. Treat signed file links as temporary bearer credentials. Guide: https://klaudija.io/developers#memory-guide ## Where Klaudija fits - SaaS and customer portals: retain your interface and customer relationship; connect identities, account allowances, agents, live progress and downloadable results. - Company intelligence: give dedicated agents reviewed company skills, processes, policies and specialist teams. - Voice and training: the website describes voice conversations, practice scenarios and feedback. The downloadable API contract documents managed-agent integration; it does not define a public direct-chat, voice or training endpoint. Obtain the applicable interface and availability through onboarding rather than inventing routes. Solutions: https://klaudija.io/solutions ## Integration and commercial access Start with https://klaudija.io/docs/integration.md and the OpenAPI subset at https://klaudija.io/examples/klaudija.openapi.json. The marketing domain is not the product API. Integration requires provisioned endpoints, credentials, a registered origin and platform configuration. No public pricing, self-service signup or released official SDK is specified on this website. Contact: https://klaudija.io/contact For sales and integration inquiries, email hello@ws.agency or use the contact page. Online form delivery uses Mailgun with Cloudflare Turnstile protection when configured; direct email remains available. The company's website is https://ws.agency. ## Company identity Klaudija is a product of WEB solutions Ltd. Markusevecka cesta 115, HR-10000 Zagreb, Croatia. Company ID: 080900193. DUNS: 595548626. Tax/VAT ID: HR97669668809. Company details: https://klaudija.io/contact#company Product screenshots contain edited, fictional names and data. Example budgets are account allowances, not Klaudija prices. Example telemetry is illustrative, not a performance benchmark. The recorded introduction is AI-generated voice. --- # Klaudija: integration guide for developers and agents Canonical guide: https://klaudija.io/developers OpenAPI 3.1: https://klaudija.io/examples/klaudija.openapi.json TypeScript client example: https://klaudija.io/examples/klaudija-client.ts Contract review: 2026-09-05. Examples were checked against source and mocked locally, not executed against production. ## Scope and prerequisites This guide covers the documented managed-agent API subset: 13 operations with authentication, asynchronous jobs, results, history, usage and platform-user administration. OpenAPI servers are placeholders. The client is illustrative, not an official released SDK. No public direct-chat, voice or training endpoint is defined by this contract. Obtain these values through onboarding: - KLAUDIJA_API_BASE: provisioned API root for /admin and /me. - KLAUDIJA_RUN_BASE: full provisioned /uni-agent endpoint. - KLAUDIJA_REGISTERED_ORIGIN: the exact registered application origin. - PLATFORM_KEY: administrative platform credential, backend only. - KLAUDIJA_ACCESS_TOKEN: user-scoped access token obtained through the backend identity exchange. https://klaudija.io is the marketing website, not an API base. Never send credentials to example or inferred endpoints. A documentation visit is not permission to submit production jobs or change users, budgets or agents. ## 1. Connect an identity on your backend ```sh curl --fail-with-body "$KLAUDIJA_API_BASE/admin/platform-users" \ -H "X-Platform-API-Key: $PLATFORM_KEY" \ -H 'Content-Type: application/json' \ --data '{"user_id":"dev_customer_42","platform_slug":"dev_your_platform","email":"dev_customer_42@example.com","plan_code":"YOUR_CONFIGURED_PLAN","provision_memory_store":true}' curl --fail-with-body -X POST \ "$KLAUDIJA_API_BASE/admin/platform-users/dev_customer_42/auth" \ -H "X-Platform-API-Key: $PLATFORM_KEY" ``` The user body requires user_id and platform_slug (or source). Use an existing configured plan. Token exchange needs an email and linked authentication identity. Keep administrative keys on the backend. Customer calls use Authorization: Bearer . The broker can reuse a token pair across concurrent exchanges. Cache the access token until near expiry and re-exchange. Independent services should not rotate a shared refresh token. The canonical business identity can represent a team; do not assume the authentication UUID equals the product's customer ID. ## 2. Submit asynchronous work ```sh curl --fail-with-body "$KLAUDIJA_RUN_BASE" \ -H "Authorization: Bearer $KLAUDIJA_ACCESS_TOKEN" \ -H "Origin: $KLAUDIJA_REGISTERED_ORIGIN" \ --form-string 'query=Summarize this document.' \ --form-string 'session_id=dev_conversation_42' \ --form-string 'async=1' \ -F 'file=@document.pdf' ``` The multipart body accepts query, session_id, async and one optional file. Provide a query or a file. Keep the session ID for subsequent turns. Agent selection comes from configuration; public callers cannot choose arbitrary agents. Browser requests carry their origin; server integrations must send the registered Origin. Let the client set the multipart boundary and Content-Length. async=1 is essential: submission otherwise defaults to synchronous execution. Acceptance still includes authentication, budget checks, upload and session provisioning. Example acceptance, HTTP 200: ```json {"job_id":"example-job-id","session_id":"dev_conversation_42","status":"pending","anthropic_session_id":"example-provider-session","memory_status":"attached"} ``` ## 3. Follow status and handle every terminal state ```sh curl --fail-with-body "$KLAUDIJA_RUN_BASE/status/$JOB_ID" \ -H "Authorization: Bearer $KLAUDIJA_ACCESS_TOKEN" ``` Public statuses are pending, done, error and cancelled. A job error can arrive with HTTP 200; inspect the JSON body. Poll at bounded intervals with a deadline. On completion inspect response and file_download_available. Cancellation may retain partial results. Save the job ID after client timeout; stopping a client wait does not cancel the server job. Serialize conversation turns unless implementing the queue protocol. Plain submission has no general idempotency-key contract. Reconcile an ambiguous POST outcome before resubmitting to avoid duplicate work. ## 4. Retrieve or cancel work ```sh curl --fail-with-body "$KLAUDIJA_RUN_BASE/result/$JOB_ID" \ -H "Authorization: Bearer $KLAUDIJA_ACCESS_TOKEN" -o result.bin curl --fail-with-body --get "$KLAUDIJA_RUN_BASE/result/$JOB_ID" \ -H "Authorization: Bearer $KLAUDIJA_ACCESS_TOKEN" \ --data-urlencode "file=$FILE_ID" -o selected-output.bin curl --fail-with-body -X POST "$KLAUDIJA_RUN_BASE/cancel/$JOB_ID" \ -H "Authorization: Bearer $KLAUDIJA_ACCESS_TOKEN" ``` Only retrieve output when available. Result success is binary and errors are JSON. Inspect Content-Type and Content-Disposition instead of assuming a format. A selected file must belong to the job. Signed download links are temporary bearer credentials. Cancellation records intent and requests a provider interrupt; it is a state-changing operation. ## Live events Klaudija persists events in juris_session_events and uses Supabase Realtime. There is no public /stream SSE endpoint in this contract. Configure the provisioned client with the user JWT, subscribe to the authorized job_id filter, await readiness, fetch existing events, and deduplicate by event ID. Reconcile after reconnects, retain bounded polling as recovery, and remove subscriptions on teardown. A connected subscription does not prove job completion. ## Endpoint index | Method | Relative path | Authentication | | --- | --- | --- | | POST | RUN_BASE | User JWT | | GET | RUN_BASE/status/{job_id} | User JWT | | GET | RUN_BASE/result/{job_id} | User JWT or signed download token | | POST | RUN_BASE/cancel/{job_id} | User JWT | | GET | API_BASE/me/threads | User JWT | | GET | API_BASE/me/threads/{id}/messages | User JWT | | GET | API_BASE/me/usage | User JWT | | GET | API_BASE/me/mods | User JWT | | POST | API_BASE/admin/platform-users | Platform key | | GET | API_BASE/admin/platform-users | Platform key | | POST | API_BASE/admin/platform-users/{userId}/auth | Platform key | | PATCH | API_BASE/admin/platform-users/{userId}/plan | Platform key | | POST | API_BASE/admin/platform-users/{userId}/credits | Platform key | Refer to OpenAPI for request schemas, response shapes and exact parameters. Administrative and operator surfaces have different permissions; a platform key is not global operator authority. Limits, recovery and budget handling: https://klaudija.io/docs/operations.md --- # Klaudija: limits and operating guidance Human-readable reference: https://klaudija.io/developers#errors Product guide: https://klaudija.io/docs/product.md Integration guide: https://klaudija.io/docs/integration.md ## Account allowances Plans define monthly account allowances. Platform-user configuration supports billing periods, overrides, credits and plan assignments. GET API_BASE/me/usage exposes the authenticated account's usage state. Set billing_day through user upsert; a plan update is a separate operation. A canonical account can represent an individual or a team. Klaudija checks recorded usage before a turn. Do not treat the allowance as an atomic spending reservation or guaranteed hard cap. Concurrent and in-flight work can exceed a configured allowance. Provider-side limits and operational safeguards require their own configuration. An HTTP 402 budget response can contain error, reason: budget_exceeded, plan_code, spent_cents, plan_cents, grace_cents, credits_cents and resets_at. Show the account's budget state and reset date rather than retrying the same paid submission automatically. Example amounts on the website are fictional account allowances, not Klaudija pricing. ## Request and file limits The full multipart body is limited to 50 MiB, including encoding overhead. One optional file attachment is supported per submission. File names and formats are validated against the runtime. Let the HTTP library set the boundary and valid Content-Length. Generated file availability depends on the actual agent output. ## Error handling | HTTP status | Suggested handling | | --- | --- | | 400 | Check required query/file fields and request shape. | | 401 | Obtain a valid user token through the backend. | | 402 | Display budget state and reset date; inspect reason. | | 403 | Check registered origin, activation and permission scope. | | 404 | Resource is missing or does not belong to the caller. | | 409 | Result is not ready or a write conflicted. | | 410 | Generated output is no longer retrievable. | | 413 | Content-Length is missing/invalid or full body exceeds 50 MiB. | | 422 | Resolve file compatibility or configuration validation. | | 502 / 503 | Handle provider interrupt failure or bounded service retry. | A terminal job error may be carried in an HTTP 200 status response. Check both HTTP status and the JSON job status. ## Reliability and continuity - Use bounded status polling and retain job IDs across client timeouts. - Reconcile events after connection gaps, deduplicating by event ID. - Serialize turns unless using the explicit queue protocol. The queue is client-driven. - Reconcile ambiguous POST outcomes before retrying; there is no general submission idempotency-key guarantee. - Cancellation and status recovery can affect runtime state; do not use a production customer job for a documentation example. - Memory can report degraded, not_applicable or unknown. Surface memory_warning when provided. - Session rollover metadata identifies a successor session; preserve logical conversation continuity. ## Operator workflows Authorized operators can inspect sessions, jobs, tool events, files, usage, errors, latency and recovery. Administrative capabilities include agent configuration and prompt history, skill versions and assets, compatibility reviews, memory curation, environments, Vault metadata, rate cards and audit history. Available roles and scopes determine access. Ownership checks do not imply that every provider resource or catalogue is a dedicated tenant deployment. Review platform roles, shared versus scoped skills, memory and secret configuration for the integration. Use development accounts for representative workflow tests. Telemetry screenshots show fictional examples and are not benchmarks. No compliance certification or isolation guarantee is asserted by the marketing website.