List 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 admin of the pipe whose knowledge base you want to list.
3. Pipe UUID: Identify the UUID of the pipe whose knowledge base items you want to retrieve.

See our Get resource IDs page for how to find these values.

List All Knowledge Base Items

The aiKnowledgeBases query returns all data sources associated with a pipe, regardless of type (documents, plain texts, or data lookups). Each item includes a type field so you can identify its kind and then fetch full details using the type-specific queries.

Inputs

• pipeUuid: UUID of the pipe whose knowledge base items you want to list (required).

Example: list all knowledge base items for a pipe

query {
  aiKnowledgeBases(pipeUuid: "pipe-uuid-123") {
    id
    name
    description
    type
    updatedAt
  }
}

Response:

{
  "data": {
    "aiKnowledgeBases": [
      {
        "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"
      },
      {
        "id": "a93b2d11-5e8c-4f21-b3d7-9a1e7f804c35",
        "name": "Product Manual",
        "description": "Uploaded product documentation",
        "type": "knowledge_base_documents",
        "updatedAt": "2025-01-18T09:30:00Z"
      },
      {
        "id": "c7d45e82-3a1f-4b96-8c2e-6f0d3a592b47",
        "name": "Customer Records",
        "description": "Looks up customer data from CRM pipe",
        "type": "data_lookups",
        "updatedAt": "2025-01-15T14: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 Knowledge Base Document.
  • "knowledge_base_plain_texts" — free-form text content. See Get Knowledge Base Plain Text.
  • "data_lookups" — a live data lookup from another pipe. See Get Knowledge Base Data Lookup.
• updatedAt: When the item was last updated.

Error handling

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

{
  "data": {
    "aiKnowledgeBases": null
  },
  "errors": [
    {
      "message": "Pipe not found with id: pipe-uuid-123",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["aiKnowledgeBases"]
    }
  ]
}

Error response explained

• data.aiKnowledgeBases: 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 an admin of the pipe.
  • "Pipe not found with id: <uuid>" — the pipeUuid does not match an existing pipe.

Tips

• Filter by type: The response includes all item types. Use the type field to filter results client-side if you only need items of a specific kind.
• Fetch full details: This query returns a summary for each item. To retrieve type-specific fields (such as content for plain texts or sourceRepoId for data lookups), use the individual get queries after identifying the item id and type.