Create 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 where you want to create the document.
3. Pipe UUID: Identify the pipe UUID where the document will be created.

Step 1: Find Your Pipe UUID

See our Get resource IDs page for how to find the pipe UUID.

Step 2: Create a Knowledge Base Document

Knowledge base documents are PDF files that AI agents can use as a reference when answering questions or executing tasks. 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

• pipeUuid: UUID of the pipe the document belongs to (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 {
  createAiKnowledgeBaseDocument(
    input: {
      pipeUuid: "pipe-uuid-123"
      name: "HR Policy"
      description: "Company HR policy document"
      documentUrl: "<downloadUrl from createPresignedUrl>"
    }
  ) {
    knowledgeBaseDocument {
      id
      name
      description
      updatedAt
    }
  }
}

Response:

{
  "data": {
    "createAiKnowledgeBaseDocument": {
      "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, pipe not found, or service unavailable), you'll receive an error response:

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

Error response explained

• data.createAiKnowledgeBaseDocument: 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.
  • "Field 'createAiKnowledgeBaseDocument' doesn't exist on type 'Mutation'" — the feature flag is not enabled for the organization.

Tips

• Naming: Use descriptive names so agents and administrators can identify documents easily.
• Associating with agents: After creating a document, use its id as an entry in dataSourceIds when creating or updating an AI agent. See the Create AI Agent mutation for details.
• 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.