Persona

https://docs.sindarin.tech
Admin
Persona is an infrastructure platform for deploying conversational speech AI personas powered by...
Tokens:32,789
Snippets:161
Trust Score:6.4
Update:11 months ago
Show doc for...
Tokens:
Raw
### Get User by ID - Python

Source: https://docs.sindarin.tech/users/GET--userId-

Retrieves user information using a Python `requests` library with the required headers and path parameters.  Requires the `requests` library to be installed. The response contains user details such as ID, charges, charge limit, and creation timestamp.

```Python
import requests

url = "https://api.sindarin.tech/v1/users/string"
headers = {"x-api-key": "string"}

response = requests.get(url, headers=headers)

if response.status_code == 200:
    print(response.json())
else:
    print("Error:", response.status_code, response.text)
```

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

### Get User by ID - Go

Source: https://docs.sindarin.tech/users/GET--userId-

Retrieves user information using a Go HTTP request with the required headers and path parameters. Necessary dependencies include the `net/http` package.  The response contains user details such as ID, charges, charge limit, and creation timestamp.

```Go
package main

import (
	"fmt"
	"net/http"
)

func main() {
	resp, err := http.Get("https://api.sindarin.tech/v1/users/string?x-api-key=string")
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

defer resp.Body.Close()

	fmt.Println("Response Status:", resp.Status)
}
```

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

### Retrieve LLMs - TypeScript

Source: https://docs.sindarin.tech/resources/GET-llms

This snippet provides an example of how to retrieve a list of available LLMs using TypeScript, though the code example is not provided within this document.  It requires an API key for authentication and sends a GET request to the specified endpoint. The response is a JSON array containing LLM details.

```TypeScript

```

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

### Sample JSON response for retrieving conversations

Source: https://docs.sindarin.tech/conversations/GET-conversations

Illustrates the structure of the successful 200 response from the GET /v1/conversations endpoint, including a summary section and an array of conversation objects with messages, cost, and metadata.

```JSON
{
  "summary": {
    "users": [
      "string"
    ],
    "personaIds": [
      "string"
    ]
  },
  "conversations": [
    {
      "userId": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "personaId": "string",
      "messages": [
        {
          "role": "string",
          "content": "string",
          "actions": {}
        }
      ],
      "cost": 0,
      "duration": 0,
      "metadata": {}
    }
  ]
}
```

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

### Career Coach Workflow Implementation

Source: https://docs.sindarin.tech/persona/core-concepts/workflows

Complete example of a career guidance Persona workflow that dynamically adjusts behavior based on user input. Tracks field selection and experience level to provide tailored advice through nested conditionals.

```handlebars
### Background ###
 
You are a friendly and knowledgeable career advisor named Alex.
 
Your goal is to help users explore their career options and provide guidance.
 
Always maintain a positive and encouraging tone.
 
Your messages will be spoken aloud via speech synthesis,
so use brief, 1-2 sentence statements and speak casually.
 
### Current Goals ###
 
Currently, your goal is to:
 
{{#unless state.field}}
[ ] Find out what field the user is interested in. Ask them about their career interests.
{{else}}
  {{#ifEqualsAll state.field "AI"}}
[ ] Tell the user how impressed you are with their career choice!
  {{else}}
    {{#unless state.years_of_experience}}
[ ] Find out how many years of experience they have in {{state.field}}.
    {{else}}
      {{#ifCond state.years_of_experience '<' 2}}
[ ] Provide early-stage career advice, with an emphasis on finding mentors.
      {{else}}
[ ] Provide late-stage career advice, with emphasis on leadership.
      {{/ifCond}}
    {{/unless}}
  {{/ifEqualsAll}}
{{/unless}}
 
 
### Additional Context
 
If relevant to the current conversation, relay one of the following anecdotes or mantras:
 
{{#each scenarios}}
- {{context}}
{{/each}}

```

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

### Get User by ID - JavaScript

Source: https://docs.sindarin.tech/users/GET--userId-

Retrieves user information using a JavaScript request with the required headers and path parameters. Requires an API key and a user ID to retrieve the specified user's data.  The response contains user details like ID, charges, charge limit, and creation timestamp.

```JavaScript
fetch("https://api.sindarin.tech/v1/users/string", { \
  method: "GET", \
  headers: { \
    "x-api-key": "string" \
  }
})
```

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

### Press Phone Keys Action Schema JSON

Source: https://docs.sindarin.tech/persona/miscellanous/ivr-navigation

Defines the JSON schema for the press_phone_keys action, which enables Personas to listen for IVR prompts and press corresponding keys. It includes a description, examples of user prompts and assistant responses, and specifies the type as an array of integers representing keys. This schema is used in Persona action configurations to automate phone tree navigation based on predefined examples.

