Get the onboarding checklist

Get the rooftop's Vini onboarding checklist, grouped by agent segment and section, with each task's status.

GEThttps://api.spyne.ai/console/v1/onboarding/task/get-onboarding-task-v2

AuthBearer token (console user)Rate limitNot documentedProcessingSynchronous.

The API finds the rooftop's active product line by name (for Vini, conversationalAi) and reads all its active onboarding tasks, newest first. Tasks are grouped by segment (segmentName, one per agent) and then by section (task_group_name). Tasks without a segment go in a separate top-level list. Each task has its status and, when the template set it, whether it is required. You can pass one or more product line IDs instead. Nothing is written.

Before you call it

Send Authorization: Bearer YOUR_TOKEN. The token is the signed-in console user's session token. It is checked against the user service on every call.
The rooftop must have an active conversationalAi product line with onboarding tasks. Tasks are created from the product line's task template when onboarding starts.
Pass either productLineId, or both teamId and productLineName.
If a rooftop has more than one active conversationalAi product line, the one used is not defined. The lookup takes the first row with no ordering.
The call is synchronous. Rate limit: not documented.

Query parameters

Requiredalways sendRequired ifrequired only in the case describedOptionalcan be left out

Request checklist

Authenticate: send Authorization: Bearer YOUR_TOKEN.
Pick the product line: pass teamId and productLineName=conversationalAi.
Read each agent: read data.product_group.segment_name.<segmentName>.task_group_list for each agent the rooftop bought.
Read status: ignore tasks with is_active: false. Treat status: "COMPLETED" as done.
Handle duplicates: if the same task_name appears more than once in a segment, use the row with the latest updated_at.

Parameter	Type	Required	Description
Product line to read	—	Required	Send `productLineId`, or both `teamId` and `productLineName`.
`teamId`	string	Required if	Rooftop ID. Required unless `productLineId` is sent. Used with `productLineName` to find the product line.
`productLineName`	string	Required if	Required unless `productLineId` is sent. `conversationalAi` for Vini. Allowed values: `studioAi`, `conversationalAi`.
`productLineId`	string	Optional	One product line ID, or up to 20 comma-separated IDs. With more than one ID, do not send `teamId`, `productLineName` or `productGroup`.
`productGroup`	string	Optional	Accepted but not used to filter the result.

Sample request

curl -X GET "https://api.spyne.ai/console/v1/onboarding/task/get-onboarding-task-v2?teamId=<teamId>&productLineName=conversationalAi" \
  -H "Authorization: Bearer YOUR_TOKEN"

import requests

resp = requests.get(
    "https://api.spyne.ai/console/v1/onboarding/task/get-onboarding-task-v2",
    params={"teamId": "<teamId>", "productLineName": "conversationalAi"},
    headers={"Authorization": "Bearer YOUR_TOKEN"},
)
segments = resp.json()["data"]["product_group"]["segment_name"]

const params = new URLSearchParams({ teamId: "<teamId>", productLineName: "conversationalAi" });
const res = await fetch(
  `https://api.spyne.ai/console/v1/onboarding/task/get-onboarding-task-v2?${params}`,
  { headers: { Authorization: "Bearer YOUR_TOKEN" } }
);
const { data } = await res.json();

Sample response

