Get 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 admin of the pipe that owns the document.
3. Pipe UUID: Identify the UUID of the pipe that owns the document.
4. Document ID: Identify the UUID of the document you want to retrieve. Use the List Knowledge Base Items query to find document IDs.

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

Get a Knowledge Base Document

A knowledge base document is an uploaded file (such as a PDF or text file) used as an AI data source. The aiKnowledgeBaseDocument query retrieves a single document by its ID within a pipe.

Inputs

• id: UUID of the knowledge base document to retrieve (required).
• pipeUuid: UUID of the pipe that owns the document (required).

Example: retrieve a knowledge base document

query {
  aiKnowledgeBaseDocument(id: "a93b2d11-5e8c-4f21-b3d7-9a1e7f804c35", pipeUuid: "pipe-uuid-123") {
    id
    name
    description
    content
    updatedAt
  }
}

Response:

{
  "data": {
    "aiKnowledgeBaseDocument": {
      "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:00Z"
    }
  }
}

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: URL or reference to the uploaded document content.
• updatedAt: When the document was last updated.

Error handling

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

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

Error response explained

• data.aiKnowledgeBaseDocument: 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.
  • "Record not found" — the document id does not match any document in the pipe.

Tips

• Listing documents: Use the List Knowledge Base Items query with type filtering to find all documents for a pipe before fetching individual details.
• Managing documents: Use Create Knowledge Base Document, Update Knowledge Base Document, and Delete Knowledge Base Document to manage documents.