```json
{
  "press_phone_keys": {
    "_description": "When you should press a key or keys to navigate a phone tree.",
    "_examples": [
      {
        "user says": "Welcome to ACME co. Please press 5 to speak to a representative.",
        "assistant action includes": {
          "press_phone_keys": [
            5
          ]
        }
      }
    ],
    "type": "array"
  }
}
```

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

### Define boosting thresholds in JSON

Source: https://docs.sindarin.tech/persona/persona-fields/actions

Shows how to set up _boosting parameters (force, floor, encourage) with similarity thresholds and optional thought injections. These settings can be applied globally, per action, or per example to influence action selection.

```JSON
{
  "force": {
    "threshold": 0.95,
    "thought": "I must take the {{actionName}} action right now."
  },
  "floor": {
    "threshold": 0.7
  },
  "encourage": {
    "threshold": 0.85,
    "thought": "I should strongly consider taking the {{actionName}} action."
  }
}
```

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

### GET /v1/personas

Source: https://docs.sindarin.tech/personas/GET-personas

Retrieves a list of personas for the team associated with the provided API key. The endpoint returns detailed persona configurations including prompts, LLM settings, and lifecycle event webhooks.

```APIDOC
## GET /v1/personas

### Description
Retrieves a list of personas for the team associated with the provided API key.

### Method
GET

### Endpoint
/v1/personas

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication

### Request Example
```bash
curl -X GET "https://api.sindarin.tech/v1/personas" \
  -H "x-api-key: your-api-key"
```

### Response
#### Success Response (200)
- **name** (string) - Persona name
- **initialMessage** (string) - Initial message shown to the user
- **messages** (array) - Pre‑defined message sequence
- **prompt** (string) - System prompt for the LLM
- **actions** (object) - JSON schema for dynamic actions
- **llmConfig** (object) - Configuration for the language model
- **ttsConfig** (object) - Text‑to‑speech settings
- **lifecycleEvents** (object) - Webhook definitions for init, state changes, and end events
- **interjections** (object) - Settings for spontaneous interjections
- **interruptionHandling** (object) - Policy for handling interruptions
- **language** (string) - Language code (e.g., "en")
- **limitReachedMessage** (string) - Message shown when usage limits are hit
- **hangup** (object) - Hang‑up behavior configuration

#### Response Example
```json
[
  {
    "name": "string",
    "initialMessage": "string",
    "messages": [
      {
        "role": "user",
        "content": "string"
      }
    ],
    "prompt": "string",
    "actions": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "_boosting": {
        "force": {
          "threshold": 1,
          "thought": "string",
          "message": "string"
        },
        "floor": {
          "threshold": 1
        },
        "encourage": {
          "threshold": 1,
          "thought": "string",
          "message": "string"
        }
      },
      "properties": {}
    },
    "llmConfig": {
      "llm": "llama-3-1-8b",
      "endpoint": "http://example.com",
      "apiKey": "string",
      "temperature": 1,
      "repetitionPenalty": -3.5
    },
    "ttsConfig": {
      "voiceId": "string"
    },
    "lifecycleEvents": {
      "onInit": {
        "webhook": {
          "url": "http://example.com",
          "method": "GET",
          "body": {},
          "headers": {},
          "_response_assignments": {
            "state": [
              {
                "stateKey": "string",
                "responsePath": "string"
              }
            ],
            "details": [
              {
                "detailsKey": "string",
                "responsePath": "string"
              }
            ]
          }
        }
      },
      "onStateChanged": {
        "webhook": {
          "url": "http://example.com",
          "method": "GET",
          "body": {},
          "headers": {},
          "_response_assignments": {
            "state": [
              {
                "stateKey": "string",
                "responsePath": "string"
              }
            ],
            "details": [
              {
                "detailsKey": "string",
                "responsePath": "string"
              }
            ]
          }
        }
      },
      "onEnd": {
        "webhook": {
          "url": "http://example.com",
          "method": "GET",
          "body": {},
          "headers": {}
        }
      }
    },
    "interjections": {
      "enabled": true,
      "minWait": 5000,
      "maxWait": {
        "ref": {
          "path": [
            "minWait"
          ]
        }
      },
      "thought": "string"
    },
    "interruptionHandling": {
      "backdown": "immediate"
    },
    "language": "en",
    "limitReachedMessage": "string",
    "hangup": {
      "enabled": true,
      "timer": {
        "after": 15000,
        "warning": {
          "enabled": true,
          "thought": "string",
          "message": "string"
        }
      }
    }
  }
]
```
```

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

