Schema - Salty

The schema endpoints let agents extend Salty’s data model without leaving the API. See Concepts → Schema engine for how validation works.

Endpoints

Method	Path	Purpose
`GET`	`/schema`	Full workspace schema, grouped by object type
`GET`	`/schema/:object_type`	Attributes defined for one object type
`POST`	`/schema/:object_type/attributes`	Add an attribute definition
`PATCH`	`/schema/:object_type/attributes/:key`	Modify (metadata + append enums + toggle required)
`DELETE`	`/schema/:object_type/attributes/:key`	Soft-delete (sets `deprecated_at`)

:object_type is one of person, company, deal, note, task, activity, or a custom object’s UUID (not its slug).

Add an attribute

curl -X POST $SALTY_API/schema/person/attributes \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attribute_key": "lifecycle_stage",
    "display_name": "Lifecycle Stage",
    "data_type": "enum",
    "enum_values": ["lead", "customer", "churned"],
    "is_required": false,
    "default_value": "lead"
  }'

Response:

{
  "id": "2a48bdd8-61e6-4ad1-bf8b-8d58ba6e1666",
  "object_type": "person",
  "attribute_key": "lifecycle_stage",
  "display_name": "Lifecycle Stage",
  "data_type": "enum",
  "is_required": false,
  "default_value": "lead",
  "enum_values": ["lead", "customer", "churned"],
  "reference_object_type": null,
  "deprecated": false,
  "deprecated_at": null,
  "created_at": "2026-05-24T02:45:46.461Z"
}

Constraints by `data_type`

enum requires non-empty enum_values. Otherwise → 400 enum_values_required.
reference requires reference_object_type ∈ {person, company, deal}. Otherwise → 400 reference_object_type_required.
All keys must match ^[a-z][a-z0-9_]*$ (lowercase snake_case, max 64 chars).
Duplicate (workspace_id, object_type, attribute_key) → 409 attribute_exists.

Modify (PATCH)

curl -X PATCH $SALTY_API/schema/person/attributes/lifecycle_stage \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Lifecycle",
    "enum_values_append": ["prospect", "qualified"],
    "is_required": true
  }'

What you can edit:

display_name
default_value
is_required (both directions; doesn’t backfill existing rows)
enum_values_append — array of new values to add. Duplicates are deduped server-side.

What you can’t edit:

data_type — frozen after creation. Changing it would require a data migration.
enum_values — only appendable in v1. Removing values silently invalidates existing rows; the v1.1 endpoint will require explicit migration semantics.

Deprecate (DELETE)

curl -X DELETE $SALTY_API/schema/person/attributes/lead_source \
  -H "Authorization: Bearer $SALTY_API_KEY"
# 204 No Content

Sets deprecated_at = now(). Existing data with the key stays readable. New writes of the key return 400 attribute_deprecated. The attribute still shows up in GET /schema with "deprecated": true.

Read

curl $SALTY_API/schema -H "Authorization: Bearer $SALTY_API_KEY"

{
  "objects": {
    "person": [ /* ... */ ],
    "company": [],
    "deal": [],
    "note": [],
    "task": [],
    "activity": []
  }
}

​Endpoints

​Add an attribute

​Constraints by data_type

​Modify (PATCH)

​Deprecate (DELETE)

​Read