Collections

Collections group the indexed content an application or agent can search. Use them to separate products, audiences, or internal and public knowledge.

Create a collection

Requires collections:write and a paid plan: Node.js and Python examples use the Bulkgrid SDKs. Set BULKGRID_API_KEY in your backend environment; cURL examples also use BULKGRID_BASE_URL=https://bulkgrid.com.

import { BulkgridClient } from '@bulkgrid/sdk';

const client = new BulkgridClient({
  apiKey: process.env.BULKGRID_API_KEY ?? '',
  baseUrl: process.env.BULKGRID_BASE_URL ?? 'https://bulkgrid.com',
});

const data = await client.collections.create({
  name: 'Product documentation',
  description: 'Content for the support assistant',
});
console.log(data);

import os
from bulkgrid import BulkgridClient

with BulkgridClient(
    api_key=os.environ["BULKGRID_API_KEY"],
    base_url=os.environ.get("BULKGRID_BASE_URL", "https://bulkgrid.com"),
) as client:
    data = client.collections.create(
        {
            "name": "Product documentation",
            "description": "Content for the support assistant",
        }
    )
    print(data)

curl "$BULKGRID_BASE_URL/api/v1/collections" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BULKGRID_API_KEY" \
  -d '{"name":"Product documentation","description":"Content for the support assistant"}'

Use the returned collection ID when adding source, folder, or URL rules. Select this collection when creating an API key or approving an OAuth connection.

Include and exclude content

Collection rules support:

action: include or exclude
target: source, folder, or url
source context through source_id
target value through target_id
optional metadata on added rules

Read and update rules

GET /api/v1/collections/{collectionId}/rules requires collections:read. PATCH on the same path requires collections:write and accepts add and remove arrays. Each rule uses action, target, source_id, and target_id. Source targets identify the source, folder targets identify a folder path, and URL targets identify a document URL. Use IDs and paths returned for sources available to your workspace.

Include an entire source

Set SOURCE_ID and COLLECTION_ID to the IDs returned when creating or listing those resources. This expands the collection’s searchable content. The CLI requires a scoped API key, as described in CLI setup.

import { BulkgridClient } from '@bulkgrid/sdk';

const client = new BulkgridClient({
  apiKey: process.env.BULKGRID_API_KEY ?? '',
  baseUrl: process.env.BULKGRID_BASE_URL ?? 'https://bulkgrid.com',
});

const data = await client.collections.addSource({
  collectionId: process.env.COLLECTION_ID ?? '',
  sourceId: process.env.SOURCE_ID ?? '',
});
console.log(data);

import os
from bulkgrid import BulkgridClient

with BulkgridClient(
    api_key=os.environ["BULKGRID_API_KEY"],
    base_url=os.environ.get("BULKGRID_BASE_URL", "https://bulkgrid.com"),
) as client:
    data = client.collections.add_source(
        os.environ["COLLECTION_ID"], os.environ["SOURCE_ID"]
    )
    print(data)

curl -X PATCH "$BULKGRID_BASE_URL/api/v1/collections/$COLLECTION_ID/rules" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BULKGRID_API_KEY" \
  -d "{\"add\":[{\"action\":\"include\",\"target\":\"source\",\"source_id\":\"$SOURCE_ID\",\"target_id\":\"$SOURCE_ID\"}]}"

bulkgrid sources include "$SOURCE_ID" "$COLLECTION_ID" \
  --url "${BULKGRID_BASE_URL:-https://bulkgrid.com}"

Choose the scope

include an entire source
include one folder from a source
exclude a noisy subfolder
include or exclude specific URLs

Inspect effective coverage

The rules endpoint does more than just list rules. It also returns:

aggregate rule counts
effective counts by source

That matters because customers need to understand the actual collection boundary after include and exclude rules interact.

Search and access

Pass collectionId to search to restrict retrieval to a collection. Select approved collections when creating an API key or approving an OAuth connection. A search filter cannot grant access beyond the credential’s approved collections. Manage AI and CLI grants in Connected Apps. See Authentication and API key scopes.

Manage collections

Use GET /api/v1/collections with collections:read to list collections. Use PATCH /api/v1/collections/{collectionId} with collections:write to update a collection. Collection creation requires a paid plan; see plan limits.

Get started

Index

More

Access and operations

Create a collection

Include and exclude content

Read and update rules

Include an entire source

Choose the scope

Inspect effective coverage

Search and access

Manage collections

​Create a collection

​Include and exclude content

​Read and update rules

​Include an entire source

​Choose the scope

​Inspect effective coverage

​Search and access

​Manage collections

Create a collection

Include and exclude content

Read and update rules

Include an entire source

Choose the scope

Inspect effective coverage

Search and access

Manage collections