### Sample webhook response JSON

Source: https://docs.sindarin.tech/persona/persona-fields/actions

Provides an example of a webhook response body containing a list of cars. This JSON can be used as the source data for response assignments.

```JSON
{
  "cars": [
    {
      "model": "Model T",
      "color": "Red"
    }
  ]
}
```

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

### GET /v1/conversations

Source: https://docs.sindarin.tech/conversations/GET-conversations

Retrieves conversation transcripts for the team associated with the provided API key. Supports filtering by date range, pagination, and various identifiers.

```APIDOC
## GET /v1/conversations

### Description
Retrieves conversation transcripts for the team associated with the provided API key. Supports filtering by date range, pagination, and various identifiers.

### Method
GET

### Endpoint
/v1/conversations

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication

#### Query Parameters
- **start** (string) - Optional - Start date for filtering conversations (default is 30 days ago)
- **end** (string) - Optional - End date for filtering conversations (default is current date)
- **page** (integer) - Optional - Page number for pagination (default: 0)
- **limit** (integer) - Optional - Number of conversations per page (default: 30)
- **callsid** (string) - Optional - Twilio Call SID to filter conversations
- **personaIds** (string) - Optional - Comma-separated list of persona IDs to filter conversations
- **userIds** (string) - Optional - Comma-separated list of user IDs to filter conversations

### Request Example
```
curl -X GET "https://api.sindarin.tech/v1/conversations?start=2019-08-24&end=2019-08-24&page=0&limit=30&callsid=string&personaIds=string&userIds=string" \
  -H "x-api-key: string"
```

### Response
#### Success Response (200)
- **summary** (object) - Contains arrays of users and persona IDs
- **conversations** (array) - List of conversation objects with details

#### Response Example
```
{
  "summary": {
    "users": [
      "string"
    ],
    "personaIds": [
      "string"
    ]
  },
  "conversations": [
    {
      "userId": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "personaId": "string",
      "messages": [
        {
          "role": "string",
          "content": "string",
          "actions": {}
        }
      ],
      "cost": 0,
      "duration": 0,
      "metadata": {}
    }
  ]
}
```
```

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

### Define Alex Career Coach Actions Schema

Source: https://docs.sindarin.tech/persona/core-concepts/workflows

JSON Schema defining Alex's action types for updating user state during career coaching conversations. Includes SetField and SetYearsOfExperience actions with validation rules and usage examples.

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "SetField": {
      "_description": "Update the user's field of interest in the state.",
      "_action_type": "update_state",
      "_examples": [
        {
          "user says": "I'm interested in AI.",
          "assistant action includes": { "field": "AI" }
        }
      ],
      "required": ["field"],
      "properties": {
        "field": { "type": "string" }
      }
    },
    "SetYearsOfExperience": {
      "_description": "Update the user's years of experience in the state.",
      "_action_type": "update_state",
      "_examples": [
        {
          "user says": "I have 5 years of experience.",
          "assistant action includes": { "years_of_experience": 5 }
        }
      ],
      "required": ["years_of_experience"],
      "properties": {
        "years_of_experience": { "type": "number" }
      }
    }
  }
}
```

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

### GET /v1/users/{userId}

Source: https://docs.sindarin.tech/users/GET--userId-

Retrieves detailed information for a specific user identified by their user ID. This endpoint requires an API key for authentication. It is useful for accessing user charges, limits, and metadata.

```APIDOC
## GET /v1/users/{userId}

### Description
Retrieve a user's information by their ID

### Method
GET

### Endpoint
/v1/users/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - ID of the user to retrieve

#### Query Parameters

#### Request Body

#### Headers
- **x-api-key** (string) - Required - API key for authentication

### Request Example
{
  "example": "No request body required for GET request"
}

### Response
#### Success Response (200)
- **userId** (string) - The unique identifier of the user
- **charges** (integer) - The current charges for the user
- **chargeLimit** (integer) - The charge limit for the user
- **createdAt** (string) - The creation date of the user in ISO 8601 format
- **metadata** (object) - Additional metadata for the user

#### Response Example
{
  "userId": "string",
  "charges": 0,
  "chargeLimit": 0,
  "createdAt": "2019-08-24T14:15:22Z",
  "metadata": {}
}

### Error Responses
- 400: Bad Request
- 401: Unauthorized
- 404: Not Found
- 500: Internal Server Error
```

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

### GET /v1/resources/languages

Source: https://docs.sindarin.tech/resources/GET-languages

Retrieves the list of available languages for personas. This endpoint requires authentication via API key and returns a JSON object mapping language codes to language names.

```APIDOC
## GET /v1/resources/languages

