List Assistant Knowledge Base Items

Before You Begin

🔗 Use the GraphQL Playground to execute the queries in this guide.

➡️ New to GraphQL? Learn how to navigate the Playground with our Playground Basics Guide.

Prerequisites

1. Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
2. Permissions: You must be a super admin of the organization.
3. Assistant ID: The UUID of the assistant whose knowledge base items you want to list.
4. Organization UUID: The UUID of the organization that owns the assistant.

Overview

AI assistants can be associated with multiple resource types — portals, interfaces, Slack channels, pipes, and more. The aiAssistantKnowledgeBases query returns all data sources attached to any assistant by passing its ID directly, regardless of which channel or resource type the assistant is connected to.

Each item in the response includes a type field so you can identify its kind and then fetch full details using the type-specific queries.

Step 1: Find Your Assistant ID and Organization UUID

The assistant UUID can be retrieved from the assistant configuration in Pipefy. The organization UUID is available from the organization query:

{
  organization(id: "your-org-id") {
    uuid
    name
  }
}

Step 2: List All Knowledge Base Items

Inputs

• assistantId: UUID of the assistant whose knowledge base items you want to list (required).
• organizationUuid: UUID of the organization that owns the assistant (required).

query {
  aiAssistantKnowledgeBases(assistantId: "ast-uuid-456", organizationUuid: "org-uuid-789") {
    id
    name
    description
    type
    updatedAt
  }
}

Response:

{
  "data": {
    "aiAssistantKnowledgeBases": [
      {
        "id": "a93b2d11-5e8c-4f21-b3d7-9a1e7f804c35",
        "name": "Product Manual",
        "description": "Uploaded product documentation",
        "type": "knowledge_base_documents",
        "updatedAt": "2025-01-18T09:30:00Z"
      },
      {
        "id": "f27e4cac-1724-4879-a575-28ccdee4c022",
        "name": "Company FAQ",
        "description": "Frequently asked questions about the company",
        "type": "knowledge_base_plain_texts",
        "updatedAt": "2025-01-20T10:00:00Z"
      }
    ]
  }
}

Response explained

• id: Unique identifier of the knowledge base item. Use this with type-specific queries to retrieve full details.
• name: Display name of the item.
• description: Short description of the item's purpose.
• type: The kind of knowledge base item. Possible values:
  • "knowledge_base_documents" — an uploaded file. See Get Assistant Knowledge Base Document.
• updatedAt: When the item was last updated.

Error handling

If the query fails (e.g., permission denied or organization not found), you'll receive an error response:

{
  "data": {
    "aiAssistantKnowledgeBases": null
  },
  "errors": [
    {
      "message": "Organization not found with id: org-uuid-789",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["aiAssistantKnowledgeBases"]
    }
  ]
}

Error response explained

• data.aiAssistantKnowledgeBases: Returns null when the operation fails.
• errors: Array containing error details when the operation fails.
• errors[].message: Human-readable error description. Common messages:
  • "Permission denied" — the authenticated user is not a super admin of the organization.
  • "Organization not found with id: <uuid>" — the organizationUuid does not match an existing organization.

Tips

• Fetch full details: This query returns a summary for each item. To retrieve type-specific fields (such as content for documents), use the individual get queries after identifying the item id and type.
• Managing documents: Use Create Assistant Knowledge Base Document, Update Assistant Knowledge Base Document, and Delete Assistant Knowledge Base Document to manage assistant documents.