Metadata Parameter

The meta query parameter controls whether the API response includes metadata about the sheet structure and available filtering options.

Usage

Add meta=true to your request:

GET /api/v1/bridge/{bridgeId}/{sheetId}?meta=true

Default Behavior

When meta is not specified or set to false, the response is a simple array of rows:

[
  {
    "sheetbridge_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Phillip",
    "email": "phillip@example.com",
    "can_attend": "true"
  },
  {
    "sheetbridge_id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Syed",
    "email": "phillip@example.com",
    "can_attend": "true"
  }
]

With Metadata

When meta=true is requested, the response includes a meta object:

{
  "data": [
    {
      "sheetbridge_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Phillip",
      "email": "phillip@example.com",
      "can_attend": "true"
    },
    {
      "sheetbridge_id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Syed",
      "email": "syed@example.com",
      "can_attend": "true"
    }
  ],
  "meta": {
    "filterable_columns": ["name", "email", "can_attend"],
    "canonical_keys": ["name", "email", "can_attend", "sheetbridge_id"],
    "system_managed": ["sheetbridge_id"],
    "operators": ["_eq", "_neq", "_contains", "_in", "_null", "_notnull", "_gt", "_gte", "_lt", "_lte"],
    "warnings": []
  }
}

Metadata Fields

Field	Description
`filterable_columns`	Array of column names that can be used for filtering
`canonical_keys`	Array of all column names in the sheet (normalized)
`system_managed`	Array of columns managed by SheetBridge (e.g., `sheetbridge_id`)
`operators`	Array of available filter operators
`warnings`	Array of warnings about the sheet structure or data

Use Cases

Metadata is useful when:

Building dynamic UIs that need to know available columns
Discovering filterable columns programmatically
Understanding which operators are available
Detecting potential issues via warnings

Example: Discovering Filterable Columns

curl "{{ config('app.url') }}/api/v1/bridge/{bridgeId}/{sheetId}?meta=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

The response will include filterable_columns which you can use to build dynamic filter interfaces.