### Description
Retrieves the list of available languages for personas

### Method
GET

### Endpoint
/v1/resources/languages

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Headers
#### Required Headers
- **x-api-key** (string) - Required - API key for authentication

### Request Example
```
curl -X GET "https://api.sindarin.tech/v1/resources/languages" \
  -H "x-api-key: string"
```

### Response
#### Success Response (200)
- **en** (string) - English language code
- **es** (string) - Spanish language code
- **fr** (string) - French language code

#### Response Example
```
{
  "en": "English",
  "es": "Spanish",
  "fr": "French"
}
```

#### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
- **500** - Internal Server Error
```

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

### GET /v1/personas/{id}/saytext

Source: https://docs.sindarin.tech/personas/GET-saytext

This endpoint retrieves an audio file of the specified text spoken by the given persona. It requires authentication via API key and uses path and query parameters to identify the persona and provide the text. The response is an audio buffer representing the spoken text.

```APIDOC
## GET /v1/personas/{id}/saytext

### Description
Retrieves an audio file of the specified text spoken by the given persona.

### Method
GET

### Endpoint
/v1/personas/{id}/saytext

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the persona

#### Query Parameters
- **text** (string) - Required - The text to be spoken by the persona

#### Headers
- **x-api-key** (string) - Required - API key for authentication

#### Request Body
None

### Request Example
```
curl -X GET "https://api.sindarin.tech/v1/personas/string/saytext?text=string" \
  -H "x-api-key: string"
```

### Response
#### Success Response (200)
Audio buffer of the spoken text

#### Response Example
```
"string"
```

#### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
```

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

### Get User by ID - cURL

Source: https://docs.sindarin.tech/users/GET--userId-

Retrieves user information using a cURL request with the required headers and path parameters.  Requires an API key and a user ID to retrieve the specified user's data. The response contains user details such as ID, charges, charge limit, and creation timestamp.

```cURL
curl -X GET "https://api.sindarin.tech/v1/users/string" \
  -H "x-api-key: string"
```

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

### GET /v1/users

Source: https://docs.sindarin.tech/users/GET-users

Retrieves a paginated list of users for the authenticated team. Supports filtering by page and limit.

```APIDOC
## GET /v1/users

### Description
Retrieves a paginated list of users for the authenticated team.

### Method
GET

### Endpoint
/v1/users

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number for pagination. Default: `1`
- **limit** (integer) - Optional - Number of users per page. Default: `10`

#### Headers
- **x-api-key** (string) - Required - API key for authentication

### Request Example
```json
{
  "queryParams": {
    "page": 1,
    "limit": 10
  },
  "headers": {
    "x-api-key": "string"
  }
}
```

### Response
#### Success Response (200)
- **users** (array) - A list of user objects.
  - **userId** (string) - The unique identifier for the user.
  - **charges** (integer) - The current number of charges associated with the user.
  - **chargeLimit** (integer) - The maximum limit for charges.
  - **createdAt** (string) - The timestamp when the user was created (ISO 8601 format).
  - **metadata** (object) - Additional metadata for the user.
- **currentPage** (integer) - The current page number of the returned results.
- **totalPages** (integer) - The total number of pages available.
- **totalUsers** (integer) - The total number of users.

#### Response Example
```json
{
  "users": [
    {
      "userId": "string",
      "charges": 0,
      "chargeLimit": 0,
      "createdAt": "2019-08-24T14:15:22Z",
      "metadata": {}
    }
  ],
  "currentPage": 0,
  "totalPages": 0,
  "totalUsers": 0
}
```
```

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

### Retrieve all conversations using cURL

Source: https://docs.sindarin.tech/conversations/GET-conversations

Executes a GET request to the /v1/conversations endpoint with optional query parameters. Requires the x-api-key header for authentication. Returns a JSON payload with conversation details. No additional dependencies beyond cURL.

```cURL
curl -X GET \"https://api.sindarin.tech/v1/conversations?start=2019-08-24&end=2019-08-24&page=0&limit=30&callsid=string&personaIds=string&userIds=string\" \\\n  -H \"x-api-key: string\"
```

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

### Retrieve spoken audio using cURL

Source: https://docs.sindarin.tech/personas/GET-saytext

Calls the Say Text endpoint with a GET request, providing the persona ID and text query parameter. Requires the x-api-key header for authentication. Returns an audio buffer of the spoken text.

```cURL
curlX GET "https://api.sindarin.tech/v1/personas/string/saytext?text=string" \
  -H "x-api-key: string"
