---
title: "Create a trait definition"
method: POST
path: "/api/v1/ackdb/schemas/traits"
tags: ["ackDB"]
---

# Create a trait definition

`POST /api/v1/ackdb/schemas/traits`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/ackdb/schemas/traits`
- Auth: HTTP bearer

Creates a new trait definition. Use this to register custom traits beyond the defaults provided by source definitions. If the trait already exists, it will be updated.

## Request body

- object
  - `traitKey` string, required: Unique trait key identifier.
  - `valueType` 'string' | 'number' | 'boolean' | 'date' | 'string_array', required: Data type for this trait's values.
  - `source` string, required: Source that produces this trait.
  - `description` string: Human/AI-readable description of what this trait means.
  - `allowedValues` unknown[]: If set, restricts trait values to this list.
    - unknown

## Response `201`

Trait definition created

- object
  - `data` AckdbTraitDefinition, required: Trait definition. Like Salesforce custom fields - defines what computed fields exist. AI agents discover fields by listing these at runtime.
    - `traitKey` string, required: Unique within org. Convention: prefix with source name.
    - `valueType` 'string' | 'number' | 'boolean' | 'date' | 'string_array', required: Type system for trait validation and storage. Controls how trait values are validated on ingest and stored in the entity_traits table.
    - `source` string, required: Which source system this trait comes from.
    - `description` string, required: Human/AI-readable description. AI agents use this to understand the trait.
    - `allowedValues` unknown[], required: Optional enum constraint. Write API rejects values not in this list.
      - unknown
    - `scope` 'entity' | 'contact': Trait grain: entity (company) or contact. Defaults to "entity".
    - `createdAt` string, date-time, required

## Other responses

- `400`: Validation error - missing required fields

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)