Get Assistant Knowledge Base Document

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 that owns the document.
4. Organization UUID: The UUID of the organization that owns the assistant.
5. Document ID: The UUID of the document you want to retrieve.

Overview

A knowledge base document is an uploaded file (such as a PDF or text file) used as an AI data source. The aiAssistantKnowledgeBaseDocument query retrieves a single document by its ID within an assistant, returning full details including the file content URL.

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
  }
}

To find your assistant ID, navigate to the AI assistant settings in Pipefy and copy the UUID from the assistant's configuration page.

Step 2: Find the Document ID

Use the List Assistant Knowledge Base Items query to retrieve all knowledge base items for the assistant and identify the document you want to fetch:

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

Look for items with "type": "knowledge_base_documents" in the response to find the document IDs.

Step 3: Get the Knowledge Base Document

Inputs

• id: UUID of the knowledge base document to retrieve (required).
• assistantId: UUID of the assistant that owns the document (required).
• organizationUuid: UUID of the organization that owns the assistant (required).

query {
  aiAssistantKnowledgeBaseDocument(
    id: "a93b2d11-5e8c-4f21-b3d7-9a1e7f804c35"
    assistantId: "ast-uuid-456"
    organizationUuid: "org-uuid-789"
  ) {
    id
    name
    description
    content
    updatedAt
  }
}

Response:

{
  "data": {
    "aiAssistantKnowledgeBaseDocument": {
      "id": "a93b2d11-5e8c-4f21-b3d7-9a1e7f804c35",
      "name": "Product Manual",
      "description": "Uploaded product documentation",
      "content": "https://storage.example.com/documents/product-manual.pdf",
      "updatedAt": "2025-01-18T09:30:00+00:00"
    }
  }
}

Response explained

• id: Unique identifier of the document. Use this in update or delete operations.
• name: Display name of the document.
• description: Short description of the document's purpose.
• content: A pre-signed URL pointing directly to the uploaded file (e.g., "https://storage.example.com/documents/product-manual.pdf"). Use this URL to download or display the document. Pre-signed URLs are time-limited — do not cache or store them for later use.
• updatedAt: When the document was last updated.

Error handling

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

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

Error response explained

• data.aiAssistantKnowledgeBaseDocument: 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.
  • "Record not found" — the document id does not match any document on the assistant.

Tips

• Listing documents: Use the List Assistant Knowledge Base Items query to find all documents for an assistant before fetching individual details.
• Managing documents: Use Create Assistant Knowledge Base Document, Update Assistant Knowledge Base Document, and Delete Assistant Knowledge Base Document to manage assistant documents.