```

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

### GET /v1/resources/llms

Source: https://docs.sindarin.tech/resources/GET-llms

Retrieve a list of available LLMs for use with Personas. This endpoint requires API key authentication.

```APIDOC
## GET /v1/resources/llms

### Description
Retrieve a list of available LLMs for use with Personas.

### Method
GET

### Endpoint
/v1/resources/llms

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication

### Request Example
```bash
curl -X GET "https://api.sindarin.tech/v1/resources/llms" \
  -H "x-api-key: YOUR_API_KEY"
```

### Response
#### Success Response (200)
Returns an array of LLM objects:
- **id** (string) - Unique identifier for the LLM
- **name** (string) - Human-readable name of the LLM

#### Response Example
```json
[
  {
    "id": "gpt-4",
    "name": "GPT-4"
  }
]
```
```

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

### URL Interpolation Examples in JSON

Source: https://docs.sindarin.tech/persona/persona-fields/actions

Demonstrates how to inject action body fields or details variables into URLs using placeholders or Handlebars templating. Inputs are action body and details/state objects; outputs are resolved URLs. Requires Handlebars for variable injection; limitations include potential syntax errors if placeholders mismatch data.

```json
{
  "city": "Boston"
}
```

```json
{
  "userId": "123"
}
```

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

### Voice response structure

Source: https://docs.sindarin.tech/resources/GET-voices

Example response structure for the voices endpoint. Returns an array of voice objects with properties including id, accent, gender, age, provider, model, primary status, and primaryId.

```json
[
  {
    "id": "string",
    "accent": "string",
    "gender": "string",
    "age": "string",
    "provider": "string",
    "model": "string",
    "primary": true,
    "primaryId": "string"
  }
]
```

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

### POST /v1/phone/makecall

Source: https://docs.sindarin.tech/phone/POST-makecall

This endpoint initiates an outbound phone call using the provided caller and recipient numbers, along with a persona configuration for AI-driven interactions. It requires Twilio credentials and supports recording, metadata, and various event hooks. The call is handled via Twilio, with the persona guiding the conversation using specified LLM and TTS settings.

```APIDOC
## POST /v1/phone/makecall

### Description
Initiates an outbound call using the provided persona configuration and Twilio credentials.

### Method
POST

### Endpoint
/v1/phone/makecall

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
`application/json` Required
- **callerPhoneNumber** (string) - Required - The phone number to use as the caller ID
- **recipientPhoneNumber** (string) - Required - The phone number to call
- **personaConfig** (object) - Required - Configuration for the AI persona, including name, messages, prompt, actions, LLM settings, TTS, lifecycle events, interjections, interruption handling, language, limit message, and hangup options
- **record** (boolean) - Optional - Whether to record the call. Default: false
- **twilioAccountSid** (string) - Required - The Twilio Account SID to use for this call
- **twilioAuthToken** (string) - Required - The Twilio Auth Token to use for this call
- **metadata** (object) - Optional - Additional metadata for the call. Default: {}

### Header Parameters
- **x-api-key** (string) - Required - API key for authentication

### Request Example
{
  "callerPhoneNumber": "string",
  "recipientPhoneNumber": "string",
  "personaConfig": {
    "name": "string",
    "initialMessage": "string",
    "messages": [
      {
        "role": "user",
        "content": "string"
      }
    ],
    "prompt": "string",
    "actions": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "_boosting": {
        "force": {
          "threshold": 1,
          "thought": "string",
          "message": "string"
        },
        "floor": {
          "threshold": 1
        },
        "encourage": {
          "threshold": 1,
          "thought": "string",
          "message": "string"
        }
      },
      "properties": {}
    },
    "llmConfig": {
      "llm": "llama-3-1-8b",
      "endpoint": "http://example.com",
      "apiKey": "string",
      "temperature": 1,
      "repetitionPenalty": -3.5
    },
    "ttsConfig": {
      "voiceId": "string"
    },
    "lifecycleEvents": {
      "onInit": {
        "webhook": {
          "url": "http://example.com",
          "method": "GET",
          "body": {},
          "headers": {},
          "_response_assignments": {
            "state": [
              {
                "stateKey": "string",
                "responsePath": "string"
              }
            ],
            "details": [
              {
                "detailsKey": "string",
                "responsePath": "string"
              }
            ]
          }
        }
      },
      "onStateChanged": {
        "webhook": {
          "url": "http://example.com",
          "method": "GET",
          "body": {},
          "headers": {},
          "_response_assignments": {
            "state": [
              {
                "stateKey": "string",
                "responsePath": "string"
              }
            ],
            "details": [
              {
                "detailsKey": "string",
                "responsePath": "string"
              }
            ]
          }
        }
      },
      "onEnd": {
        "webhook": {
          "url": "http://example.com",
          "method": "GET",
          "body": {},
          "headers": {}
        }
      }
    },
    "interjections": {
      "enabled": true,
      "minWait": 5000,
      "maxWait": {
        "ref": {
          "path": [
            "minWait"
          ]
        }
      },
      "thought": "string"
    },
    "interruptionHandling": {
      "backdown": "immediate"
    },
    "language": "en",
    "limitReachedMessage": "string",
    "hangup": {
      "enabled": true,
      "timer": {
        "after": 15000,
        "warning": {
          "enabled": true,
          "thought": "string",
          "message": "string"
        }
      }
    }
  },
  "record": false,
  "twilioAccountSid": "string",
  "twilioAuthToken": "string",
  "metadata": {}
}

