PIpipeshub-ai
Agents

List agents

Changed on

Retrieve a paginated list of agents available to the authenticated user.

Overview

Returns agents accessible through direct, team, or org-level permissions. Search is performed across agent name, description, and tags. Sorting and pagination are applied by the AI backend and the resulting envelope is forwarded unchanged by the Node gateway.

Gateway contract

The Node route supports only these query params: page, limit, search, sort_by, and sort_order.

The Python backend also understands isDeleted, but this gateway route does not forward it, so it is not part of the public API contract here. Any other query parameter is ignored, not refused.

get/agents

Request

  • Base URL
    https://app.pipeshub.com/api/v1
  • URL
    https://app.pipeshub.com/api/v1/agents
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: /api/v1/oauth2/authorize
      Client credentials
      Token URL: /api/v1/oauth2/token scopes: agent:read

Query parameters

pageinteger

1-based page number.

limitinteger

Maximum number of agents to return in the current page.

searchstring

Case-insensitive search across agent name, description, and tags. Leading/trailing whitespace is trimmed; a blank value is refused with VALIDATION_ERROR, and so is a printf-style format specifier (%s, %x, ...). Markup (HTML tags, javascript:, event handlers) is refused with HTTP_BAD_REQUEST by the sanitizer every route runs.

sort_bystring

Backend sort field. Leading/trailing whitespace is trimmed and a blank value is refused. Any other value is accepted. Common value is updatedAtTimestamp.

sort_order'asc' | 'desc'

Sort direction.

Response

Paginated list of accessible agents.

successboolean required

Example response

{
  "success": true,
  "agents": [
    {
      "_id": "agentInstances/e6f848ca-e2ab-4594-9925-e1136629f474",
      "_key": "e6f848ca-e2ab-4594-9925-e1136629f474",
      "_rev": "_lkNlcOm---",
      "user_role": "OWNER",
      "access_type": "INDIVIDUAL"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "limit": 20,
    "totalItems": 2,
    "totalPages": 1
  }
}

Changes

  • dbb5e203b445Revision changes
    • breaking

      added the pattern \S to the query request parameter sort_by

    • breaking

      added the pattern ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]|<[^>]{0,10000}>))[\s\S]*?\S to the query request parameter search

    • breaking

      the response property //// became nullable for the status

    • breaking

      the response property //// became nullable for the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

  • fc76aa045994Revision changes
    • warning

      added the new docs enum value to the //////// response property for the response status

    • warning

      added the new sheets enum value to the //////// response property for the response status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status