Documentation

REST API

Use the REST API when you are outside the JavaScript SDK: your own backend jobs, internal automations, partner agents, Python scripts, CI, or any language with an HTTP client.

Base URLs

Auth API
https://auth.ductai.vercel.app
Agent API
https://api.ductai.vercel.app/v1
Shell Runtime
Hosted iframe and chat UI. Use this for embedding, not direct action calls.

Authenticate

Pick the credential that matches who is calling. Both paths hit the same /invoke and /message endpoints.

Company backend (st_)
Your servers, cron jobs, or internal LLM pipelines. Exchange DUCT_SECRET_KEY for a shell token at POST /v1/shell-token. Keep the secret on your infrastructure only.
Partner / external agent (at_)
Third-party automations that should not receive your root secret. Exchange shell_id + agent profile slug at POST /v1/agent-access-token. Scoped to the profile allow-list.

Shell token — company backend and internal automations

A shell token proves the caller is the company that owns the shell. Use this for jobs you run on your own servers. Never share sk_duct_… with external parties.

bash
curl -X POST https://auth.ductai.vercel.app/v1/shell-token \

Response: { "shell_token": "st_...", "expires_in": 3600 }. Store DUCT_SECRET_KEY in env vars only on the server side.

Agent access profile — partner and external agents

Create a named profile in Dashboard → Shell → Agent setup. External callers pass shellId + unique profile slug — nothing secret.

bash
curl -X POST https://auth.ductai.vercel.app/v1/agent-access-token \

Invoke An Action

bash
curl -X POST https://api.ductai.vercel.app/v1/shells/shell_acme_prod/invoke \

Ask A Natural-Language Question

Callers send a message to /message and Duct routes it to text, a tool call, or a clarification. Both agent_token and shell_token are accepted. Use shell_token for your own backend; use agent_token for partner agents that should not hold your root secret.

bash
# Company backend (shell token)

Python client — shell token (company backend)

python
import os

Python client — agent token (partner / external agent)

python
import os

JavaScript client — agent token (partner / external agent)

js
async function getAgentToken(shellId, profile) {

User Consent Token

For actions tied to a real user, pass a delegated user token in X-Duct-User-Consent. This is separate from the shell token and represents the user's authorization.

Do not expose secrets

Shell secret keys and user-token generation must stay server-side. Browser code should only call your own backend.

Search the Capability Network

Find shells that expose a matching capability across the Duct network. Use this before making a cross-shell call.

bash
curl -X POST https://api.ductai.vercel.app/v1/registry/search \
  -H "Content-Type: application/json" \
  -d '{"query": "trigger refund", "side_effects": true, "limit": 5}'

Cross-Shell Action

Call an action on another public shell directly from your shell. See the Inter-Shell Protocol docs for gate checks and the consent matrix.

bash
curl -X POST https://api.ductai.vercel.app/v1/intershell/message \