### Response
#### Success Response (201)
- **callSid** (string) - The unique identifier for the initiated call

#### Response Example
{
  "callSid": "string"
}

#### Error Responses
- **400** - Bad Request (invalid input)
- **401** - Unauthorized (invalid API key or credentials)
```

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

### Update LLM Config with cURL

Source: https://docs.sindarin.tech/personas/PUT-llmConfig

Example cURL request to update a Persona's LLM configuration. Requires API key and specific LLM parameters in the request body.

```shell
curl -X PUT "https://api.sindarin.tech/v1/personas/string/llmConfig" \
  -H "x-api-key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "llm": "llama-3-1-8b",
    "endpoint": "http://example.com",
    "apiKey": "string",
    "temperature": 1,
    "repetitionPenalty": -3.5
  }'
```

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

### Retrieve Paginated Users via API

Source: https://docs.sindarin.tech/users/GET-users

Retrieves a paginated list of users for the authenticated team using the GET /v1/users endpoint. Requires an API key in the x-api-key header. Accepts query parameters for page and limit. Returns a JSON object containing an array of users and pagination metadata such as current page, total pages, and total users.

```curl
curl -X GET "https://api.sindarin.tech/v1/users?page=1&limit=10" \
  -H "x-api-key: string"
```

```json
{
  "users": [
    {
      "userId": "string",
      "charges": 0,
      "chargeLimit": 0,
      "createdAt": "2019-08-24T14:15:22Z",
      "metadata": {}
    }
  ],
  "currentPage": 0,
  "totalPages": 0,
  "totalUsers": 0
}
```

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

### Webhook Constants JSON Schema

Source: https://docs.sindarin.tech/persona/persona-fields/actions

Defines the JSON schema for _webhook_constants, a configuration object for webhook actions. It includes required properties like url and method, optional header/body/headers, and advanced options for responses and reactions. Inputs are JSON objects conforming to this schema; outputs include validated webhook requests with merged data from state and action body. Note that method is limited to GET, POST, PUT, and _response_handler currently only supports fire_and_forget.

```json
{
  "type": "object",
  "properties": {
    "url": { "type": "string" },
    "method": { "type": "string", "enum": ["GET", "POST", "PUT"] },
    "headers": { "type": "object" },
    "body": { "type": "object" },
    "_success_reaction_string": { "type": "string" },
    "_error_reaction_string": { "type": "string" },
    "_maximum_response_length": { "type": "number", "minimum": 0, "maximum": 10000 },
    "_response_handler": { "type": "string", "enum": ["fire_and_forget"] },
    "_response_assignments": {
      "type": "object",
      "properties": {
        "state": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "stateKey": { "type": "string" },
              "responsePath": { "type": "string" }
            },
            "required": ["responsePath"]
          }
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "detailsKey": { "type": "string" },
              "responsePath": { "type": "string" }
            },
            "required": ["responsePath"]
          }
        }
      }
    }
  },
  "required": ["url", "method"]
}
```

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

### POST /v1/users

Source: https://docs.sindarin.tech/users/POST-users

Creates a new user with a unique identifier and optional charge limit. Uses team default if limit not specified.

```APIDOC
## POST /v1/users

### Description
Creates a new user for the team with the given userId and optional chargeLimit

### Method
POST

### Endpoint
/v1/users

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication

#### Request Body
- **userId** (string) - Required - The unique identifier for the user
- **chargeLimit** (number) - Optional - The charge limit for the user. If not provided, the team's default charge limit will be used.

### Request Example
{
  "userId": "string",
  "chargeLimit": 0
}

### Response
#### Success Response (201)
- **message** (string) - User initialized successfully

