Simwood

https://docs.simwood.com
Admin
Simwood is a telecommunications carrier platform providing APIs for voice services, Conversational...
Tokens:99,487
Snippets:934
Trust Score:9.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example Response for Get Webhooks

Source: https://docs.simwood.com/services/conversational-ai/reference/tag/webhooks/get/webhooks

Example JSON response returned with status 200 when webhook configurations are found.

```json
[
  {
    "id": "string",
    "agent_id": null,
    "event_type": "conversation.completed",
    "url": "https://example.com",
    "request_headers": {
      "additionalProperty": "string"
    },
    "enabled": true,
    "created_at": "2026-07-18T10:26:52.866Z",
    "updated_at": "2026-07-18T10:26:52.866Z"
  }
]

```

--------------------------------

### Example response for get configuration template

Source: https://docs.simwood.com/services/intelligence/reference/tag/configuration-templates/get/configuration-templates/template_id

Shows the JSON structure returned on a successful request. The definition field is an object that can contain additional properties.

```json
{
  "id": 1,
  "name": "string",
  "description": "string",
  "version": 1,
  "created_at": "string",
  "updated_at": "string",
  "definition": {
    "additionalProperty": "anything"
  }
}
```

--------------------------------

### Example response for get knowledge base document

Source: https://docs.simwood.com/services/conversational-ai/reference/tag/knowledge-base/get/knowledge-base/id

Example JSON response returned with a 200 status. Shows the document fields including id, name, type, size_bytes, source_url, and timestamps.

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "string",
  "type": "url",
  "size_bytes": 1,
  "source_url": null,
  "created_at": "2026-10-14T03:43:13.637Z",
  "updated_at": "2026-10-14T03:43:13.637Z"
}

```

--------------------------------

### GET /configurations

Source: https://docs.simwood.com/services/intelligence/reference/tag/configurations

Retrieves a list of all configurations.

```APIDOC
## GET /configurations

### Description
Retrieves a list of all configurations.

### Method
GET

### Endpoint
/configurations

### Response
#### Success Response (200)
- **configurations** (array) - List of configuration objects.

#### Response Example
{
  "configurations": []
}
```

--------------------------------

### Example 200 response for list knowledge base documents

Source: https://docs.simwood.com/services/conversational-ai/reference/tag/knowledge-base/get/knowledge-base

Example 200 response body for GET /knowledge-base. Contains a documents array with id, name, type, size_bytes, source_url, and timestamps. The type can be 'url' and size_bytes is a number.

```json
{
  "documents": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "string",
      "type": "url",
      "size_bytes": 1,
      "source_url": null,
      "created_at": "2026-10-14T03:43:13.252Z",
      "updated_at": "2026-10-14T03:43:13.252Z"
    }
  ]
}
```

--------------------------------

### GET /intelligence/v1/configuration-templates

Source: https://docs.simwood.com/services/intelligence/reference/tag/configuration-templates/get/configuration-templates

Returns the active platform configuration templates available to your account, paginated. Each item is a summary; fetch a single template to get its full definition.

```APIDOC
## GET /intelligence/v1/configuration-templates

### Description
Returns the active platform configuration templates available to your account, paginated. Each item is a summary; fetch a single template to get its full definition.

### Method
GET

### Endpoint
https://api.simwood.com/intelligence/v1/configuration-templates

### Parameters
#### Query Parameters
- **cursor** (string, nullable) - Optional - Pagination cursor from a previous response's `next_cursor`. Omit for the first page.
- **limit** (integer) - Optional - Maximum number of templates to return (1–100, default 20).

