Teams

Overview

Use the Teams API call to create, update, retrieve, and delete AI teams. With this REST API, you can do the following:

• Create teams
• Update teams
• Get teams
• Get teams by ID
• Delete teams by ID

Team execution modes

A team runs in one of two modes:

• Static-flow mode — agents run along a fixed path defined by _flow (__start__ → … → __end__). The same order every time.
• Supervisory mode — enabled automatically when any agent in _agents has a non-empty _subAgents list. A supervisor agent decides at runtime which sub-agent runs next, so _flow is ignored (pass []). Use _order to chain multiple supervisors and the optional _onfailure for a fallback agent. See Supervisory teams.

Using the namespace filter

Note: The nsfilter (namespace filter) query parameter is mandatory for every API request. It sets the context, helping you look up resources within that namespace.

Example:

GET /aisvc/api/v1/teams?nsfilter=your_namespace

Create Teams

Endpoint

POST /aisvc/api/v1/teams

Request

Query parameters

Parameter	Type	Description	Required
nsfilter	String	Filter by namespace.	Required

Body parameters

Parameter	Type	Description	Required
_name	String	Name of the team.	Required
_namespaces	Array of String	Namespaces to include.	Required
_agents	Array of Object	List of agents. Each item has _userType and may include the supervisory fields _subAgents, _order, and _onfailure (see Supervisory teams).	Required
_flow	Array of Object	Static-flow graph as from/to edges. Required for static-flow teams; omit or pass [] for supervisory teams.	Optional
_permissionProfileId	String	The id of the permission profile to use for the Team execution, which will run with the specified profile’s context instead of the user’s.	Optional

Body example (static-flow team)

{
  "_name": "The BIM Analyst",
  "_namespaces": ["testproject_Lik2UwIN"],
  "_agents": [{ "_userType": "bim_analyst" }],
  "_flow": [
    { "from": "__start__", "to": "bim_analyst" },
    { "from": "bim_analyst", "to": "__end__" }
  ]
}

Supervisory teams

A team runs in supervisory mode when any agent in _agents has a non-empty _subAgents list. In this mode a supervisor agent routes to its sub-agents at runtime, so _flow is ignored (pass []).

Each object in _agents supports:

Field	Type	Description	Required
_userType	String	The agent's user type.	Required
_subAgents	Array of Object	Worker agents this supervisor may delegate to, each { "_userType": "..." }. A non-empty list makes the agent a supervisor and the team supervisory.	Optional
_order	Number	Supervisor chain position; the lowest _order is the entry point. Use when chaining multiple supervisors.	Optional
_onfailure	String	_userType of a fallback agent used when routing gets stuck (for example, a loop).	Optional

Body example (supervisory team)

{
  "_name": "Platform Co-Supervisor Team",
  "_namespaces": ["testproject_Lik2UwIN"],
  "_agents": [
    {
      "_userType": "content_supervisor",
      "_order": 1,
      "_subAgents": [
        { "_userType": "file_specialist" },
        { "_userType": "model_specialist" }
      ]
    },
    {
      "_userType": "operations_supervisor",
      "_order": 2,
      "_subAgents": [
        { "_userType": "telemetry_specialist" },
        { "_userType": "access_specialist" }
      ]
    }
  ],
  "_flow": []
}

Response codes

Code	Description
200	Success

Update Teams

Endpoint

POST /aisvc/api/v1/teams

Request

Query parameters

Parameter	Type	Description	Required
nsfilter	String	Filter by namespace.	Required

Body parameters

Parameter	Type	Description	Required
_name	String	Name of the team.	Required
_agents	Array of Object	List of agents. Each item has _userType and may include the supervisory fields _subAgents, _order, and _onfailure (see Supervisory teams).	Required
_flow	Array of Object	Static-flow graph as from/to edges. Required for static-flow teams; omit or pass [] for supervisory teams.	Optional
_namespaces	Array of String	Namespaces to include.	Required
_id	String	ID of the team (for update).	Required when updating

Body example

{
  "_name": "The BIM Analyzer",
  "_agents": [
    {
      "_userType": "bim_analyst"
    }
  ],
  "_flow": [
    { "from": "__start__", "to": "bim_analyst" },
    { "from": "bim_analyst", "to": "__end__" }
  ],
  "_namespaces": ["testproject_Lik2UwIN"],
  "_id": "1e82300b-f8e9-410d-a89b-c14b104e464c"
}

Response codes

Code	Description
200	Success
400	Bad Request
404	Not Found

Get Teams

Endpoint

GET /aisvc/api/v1/teams

Request

Query parameters

Parameter	Type	Description	Required
nsfilter	String	Filter by namespace.	Required
offset	Number	Offset for pagination.	Optional
pagesize	Number	Number of results per page.	Optional

Response codes

Code	Description
200	Success
400	Bad Request

Response data example

{
  "_offset": 2,
  "_pageSize": 2,
  "_total": 10,
  "_list": [
    {
      "id": "f1deea65-7b9d-4678-96c7-7094be0becde",
      "_name": "The BIM Analyzer",
      "_agents": [
        { "_userType": "bim_analyst" }
      ],
      "_flow": [
        { "from": "__start__", "to": "bim_analyst" },
        { "from": "bim_analyst", "to": "__end__" }
      ],
      "_namespaces": ["testproject_Lik2UwIN"]
    }
  ]
}

Get Teams by ID

Endpoint

GET /aisvc/api/v1/teams/{id}

Request

Path parameters

Parameter	Type	Description	Required
id	String	ID of the team.	Required

Query parameters

Parameter	Type	Description	Required
nsfilter	String	Filter by namespace.	Required

Response codes

Code	Description
200	Success
404	Not Found

Response data example

{
  "id": "f1deea65-7b9d-4678-96c7-7094be0becde",
  "_name": "The BIM Analyzer",
  "_agents": [
    { "_userType": "bim_analyst" }
  ],
  "_flow": [
    { "from": "__start__", "to": "bim_analyst" },
    { "from": "bim_analyst", "to": "__end__" }
  ],
  "_namespaces": ["testproject_Lik2UwIN"]
}

Delete Teams by ID

Endpoint

DELETE /aisvc/api/v1/teams/{id}

Request

Path parameters

Parameter	Type	Description	Required
id	String	ID of the team.	Required

Query parameters

Parameter	Type	Description	Required
nsfilter	String	Filter by namespace.	Required

Response codes

Code	Description
204	Success
404	Not Found