> ## Documentation Index > Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Agent > Returns the published agent with its complete normalized configuration ## OpenAPI ````yaml latest.yml GET /v1/agents/{agent_id} openapi: 3.0.1 info: title: Cartesia API version: 0.0.1 servers: - url: https://api.cartesia.ai description: Production security: [] paths: /v1/agents/{agent_id}: get: tags: - Agents summary: Get an agent description: Returns the published agent with its complete normalized configuration operationId: getV1AgentsByAgent_id parameters: - name: agent_id in: path description: Unique identifier for the agent. required: true schema: description: Unique identifier for the agent. type: string minLength: 1 - $ref: '#/components/parameters/CartesiaVersionHeader' responses: '200': description: Get an agent content: application/json: schema: $ref: '#/components/schemas/ManagedAgentV1' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/PublicErrorResponse' security: - APIKeyAuth: [] components: parameters: CartesiaVersionHeader: name: Cartesia-Version in: header description: API version header. required: true schema: type: string format: date example: '2026-08-14' default: '2026-08-14' enum: - '2026-08-14' schemas: ManagedAgentV1: type: object properties: config: $ref: '#/components/schemas/ManagedAgentConfigV1' created_at: description: >- An RFC 3339 / ISO 8601 date-time string with timezone (e.g. `2025-04-16T12:34:56.789Z`). type: string format: date-time description: description: Description of the agent. nullable: true type: string id: description: Unique identifier for the agent. type: string minLength: 1 name: description: Name shown for the agent. type: string updated_at: description: >- An RFC 3339 / ISO 8601 date-time string with timezone (e.g. `2025-04-16T12:34:56.789Z`). type: string format: date-time version: type: object properties: created_at: description: Time when this version was created. type: string format: date-time created_by: description: >- ID of the user or API key that created this version. `null` when no creator was recorded. nullable: true type: string minLength: 1 description: description: >- Description supplied when this version was created. `null` if none was provided. nullable: true type: string id: description: Unique identifier for an immutable agent configuration version. type: string minLength: 1 required: - id - description - created_at - created_by required: - id - name - description - created_at - updated_at - config - version title: ManagedAgent PublicErrorResponse: type: object properties: doc_url: description: URL to relevant documentation for the error type: string nullable: true error_code: description: Machine-readable error code type: string nullable: true message: description: Detailed human-readable error message type: string request_id: description: >- Unique identifier for this request. Include this when contacting support. type: string title: description: Short human-readable error summary, like "File too large" type: string required: - request_id - message - title title: PublicErrorResponse ManagedAgentConfigV1: description: >- Complete configuration for the agent's model, language, audio, and tools. type: object properties: audio: type: object properties: input: type: object properties: keyterms: description: >- Words or phrases that the speech recognizer should prioritize. type: array items: type: string noise_suppression: description: >- Noise suppression applied to incoming audio. Use `off` to disable it, `auto` for the default level, or `max` for stronger suppression. type: string enum: - 'off' - auto - max required: - noise_suppression - keyterms output: type: object properties: background_sound: description: Background audio played during the conversation. nullable: true type: object properties: file_id: description: ID of the audio file to play in the background. type: string minLength: 1 volume: description: Background audio volume, from `0` to `2`. type: number maximum: 2 minimum: 0 required: - file_id - volume emotion: description: >- Text-to-speech emotion supported by the selected voice and model, such as `calm`, `happy`, or `sad`. nullable: true type: string pronunciation_dictionary_id: description: ID of the pronunciation dictionary used for agent speech. nullable: true type: string minLength: 1 speed: description: >- Speech speed multiplier, from `0.6` to `1.5`. Set to `null` to use the default speed. nullable: true type: number minimum: 0.6 maximum: 1.5 voice_id: description: ID of the voice used for agent speech. type: string minLength: 1 volume: description: >- Speech volume multiplier, from `0.5` to `2`. Set to `null` to use the default volume. nullable: true type: number minimum: 0.5 maximum: 2 required: - voice_id - speed - volume - emotion - pronunciation_dictionary_id - background_sound required: - input - output initial_message: description: >- Message the agent says when the conversation begins. Set to `null` to wait for the user to speak first. nullable: true type: string instructions: description: Instructions that define the agent's behavior. type: string language: type: object properties: primary: description: >- Primary language for the conversation. Set to `null` to detect it automatically. nullable: true type: string required: - primary model: type: object properties: id: description: Model ID from `GET /v1/agents/models`. type: string example: gpt-5.4-mini minLength: 1 max_output_tokens: description: >- Maximum number of tokens the model can generate, from `1` to `4096`. Set to `null` for no limit. nullable: true type: integer minimum: 1 maximum: 4096 temperature: nullable: true type: number minimum: 0 maximum: 1 description: Controls the randomness of model responses, from `0` to `1`. required: - id - temperature - max_output_tokens system_tools: $ref: '#/components/schemas/ManagedAgentSystemToolsV1' description: Built-in tools available to the agent. additionalProperties: false tools: description: Tools available to the agent. type: array items: $ref: '#/components/schemas/ManagedAgentToolReferenceV1' maxItems: 32 uniqueItems: true required: - instructions - initial_message - model - language - audio - tools - system_tools title: ManagedAgentConfig ManagedAgentSystemToolsV1: type: object properties: end_call: description: >- Configuration for ending the call. Set to `null` to disable this tool. nullable: true type: object properties: description: description: >- What the tool does and when the agent should use it. Set to `null` to use the default system-optimized description. nullable: true type: string minLength: 1 maxLength: 2000 pre_tool_speech: description: >- Controls whether the agent speaks before using the tool. `auto` lets the agent decide, while `force` asks the agent to speak first. type: string enum: - auto - force required: - description - pre_tool_speech send_dtmf: description: >- Configuration for sending DTMF tones. Set to `null` to disable this tool. nullable: true type: object properties: description: description: >- What the tool does and when the agent should use it. Set to `null` to use the default system-optimized description. nullable: true type: string minLength: 1 maxLength: 2000 pre_tool_speech: description: >- Controls whether the agent speaks before using the tool. `auto` lets the agent decide, while `force` asks the agent to speak first. type: string enum: - auto - force required: - description - pre_tool_speech transfer_to_number: description: >- Configuration for transferring the call. Set to `null` to disable this tool. nullable: true type: object properties: description: description: >- What the tool does and when the agent should use it. Set to `null` to use the default system-optimized description. nullable: true type: string minLength: 1 maxLength: 2000 pre_tool_speech: description: >- Controls whether the agent speaks before using the tool. `auto` lets the agent decide, while `force` asks the agent to speak first. type: string enum: - auto - force transfers: description: Phone numbers the agent can transfer a call to. type: array items: type: object properties: condition: description: >- When the agent should transfer the call to this destination. type: string maxLength: 1000 minLength: 1 destination: description: Where to transfer the call. type: object properties: phone_number: description: Phone number to transfer the call to, in E.164 format. type: string pattern: ^\+[1-9]\d{6,14}$ type: description: The destination type. type: string enum: - phone required: - type - phone_number required: - destination - condition maxItems: 16 minItems: 1 uniqueItems: true required: - description - pre_tool_speech - transfers required: - end_call - send_dtmf - transfer_to_number title: ManagedAgentSystemTools ManagedAgentToolReferenceV1: type: object properties: id: description: ID of a tool from the Tools API. type: string minLength: 1 required: - id title: ManagedAgentToolReference securitySchemes: APIKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- Cartesia API key (`sk_car_...`). Get one at [play.cartesia.ai/keys](https://play.cartesia.ai/keys). x-default: $CARTESIA_API_KEY ````