Collections

Collections provide structured, persistent data storage for Foundry apps. They are schema-defined, FQL-queryable, and accessible from functions, workflows, and UI extensions.

Schemas

Every collection is backed by a JSON Schema that defines its structure, field types, and validation rules.

Supported field types

• string
• number
• integer
• boolean
• array
• object

Field indexing

Fields can be indexed to enable FQL filtering. Add the x-cs-indexable: true extension to a field in the schema to make it queryable:

{
  "type": "object",
  "properties": {
    "hostname": {
      "type": "string",
      "x-cs-indexable": true
    },
    "score": {
      "type": "integer",
      "x-cs-indexable": true
    }
  }
}

Indexed fields can be used in FQL filter expressions when querying collections.

Schema versioning

When you modify a collection schema, Foundry creates a new version. Schema changes must be compatible with existing data — you can add optional fields but cannot remove or change the type of existing fields without creating a new collection.

Managing collections

In the Falcon console

1. In the App Builder, go to Collections.
2. Click Create collection.
3. Define the schema using the visual editor or raw JSON.
4. Configure access control (read/write permissions per role).

With the Foundry CLI

Collections are defined in manifest.yml:

collections:
  - name: threat_scores
    description: Cached threat intelligence scores
    schema:
      type: object
      properties:
        indicator:
          type: string
          x-cs-indexable: true
        score:
          type: integer
        last_updated:
          type: string

CRUD operations

Collections support standard create, read, update, and delete operations.

From functions (Python)

Use FalconPy’s CustomStorage service class. Method names use PascalCase (Operation ID syntax):

import os
from falconpy import CustomStorage


def _app_headers() -> dict:
    """Build app headers for CustomStorage construction."""
    app_id = os.environ.get("APP_ID")
    if app_id:
        return {"X-CS-APP-ID": app_id}
    return {}


storage = CustomStorage(ext_headers=_app_headers())

# Create/Update
storage.PutObject(collection_name="threat_scores",
                  object_key="ioc-123",
                  body={"indicator": "10.0.0.1", "score": 85})

# Search with FQL
results = storage.SearchObjects(collection_name="threat_scores",
                                filter="indicator:'10.0.0.1'",
                                limit=10)

The ext_headers parameter handles the X-CS-APP-ID header that Foundry uses for app-scoped access. Set the APP_ID environment variable for local testing. For direct API access outside of Foundry functions, you need a separate API client with Custom Storage scope.

From the API

Collections are accessible via the CrowdStrike API using the X-CS-APP-ID header to specify the app context.

Operation	Method	Endpoint
Create/Update	PUT	/customobjects/v1/collections/{collection}/objects/{key}
Read	GET	/customobjects/v1/collections/{collection}/objects/{key}
List	GET	/customobjects/v1/collections/{collection}/objects
Search	POST	/customobjects/v1/collections/{collection}/objects
Delete	DELETE	/customobjects/v1/collections/{collection}/objects/{key}

Access control

Collection access is controlled at the app level. Configure which Falcon roles can read and write to each collection.

CSV import

You can bulk import data into a collection from a CSV file:

1. In the App Builder, navigate to the collection.
2. Click Import CSV.
3. Map CSV columns to collection fields.
4. Review and confirm the import.

Pagination

When listing or searching collections with large datasets, use pagination parameters:

• limit — Maximum number of objects to return per request
• offset — Starting position for the next page of results

For workflow-based pagination patterns, see API Pagination Strategies for Falcon Foundry.