PIpipeshub-ai
Agents

Get agent

Changed on

Retrieve agent details by its unique key.

Gateway not-found behavior: Unknown agentKey, lookup after soft-delete, and other AI-backend failures that return 404 from the Python query service are surfaced by the Node gateway as HTTP 404 with an ErrorResponse body. An agent the caller has no access to (another user's agent that is not shared) is also a 404, not a 403.

The route reads no query parameter; any that is sent is ignored.

get/agents/{agentKey}

Request

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

Path parameters

agentKeystring required

Unique agent identifier

Response

Agent details

statusstring required
messagestring required

Example response

{
  "status": "success",
  "message": "Agent retrieved successfully",
  "agent": {
    "_id": "agentInstances/e6f848ca-e2ab-4594-9925-e1136629f474",
    "_key": "e6f848ca-e2ab-4594-9925-e1136629f474",
    "_rev": "_lkNlcOm---",
    "name": "Customer Support Assistant",
    "models": [
      {
        "modelType": "llm",
        "provider": "azureOpenAI",
        "modelName": "gpt-5.6-luna",
        "modelKey": "f3a4b5b6-5b6c-4e85-9097-3202cfe696fc",
        "isMultimodal": true,
        "isReasoning": true,
        "isDefault": true,
        "modelFriendlyName": "GPT 5.4 mini"
      }
    ],
    "webSearch": {
      "provider": "serper"
    },
    "access_type": "INDIVIDUAL",
    "user_role": "OWNER"
  }
}

Changes

  • dbb5e203b445Revision changes
    • breaking

      the response property /// became nullable for the status

    • breaking

      the response property /// became nullable for 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