Create Knowledge Base Data Lookup

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 admin of the pipe where you want to create the data lookup.
Pipe UUID: Identify the UUID of the pipe that will own this data lookup.
Source Pipe ID: Identify the numeric ID of the source pipe whose records will be queried.

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

Create a Knowledge Base Data Lookup

A knowledge base data lookup is an AI data source that queries records from another pipe at runtime. When an AI agent needs information, it uses the configured conditions and output fields to retrieve matching records from the source pipe and use them as context.

Use the createAiKnowledgeBaseDataLookup mutation to create one.

Inputs

pipeUuid: UUID of the pipe that owns this data lookup (required).
name: Display name for the data lookup (required).
description: A short description of what the data lookup retrieves (optional).
sourceRepoId: ID of the source pipe whose records will be queried (required).
searchQuery: Free-text keyword to filter records in the source pipe (optional).
outputFields: List of field IDs whose values should be returned from matching records (optional).
conditions: List of filter conditions used to narrow down records in the source pipe (optional). Each condition has:
- field: ID of the field to filter on (e.g. "assignees").
- fieldUuid: UUID of the field to filter on.
- attribute: Record attribute to compare (e.g. "ASSIGNEES").
- operator: Comparison operator (e.g. "eq", "contains").
- value: Value to compare the field against.
- usingFillWithAi: When true, the AI fills this condition value at runtime instead of using a fixed value.
- inputType: Data type of the AI input value when usingFillWithAi is true (e.g. "number", "assignee_select").
- inputName: Label for the AI input parameter when usingFillWithAi is true.
- inputDescription: Description shown to the AI for this input when usingFillWithAi is true.

Example: create with conditions and output fields

mutation {
  createAiKnowledgeBaseDataLookup(
    input: {
      pipeUuid: "pipe-uuid-123"
      name: "Customer Data Lookup"
      description: "Looks up customer records from the sales pipe"
      sourceRepoId: "16"
      searchQuery: "records"
      outputFields: ["this_is_a_quote"]
      conditions: [
        {
          field: "assignees"
          attribute: "ASSIGNEES"
          operator: "contains"
          value: "10"
          usingFillWithAi: false
          inputType: "assignee_select"
        }
      ]
    }
  ) {
    knowledgeBaseDataLookup {
      id
      name
      description
      updatedAt
    }
  }
}

Example: create with AI-filled condition

When usingFillWithAi is true, the AI determines the condition value at runtime. Provide inputName, inputType, and inputDescription so the agent knows what value to supply.

mutation {
  createAiKnowledgeBaseDataLookup(
    input: {
      pipeUuid: "pipe-uuid-123"
      name: "Order Lookup by Number"
      sourceRepoId: "306422123"
      outputFields: ["create_connected_card_1", "pipe_connection_1", "assignee"]
      conditions: [
        {
          field: "number"
          fieldUuid: "5c6fb7e6-d7db-4967-98d5-5e763208d919"
          operator: "eq"
          usingFillWithAi: true
          inputName: "order_number"
          inputType: "number"
          inputDescription: "The order number to look up"
        }
      ]
    }
  ) {
    knowledgeBaseDataLookup {
      id
      name
      description
      updatedAt
    }
  }
}

Response:

{
  "data": {
    "createAiKnowledgeBaseDataLookup": {
      "knowledgeBaseDataLookup": {
        "id": "data-lookup-uuid-789",
        "name": "Customer Data Lookup",
        "description": "Looks up customer records from the sales pipe",
        "updatedAt": "2025-01-20T10:00:00Z"
      }
    }
  }
}

Response explained

knowledgeBaseDataLookup.id: Unique identifier of the created data lookup. Save this to use in update or delete operations.
knowledgeBaseDataLookup.name: Display name of the data lookup.
knowledgeBaseDataLookup.description: Short description of the data lookup's purpose.
knowledgeBaseDataLookup.updatedAt: When the data lookup 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": {
    "createAiKnowledgeBaseDataLookup": null
  },
  "errors": [
    {
      "message": "Record Not Saved - Validation failed: Name can't be blank",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": ["createAiKnowledgeBaseDataLookup"]
    }
  ]
}

Error response explained

data.createAiKnowledgeBaseDataLookup: 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 'createAiKnowledgeBaseDataLookup' 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 data lookups easily.
Output fields: Only list the field IDs that are relevant to the agent's task — keeping the output focused improves the quality of AI responses.
AI-filled conditions: Use usingFillWithAi: true for conditions whose values should be determined by the agent at runtime (e.g. looking up a record by a user-provided order number). Provide clear inputDescription values to guide the agent.
Associating with agents: After creating a data lookup, use its id as an entry in dataSourceIds when creating or updating an AI agent. See the Create AI Agent mutation for details.