REST API

API reference

Every endpoint, generated from the live OpenAPI spec. Authenticate once with a client-credentials token, then call any of them. Each endpoint has its own link — copy it from the address bar.

Base URL https://api.smoo.aiv2.10.101801 endpoints

GET/organizations/{org_id}/agents

List all agents for an organization

Requires authentication

Path Parameters

Name	Type	Description
`org_id`required	`string`

Responses

200List of agentsarray

Property	Type	Description
`id`required	`string`(uuid)	The unique identifier for the agent.
`name`required	`string`	The name of the agent.
`icon`	`string`	The icon of the agent.
`types`required	`string[]`	The types of the agent.
`directions`required	`string[]`	The directions of the agent.
`summary`required	`string`	The summary of the agent.
`instructions`required	`object`	The instructions of the agent.
`examplePrompts`	`string[]`	Example prompts to help users start conversations (max 5, each max 100 chars).
`organizationId`required	`string`(uuid)	The organization identifier of the agent.
`authPublicClientId`required	`string`(uuid)	The public client identifier of the agent.
`authPublicClientSecret`required	`string`	The public client secret of the agent.
`authPublicClientAllowedOrigins`required	`string[]`	The allowed origins of the agent.
`widgetConfig`	`object`	Configuration for the chat widget appearance and behavior.(default: `{"iconType":"smooai","iconUrl":"https://smoo.ai","requireName":true,"requireEmail":true,"requirePhone":false,"allowAnonymous":false,"colors":{"text":"#f8fafc","background":"#040d30","primary":"#00a6a6","primaryText":"#f8fafc","secondary":"#ff6b6c","chatBubbleInbound":"#06134b","chatBubbleInboundText":"#f8fafc","chatBubbleOutbound":"#00a6a6","chatBubbleOutboundText":"#f8fafc","border":"#0a1f7a"}}`)
`personality`	`object`	Configuration for the agent's personality and behavior traits.(default: `{"preset":"bright","creativity":0.7}`)
`template`	`string`enum: [customer_support, developer_assistant, knowledge_expert, sales_outreach, internal_helpdesk, schedule_a_call, custom]	Template used to create this agent.
`visibility`	`string`enum: [public, internal]	Where this agent is accessible (public widget or internal dashboard).(default: `"public"`)
`role`	`string`enum: [customer, smoo_builder]	customer (default, built by the org) or smoo_builder (auto-provisioned org admin assistant).(default: `"customer"`)
`kind`	`string`enum: [chat, workflow]	SMOODEV-2204 — `chat` (conversational, default) or `workflow` (single-shot data pipeline like Signal Agent — no widget). DB column is NOT NULL with default `chat`, so reads always return a value; create can omit it to take the default.(default: `"chat"`)
`isBuiltin`	`boolean`	True only for the built-in Smoo Builder agent. Cannot be deleted; role is locked. Defaults to false so create callers can omit it.(default: `false`)
`enabled`	`boolean`	th-6e556c — lifecycle on/off switch. When false the agent stops serving: session-creation entry points (web chat + voice refuse; social channels silently drop). Defaults to true so existing agents and create callers that omit it stay live. Duplicated agents are created disabled.(default: `true`)
`responseMode`	`string`enum: [auto, approval]	SMOODEV-1168 — `auto` (default) sends agent responses immediately on the originating channel; `approval` writes drafts to conversation_drafts and suppresses dispatch for human review. DB column is NOT NULL with default `auto`, so reads always return a value; create can omit it to take the default.(default: `"auto"`)
`toolConfig`	`object`	Configuration for agent tools and integrations.(default: `{"enabledTools":[]}`)
`extensionConfig`	`object`	SMOODEV-2259 — per-agent SEP extension enablement. Intersected with the server allowlist; empty/missing is fail-closed (no extensions for this agent).(default: `{"enabledExtensions":[]}`)
`knowledgeSelection`	`unknown`	SMOODEV-775 — which org-scoped knowledge this agent can search. Default `all_org`; `selected` lets the agent subscribe to specific folders and/or documents. DB column is NOT NULL with a default, so reads always return a value; create can omit it to take the default.
`conversationWorkflow`	`object`	Structured goal + steps for multi-turn conversation flow. Optional — freeform-prompt agents work without this.
`assessmentRubric`	`object`	SMOODEV-2172 — per-agent assessment scoring rubric (dimensions × behavioral score bands + deterministic posture thresholds). Rendered host-side into the system prompt; record_assessment recomputes the posture from scores. Nullable — non-assessment agents omit it.
`callerIdentityResolution`	`object`	SMOODEV-670 — opt-in CRM contact lookup for personalization. UX only, NEVER an auth signal (phone/email headers are spoofable).(default: `{"enabled":false,"allowedFields":["firstName","lastName","jobTitle"]}`)
`voiceProfileId`	`string`(uuid)	SMOODEV-799 — reference to a row in voice_profiles. NULL means use the system default voice (Aria — peppy).
`greeting`	`string`	SMOODEV-798 / SMOODEV-932 — channel-agnostic initial greeting seed. composeChannelGreeting rephrases this per channel (voice, chat, sms). NULL falls back to per-channel defaults.
`thinkingTone`	`string`enum: [none, soft-chime, ambient-pulse, marimba-ticks]	SMOODEV-2931 — the looping tone voice callers hear while this agent thinks, so a slow tool turn does not read as a dropped call. `none` disables it; NULL takes the pipeline default (soft-chime).
`model`	`string`	SMOODEV-2172 — per-agent LLM model override for the smooth-operator engine (operator 1.22 AgentBehaviorConfig.model). NULL falls back to the deployment default (SMOOTH_AGENT_MODEL).
`maxIterations`	`integer`	SMOODEV-2172 — per-agent cap on the operator's tool-call loop (operator 1.22 AgentBehaviorConfig.max_iterations). NULL falls back to the engine's built-in iteration cap.
`createdBy`required	`string`(uuid)	The user identifier of the agent.
`createdAt`required	`string`(date)	The date and time the agent was created.
`updatedAt`required	`string`(date)	The date and time the agent was last updated.

400Bad request - validation error

Property	Type	Description
`message`required	`string`
`cause`	`string`

401Unauthorized

Property	Type	Description
`message`required	`string`
`cause`	`string`

404Not found

Property	Type	Description
`message`required	`string`
`cause`	`string`

500Internal server error

Property	Type	Description
`message`required	`string`
`cause`	`string`

Code Examples

const token = process.env.SMOO_ACCESS_TOKEN!;

const response = await fetch(`https://api.smoo.ai/organizations/${org_id}/agents`, {
    method: "GET",
    headers: {
        Authorization: `Bearer ${token}`,
    },
});

const data = await response.json();