API Reference

REST API, end-to-end typed SDKs

Base URL: https://api.tropic.run/v1. Every endpoint returns predictable JSON with stable idempotency semantics. TypeScript + Python SDKs are fully typed against the same OpenAPI spec.

Auth

Bearer API keys. Scoped to read / write / admin. Rotate any time without downtime.

Idempotency

Pass `Idempotency-Key` on any POST. Safe retries up to 24h.

Rate limits

1000 req/min per key by default. Headers expose current window.

Authentication

curl

bash

curl https://api.tropic.run/v1/agents \
  -H "Authorization: Bearer sk_live_..."

Agents

POST

/v1/agents

Create a new agent with persona, knowledge, and channels.

GET

/v1/agents

List all agents in your workspace.

GET

/v1/agents/{id}

Retrieve a specific agent's config + metrics.

PATCH

/v1/agents/{id}

Update persona, tools, or knowledge sources.

DELETE

/v1/agents/{id}

Tombstone an agent (30-day soft-delete).

Sessions

POST

/v1/sessions

Start a new conversation session.

POST

/v1/sessions/{id}/messages

Send a user message and receive the agent response.

GET

/v1/sessions/{id}

Fetch a session's full transcript + metadata.

POST

/v1/sessions/{id}/handoff

Manually escalate a session to a human.

Knowledge

POST

/v1/knowledge/sources

Add a knowledge source (URL, Notion, Drive, upload).

POST

/v1/knowledge/sources/{id}/resync

Force a reindex right now.

GET

/v1/knowledge/search

Semantic search across all sources for this workspace.

Webhooks

POST

/v1/webhooks

Subscribe an endpoint to event types.

GET

/v1/webhooks

List all configured webhooks.

POST

/v1/webhooks/{id}/rotate-secret

Rotate the signing secret safely.

End-to-end example

send-message.ts

typescript

import { Tropic } from "@tropic/sdk";

const tropic = new Tropic({ apiKey: process.env.TROPIC_API_KEY });

const session = await tropic.sessions.start({
  agentId: "agent_01H…",
  context: { userId: "user_123", plan: "growth" },
});

const reply = await tropic.sessions.send(session.id, {
  role: "user",
  content: "Upgrade me to Enterprise.",
});

if (reply.handoffRequested) {
  // your CRM / support system takes over with the full transcript
  await escalateToHuman(session.id);
}

Ready to build against the API?

Grab a test key in the dashboard — every workspace gets one by default.

Start Free Full docs

API Reference

REST API, end-to-end typed SDKs

Base URL: https://api.tropic.run/v1. Every endpoint returns predictable JSON with stable idempotency semantics. TypeScript + Python SDKs are fully typed against the same OpenAPI spec.

Auth

Bearer API keys. Scoped to read / write / admin. Rotate any time without downtime.

Idempotency

Pass `Idempotency-Key` on any POST. Safe retries up to 24h.

Rate limits

1000 req/min per key by default. Headers expose current window.

Authentication

curl

bash

curl https://api.tropic.run/v1/agents \
  -H "Authorization: Bearer sk_live_..."

Agents

POST

/v1/agents

Create a new agent with persona, knowledge, and channels.

GET

/v1/agents

List all agents in your workspace.

GET

/v1/agents/{id}

Retrieve a specific agent's config + metrics.

PATCH

/v1/agents/{id}

Update persona, tools, or knowledge sources.

DELETE

/v1/agents/{id}

Tombstone an agent (30-day soft-delete).

Sessions

POST

/v1/sessions

Start a new conversation session.

POST

/v1/sessions/{id}/messages

Send a user message and receive the agent response.

GET

/v1/sessions/{id}

Fetch a session's full transcript + metadata.

POST

/v1/sessions/{id}/handoff

Manually escalate a session to a human.

Knowledge

POST

/v1/knowledge/sources

Add a knowledge source (URL, Notion, Drive, upload).

POST

/v1/knowledge/sources/{id}/resync

Force a reindex right now.

GET

/v1/knowledge/search

Semantic search across all sources for this workspace.

Webhooks

POST

/v1/webhooks

Subscribe an endpoint to event types.

GET

/v1/webhooks

List all configured webhooks.

POST

/v1/webhooks/{id}/rotate-secret

Rotate the signing secret safely.

End-to-end example

send-message.ts

typescript

import { Tropic } from "@tropic/sdk";

const tropic = new Tropic({ apiKey: process.env.TROPIC_API_KEY });

const session = await tropic.sessions.start({
  agentId: "agent_01H…",
  context: { userId: "user_123", plan: "growth" },
});

const reply = await tropic.sessions.send(session.id, {
  role: "user",
  content: "Upgrade me to Enterprise.",
});

if (reply.handoffRequested) {
  // your CRM / support system takes over with the full transcript
  await escalateToHuman(session.id);
}

Ready to build against the API?

Grab a test key in the dashboard — every workspace gets one by default.

Start Free Full docs