### Request Example
```
curl https://api.simwood.com/intelligence/v1/configuration-templates \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **items** (array) - List of configuration template summaries.
  - **id** (integer) - Template ID.
  - **name** (string) - Template name.
  - **description** (string) - Template description.
  - **version** (integer) - Template version.
  - **created_at** (string) - Creation timestamp.
  - **updated_at** (string) - Last update timestamp.
- **next_cursor** (string) - Pagination cursor for the next page.

#### Response Example
```
{
  "items": [
    {
      "id": 1,
      "name": "string",
      "description": "string",
      "version": 1,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "next_cursor": "string"
}
```

### Error Responses
- **403** - Missing gateway headers or insufficient scope.
- **422** - Validation Error.

```

--------------------------------

### Metadata field example

Source: https://docs.simwood.com/services/conversational-ai/concepts/conversations

JSON example of the metadata field, containing start_time_unix_secs, accepted_time_unix_secs, and call_duration_secs.

```json
"metadata": {
  "start_time_unix_secs": 1719820800,
  "accepted_time_unix_secs": 1719820802,
  "call_duration_secs": 143
}
```

--------------------------------

### Transcript array example

Source: https://docs.simwood.com/services/conversational-ai/concepts/conversations

JSON example of the transcript array, showing turns with role, message, and time_in_call_secs. Each turn may also include tool_calls and tool_results when applicable.

```json
"transcript": [
  {
    "role": "agent",
    "message": "Hello, thanks for calling. How can I help you today?",
    "time_in_call_secs": 0.0
  },
  {
    "role": "user",
    "message": "I'd like to cancel my subscription.",
    "time_in_call_secs": 3.4
  }
]
```

--------------------------------

### GET /intelligence/v1/configurations

Source: https://docs.simwood.com/services/intelligence/reference/tag/configurations/get/configurations

Returns your account's configurations, newest first and paginated. Each item is a summary (identity, version, active state, and derived sync_state); fetch a single configuration to get its resolved operators and actions. Follow next_cursor to page through the list.

```APIDOC
## GET /intelligence/v1/configurations

### Description
Returns your account's configurations, newest first and paginated. Each item is a summary (identity, version, active state, and derived sync_state); fetch a single configuration to get its resolved operators and actions. Follow `next_cursor` to page through the list.

### Method
GET

### Endpoint
https://api.simwood.com/intelligence/v1/configurations

### Authentication
Auth Required. Required scope: `intelligence:read`

### Parameters
#### Query Parameters
- **cursor** (string, nullable) - Optional - Pagination cursor from a previous response's `next_cursor`. Omit for the first page.
- **limit** (integer) - Optional - Maximum number of items to return (1–100, default 20). Default: 20. Min: 1, Max: 100.

### Request Example
```
curl https://api.simwood.com/intelligence/v1/configurations \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **items** (array) - List of configuration summaries.
  - **uuid** (string) - Configuration UUID.
  - **name** (string) - Configuration name.
  - **description** (string) - Configuration description.
  - **version** (integer) - Configuration version.
  - **template_id** (integer) - Template ID.
  - **is_active** (boolean) - Whether the configuration is active.
  - **sync_state** (string) - Derived sync state (e.g., "live").
  - **created_at** (string) - Creation timestamp.
  - **updated_at** (string) - Last update timestamp.
- **next_cursor** (string) - Cursor for the next page, if any.

#### Response Example
```
{
  "items": [
    {
      "uuid": "string",
      "name": "string",
      "description": "string",
      "version": 1,
      "template_id": 1,
      "is_active": true,
      "sync_state": "live",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "next_cursor": "string"
}
```

### Error Responses
#### 403 - Missing gateway headers or insufficient scope
- **application/json** - Error response.

#### 422 - Validation Error
- **application/json** - Error response.

```

--------------------------------

### POST /sessions

Source: https://docs.simwood.com/services/intelligence/reference/tag/sessions

Creates a new session to start realtime analysis on a live call.

```APIDOC
## POST /sessions

### Description
Creates a new session to start realtime analysis on a live call.

### Method
POST

### Endpoint
/sessions

```

--------------------------------

### Create configuration with curl POST to /configurations

Source: https://docs.simwood.com/services/intelligence/guides/start-from-a-template

Creates a configuration you own by POSTing the completed template definition. Pass template_id for lineage only; later template changes never affect your configuration. The response returns your configuration's uuid. To dry-run without persisting, use POST /configurations/validate.

```bash
curl -X POST https://api.simwood.com/intelligence/v1/configurations \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "acme-fraud-detection",
    "template_id": 3,
    "operators": [ /* completed from the template definition */ ],
    "actions": [
      {
        "type": "webhook",
        "webhook_url": "https://example.com/hooks/fraud",
        "once_per_session": true,
        "condition": { "operator": "fraud-confidence", "expression": "result.value > 80" }
      }
    ]
  }'
```

--------------------------------

### Successful response for listing configuration templates

Source: https://docs.simwood.com/services/intelligence/reference/tag/configuration-templates/get/configuration-templates

Example JSON response for a successful 200 request. Contains an array of template summaries with id, name, description, version, and timestamps, plus a next_cursor for pagination.

```json
{
  "items": [
    {
      "id": 1,
      "name": "string",
      "description": "string",
      "version": 1,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "next_cursor": "string"
}

```

--------------------------------

### Get a specific operator version via cURL

Source: https://docs.simwood.com/services/intelligence/reference/tag/operators/get/operators/name/versions/version

Sends a GET request to retrieve a specific historical version of an operator, using the required intelligence:read scope and a bearer token. Replace {name} and the version number (1 in this example) as needed.

```shell
curl 'https://api.simwood.com/intelligence/v1/operators/{name}/versions/1' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

```

--------------------------------

### GET /intelligence/v1/conversations

Source: https://docs.simwood.com/services/intelligence/reference/tag/conversations/get/conversations

Returns a page of conversations for the authenticated account, most recently started first. Use optional filters to narrow by call id, end-user, medium, status, or start time window, and paginate using the cursor from the previous page's next_cursor.

```APIDOC
## GET /intelligence/v1/conversations

### Description
Returns a page of conversations for the authenticated account, most recently started first. Use the optional filters to narrow by call id (`transport_key`), end-user (`user_id`), medium, status, or start time window. Paginate using the `cursor` from the previous page's `next_cursor`.

### Method
GET

### Endpoint
https://api.simwood.com/intelligence/v1/conversations

### Parameters
#### Query Parameters
- **transport_key** (string) - Optional - Filter by call id / transport key.
- **user_id** (string) - Optional - Filter by end-user identifier.
- **medium** (string) - Optional - Filter by medium, e.g. `voice`.
- **status** (string) - Optional - Filter by status: `open` or `closed`.
- **started_after** (string) - Optional - ISO 8601 datetime — return only conversations that started after this time.
- **started_before** (string) - Optional - ISO 8601 datetime — return only conversations that started before this time.
- **limit** (integer) - Optional - Page size (default 50, max 200). Min: 1, Max: 200, Default: 50.
- **cursor** (string) - Optional - Opaque keyset cursor from the previous page's `next_cursor`.

### Request Example
```
curl https://api.simwood.com/intelligence/v1/conversations \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **items** (array) - List of conversation objects.
  - **conversation_id** (string) - Unique identifier for the conversation.
  - **medium** (string) - Medium of the conversation (e.g., voice).
  - **status** (string) - Status of the conversation (open or closed).
  - **transport_key** (string) - Call id / transport key.
  - **user_id** (string) - End-user identifier.
  - **source_sessions** (array of string) - Source session identifiers.
  - **configuration_ids** (array of string) - Configuration identifiers.
  - **started_at** (string) - Start time of the conversation.
  - **ended_at** (string) - End time of the conversation.
  - **turn_count** (integer) - Number of turns in the conversation.
  - **usage** (object) - Usage details.
    - **audio_seconds** (integer) - Total audio seconds.
    - **operator_results_emitted** (integer) - Number of operator results emitted.
  - **created_at** (string) - Creation timestamp.
  - **updated_at** (string) - Last update timestamp.
- **next_cursor** (string) - Opaque cursor for the next page.

#### Response Example
```
{
  "items": [
    {
      "conversation_id": "string",
      "medium": "string",
      "status": "string",
      "transport_key": "string",
      "user_id": "string",
      "source_sessions": [
        "string"
      ],
      "configuration_ids": [
        "string"
      ],
      "started_at": "string",
      "ended_at": "string",
      "turn_count": 0,
      "usage": {
        "audio_seconds": 0,
        "operator_results_emitted": 0
      },
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "next_cursor": "string"
}
```

### Error Responses
- **403** - Missing gateway headers or insufficient scope.
- **422** - Validation Error.

```

--------------------------------

### POST /configurations

Source: https://docs.simwood.com/services/intelligence/reference/tag/configurations

Creates a new configuration.

```APIDOC
## POST /configurations

### Description
Creates a new configuration.

### Method
POST

### Endpoint
/configurations

### Request Body
- **configuration** (object) - The configuration to create.

### Request Example
{
  "configuration": {}
}

### Response
#### Success Response (200)
- **uuid** (string) - The UUID of the created configuration.
- **sync_state** (string) - The sync state of the configuration (live or pending).

#### Response Example
{
  "uuid": "string",
  "sync_state": "live"
}
```

--------------------------------

### Browse templates with curl to /configuration-templates

Source: https://docs.simwood.com/services/intelligence/guides/start-from-a-template

Lists available templates. Requires intelligence:read and intelligence:write permissions. Each template entry includes a numeric id, name, and description.

```bash
curl https://api.simwood.com/intelligence/v1/configuration-templates \
  -H "Authorization: Bearer sk_live_..."
```

--------------------------------

### Example response for creating a knowledge base document from text

Source: https://docs.simwood.com/services/conversational-ai/reference/tag/knowledge-base/post/knowledge-base/text

Shows the JSON response returned when the document is created successfully (HTTP 201). Includes the document ID, name, type, size, source URL, and timestamps.

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "string",
  "type": "url",
  "size_bytes": 1,
  "source_url": null,
  "created_at": "2026-10-14T03:43:21.256Z",
  "updated_at": "2026-10-14T03:43:21.256Z"
}
```

--------------------------------

### GET /sessions/{session_id}

Source: https://docs.simwood.com/services/intelligence/reference/tag/sessions/get/sessions/session_id

Returns the current state of a session, including its status, start time, configuration, and customer metadata. Requires the intelligence:read scope.

```APIDOC
## GET /sessions/{session_id}

### Description
Returns the current state of a session — its `status`, when it started, the configuration in force, and the `customer_metadata` it was created with.

### Method
GET

### Endpoint
https://api.simwood.com/intelligence/v1/sessions/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The session identifier returned when the session was created.

### Request Example
```
curl 'https://api.simwood.com/intelligence/v1/sessions/{session_id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **session_id** (string) - The session identifier.
- **status** (string) - The current status of the session.
- **started_at** (string) - The timestamp when the session started.
- **call_id** (string) - The call identifier associated with the session.
- **configuration_id** (string) - The configuration identifier in force.
- **customer_metadata** (object) - The customer metadata provided at session creation.

#### Response Example
```
{
  "session_id": "string",
  "status": "string",
  "started_at": "string",
  "call_id": "string",
  "configuration_id": "string",
  "customer_metadata": {
    "additionalProperty": "anything"
  }
}
```

### Error Responses
- **403** - Missing gateway headers or insufficient scope.
- **404** - Resource not found.
- **422** - Validation Error.
```

--------------------------------

### Successful response schema for get conversation

Source: https://docs.simwood.com/services/intelligence/reference/tag/conversations/get/conversations/conversation_id

Example response body for a successful (200) request. Shows the conversation metadata fields including lifecycle state, usage counters, and timestamps.

```json
{
  "conversation_id": "string",
  "medium": "string",
  "status": "string",
  "transport_key": "string",
  "user_id": "string",
  "source_sessions": [
    "string"
  ],
  "configuration_ids": [
    "string"
  ],
  "started_at": "string",
  "ended_at": "string",
  "turn_count": 0,
  "usage": {
    "audio_seconds": 0,
    "operator_results_emitted": 0
  },
  "created_at": "string",
  "updated_at": "string"
}

```

--------------------------------

### Add a document from a file

Source: https://docs.simwood.com/services/conversational-ai/guides/manage-knowledge-base

Uploads a file. Supported formats: .txt, .pdf, .docx, .epub, .html.

```bash
curl -X POST https://api.simwood.com/convai/v1/knowledge-base/file \
  -H "Authorization: Bearer sk_live_..." \
  -F "name=Product catalogue" \
  -F "file=@catalogue.pdf"
```

--------------------------------

### Example response for get webhook configuration by ID

Source: https://docs.simwood.com/services/conversational-ai/reference/tag/webhooks/get/webhooks/id

Shows the JSON structure returned when the webhook configuration is found (HTTP 200). The `agent_id` can be null, and `request_headers` is an object with additional properties.

```json
{
  "id": "string",
  "agent_id": null,
  "event_type": "conversation.completed",
  "url": "https://example.com",
  "request_headers": {
    "additionalProperty": "string"
  },
  "enabled": true,
  "created_at": "2026-07-18T10:26:52.935Z",
  "updated_at": "2026-07-18T10:26:52.935Z"
}

```

--------------------------------

### POST /sessions

Source: https://docs.simwood.com/services/intelligence/reference/tag/sessions/post/sessions

Starts analysis on a single live call: taps the call audio, applies the given configuration, starts its operators, and waits for the session to establish before responding (201). The target call must already be known to the platform, identified by call_id; an unknown one, or one belonging to another account, returns 404. Pass customer_metadata to have an opaque object echoed back on every webhook this session triggers. Returns 502 if the session cannot be established, or 504 if establishment times out.

```APIDOC
## POST /sessions

### Description
Starts analysis on a single live call: taps the call audio, applies the given configuration, starts its operators, and waits for the session to establish before responding (201). The target call must already be known to the platform, identified by call_id; an unknown one, or one belonging to another account, returns 404. Pass customer_metadata to have an opaque object echoed back on every webhook this session triggers. Returns 502 if the session cannot be established, or 504 if establishment times out.

### Method
POST

### Endpoint
https://api.simwood.com/intelligence/v1/sessions

### Authentication
Required. Bearer token. Required scope: `intelligence:write`

### Parameters
#### Request Body
- **call_id** (string) - Required - Identifier of the live call to analyse. It must already be known to the platform.
- **configuration_id** (string) - Required - UUID of the configuration to apply. Must be one of your account's active configurations.
- **customer_metadata** (object) - Optional - Opaque object stored with the session and echoed back, verbatim, on every webhook this session triggers. Use it to carry your own correlation reference (e.g. a CRM id).
- **transcript_events** (boolean) - Optional - When true, transcript turns are emitted on the session's event stream alongside operator results.

### Request Example
```json
{
  "call_id": "",
  "configuration_id": "",
  "customer_metadata": {
    "additionalProperty": "anything"
  },
  "transcript_events": true
}
```

### Response
#### Success Response (201)
- **session_id** (string) - The identifier of the created session.

#### Response Example
```json
{
  "session_id": "string"
}
```

### Error Responses
- **403** - Missing gateway headers or insufficient scope
- **404** - Call not found
- **422** - Validation Error
- **502** - Session failed to establish
- **504** - Session establishment timed out

```

--------------------------------

### Create a configuration with operators and webhook action

Source: https://docs.simwood.com/services/intelligence/guides/analyse-a-live-call

Creates a configuration named 'fraud-detection' that runs two operators every five turns and fires a webhook action when fraud confidence exceeds 80 with high confidence. The response includes a uuid and sync_state; wait until sync_state is 'live' before starting a session. To validate without saving, post the same body to /configurations/validate.

```bash
curl -X POST https://api.simwood.com/intelligence/v1/configurations \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fraud-detection",
    "operators": [
      { "name": "fraud-confidence", "granularity": { "on": "turn", "every": 5 }, "include_prior_results": true },
      { "name": "fraud-indicators", "granularity": { "on": "turn", "every": 5 } }
    ],
    "actions": [
      {
        "type": "webhook",
        "webhook_url": "https://example.com/hooks/fraud",
        "once_per_session": true,
        "condition": {
          "operator": "fraud-confidence",
          "expression": "result.value > 80 AND confidence > 0.75"
        }
      }
    ]
  }'
```

--------------------------------

### cURL request to get a configuration template

Source: https://docs.simwood.com/services/intelligence/reference/tag/configuration-templates/get/configuration-templates/template_id

Use this cURL command to fetch a configuration template by its ID. Replace YOUR_SECRET_TOKEN with a valid bearer token. The example uses template ID 1.

```shell
curl https://api.simwood.com/intelligence/v1/configuration-templates/1 \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

```

--------------------------------

### cURL request to start a LiveKit conversation

Source: https://docs.simwood.com/services/conversational-ai/reference/tag/agents/post/agents/id/conversations

Sends a POST request to the conversations endpoint with a JSON body containing a config object. Requires the `convai:write` scope and a valid agent ID. The example sets `text_only` to true and includes an empty `dynamic_variables` object.

```shell
curl 'https://api.simwood.com/convai/v1/agents/{id}/conversations' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "config": {
    "conversation_config_override": {
      "text_only": true
    },
    "dynamic_variables": {}
  }
}'

```

--------------------------------

### Create an agent with curl

Source: https://docs.simwood.com/services/conversational-ai/guides/create-your-first-agent

Create an agent with a minimal configuration: a prompt, a voice, and sensible defaults. The response includes the agent's id. You can refine the configuration later with PUT /agents/:id.

```bash
curl -X POST https://api.simwood.com/convai/v1/agents \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My first agent",
    "configuration": {
      "asr": {
        "keywords": []
      },
      "turn": {
        "timeout_seconds": 10,
        "silence_timeout_seconds": 3
      },
      "tts": {
        "voice_id": "<voice-id>",
        "settings": {
          "stability": 0.5,
          "similarity_boost": 0.75,
          "speed": 1.0
        }
      },
      "agent": {
        "first_message": "Hello, thanks for calling. How can I help you today?",
        "language": "en",
        "prompt": {
          "text": "You are a helpful assistant. Answer questions clearly and concisely. If you cannot help, say so politely and offer to transfer the caller.",
          "temperature": 0.5,
          "model": "gpt-4o"
        },
        "knowledge_base": [],
        "tools": []
      },
      "conversation": {
        "max_duration_seconds": 600
      }
    }
  }'
```

--------------------------------

### Start a session on a live call with curl

Source: https://docs.simwood.com/services/intelligence/guides/analyse-a-live-call

Creates a session by posting the call_id and configuration_id to /intelligence/v1/sessions. The optional customer_metadata is echoed back on every webhook. The response returns a session_id used for other endpoints.

```bash
curl -X POST https://api.simwood.com/intelligence/v1/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "call_id": "call-abc-123",
    "configuration_id": "5f1c…",
    "customer_metadata": { "your_ref": "ticket-9981" }
  }'
```

--------------------------------

### Analysis field example

Source: https://docs.simwood.com/services/conversational-ai/concepts/conversations

JSON example of the analysis field, showing data_collection_results, call_successful, and transcript_summary. Present when the agent is configured with analysis.data_collection.

```json
"analysis": {
  "data_collection_results": {
    "customer_intent": "cancel subscription",
    "issue_resolved": true
  },
  "call_successful": "success",
  "transcript_summary": "Caller wanted to cancel their subscription. Agent confirmed cancellation."
}
```

--------------------------------

### Agent language model configuration: first_message, prompt, knowledge_base, tools

Source: https://docs.simwood.com/services/conversational-ai/concepts/agents

Defines the agent's initial message, system prompt, knowledge base references, and tools.

```json
"agent": {
  "first_message": "Hello, thanks for calling. How can I help you today?",
  "language": "en",
  "prompt": {
    "text": "You are a helpful customer service agent for Acme Corp...",
    "temperature": 0.5,
    "model": "gpt-4o"
  },
  "knowledge_base": [
    { "type": "url", "id": "doc-uuid-...", "source": "https://..." }
  ],
  "tools": []
}
```

--------------------------------

### Add a document from a URL

Source: https://docs.simwood.com/services/conversational-ai/guides/manage-knowledge-base

Fetches and indexes the page at the given URL. Pass a name to identify it in the list.

```bash
curl -X POST https://api.simwood.com/convai/v1/knowledge-base/url \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support FAQ",
    "url": "https://example.com/support/faq"
  }'
```

--------------------------------

### Example 200 Response for List Conversations

Source: https://docs.simwood.com/services/conversational-ai/reference/tag/agents/get/agents/id/conversations

Example JSON response for a successful 200 request. Shows the structure of a conversation object, including agent_id, id, status, transcript, and metadata fields.

```json
[
  {
    "agent_id": "string",
    "id": "string",
    "status": "initiated",
    "transcript": [
      {
        "role": "agent",
        "message": null,
        "tool_calls": [
          {}
        ],
        "tool_results": [
          {}
        ],
        "feedback": {},
        "llm_override": {},
        "time_in_call_secs": 1,
        "conversation_turn_metrics": {
          "metrics": {
            "additionalProperty": {
              "elapsed_time": 1
            }
          }
        },
        "rag_retrieval_info": {}
      }
    ],
    "metadata": {
      "start_time_unix_secs": 1,
      "accepted_time_unix_secs": 1,
      "call_duration_secs": 1
    }
  }
]
```

--------------------------------

### Example SIP UAC configuration response

Source: https://docs.simwood.com/services/conversational-ai/reference/tag/agents/get/agents/id/sip-uac

Example JSON response for a successful request (HTTP 200). Shows the structure of the SIP UAC configuration, including `aor`, `sip_domain`, `sip_username`, and `sip_registrar`.

```json
{
  "aor": "string",
  "sip_domain": null,
  "sip_username": null,
  "sip_registrar": null
}

```

--------------------------------

### Fetch template definition with curl to /configuration-templates/<template_id>

Source: https://docs.simwood.com/services/intelligence/guides/start-from-a-template

Fetches the full template, including its definition with operators, granularities, and actions. Actions are deliberately missing delivery destinations; granularities are suggested, not fixed.

```bash
curl https://api.simwood.com/intelligence/v1/configuration-templates/<template_id> \
  -H "Authorization: Bearer sk_live_..."
```

--------------------------------

### cURL request to get an operator

Source: https://docs.simwood.com/services/intelligence/reference/tag/operators/get/operators/name

Sends a GET request to the Simwood Intelligence API to retrieve the named operator. Replace {name} with the operator's kebab-case name and YOUR_SECRET_TOKEN with your bearer token.

```shell
curl 'https://api.simwood.com/intelligence/v1/operators/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

```

--------------------------------

### GET /conversations

Source: https://docs.simwood.com/services/intelligence/reference/tag/conversations

Lists conversation records.

```APIDOC
## GET /conversations

### Description
Lists conversation records.

### Method
GET

### Endpoint
/conversations

### Response
#### Success Response (200)
- **conversations** (array) - List of conversation records.

#### Response Example
{
  "conversations": []
}
```

--------------------------------

### Create webhook for conversation.initiating event

Source: https://docs.simwood.com/services/conversational-ai/guides/receive-conversation-events

POST to /webhooks to create a webhook that fires when a call is answered (conversation.initiating). Requires the same setup as the completed event webhook. Use request_headers to pass a shared secret for verification.

```bash
curl -X POST https://api.simwood.com/convai/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "conversation.initiating",
    "url": "https://example.com/hooks/calls",
    "request_headers": {
      "X-Webhook-Secret": "your-shared-secret"
    }
  }'
```

--------------------------------

### POST /knowledge-base/file

Source: https://docs.simwood.com/services/conversational-ai/concepts/knowledge-base

Creates a knowledge base document from an uploaded file. Supported file types include .txt, .pdf, .docx, .epub, and .html.

```APIDOC
## POST /knowledge-base/file

### Description
Creates a knowledge base document from an uploaded file. Supported file types include .txt, .pdf, .docx, .epub, and .html.

### Method
POST

### Endpoint
https://api.simwood.com/convai/v1/knowledge-base/file

### Parameters
#### Request Body (multipart/form-data)
- **name** (string) - Required - Name of the document.
- **file** (file) - Required - The file to upload.

### Request Example
curl -X POST https://api.simwood.com/convai/v1/knowledge-base/file \
  -H "Authorization: Bearer sk_live_..." \
  -F "name=Product catalogue" \
  -F "file=@catalogue.pdf"

### Response
#### Success Response (200)
- **id** (string) - Unique identifier of the created document.

#### Response Example
{
  "id": "doc-uuid-3"
}
```

--------------------------------

### GET /voices

Source: https://docs.simwood.com/services/conversational-ai/reference/tag/voices

Retrieves a list of available voices.

```APIDOC
## GET /voices

### Description
Retrieves a list of available voices.

### Method
GET

### Endpoint
/voices

### Response
#### Success Response (200)
Returns a list of voices.

```

--------------------------------

### JSON response schema for get operator

Source: https://docs.simwood.com/services/intelligence/reference/tag/operators/get/operators/name

Shows the structure of the 200 response for the get operator endpoint. The response includes fields such as name, description, prompt, output_type, output_config, model_tier, include_reasoning, parameters, account, version, is_current, created_at, and updated_at.

```json
{
  "name": "string",
  "description": "string",
  "prompt": "string",
  "output_type": "classification",
  "output_config": {
    "additionalProperty": "anything"
  },
  "model_tier": "fast",
  "include_reasoning": true,
  "parameters": [
    {
      "name": "string",
      "type": "kb_document",
      "description": "string"
    }
  ],
  "account": "string",
  "version": 1,
  "is_current": true,
  "created_at": "string",
  "updated_at": "string"
}

```

--------------------------------

### GET /sessions/{session_id}

Source: https://docs.simwood.com/services/intelligence/reference/tag/sessions

Retrieves the details of a specific session.

```APIDOC
## GET /sessions/{session_id}

### Description
Retrieves the details of a specific session.

### Method
GET

### Endpoint
/sessions/{session_id}

```

--------------------------------

### Response for successful document creation

Source: https://docs.simwood.com/services/conversational-ai/reference/tag/knowledge-base/post/knowledge-base/file

Example JSON response returned when the document is created (HTTP 201). Contains the document ID, name, type, size, source URL, and timestamps.

```json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "string",
  "type": "url",
  "size_bytes": 1,
  "source_url": null,
  "created_at": "2026-10-14T03:43:21.245Z",
  "updated_at": "2026-10-14T03:43:21.245Z"
}
```
Tokens:
Raw