#### Response Example
{
  "message": "User initialized successfully"
}
```

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

### Implement Workflow Loop with Handlebars

Source: https://docs.sindarin.tech/persona/core-concepts/workflows

Demonstrates the core workflow loop pattern that connects prompts to state updates and back. Shows how Handlebars templates drive Persona behavior through dynamic prompting.

```handlebars

  Prompt (Handlebars) ---> Action (update_state) ---> State
            ↑                                           ↓
            │                                           │
            └───────────────────────────────────────────┘

```

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

### Get Conversation by ID (JavaScript)

Source: https://docs.sindarin.tech/conversations/GET--conversationId-

Example of retrieving conversation details using JavaScript. This asynchronous function makes a GET request to the Sindarin API, requiring an API key and conversation ID for authentication and identification. Returns conversation data including cost, messages, status, and duration.

```javascript
async function getConversationById(conversationId, apiKey) {
  const response = await fetch(`https://api.sindarin.tech/v1/conversations/${conversationId}`, {
    method: 'GET',
    headers: {
      'x-api-key': apiKey
    }
  });
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return await response.json();
}

// Example usage:
// getConversationById('some-conversation-id', 'your-api-key')
//   .then(data => console.log(data))
//   .catch(error => console.error('Error fetching conversation:', error));
```

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

### Initialize New User with cURL

Source: https://docs.sindarin.tech/users/POST-users

Sends a POST request to create a new user, requiring an x-api-key header and JSON body with userId (required string) and chargeLimit (optional number). The endpoint uses the team's default limit if chargeLimit is omitted. Successful response returns a JSON message; errors include 400 for bad requests or 401 for auth failures.

```curl
curl -X POST "https://api.sindarin.tech/v1/users" \
  -H "x-api-key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "string",
    "chargeLimit": 0
  }'
```

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

### POST /v1/personas/new

Source: https://docs.sindarin.tech/personas/POST-new

Creates a new AI persona with customizable behavior, voice, and interaction patterns. Requires API key authentication.

```APIDOC
## POST /v1/personas/new

### Description
Creates a new AI persona with configurable behavior, language model settings, voice configuration, and interaction patterns.

### Method
POST

### Endpoint
`/v1/personas/new`

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - API key for authentication

#### Request Body
- **name** (string) - Required - Persona display name
- **initialMessage** (string) - Required - Initial greeting message
- **messages** (array<object>) - Required - Conversation history
- **prompt** (string) - Required - System prompt for the persona
- **actions** (object) - Required - Behavior configuration
- **llmConfig** (object) - Required - Language model configuration
- **ttsConfig** (object) - Required - Text-to-speech configuration
- **lifecycleEvents** (object) - Required - Webhook events configuration
- **interjections** (object) - Required - Interjection settings
- **interruptionHandling** (object) - Required - Interruption behavior
- **language** (string) - Required - Supported values: "en", "de", "es", "fr", "it", "multi"
- **limitReachedMessage** (string) - Optional - Message when limits are reached
- **hangup** (object) - Required - Call termination settings

### Request Example
```json
{
  "name": "string",
  "initialMessage": "string",
  "messages": [
    {
      "role": "user",
      "content": "string"
    }
  ],
  "prompt": "string",
  "actions": {
    "_boosting": {
      "force": {
        "threshold": 1,
        "thought": "string",
        "message": "string"
      },
      "floor": {
        "threshold": 1
      },
      "encourage": {
        "threshold": 1,
        "thought": "string",
        "message": "string"
      }
    }
  },
  "llmConfig": {
    "llm": "llama-3-1-8b",
    "endpoint": "http://example.com",
    "apiKey": "string",
    "temperature": 1,
    "repetitionPenalty": -3.5
  },
  "ttsConfig": {
    "voiceId": "string"
  },
  "lifecycleEvents": {
    "onInit": {
      "webhook": {
        "url": "http://example.com",
        "method": "GET",
        "body": {},
        "headers": {}
      }
    }
  },
  "interjections": {
    "enabled": true,
    "minWait": 5000,
    "thought": "string"
  },
  "interruptionHandling": {
    "backdown": "immediate"
  },
  "language": "en",
  "hangup": {
    "enabled": true,
    "timer": {
      "after": 15000
    }
  }
}
```

### Response
#### Success Response (200)
- **personaId** (string) - Unique identifier for the created persona

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

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

### Update User Charge Limit - Go

Source: https://docs.sindarin.tech/users/PUT-chargeLimit

Demonstrates updating a user's charge limit using Go. Requires an API key and user ID to be passed as headers and path parameters respectively. The request body specifies the new charge limit.

```Go
/* Go code for updating user charge limit would go here */
```

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

### Retrieve All Personas Using cURL

Source: https://docs.sindarin.tech/personas/GET-personas

