Get contracted agent details

Get each contracted Vini agent type for the rooftop, with the created agent's summary when one exists.

GEThttps://api.spyne.ai/console/v1/product-onboarding/vini/agents/teams/{teamId}/enterpriseId/{enterpriseId}

AuthBearer token (console user)Rate limitNot documentedProcessingSynchronous; waits for the agent service (30-second timeout).

The API reads the Vini products the rooftop has in the Contracted, Onboarding or Live stage and returns one entry per agent type. Each entry carries the agent type details. If an agent has already been created for that type, it also carries a config summary with the agent's ID, name, image, phone number and whether it is onboarded. Stage details for each product are added when available. Nothing is written.

Before you call it

Send Authorization: Bearer YOUR_TOKEN, the signed-in console user's session token. It is checked here and passed on to the agent service, which checks it again.
You need teamId and enterpriseId.
The rooftop must have Vini products in Contracted, Onboarding or Live. If it has none, you get 200 with an empty data array.
The agent types are worked out from the rooftop's products. A purchasedAgentTypes query parameter is not read.
The call is synchronous. It waits for the agent service, with a 30-second timeout, and returns its response. Rate limit: not documented.

Path parameters

Requiredalways send

Request checklist

Authenticate: send Authorization: Bearer YOUR_TOKEN.
Identify the rooftop: put teamId and enterpriseId in the path.
Read the agents: read contractedAgents[]. An empty config means no agent has been created for that type yet.
Read state: use config.isOnboarded and config.teamAgentMappingId for the agent's onboarding state and ID.

Parameter	Type	Required	Description
`teamId`	string	Required	Rooftop ID.
`enterpriseId`	string	Required	Dealer group ID.

Sample request

curl -X GET "https://api.spyne.ai/console/v1/product-onboarding/vini/agents/teams/<teamId>/enterpriseId/<enterpriseId>" \
  -H "Authorization: Bearer YOUR_TOKEN"

import requests

resp = requests.get(
    "https://api.spyne.ai/console/v1/product-onboarding/vini/agents/teams/<teamId>/enterpriseId/<enterpriseId>",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
)
agents = resp.json().get("contractedAgents", [])

const res = await fetch(
  "https://api.spyne.ai/console/v1/product-onboarding/vini/agents/teams/<teamId>/enterpriseId/<enterpriseId>",
  { headers: { Authorization: "Bearer YOUR_TOKEN" } }
);
const { contractedAgents = [] } = await res.json();

Sample response

{
  "contractedAgents": [
    {
      "agentTypeId": "<agentTypeId>",
      "name": "Sales Inbound",
      "agentType": "sales",
      "agentUseCase": "<agentUseCase>",
      "agentCallType": "inbound",
      "availableCount": 0,
      "config": {
        "teamAgentMappingId": "<teamAgentMappingId>",
        "name": "<agentName>",
        "imageUrl": "https://example.com/avatar.png",
        "phoneNumber": "<phoneNumber>",
        "isOnboarded": false
      },
      "productDetailId": "<productDetailId>",
      "defaultImageUrl": "https://example.com/default-avatar.png",
      "stage": "Onboarding",
      "subStage": null
    },
    {
      "agentTypeId": "<agentTypeId>",
      "name": "Service Outbound",
      "agentType": "service",
      "agentUseCase": "<agentUseCase>",
      "agentCallType": "outbound",
      "availableCount": 1,
      "config": {},
      "productDetailId": null,
      "defaultImageUrl": "https://example.com/default-avatar.png",
      "stage": null,
      "subStage": null
    }
  ]
}

{
  "data": [],
  "message": "No conversational AI agents found in contracting data"
}

{
  "statusCode": 400,
  "message": "Failed to retrieve contracted agents",
  "errorCode": "BAD_REQUEST",
  "timestamp": "2026-10-12T10:00:00.000Z",
  "requestId": "<requestId>",
  "context": {},
  "path": "/conversation/agents/team/<teamId>/enterprise/<enterpriseId>?purchasedAgentTypes=inboundSales",
  "method": "GET"
}

{
  "message": "Invalid Token",
  "error": true,
  "code": "ERROR_AUTH_401",
  "details": "",
  "data": null
}

{
  "message": "No response received from external API",
  "error": "timeout of 30000ms exceeded"
}

Response parameters (200)

Parameter	Type	Description
`contractedAgents`	array	One entry per contracted agent type.
`contractedAgents[].agentTypeId`	string	Agent type ID.
`contractedAgents[].name`	string	Agent type name, for example "Sales Inbound". This is not the created agent's name.
`contractedAgents[].agentType`	string	Agent type, for example `sales`.
`contractedAgents[].agentUseCase`	string	Agent use case.
`contractedAgents[].agentCallType`	string	`inbound` or `outbound`.
`contractedAgents[].availableCount`	number	How many more agents of this type can be created: 1 minus the number of active agents, never below 0.
`contractedAgents[].config`	object	Created agent summary, or an empty object when none exists yet.
`config.teamAgentMappingId`	string	The created agent's ID.
`config.name`	string	The created agent's name, or `""`.
`config.imageUrl`	string	The agent's avatar, or `""`. Use `defaultImageUrl` when it is empty.
`config.phoneNumber`	string	The agent's active phone number. Left out when there is none.
`config.isOnboarded`	boolean	Whether the agent is onboarded (activated).
`contractedAgents[].productDetailId`	string or null	The rooftop's product record for this agent, when found.
`contractedAgents[].defaultImageUrl`	string or null	A fallback avatar, the same on every entry.
`contractedAgents[].stage`	string or null	Product stage, when found.
`contractedAgents[].subStage`	string or null	Product sub-stage, when found.
`data`	array	Only in the "no products" response. Always empty.
`message`	string	Only in the "no products" response.

Errors

Status	Code	When it happens
`400`	Missing `teamId`	The framework rejects the request.
`400`	`Failed to retrieve contracted agents`	The agent service could not read the agent types. Its error body is passed through unchanged.
`401`	`ERROR_AUTH_401`	Missing, malformed or invalid token, here or at the agent service.
Other 4xx / 5xx	Passed through	Any error status and body from the agent service is returned as is.
`500`	`No response received from external API`	The agent service did not answer, for example a timeout after 30 seconds.
`500`	`Error setting up request`	The call to the agent service could not be built.

What happens next

Use config.teamAgentMappingId to open or configure an agent, and config.isOnboarded for its activation state. When the agent is configured, mark Agent Customization done for its segment. The agent setup endpoints in the Agent Setup section come next.

This call comes after Get the onboarding checklist.