Get an agent

Return the saved settings of one existing agent, plus details of its voice. The console UI calls this to pre-fill the "Agent Customization" form when the agent already exists.

GEThttps://api.spyne.ai/conversation/agents/team/{teamId}/enterprise/{enterpriseId}/agent-mapping/{teamAgentMappingId}

AuthBearer token (console user)Rate limitNot documentedProcessingSynchronous; database reads plus a best-effort voice catalog lookup

The call reads one active agent on the rooftop by its teamAgentMappingId. It returns the agent's name, avatar, messages, transfer mode, voice (tts), assertiveness, ambient sound and phone number, if one is attached. It also looks up the voice in the voice catalog and returns it as voiceConfig. If that lookup fails, voiceConfig is null and the call still succeeds. Nothing is stored.

Auth: Bearer token of a signed-in user, checked with the identity service. The route does not check that the token belongs to this dealer group or rooftop. Rate limit: not documented. Processing: synchronous. Database reads plus a best-effort voice catalog lookup.

Before you call it

The agent must already exist. Before the first save there is nothing to read.
teamAgentMappingId is the agent id. Get it from the contracted-agents list (config.teamAgentMappingId), from List agents, or from data.agentId in the Create an agent response.
Leave isDemoAgent out for a real dealer agent.

Path parameters

Requiredalways sendOptionalcan be left out

Parameter	Type	Required	Description
`teamId`	string	Required	Rooftop.
`enterpriseId`	string	Required	Dealer group.
`teamAgentMappingId`	string	Required	Agent id.

Query parameters

Parameter	Type	Required	Description
`isDemoAgent`	string	Optional	Only the literal `true` reads a console demo agent instead of a real one.

Sample request

curl "https://api.spyne.ai/conversation/agents/team/<teamId>/enterprise/<enterpriseId>/agent-mapping/<teamAgentMappingId>" \
  -H "Authorization: Bearer YOUR_TOKEN"

import requests

url = ("https://api.spyne.ai/conversation/agents/team/<teamId>"
       "/enterprise/<enterpriseId>/agent-mapping/<teamAgentMappingId>")
res = requests.get(url, headers={"Authorization": "Bearer YOUR_TOKEN"})
print(res.status_code, res.json())

const url = 'https://api.spyne.ai/conversation/agents/team/<teamId>/enterprise/<enterpriseId>/agent-mapping/<teamAgentMappingId>';
const res = await fetch(url, { headers: { Authorization: 'Bearer YOUR_TOKEN' } });
console.log(res.status, await res.json());

Sample response

{
  "teamAgentMappingId": "<teamAgentMappingId>",
  "templateId": null,
  "name": "Ava",
  "gender": "female",
  "description": "",
  "avatarId": "<avatarId>",
  "imageUrl": "https://example.com/avatar.png",
  "languageCode": "",
  "countryCode": "US",
  "nationality": "American",
  "city": "LA",
  "firstMessage": "Thanks for calling Example Motors, this is Ava. How can I help?",
  "voicemailMessage": "Hi, this is Ava from Example Motors. Please call us back.",
  "endCallMessage": "Thanks for calling. Goodbye.",
  "afterHoursMessage": "We are closed right now, but I can still help.",
  "partiallyOpenMessage": "",
  "transferMode": "seamless",
  "transferModeRule": "",
  "audioUrl": "",
  "capabilities": [],
  "phoneNumber": "+1XXXXXXXXXX",
  "tts": {
    "provider": "elevenlabs",
    "voiceId": "<voiceId>",
    "voiceSettings": { "speed": 1 },
    "supportedLanguages": ["en"]
  },
  "executionMode": "single_agent",
  "assertiveness": "low",
  "ambientSound": { "type": "office", "volume": 0.6 },
  "voiceConfig": {
    "voiceId": "<voiceId>",
    "name": "Example Voice",
    "gender": "female",
    "previewUrl": "https://example.com/preview.mp3"
  }
}

{
  "statusCode": 404,
  "message": "No active agent <teamAgentMappingId> for team <teamId> in enterprise <enterpriseId>",
  "errorCode": "NOT_FOUND",
  "timestamp": "2026-10-12T10:00:00.000Z",
  "requestId": "req_1760263200000_abc123xyz",
  "context": {},
  "path": "/conversation/agents/team/<teamId>/enterprise/<enterpriseId>/agent-mapping/<teamAgentMappingId>",
  "method": "GET"
}

A 401 has the same shape as on Browse the voice library.

Response parameters (200)

Parameter	Type	Description
`teamAgentMappingId`	string	Agent id.
`templateId`	string	Legacy template id, if any.
`name`	string	Agent name.
`gender`, `imageUrl`, `nationality`, `city`, `countryCode`	string	Persona details. When unset, `nationality` reads back as `American`, `city` as `LA` and `countryCode` as `US`.
`avatarId`	string	Avatar id.
`description`	string	Agent description.
`languageCode`	string	Language code on the agent record.
`firstMessage`, `voicemailMessage`, `endCallMessage`, `afterHoursMessage`, `partiallyOpenMessage`	string	Call messages. Empty string when unset.
`transferMode`	string	`seamless` (default) or `nudge`.
`transferModeRule`	string	Rule used with `nudge`.
`audioUrl`, `agentCardText`	string	Card display fields.
`capabilities`	array	Agent capabilities.
`phoneNumber`	string	E.164 number attached to this agent, if any.
`tts`	object	Voice: `provider`, `model`, `voiceId`, `voiceSettings`, `supportedLanguages`.
`executionMode`	string	Defaults to `single_agent`.
`assertiveness`	string	`none`, `low`, `medium` or `high`. Unset reads back as `low`.
`ambientSound`	object	`type` and `volume`. Unset reads back as `office` at `0.6`.
`voiceConfig`	object or null	Catalog details of the voice (same fields as a voice in Browse the voice library), or `null`.

Errors

Status	Reason	When it happens
`401`	Authentication failed	Missing or rejected token.
`404`	No active agent ...	No active, non-demo agent with this id on this dealer group and rooftop.
`500`	Internal server error	A database read failed.

What happens next

Pre-fill the agent form. Send the edited values to Update an agent.