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

# Managing Collections

> Create, configure, and organize your routes with Collections

# Managing Collections

## Creating a Collection

<Steps>
  <Step title="Navigate to Collections">
    From the main navigation, click **Collections** in the sidebar
  </Step>

  <Step title="Create New Collection">
    Click the **+ Create Collection** button
  </Step>

  <Step title="Configure Details">
    * **Name**: Enter a descriptive name for your collection
    * **Icon**: Choose an icon to visually identify the collection
    * **Description**: (Optional) Add notes about the collection's purpose
  </Step>

  <Step title="Save">
    Click **Create** to save your new collection
  </Step>
</Steps>

<Note>
  You can also create a collection on the fly when creating a new secret. In the secret creation form, type a new name in the collection picker to create and assign a collection in one step — no need to pre-create it.
</Note>

## Collection Tabs

Each collection has multiple tabs for different aspects of configuration:

### Overview

View and edit basic collection information:

* Collection name and icon
* Description
* Creation date and metadata

### Routes

Manage routes within the collection:

* View all routes in the collection
* Add existing routes
* Create new routes directly in the collection
* View route status (enabled/disabled)

### Secrets

Manage secrets attached to the collection:

* View all secrets in the collection
* Move secrets from other collections
* Create new secrets in this collection
* Secrets can be referenced by collection variables

**Quick move from the Secrets list:** You don't need to open a collection to assign secrets to it. From the main Secrets page, hover over any secret row and use the **Move to Collection** submenu to assign it in-place. This works across collections — you can reassign a secret from one collection to another without opening either.

### Variables

Create and manage reusable variables:

* Define value variables (plain text)
* Define secret variables (reference encrypted secrets)
* Copy variable references to use in routes
* See [Collection Variables](/essentials/collections/collection-variables) for details

### Environments

Configure environment-specific defaults:

* **Expected Environments**: Auto-provision routes with selected environments
* **Base URL**: Default target URL per environment
* **Default Clients**: Automatically attach clients to routes in each environment
* See [Collection Environment Defaults](/essentials/environments/collection-environment-defaults) for details

### Bulk Operations

(Coming soon) Apply changes to all routes in the collection at once.

## Adding Routes to a Collection

### Option 1: During Route Creation

When creating a new route:

1. Fill in the route details
2. In the **Collection** dropdown, select your collection
3. Save the route

The route will automatically inherit any collection environment defaults.

### Option 2: From the Collection Page

1. Navigate to your collection
2. Go to the **Routes** tab
3. Click the **+** button
4. Select **Create new route** or **Add existing route**

### Option 3: From an Existing Route

1. Open any route's detail page
2. Click the **Collection** dropdown
3. Select the target collection
4. Save changes

## Moving Secrets to a Collection

Secrets can be organized by moving them into collections:

<Steps>
  <Step title="Navigate to Collection">
    Open your collection and go to the **Secrets** tab
  </Step>

  <Step title="Add Secret">
    Click the **+** button in the Secrets card header
  </Step>

  <Step title="Select Secret">
    Choose a secret from the list of available secrets
  </Step>

  <Step title="Confirm">
    Click **Move to this collection** to complete the transfer
  </Step>
</Steps>

<Info>
  Moving a secret to a collection doesn't break existing routes — secrets can still be used by any route that references them.
</Info>

## Configuring Environment Defaults

Collections can define default settings that apply to all routes when they're created or updated:

### Setting Expected Environments

1. Go to the **Environments** tab
2. In the **Expected environments** section, click on environment names to toggle them
3. Selected environments will be auto-provisioned for new routes added to the collection

<Tip>
  Expected environments are indicated with a checkmark and colored background
</Tip>

### Configuring Per-Environment Defaults

For each environment, you can configure:

<Steps>
  <Step title="Select Environment">
    Use the environment dropdown to choose which environment to configure
  </Step>

  <Step title="Set Base URL">
    Enter the default target URL for routes in this environment
  </Step>

  <Step title="Add Default Clients">
    Select clients that should automatically be attached to routes
  </Step>

  <Step title="Save">
    Click **Save** to apply the environment configuration
  </Step>
</Steps>

### Applying Defaults to Existing Routes

After configuring environment defaults, you can apply them to existing routes:

1. Configure your environment defaults
2. Review the sync status showing how many routes are out of sync
3. Click **Apply to routes** to bulk-update all routes in the collection

<Warning>
  Applying defaults will overwrite the base URL and client assignments for existing routes in that environment. Review carefully before applying.
</Warning>

## Editing Collection Details

1. Navigate to your collection
2. Go to the **Overview** tab
3. Edit the collection name, icon, or description
4. Changes are saved automatically

## Deleting a Collection

<Warning>
  Deleting a collection does NOT delete the routes, secrets, or variables within it. They will simply no longer be associated with a collection.
</Warning>

To delete a collection:

1. Navigate to the Collections list
2. Click the **⋯** menu for the collection
3. Select **Delete collection**
4. Confirm the deletion

## Collection Icons

Choose from a wide variety of icons to visually identify your collections:

<CardGroup cols={3}>
  <Card title="Files & Storage" icon="folder">
    Folders, Archives, Boxes, Databases
  </Card>

  <Card title="Code & Development" icon="code">
    Code, Terminal, Git, Webhooks
  </Card>

  <Card title="Security" icon="shield">
    Shields, Locks, Keys, Fingerprints
  </Card>

  <Card title="Commerce" icon="shopping-cart">
    Carts, Cards, Wallets, Receipts
  </Card>

  <Card title="Communication" icon="mail">
    Mail, Messages, Phones, Notifications
  </Card>

  <Card title="Performance" icon="gauge">
    Charts, Gauges, Trends, Analytics
  </Card>
</CardGroup>

...and many more! Select an icon that best represents your collection's purpose.

## Best Practices

<AccordionGroup>
  <Accordion title="Organize by Project or Service" icon="sitemap">
    Create collections for each distinct project, microservice, or API integration:

    * `Stripe Payments`
    * `SendGrid Email`
    * `Auth0 Authentication`
  </Accordion>

  <Accordion title="Use Consistent Naming" icon="text">
    Establish a naming convention for collections:

    * `[Service] - [Environment]` → `Shopify - Production`
    * `[Client] - [Integration]` → `Acme Corp - Payments`
    * `[Team] - [Project]` → `Platform Team - API Gateway`
  </Accordion>

  <Accordion title="Leverage Environment Defaults" icon="layer-group">
    Set base URLs and default clients at the collection level to ensure new routes are configured correctly from the start
  </Accordion>

  <Accordion title="Keep Secrets Organized" icon="key">
    Move related secrets into the same collection as the routes that use them for easier management
  </Accordion>

  <Accordion title="Document Collection Purpose" icon="file-text">
    Use the Description field to explain what the collection is for, which team owns it, and any special considerations
  </Accordion>
</AccordionGroup>

## Example Collection Setups

### E-commerce Integration

```text theme={"dark"}
Collection: Shopify Store
Icon: Shopping Bag
Routes: Product Sync, Order Webhook, Inventory Update
Secrets: Shopify API Key, Shopify Webhook Secret
Variables:
  - shop_domain = acme-store.myshopify.com
  - api_version = 2024-01
Expected Environments: staging, production
```

### Payment Processing

```text theme={"dark"}
Collection: Stripe Payments
Icon: Credit Card
Routes: Create Charge, Refund, List Customers
Secrets: Stripe Secret Key (prod), Stripe Secret Key (test)
Variables:
  - stripe_api_key = [Secret: Stripe Secret Key]
  - webhook_endpoint = /webhooks/stripe
Expected Environments: sandbox, production
```

### Notification Service

```text theme={"dark"}
Collection: SendGrid Email
Icon: Mail
Routes: Send Email, Send Bulk, Get Templates
Secrets: SendGrid API Key
Variables:
  - from_email = noreply@example.com
  - default_template_id = d-abc123
Expected Environments: development, production
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Collection Variables" icon="brackets-curly" href="/essentials/collections/collection-variables">
    Learn how to use variables in your routes
  </Card>

  <Card title="Environment Defaults" icon="layer-group" href="/essentials/environments/collection-environment-defaults">
    Configure environment-specific settings
  </Card>

  <Card title="Creating Routes" icon="route" href="/essentials/routes/creating-routes">
    Add routes to your collection
  </Card>

  <Card title="Managing Secrets" icon="key" href="/essentials/secrets/creating-secrets">
    Create and organize secrets
  </Card>
</CardGroup>