Update 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.
Document ID: The id returned when the document was created. See Create Assistant Knowledge Base Document.
Assistant ID: The UUID of the assistant that owns the document.
Organization UUID: The UUID of the organization that owns the assistant.

Update an Assistant Knowledge Base Document

Use the updateAiAssistantKnowledgeBaseDocument mutation to change a document's name, description, or replace its file. All content fields are optional — only the attributes you provide will be updated; omitted fields remain unchanged.

To replace the document file, follow Steps 1 and 2 below to upload the new file and obtain a fresh downloadUrl. If you only need to update the name or description, you can skip directly to Step 3.

Step 1: Get a presigned upload URL (only when replacing the file)

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

Inputs

organizationId: Your organization ID (required).
fileName: The name of the file including extension, e.g. "policy-v2.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-v2.pdf"
      contentType: "application/pdf"
    }
  ) {
    url
    downloadUrl
  }
}

Response:

{
  "data": {
    "createPresignedUrl": {
      "url": "https://pipefy-development.s3.sa-east-1.amazonaws.com/orgs/.../policy-v2.pdf?X-Amz-Signature=...",
      "downloadUrl": "https://pipefy-development.s3.sa-east-1.amazonaws.com/orgs/.../policy-v2.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 new file. Pass this as documentUrl in Step 3. Note that this URL expires after 7 days — use it immediately rather than storing it for later.

Step 2: Upload the new file (only when replacing 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-v2.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 3: Update the knowledge base document

Inputs

assistantId: UUID of the assistant that owns the document (required).
organizationUuid: UUID of the organization that owns the assistant (required).
documentId: ID of the document to update (required).
name: New display name of the document (optional).
description: New description of the document (optional).
documentUrl: Permanent download URL of the new file from createPresignedUrl (optional — only required when replacing the file).

Example: update name and description only

mutation {
  updateAiAssistantKnowledgeBaseDocument(
    input: {
      assistantId: "assistant-uuid-123"
      organizationUuid: "org-uuid-456"
      documentId: "doc-uuid-789"
      name: "HR Policy v2"
      description: "Updated HR policy document — revised April 2025"
    }
  ) {
    knowledgeBaseDocument {
      id
      name
      description
      updatedAt
    }
  }
}

Example: replace the document file

mutation {
  updateAiAssistantKnowledgeBaseDocument(
    input: {
      assistantId: "assistant-uuid-123"
      organizationUuid: "org-uuid-456"
      documentId: "doc-uuid-789"
      name: "HR Policy v2"
      description: "Updated HR policy document — revised April 2025"
      documentUrl: "<downloadUrl from createPresignedUrl>"
    }
  ) {
    knowledgeBaseDocument {
      id
      name
      description
      updatedAt
    }
  }
}

Response:

{
  "data": {
    "updateAiAssistantKnowledgeBaseDocument": {
      "knowledgeBaseDocument": {
        "id": "doc-uuid-789",
        "name": "HR Policy v2",
        "description": "Updated HR policy document — revised April 2025",
        "updatedAt": "2025-04-14T12:00:00Z"
      }
    }
  }
}

Response explained

knowledgeBaseDocument.id: Unique identifier of the document.
knowledgeBaseDocument.name: Current display name of the document.
knowledgeBaseDocument.description: Current description of the document.
knowledgeBaseDocument.updatedAt: When the document was last updated.

Error handling

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

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

Error response explained

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

Partial updates: Only the fields you include in the mutation input will be changed. Omitting a field leaves its current value intact.
Replacing the file: When providing a new documentUrl, the document will be re-processed and re-indexed for the assistant automatically.
Assistant scope: This mutation works with any assistant regardless of which channel it is connected to (portal, Slack, pipe, etc.).
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 updating the knowledge base document.
Finding your document ID: The id is returned by the createAiAssistantKnowledgeBaseDocument mutation. See Create Assistant Knowledge Base Document.