Ledga
POST/attribute-definitions

Declare a searchable attribute key

Declare a key (required to opt a tenant into strict mode). Applies the same key guard rails as the write path (charset, reserved-name, distinct-key cap). Requires the attributes:admin capability on the API key (this endpoint mutates tenant-wide governance state); a key without it receives 403 ATTRIBUTE_ADMIN_CAPABILITY_REQUIRED.

Request bodyrequired

FieldTypeDescription
keyrequired string
max length: 64
 Lowercase snake_case. Must not be reserved or exceed the tenant distinct-key cap.
label string
nullable
indexed boolean
default: true

Responses

201Attribute definition declared 
{
  "success": true,
  "data": {
    "id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
    "key": "customer_id",
    "label": "Customer ID",
    "indexed": true,
    "usage_count": 1200,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
}
401Unauthenticated 
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}
403Forbidden — missing the required 'attributes:admin' capability (ATTRIBUTE_ADMIN_CAPABILITY_REQUIRED) 
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}
409Key already declared 
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}
422Guard-rail violation (INVALID_ATTRIBUTE_KEY / RESERVED_ATTRIBUTE_KEY / ATTRIBUTE_KEY_CAP_EXCEEDED) 
{
  "success": false,
  "message": "Validation failed",
  "code": "VALIDATION_ERROR"
}

Examples

curl -X POST https://ledga.io/api/v1/attribute-definitions \
  -H "Authorization: Bearer sk_xxxxxxxx_your_secret" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "customer_id",
  "label": "Customer ID",
  "indexed": true
}'

← All endpoints