Embed Kumo's complete model and run loop, point your own agents at Kumo, or connect Kumo to the systems you already run. Every request is a named user; every model call, approval, tool call, receipt, and outcome is traceable.
Tokens are minted per user, per workspace. The API applies the same visibility model as the app: self-service users see themselves, managers their team, HR the workspace. Scopes can only narrow that further.
The REST endpoints, the OpenAPI spec, this reference, and the MCP server's tool list are all generated from the same operation registry the runtime executes. Docs cannot go stale by construction.
Writes run through the platform's own engines: validation, approvals, notifications included. Every MCP call, inbound or outbound, lands in the audit log with who, what, and when.
Four named products, one permission and audit model: Kumo AI Platform, Kumo API, Kumo MCP, and Kumo HR Agent Kit SDK.
Kumo’s model, planner, durable run loop, approvals, co-signature, artifacts, memory, credits, and tamper-evident audit in one governed platform.
Embed the complete Kumo Agent or call individual HR operations through a versioned REST and Agent API with delegated identity.
A matched server, client, and outbound Connector. Your systems call Kumo; Kumo calls the named tools you choose to publish.
A typed TypeScript client, headless controller, and accessible React panel for putting Kumo inside a customer application.
Use Kumo's complete agent in your product, let another agent call Kumo, or let Kumo act across your systems. All three preserve named-user permissions, approvals, credits, and the same tamper-evident audit trail.
Embed
The Agent API and SDK run Kumo's own model, planner, durable loop, approvals, artifacts, and audit trail inside your customer experience.
Embed Kumo →Inbound
Claude Code, Cursor, VS Code, or anything you have built yourself posts JSON-RPC to https://kumohr.com/api/mcp with a personal access token. The tool list is your API, filtered to that token's scopes.
Outbound
An admin connects any MCP server under Settings → Connections: a published URL, or an outbound connector that dials out from inside your network. Every external action waits for a person to approve it.
Set up outbound →Create a token in Kumo under Settings → API access. Pick a name and the scopes it should carry. The secret is shown exactly once. Send it on every request; revoke it any time from the same screen. After you mint one, the same connect buttons appear with the token already filled in.
leave:readRead leave requests and balancesleave:writeCreate leave requestsreports:readRun read-only reportsagent:runStart and continue Kumo agent workagent:readRead agent conversations, runs, and eventsagent:approveApprove or decline agent actionsagent:artifactsUpload inputs and retrieve agent deliverablesaudit:readRead and export the agent audit trailNeed a token? Sign in and open Settings → API access.
This is Kumo's model and durable run loop, not a customer-supplied chatbot. Your backend exchanges one admin-created integration credential for a short-lived credential delegated to an existing Kumo user. Runs inherit that user's live tenant role; scopes can only narrow it.
Personal tokens and admin integration credentials are created under Settings → API access. Secrets are shown once, stored as hashes, independently scoped, expirable, and revocable. Integration credentials stay on your backend; browsers receive only short-lived delegated credentials.
exchange_agent_tokenagent:runPOST /api/v1/agent/tokenlist_agent_threadsagent:readGET /api/v1/agent/threadscreate_agent_threadagent:runPOST /api/v1/agent/threadsget_agent_threadagent:readGET /api/v1/agent/threads/{id}send_agent_messageagent:runPOST /api/v1/agent/threads/{id}/messagesget_agent_runagent:readGET /api/v1/agent/runs/{id}stream_agent_runagent:readGET /api/v1/agent/runs/{id}/eventsdecide_agent_runagent:approvePOST /api/v1/agent/runs/{id}/decisionsanswer_agent_runagent:runPOST /api/v1/agent/runs/{id}/answerscancel_agent_runagent:approvePOST /api/v1/agent/runs/{id}/canceldecide_agent_actionagent:approvePOST /api/v1/agent/runs/{id}/actions/{actionId}/decisionsupload_agent_attachmentagent:artifactsPOST /api/v1/agent/attachmentslist_agent_artifactsagent:artifactsGET /api/v1/agent/artifactsget_agent_artifactagent:artifactsGET /api/v1/agent/runs/{id}/artifacts/{artifactId}download_agent_artifactagent:artifactsGET /api/v1/agent/runs/{id}/artifacts/{artifactId}/downloadlist_agent_auditaudit:readGET /api/v1/agent/auditexport_agent_auditaudit:readGET /api/v1/agent/audit/exportverify_agent_auditaudit:readPOST /api/v1/agent/audit/verifylist_agent_webhooksagent:readGET /api/v1/agent/webhookscreate_agent_webhookagent:runPOST /api/v1/agent/webhooksdisable_agent_webhookagent:runDELETE /api/v1/agent/webhooks/{id}Mutations use Idempotency-Key. Run events are resumable SSE with event IDs. Webhooks are signed and retried. Responses carry request and audit correlation IDs so one external request can be followed through the model, approval, tool, connected system, receipt, artifact, credits, and final outcome.
Point any MCP-capable agent at https://kumohr.com/api/mcp (streamable HTTP, server kumo-hr) with your token in the Authorization header. Protocol versions 2025-06-18 and 2025-03-26. Its tool list is your API: the same operations below, filtered to your token's scopes.
Opens Cursor and asks you to confirm the server.
Any other client reads the same thing from a standard mcp.json:
Your agent can only do what your role allows. The same RBAC that gates the app gates every tool call; the token cannot escalate.
tools/list only advertises operations the token's scopes permit, so an agent holding a read-only token never even sees the write tools.
Every tool call is recorded in the audit log: which token, which tool, which arguments, and whether it succeeded. You can see everything it did.
One tool per operation, named after it. A token only sees the rows its scopes cover. This list is generated from the same registry the server executes.
get_meany tokenGET /api/v1/melist_leave_requestsleave:readGET /api/v1/leave/requestscreate_leave_requestleave:writePOST /api/v1/leave/requestsuntaken_leave_reportreports:readGET /api/v1/reports/untaken-leave4 operations, and tools only; no MCP resources or prompts yet. Authentication is a personal access token in a header, which covers Cursor, Claude Code, and VS Code. Hosted connectors that require OAuth, such as ChatGPT, cannot connect yet. We would rather say so than ship a button that fails.
Kumo is also an MCP client. An admin allow-lists a server under Settings → Connections. Its tools join the agent's catalogue as mcp__<name>__<tool>. This is how Kumo reaches a calendar, a chat tool, an ERP, an LMS, or anything else that speaks MCP, not a special case for one vendor.
External tools never run unattended. The person sees which system, which operation, and the arguments, then approves. There is no setting that turns this off.
Each call carries who asked, which workspace, and which approved action as headers and JSON-RPC metadata, so it shows against the right name in that system's own audit trail.
Approving a retried step sends the same idempotency key, so an adapter that honours it cannot apply the same change twice.
If the system can publish an https MCP endpoint, register that URL. If it lives on a network that will never accept inbound traffic, add an outbound connector instead: same tools, same approval, no inbound port.
You run a small process beside the system you already have. It dials out to Kumo, publishes the tools on the local adapter, and takes approved calls. No inbound firewall rule, no public URL, no certificate for you to manage.
Add the connector in Settings → Connections. The pairing token is shown once. Point MCP_URL at any local MCP adapter: the system you already run, or a thin wrapper beside it.
Base URL https://kumohr.com. Responses use a { data } / { error: { code, message } } envelope with X-RateLimit-* headers. The machine-readable version of this reference lives at /api/v1/openapi.json.
Returns the authenticated user, workspace (tenant), role, employee id, and the scopes this token carries. Use it to verify a token before wiring anything else.
Lists leave requests you are allowed to see: your own for self-service roles, your team’s for line managers, your department’s for directors, the whole workspace for HR and admins. Filter by status and date range.
statusstringFilter by status. One of: PENDING, APPROVED, REJECTED, CANCELLED, IN_PROGRESS, COMPLETED.fromstringOnly requests ending on or after this date (YYYY-MM-DD).tostringOnly requests starting on or before this date (YYYY-MM-DD).limitnumberMax rows to return (1–200, default 50).Books time off for the token’s user through the platform’s own leave engine. Policy validation, balance movement, approval routing, and notifications all run exactly as from the app. Pass start_date plus either end_date or days; the policy defaults to annual leave.
start_daterequiredstringFirst day off (YYYY-MM-DD).end_datestringLast day off, inclusive (YYYY-MM-DD). Use this OR days.daysnumberNumber of consecutive calendar days off. Use this OR end_date.policystringLeave policy name, e.g. "Annual Leave". Defaults to the annual policy.policy_idstringExact policy id (overrides policy).reasonstringOptional short reason.half_daybooleanTrue for a single half-day request.Per-employee untaken leave for a year: allocated, used, and remaining days with department and manager, sorted by most untaken first. Runs through the same permission-gated reporting tool Kumo’s agent uses. Your role decides whose rows you see.
yearnumberBalance year (defaults to the current year).min_untaken_daysnumberOnly employees with at least this many untaken days.policystringLeave policy name filter (defaults to annual policies).REST failures use the { error: { code, message } } envelope. Over MCP the same failures come back as a tool result with isError set, so your agent can read the reason rather than crashing. GET https://kumohr.com/api/mcp returns 405; this server is POST-only. Unauthenticated calls return 401 with WWW-Authenticate.
401Missing, invalid, revoked, or expired token403Token is missing the required scope, or the user's role lacks access429Over 60 requests per minute for this token; see the Retry-After headerEvery REST response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, so you can back off before you get there.