6.2 Call employees from business systems

Business systems can delegate order checks, research summaries or ticket analysis to existing AI employees and track results by work ID. HTTP, the SDK and MCP share employee identity, business scope, BYOK and the workbench Task/Run execution pipeline.

This interface calls Teloa employees. To let employees read an external service, see MCP used by employees.

Create an integration key

Open Settings > Employee integrations, select an active employee with complete responsibilities, and choose its business scope and key lifetime. Access defaults to read-only. Starting, continuing or requesting cancellation of work requires the owner to select those permissions. Creating a key does not execute work or grant additional employee tools.

The API key is shown once. Save it in your business server’s secret manager, never in chat, browser frontend code or a repository. A configured callback also receives a separate signing secret, shown once. Save it together with the API key. If the signing secret is lost, revoke and recreate the integration.

• Keys bind a fixed employee configuration version and one business scope. Changes to responsibilities, tool grants or employee activation can require a new owner grant.
• Each integration permits 1–4 unfinished work items, selected by the owner. Existing platform admission and work budgets still apply.
• Rotating a key immediately invalidates the old API key while preserving work and results. It does not rotate the callback signing secret.
• Expiration or revocation rejects new requests, prevents queued dispatch and cancels future callbacks. Stop already accepted execution separately in the workbench. An external request already in flight may complete.
• Browser startup tokens and cookies cannot replace an integration key. Callers cannot approve tools, modify employees or select Full access through this API.

HTTP and OpenAPI

The host serves /api/v1/openapi.json using OpenAPI 3.1 with request and response JSON Schemas. Business API requests use:

Authorization: Bearer <integration-key>
Content-Type: application/json
Idempotency-Key: <UUID persisted by the caller>

Persist a command’s idempotency key before sending it. After a disconnect or missing response, retry the same UUID and request body. Reusing a key for another body, action or work item returns 409. The SDK does not generate replacement identities or automatically retry mutations.

Operation	HTTP path	Permission
Discover the granted employee	GET /api/v1/employees	read
Start work	POST /api/v1/works	execute
Read state and version	GET /api/v1/works/{workId}	read
Provide the next round’s instructions	POST /api/v1/works/{workId}/inputs	execute
Request cancellation	POST /api/v1/works/{workId}/cancel	cancel
Read a fixed result	GET /api/v1/works/{workId}/result?version=1	read
Resume event reads	GET /api/v1/works/{workId}/events?after=0	read

Start bodies are {employeeId, input, title?}, with at most 6000 characters of input and 120 characters in a title. Continue bodies are {expectedVersion, input}; cancellation uses {expectedVersion}. Unknown fields are rejected. A 202 mutation response means accepted, not completed.

Continue only after the current round ends, using its latest expectedVersion. The work ID stays the same and a new Task/Run round is created. Provide complete instructions for that round; the host adds up to 1500 characters of the previous fixed result as context. Earlier results remain readable by version.

TypeScript / JavaScript SDK

npm install @teloa/sdk

import {TeloaClient} from '@teloa/sdk'

const client = new TeloaClient({baseUrl, apiKey})
const {items: employees} = await client.listEmployees()
// The business system has already persisted requestId.
const work = await client.startWork({
  employeeId: employees[0].id,
  input: 'Check this authorized set of order records…',
}, {requestId})

const current = await client.getWork(work.id)
if (current.state === 'succeeded') {
  const result = await client.getResult(work.id)
  // Save result.version, sha256, review and your business writeback receipt.
}

The SDK has no additional runtime dependencies. It uses Fetch, supports AbortSignal and timeouts, requires HTTPS except on loopback, and does not follow redirects. Other languages can call the documented HTTP API without reproducing internal RPC.

States, results and errors

State	Meaning
queued	Saved, awaiting dispatch
running	Accepted by the native runtime or executing
waiting	Awaiting approval, owner recovery or resolution of a blocker
succeeded	The round ended normally and saved a nonempty fixed result
failed	No valid result was obtained, or configuration became invalid
cancel_requested	Cancellation requested, settlement not yet confirmed
cancelled	Cancellation confirmed, or withdrawn before dispatch

Fixed results include work ID, round, version, text, SHA-256 and review: accepted|unreviewed. Successful execution does not imply a passed delivery review, and review does not replace final business or owner acceptance. The owner handles approvals in the workbench; the integration cannot approve tools for them.

Errors use {error:{code,message,requestId}}. HTTP 401 means an invalid, expired, rotated or revoked key; 403 means the operation was not granted; 404 means work is outside this integration or a result version is absent; 409 means a version, idempotency or work-state conflict; 413/415 indicate size or content-type errors; 429 means the granted concurrency limit was reached; 503 means the service is temporarily unavailable. Recover timeouts with the original idempotent identity rather than assuming a fresh execution is safe.

MCP Server for external agents

Use the host’s /mcp endpoint with Streamable HTTP and the same integration Bearer key. Tools are:

teloa_list_employees, teloa_start_work, teloa_get_work, teloa_continue_work, teloa_cancel_work, teloa_get_result, teloa_list_work_events.

Only granted operations are advertised. Guessing a hidden tool name does not increase permissions. Mutations carry a persistent requestId; continuation and cancellation also require the work version. Long work returns an ID promptly, then callers read state or results. It does not occupy a tool connection for the entire job. MCP Tasks extensions and A2A support are not advertised.

Signed CloudEvents callbacks

The owner fixes the callback URL when creating an integration; an external work request cannot substitute a destination. Changes send CloudEvents 1.0 with type ai.teloa.work.changed.v1 and content type application/cloudevents+json. Events contain work state and result version, without input text, credentials or result content.

Headers are teloa-webhook-id, teloa-webhook-timestamp and teloa-webhook-signature. The signature is:

v1=<hex HMAC-SHA256(signingSecret, timestamp + "." + rawBody)>

Verify the raw body and timestamp before parsing JSON. The SDK’s verifyWebhook accepts a five-minute window by default. Receivers persist event IDs for deduplication and use work versions to handle potentially out-of-order notifications. Signature verification alone does not deduplicate events.

Each attempt has a 10-second timeout and does not follow redirects. Delivery automatically attempts up to five times, preserving the event ID; success requires 2xx. Inspect delivery records and manually retry failed events in Settings. Queues, cursors, fixed results and pending deliveries survive restarts. CloudEvents defines the envelope; Teloa’s persisted records, leases and retries implement delivery reliability.