> ## Documentation Index
> Fetch the complete documentation index at: https://bulkgrid.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections

> Organize sources, curate content, and control retrieval access.

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](/docs/sdk). Set `BULKGRID_API_KEY` in your backend environment; cURL examples also use `BULKGRID_BASE_URL=https://bulkgrid.com`.

<CodeGroup>
  ```js Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```

  ```bash cURL theme={null}
  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"}'
  ```
</CodeGroup>

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](/docs/cli).

<CodeGroup>
  ```js Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```

  ```bash cURL theme={null}
  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\"}]}"
  ```

  ```bash CLI theme={null}
  bulkgrid sources include "$SOURCE_ID" "$COLLECTION_ID" \
    --url "${BULKGRID_BASE_URL:-https://bulkgrid.com}"
  ```
</CodeGroup>

### 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](/docs/authentication) and [API key scopes](/docs/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](/docs/plan-gating-and-limits).