This snippet demonstrates how to call the GET /v1/personas endpoint to fetch a list of personas. It requires an x-api-key header for authentication. The response is a JSON array of persona objects, with no request body needed.

```curl
curl -X GET "https://api.sindarin.tech/v1/personas" \
  -H "x-api-key: string"
```

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

### Retrieve available languages via API using cURL

Source: https://docs.sindarin.tech/resources/GET-languages

Sends a GET request to the /v1/resources/languages endpoint to obtain a list of supported languages. Requires the x-api-key header for authentication. Returns a JSON object mapping language codes to language names.

```Shell
curl -X GET "https://api.sindarin.tech/v1/resources/languages" \\n  -H "x-api-key: string"
```

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

### Get Conversation by ID (Python)

Source: https://docs.sindarin.tech/conversations/GET--conversationId-

A Python function to retrieve conversation details from the Sindarin API. It uses the `requests` library to send a GET request, including the necessary API key and conversation ID. Error handling for the request and response is included.

```python
import requests

def get_conversation_by_id(conversation_id: str, api_key: str):
    """Retrieves conversation details from the Sindarin API.

    Args:
        conversation_id: The ID of the conversation to retrieve.
        api_key: Your Sindarin API key for authentication.

    Returns:
        A dictionary containing the conversation details, or None if an error occurs.
    """
    url = f"https://api.sindarin.tech/v1/conversations/{conversation_id}"
    headers = {
        "x-api-key": api_key
    }

    try:
        response = requests.get(url, headers=headers)
        response.raise_for_status()  # Raise an exception for bad status codes (4xx or 5xx)
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error fetching conversation: {e}")
        return None

# Example usage:
# conversation_id = "some-conversation-id"
# api_key = "your-api-key"
# conversation_data = get_conversation_by_id(conversation_id, api_key)
# if conversation_data:
#     print(conversation_data)

```

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

### Update User Charge Limit - Python

Source: https://docs.sindarin.tech/users/PUT-chargeLimit

Demonstrates updating a user's charge limit using Python. Requires an API key and user ID to be passed as headers and path parameters respectively. The request body specifies the new charge limit.

```Python
/* Python code for updating user charge limit would go here */
```

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

### Get Conversation by ID (Go)

Source: https://docs.sindarin.tech/conversations/GET--conversationId-

Demonstrates how to fetch conversation details using Go. This code snippet utilizes the `net/http` package to make a GET request to the Sindarin API, passing the conversation ID and API key. It handles potential errors and decodes the JSON response into a struct.

```go
package main

import (
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
	"time"
)

type ConversationResponse struct {
	Cost     float64    `json:"cost"`
	Messages []struct{} `json:"messages"`
	Status   string     `json:"status"`
	Duration int        `json:"duration"`
}

func getConversationById(conversationId string, apiKey string) (*ConversationResponse, error) {
	client := http.Client{
		Timeout: time.Second * 10, // Set a timeout
	}

	url := fmt.Sprintf("https://api.sindarin.tech/v1/conversations/%s", conversationId)

	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		return nil, fmt.Errorf("failed to create request: %w", err)
	}

	req.Header.Set("x-api-key", apiKey)

	res, err := client.Do(req)
	if err != nil {
		return nil, fmt.Errorf("failed to execute request: %w", err)
	}
	defer res.Body.Close()

	body, err := ioutil.ReadAll(res.Body)
	if err != nil {
		return nil, fmt.Errorf("failed to read response body: %w", err)
	}

	if res.StatusCode < 200 || res.StatusCode >= 300 {
		return nil, fmt.Errorf("API returned non-success status code: %d, body: %s", res.StatusCode, string(body))
	}

	var conversationData ConversationResponse
	err = json.Unmarshal(body, &conversationData)
	if err != nil {
		return nil, fmt.Errorf("failed to unmarshal JSON response: %w", err)
	}

	return &conversationData, nil
}

// Example usage:
// func main() {
// 	conversationID := "some-conversation-id"
// 	apiKey := "your-api-key"
// 	data, err := getConversationById(conversationID, apiKey)
// 	if err != nil {
// 		fmt.Printf("Error: %v\n", err)
// 		return
// 	}
// 	fmt.Printf("Conversation Data: %+v\n", data)
// }
```

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

### Falsy Value Detection with ifIsFalsy Helper

Source: https://docs.sindarin.tech/persona/core-concepts/workflows

Renders content when a state variable is falsy (false, 0, null, undefined, or empty string). Useful for initialization states and default message handling.

```handlebars
{{#ifIsFalsy state.hasGreeted}}
  Hello! Welcome to our conversation.
{{/ifIsFalsy}}
```
Tokens:
Raw