Create 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

Authentication: Use a Service Account token (Personal Access Tokens are deprecated).
Permissions: You must be a super admin of the organization.
Assistant ID: The UUID of the assistant you want to add the document to.
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. This mutation creates a knowledge base document and attaches it to any assistant by passing its ID directly, regardless of which channel or resource type the assistant is connected to.

The flow differs from the pipe-scoped knowledge base document in scope: instead of targeting an AI agent on a pipe, this targets an AI assistant identified by its own UUID.

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: Create a Knowledge Base Document

Creating a document is a three-step process.

Step 2.1: Get a presigned upload URL

Use the createPresignedUrl mutation to obtain a temporary S3 URL to upload your file to, and a permanent download URL to reference the file later.

Inputs

organizationId: Your organization ID (required).
fileName: The name of the file including extension, e.g. "policy.pdf" (required).
contentType: The MIME type of the file. For PDFs, use "application/pdf" (optional but recommended).

mutation {
  createPresignedUrl(
    input: { organizationId: "your-org-id", fileName: "policy.pdf", contentType: "application/pdf" }
  ) {
    url
    downloadUrl
  }
}

Response:

{
  "data": {
    "createPresignedUrl": {
      "url": "https://pipefy-development.s3.sa-east-1.amazonaws.com/orgs/.../policy.pdf?X-Amz-Signature=...",
      "downloadUrl": "https://pipefy-development.s3.sa-east-1.amazonaws.com/orgs/.../policy.pdf"
    }
  }
}

url: The presigned upload URL. Use this to upload the file via HTTP PUT. It expires in 5 minutes.
downloadUrl: The download URL to the file. Pass this as documentUrl in Step 2.3. Note that this URL expires after 7 days — use it immediately rather than storing it for later.

Step 2.2: Upload the file

Use the presigned url from the previous step to upload your file via an HTTP PUT request. Make sure to include the Content-Type header matching what you passed to createPresignedUrl.

curl -v --upload-file policy.pdf \
  --header "Content-Type: application/pdf" \
  "<url from createPresignedUrl>"

A 200 OK response means the upload succeeded. The presigned URL expires after 5 minutes, so complete this step promptly.

Step 2.3: Create the knowledge base document

Now use the downloadUrl from Step 2.1 as the documentUrl argument.

Inputs

assistantId: UUID of the assistant the document will be attached to (required).
organizationUuid: UUID of the organization that owns the assistant (required).
name: Display name of the document (required).
description: A short description of what the document contains (optional).
documentUrl: The permanent download URL returned by createPresignedUrl (required).

mutation {
  createAiAssistantKnowledgeBaseDocument(
    input: {
      assistantId: "assistant-uuid-123"
      organizationUuid: "org-uuid-456"
      name: "HR Policy"
      description: "Company HR policy document"
      documentUrl: "<downloadUrl from createPresignedUrl>"
    }
  ) {
    knowledgeBaseDocument {
      id
      name
      description
      updatedAt
    }
  }
}

Response:

{
  "data": {
    "createAiAssistantKnowledgeBaseDocument": {
      "knowledgeBaseDocument": {
        "id": "doc-uuid-789",
        "name": "HR Policy",
        "description": "Company HR policy document",
        "updatedAt": "2025-01-20T10:00:00Z"
      }
    }
  }
}

Response explained

knowledgeBaseDocument.id: Unique identifier of the created document.
knowledgeBaseDocument.name: Display name of the document.
knowledgeBaseDocument.description: Short description of the document's purpose.
knowledgeBaseDocument.updatedAt: When the document was last updated.

Error handling

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

{
  "data": {
    "createAiAssistantKnowledgeBaseDocument": null
  },
  "errors": [
    {
      "message": "Record Not Saved - Validation failed: Name can't be blank",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["createAiAssistantKnowledgeBaseDocument"]
    }
  ]
}

Error response explained

data.createAiAssistantKnowledgeBaseDocument: 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

Naming: Use descriptive names so assistants and administrators can identify documents easily.
Assistant scope: This mutation works with any assistant regardless of which channel it is connected to (portal, Slack, pipe, etc.). To add knowledge base documents to an AI agent on a pipe instead, use the Create Knowledge Base Document mutation.
PDF uploads: The upload url expires after 5 minutes — complete the upload promptly. The downloadUrl expires after 7 days; use it immediately as the documentUrl when creating the knowledge base document.