Skip to content
TanomisDocs
Open Console

Invoke from your application

2 min readUpdated

Once a version is enabled for a tenant, your product calls it over HTTP. The sequence is the same for every agent: discover your workspace, create a session, start a run, follow its events, read the result.

1. Discover the workspace once

Section titled “1. Discover the workspace once”

Ask which organizations and tenants the token may use, and keep the pair you choose:

Terminal
curl "https://api.tanomis.com/v1/me/workspaces" \
  -H "Authorization: Bearer $TANOMIS_TOKEN"

Copy organization_id and the selected tenant’s tenant_id into the two workspace headers on every later request:

X-Organization-ID: org_abc123
X-Workspace-Tenant-ID: customer-production

The headers select context. They cannot widen what the token grants.

2. Create a session

Section titled “2. Create a session”

A session is the continuity boundary for one enabled agent: it keeps the agent’s workspace, serializes runs, and is what you retry against.

Terminal
curl -X POST "https://api.tanomis.com/v1/sessions" \
  -H "Authorization: Bearer $TANOMIS_TOKEN" \
  -H "X-Organization-ID: org_abc123" \
  -H "X-Workspace-Tenant-ID: customer-production" \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"support-copilot","idempotency_key":"support-case-1842"}'

Send an idempotency_key tied to your own unit of work. A retry with the same key and body returns the same session instead of creating another.

3. Start a run

Section titled “3. Start a run”
Terminal
curl -X POST "https://api.tanomis.com/v1/sessions/$SESSION_ID/runs" \
  -H "Authorization: Bearer $TANOMIS_TOKEN" \
  -H "X-Organization-ID: org_abc123" \
  -H "X-Workspace-Tenant-ID: customer-production" \
  -H "Content-Type: application/json" \
  -d '{"input":{"prompt":"Draft a reply to this customer."},"idempotency_key":"support-case-1842-reply-1"}'

The response is the admitted run. Its id and status are the authoritative state from here on.

4. Follow the run

Section titled “4. Follow the run”

Stream the run’s events as server-sent events and store the last event id you processed:

Terminal
curl --no-buffer "https://api.tanomis.com/v1/sessions/$SESSION_ID/runs/$RUN_ID/events" \
  -H "Authorization: Bearer $TANOMIS_TOKEN" \
  -H "X-Organization-ID: org_abc123" \
  -H "X-Workspace-Tenant-ID: customer-production" \
  -H "Accept: text/event-stream"

If the connection drops, reconnect with Last-Event-ID and the stream resumes after it. The terminal events are run_completed, run_cancelled, and error. When a stream ends without one, read the run and reconnect only while it is still non-terminal. The complete consumer loop, including deduplication, is in Stream and replay events.

5. Handle a pause for a person

Section titled “5. Handle a pause for a person”

If the agent reaches an action that needs approval, or asks a question, the run pauses and the session reports awaiting_input: true. List the session’s pending interactions, show the decision to a person, and answer by the interaction’s key. The run continues from where it paused. See Approval-required actions.

6. Finish

Section titled “6. Finish”

When no more work will use the session, stop it to release its runtime:

Terminal
curl -X POST "https://api.tanomis.com/v1/sessions/$SESSION_ID/stop" \
  -H "Authorization: Bearer $TANOMIS_TOKEN" \
  -H "X-Organization-ID: org_abc123" \
  -H "X-Workspace-Tenant-ID: customer-production"

A stopped session can be resumed later. Idle sessions are suspended automatically and restored when work arrives, so you do not have to stop a session between turns of the same conversation.

Choosing between one-shot and sessions

Section titled “Choosing between one-shot and sessions”
You want Use
One independent request, streamed, no retries to reason about Invoke once and stream
Retries, several runs over the same context, file attachments, approvals, reconnection An explicit session, as above

Where to go next

Section titled “Where to go next”