# Invoke from your application

Call a deployed agent from your own backend: discover the workspace, create a session, start a run, and follow it to a result.

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.

You need an access token for the Tanomis API audience and an agent enabled for the tenant you
will select. A backend gets its token from an automation client with the `invoke` profile; see
[Authenticate a backend](/guides/run/authenticate-your-backend). The CLI's human login is not an
application credential.

## 1. Discover the workspace once

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

```bash title="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:

```text
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

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

```bash title="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

```bash title="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

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

```bash title="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](/guides/run/stream-and-replay-events).

## 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](/guides/run/approval-required-actions).

## 6. Finish

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

```bash title="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

| You want | Use |
|---|---|
| One independent request, streamed, no retries to reason about | [Invoke once and stream](/api/agents/invoke-agent) |
| Retries, several runs over the same context, file attachments, approvals, reconnection | An explicit session, as above |

## Where to go next

- [Platform API](/api): every endpoint with request and response samples in cURL, Python, and
  TypeScript.
- [Sessions and runs](/concepts/sessions-and-runs): state, retries, concurrency, recovery.
- [Attach files to a session](/guides/run/attach-files): give the agent documents to work on.