Create Knowledge Base Plain Text

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 plain text.
3. Pipe UUID: Identify the UUID of the pipe that will own this plain text.

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

Create a Knowledge Base Plain Text

A knowledge base plain text is an AI data source that stores free-form text content. When an AI agent needs information, it searches this content to provide relevant answers.

Use the createAiKnowledgeBasePlainText mutation to create one.

Inputs

• pipeUuid: UUID of the pipe that owns this plain text (required).
• name: Display name for the plain text (required).
• content: The text content that the AI agent will use as a knowledge source (required).
• description: A short description of what this plain text contains (optional).

Example: create a plain text knowledge base

mutation {
  createAiKnowledgeBasePlainText(
    input: {
      pipeUuid: "pipe-uuid-123"
      name: "Company FAQ"
      description: "Frequently asked questions about the company"
      content: "Q: What is Pipefy? A: An enterprise process management platform."
    }
  ) {
    knowledgeBasePlainText {
      id
      name
      description
      content
      updatedAt
    }
    errors
  }
}

Response:

{
  "data": {
    "createAiKnowledgeBasePlainText": {
      "knowledgeBasePlainText": {
        "id": "f27e4cac-1724-4879-a575-28ccdee4c022",
        "name": "Company FAQ",
        "description": "Frequently asked questions about the company",
        "content": "Q: What is Pipefy? A: An enterprise process management platform.",
        "updatedAt": "2025-01-20T10:00:00Z"
      },
      "errors": []
    }
  }
}

Response explained

• knowledgeBasePlainText.id: Unique identifier of the created plain text. Save this to use in update or delete operations.
• knowledgeBasePlainText.name: Display name of the plain text.
• knowledgeBasePlainText.description: Short description of the plain text's purpose.
• knowledgeBasePlainText.content: The stored text content.
• knowledgeBasePlainText.updatedAt: When the plain text was last updated.

Error handling

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

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

Error response explained

• data.createAiKnowledgeBasePlainText: 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.

Tips

• Naming: Use descriptive names so agents and administrators can identify plain texts easily.
• Content format: You can use plain prose, Q&A format, or structured text — the AI agent will search the content regardless of format.
• Associating with agents: After creating a plain text, use its id as an entry in dataSourceIds when creating or updating an AI agent. See the Create AI Agent mutation for details.