{
  "message": "Found 3 onboarding tasks",
  "totalCount": 3,
  "data": {
    "product_line_id": "<productLineId>",
    "product_group": {
      "segment_name": {
        "inboundSales": {
          "task_group_list": [
            {
              "task_group_name": "Agent Setup",
              "task_list": [
                {
                  "id": "<taskId>",
                  "product_line_id": "<productLineId>",
                  "team_id": "<teamId>",
                  "start_time": null,
                  "end_time": null,
                  "segment_name": "inboundSales",
                  "task_name": "Agent Customization",
                  "status": "PENDING",
                  "is_active": true,
                  "created_at": "2026-10-01T10:00:00.000Z",
                  "updated_at": "2026-10-01T10:00:00.000Z",
                  "required": true
                }
              ]
            },
            {
              "task_group_name": "Rooftop Setup",
              "task_list": [
                {
                  "id": "<taskId>",
                  "product_line_id": "<productLineId>",
                  "team_id": "<teamId>",
                  "start_time": "2026-10-01T11:00:00.000Z",
                  "end_time": "2026-10-01T11:00:00.000Z",
                  "segment_name": "inboundSales",
                  "task_name": "Rooftop Setup",
                  "status": "COMPLETED",
                  "is_active": true,
                  "created_at": "2026-10-01T10:00:00.000Z",
                  "updated_at": "2026-10-01T11:00:00.000Z",
                  "required": true
                }
              ]
            }
          ]
        }
      },
      "task_group_list": [
        {
          "task_group_name": "Rooftop Setup",
          "task_list": [
            {
              "id": "<taskId>",
              "product_line_id": "<productLineId>",
              "team_id": "<teamId>",
              "start_time": null,
              "end_time": null,
              "segment_name": null,
              "task_name": "User Setup",
              "status": "PENDING",
              "is_active": true,
              "created_at": "2026-10-01T10:00:00.000Z",
              "updated_at": "2026-10-01T10:00:00.000Z"
            }
          ]
        }
      ]
    }
  }
}

{
  "message": "Either productLineId, or both teamId and productLineName, must be provided",
  "error": true
}

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

{
  "message": "No conversationalAi product line found for team <teamId>",
  "data": []
}

{
  "message": "No onboarding tasks found for the specified product line",
  "data": []
}

Response parameters (200)

Parameter	Type	Description
`message`	string	`Found <n> onboarding tasks`.
`totalCount`	number	Number of active tasks returned.
`data.product_line_id`	string	The product line the tasks belong to.
`data.product_group.segment_name`	object or null	Tasks with a segment, keyed by `segmentName`, for example `inboundSales`. `null` when no task has a segment.
`data.product_group.segment_name.<segmentName>.task_group_list`	array	Sections in this segment.
`data.product_group.task_group_list`	array	Sections for tasks with no segment.
`task_group_list[].task_group_name`	string	Section name, for example `Rooftop Setup`, `Integrations`, `Agent Setup`, `Go Live Readiness`.
`task_group_list[].task_list[]`	array	Tasks in the section, newest first.
`task_list[].id`	string	Task ID.
`task_list[].product_line_id`	string	Product line ID.
`task_list[].team_id`	string	Rooftop ID.
`task_list[].start_time`	string or null	When the task was first started.
`task_list[].end_time`	string or null	When the task was completed. Cleared when it is set back to in progress.
`task_list[].segment_name`	string or null	The task's segment.
`task_list[].task_name`	string	Task name. Send this exact string as `taskName` when you mark it done.
`task_list[].status`	string	`PENDING`, `INPROGRESS`, `COMPLETED` or `N/A`.
`task_list[].is_active`	boolean	Always `true` in this response. Only active tasks are read.
`task_list[].created_at`	string	Creation time.
`task_list[].updated_at`	string	Last update time.
`task_list[].required`	boolean	Whether the task must be done before go-live. Present only when the template set it.

With several productLineId values, data is an array of { product_line_id, product_group } objects instead.

Errors

Status	Code	When it happens
`400`	Missing input	Neither `productLineId` nor both `teamId` and `productLineName` were sent.
`400`	Too many IDs	More than 20 `productLineId` values.
`400`	Conflicting inputs	Several `productLineId` values together with `teamId`, `productLineName` or `productGroup`.
`400`	Invalid `productLineName`	A value other than `studioAi` or `conversationalAi`. The framework rejects the request.
`400`	`Failed to retrieve onboarding tasks`	Any other failure while reading. The body has `error` (the error message) and `message`.
`401`	`ERROR_AUTH_401`	Missing, malformed or invalid token.
`404`	No product line	No active product line with that name for the rooftop.
`404`	No tasks	The product line has no active tasks.

What happens next

Show one checklist per agent the rooftop bought, using its segment. Use Get contracted agent details to load each agent. When a setup step finishes, call Mark a task done with the task's task_name. Call this endpoint again to refresh status.

This call comes after List active Vini products.