Skip to navigation
API ReferenceResponses

Create

Generates one or more alternative assistant responses for a conversation you supply inline to simulate Phonic agent behavior.

This endpoint is stateless, so it does not create a new conversation or store anything. The request carries the system prompt, a conversation so far as input, and the tools the assistant may call.

There are two different types of tool configurations:

  • tool_definitions: defined inline. Typically if you use LiveKit, this is where you can pass in your tool definitions.
  • tools: predefined tools configured in Phonic, referenced by name, in the same shape as the STS WebSocket config message. Today this covers built-in tools such as choose_not_to_respond and transfer tools stored in project. Your context, webhook, MCP and WebSocket tools cannot be referenced here yet; define those inline as tool_definitions.

Each item in input is a user message, an assistant message (with optional tool_calls or an action), or a tool_call_output. Every assistant tool call must be followed immediately by the tool_call_output item that carries its result.

A tool referenced in tools resolves to an action on the generated response rather than a tool call - the event a live conversation would have emitted, without the effect actually being carried out.

This is an experimental feature and must be enabled for your workspace; otherwise, it returns 404. Please contact our team if you would like access.

Authentication

AuthorizationBearer

Bearer authentication header of the form Bearer <PHONIC_API_KEY>. Manage your API keys here.

Request

This endpoint expects an object.
system_promptstringRequired>=1 character
The system prompt the assistant should follow.
inputlist of objectsRequired
The conversation so far, in order. Must contain at least one item.
voice_idstringOptionalDefaults to sabrina
ID of the voice the assistant would speak with. It shapes how the responses are worded.
default_languageenumOptional

ISO 639-1 language code that sets the assistant’s default language to recognize and speak.

additional_languageslist of enumsOptionalDefaults to []

Array of additional ISO 639-1 language codes that the assistant should be able to recognize and speak. Should not include default_language.

tool_definitionslist of objectsOptionalDefaults to []

Tools defined inline for this request only. Typically if you use LiveKit, this is where you can pass in your tool definitions. Names must be unique, must not repeat a name in tools, and cannot be one of the names Phonic reserves for its built-in tools.

projectstringOptional>=1 character

Name of the project the tools referenced by name in tools belong to. Required whenever tools names a tool stored in your workspace; built-in tools can be referenced without it.

toolslist of strings or objectsOptionalDefaults to []

Tools the assistant may call that already exist - a built-in tool, or a transfer tool stored in project, referenced by name. Names must be unique and must not repeat a name in tool_definitions. Stored tools that are not transfer tools cannot be referenced here yet; define them inline as tool_definitions instead.

phonic_modelenumOptional

The Phonic speech-to-speech model to generate with. Omit it to use the current default model.

Allowed values:
num_responsesintegerOptional1-200Defaults to 1
Number of alternative responses to generate.

Response

Success response
responseslist of objects

The generated responses - always num_responses of them.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error