Update an agent

Change an existing agent's settings. This save also completes the "Agent Customization" task.

POSThttps://api.spyne.ai/console/v1/product-onboarding/vini/agent

AuthBearer token (console user)Rate limitNot documentedProcessingSynchronous; waits for the agent backend and the database write

It is the same path as Create an agent. Sending entityConfig.agent.agentId (or its alias teamAgentMappingId) makes the call an update. To turn the agent on or off, see Go-Live.

Auth: Bearer token of a signed-in console user. The console checks it with the identity service, and the configuration store checks it again. Rate limit: not documented. Processing: synchronous. The call waits for the agent backend and the database write.

Before you call it

You need the agent id: data.agentId from Create an agent, or teamAgentMappingId from Get an agent or List agents.
Use the same entity the agent was created with. The stored copy is kept per entity.
Send the same headers as Create an agent.

How the update works

The configuration store sends only the fields you include to the agent backend. The agent backend updates the active agent with that id, but only within the enterpriseId and teamId you send. tts is replaced as a whole. The configuration store then deep-merges the fields into its stored copy, so fields you leave out stay as they were.

Request body

Requiredalways sendOptionalcan be left outRequired ifrequired only in the case described

Request checklist

Scope it: send enterpriseId, teamId, entity and entityConfig.agent.agentId.
Send what changes: only the fields you want to change. agentTypeId, agentName and avatarId are optional on update. The console UI sends the full form each time.
Voice: if you send tts, send all of it. voiceId and supportedLanguages are required inside it.

Parameter	Type	Required	Description
`enterpriseId`	string	Required	Dealer group.
`teamId`	string	Required	Rooftop.
`enterpriseName`, `teamName`	string	Optional	Stored with the record.
`entity`	string	Required	Agent type key used at create.
`entityConfig.agent`	object	Required	The changes. Fields below.
`agentId`	string	Required	Agent id. `teamAgentMappingId` is accepted as an alias.
`tts`	object	Optional	Replaced as a whole.
`tts.voiceId`	string	Required if	Required if you send `tts`.
`tts.supportedLanguages`	string[]	Required if	Required if you send `tts`. At least one language code.
Any other `entityConfig.agent` field	mixed	Optional	Same fields and rules as Create an agent.

Sample request

curl -X POST "https://api.spyne.ai/console/v1/product-onboarding/vini/agent" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enterpriseId": "<enterpriseId>",
    "teamId": "<teamId>",
    "entity": "sales_inbound",
    "entityConfig": {
      "agent": {
        "agentId": "<agentId>",
        "agentName": "Ava",
        "firstMessage": "Thanks for calling Example Motors, this is Ava. How can I help today?"
      }
    }
  }'

import requests

body = {
    "enterpriseId": "<enterpriseId>",
    "teamId": "<teamId>",
    "entity": "sales_inbound",
    "entityConfig": {"agent": {"agentId": "<agentId>", "agentName": "Ava"}},
}
res = requests.post(
    "https://api.spyne.ai/console/v1/product-onboarding/vini/agent",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json=body,
)
print(res.status_code, res.json())

const res = await fetch('https://api.spyne.ai/console/v1/product-onboarding/vini/agent', {
  method: 'POST',
  headers: { Authorization: 'Bearer YOUR_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    enterpriseId: '<enterpriseId>',
    teamId: '<teamId>',
    entity: 'sales_inbound',
    entityConfig: { agent: { agentId: '<agentId>', agentName: 'Ava' } },
  }),
});
console.log(res.status, await res.json());

Sample response

{
  "success": true,
  "message": "Agent updated successfully",
  "data": {
    "agentId": "<agentId>",
    "entity": "sales_inbound",
    "created": false,
    "agent": {
      "agentId": "<agentId>",
      "agentTypeId": "<agentTypeId>",
      "agentName": "Ava",
      "firstMessage": "Thanks for calling Example Motors, this is Ava. How can I help today?"
    }
  }
}

{
  "success": false,
  "message": "Team agent mapping with id <agentId> not found",
  "error": "Team agent mapping with id <agentId> not found"
}

401, 500 and 502 responses have the same shapes as on Create an agent.

Response parameters (200)

Parameter	Type	Description
`success`	boolean	`true` on success.
`message`	string	`Agent updated successfully`.
`data.agentId`	string	Agent id.
`data.entity`	string	Agent type key.
`data.created`	boolean	`false` for an update.
`data.agent`	object	The full stored agent object after the merge.

Errors

Status	Reason	When it happens
`400`	Validation error	An empty `agentId`, a bad `entity`, an incomplete `tts`, or another field rule fails.
`400`	Team agent mapping with id ... not found	No active agent with this id on this dealer group and rooftop.
`401`	Invalid token	Missing or rejected token.
`500`	Failed to save agent	The database write failed after the agent backend was already updated.
`502`	Bad gateway	The agent backend returned a 5xx or could not be reached. Nothing is saved in the configuration store.

What happens next

The console UI calls Mark a task done with taskName: "Agent Customization" after every successful save, including updates. For go-live, see Go-Live.