Create a custom object

Creates a new custom object type in the workspace and returns its generated JSON Schema. The name is normalized to a c_-prefixed identifier (for example "Sales Order" becomes c_sales_order).

Authorization

Authorization<token>

API key authentication. Send your key in the Authorization header as: api-key <your-api-key>.

In: header

Path Parameters

workspace*string

The workspace slug — the {slug} segment of your Clarify workspace URL.

Query Parameters

silent?boolean

When true, suppresses in-app and Slack notifications for this mutation and batches its live updates, so open views can lag by up to 20 seconds.

Header Parameters

clarify-version?string

The API version for this request. Send 2026-11 to get the behavior documented here. Omit it to use your API key's version, which this header can raise but not lower.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

The name will be normalized to a c_ prefixed identifier (e.g., "Sales Order" becomes "c_sales_order")

Length1 <= length <= 32

plural*string

The plural name will be used to display the object type in the UI

Length1 <= length <= 32

description?string

The description is stored as AI context for this object type

Lengthlength <= 256

icon?string

Icon name for the object avatar. Must be one of the curated avatar icon names (xClarifyPresentation.icon).

Value in

"Box"
"Package"
"FileText"
"Folder"
"Ticket"
"Briefcase"
"Store"
"Component"
"Layers"
"MapPin"
"Globe"
"BankNote"
"CreditCard"
"Receipt"
"ShoppingCart"
"Car"
"Truck"
"Book"
"GraduationCap"
"Shield"
"Key"
"Megaphone"
"Flag"
"Target"
"Trophy"
"Rocket"
"Zap"
"Phone"
"Image"
"Tag"
"Wrench"
"Heart"
"Users"
"Handshake"
"Database"
"FlaskConical"

backgroundColor?string

Background color for the object avatar. A Tailwind color name rendered at the 500 shade (xClarifyPresentation.backgroundColor).

Value in

"red"
"orange"
"amber"
"yellow"
"lime"
"green"
"emerald"
"teal"
"cyan"
"sky"
"blue"
"indigo"
"violet"
"purple"
"fuchsia"
"pink"
"rose"
"neutral"

properties?

Initial fields for the object, keyed by field name and valued by JSON Schema. Built-in system fields are always added and cannot be overridden.

Response Body

`application/json`

curl -X POST "https://example.com/workspaces/string/schemas/objects" \  -H "clarify-version: 2026-11" \  -H "Content-Type: application/json" \  -d '{    "name": "Project",    "plural": "Projects",    "description": "A customer project tracked alongside deals and companies.",    "icon": "Briefcase",    "backgroundColor": "blue"  }'

{  "data": {    "type": "schema",    "id": "https://getclarify.ai/schemas/entities/c_project",    "attributes": {      "$schema": "https://json-schema.org/draft/2020-12/clarify",      "$id": "https://getclarify.ai/schemas/entities/c_project",      "title": "Project",      "type": "object",      "xClarifyNamespace": "objects",      "xClarifyLabel": {        "singular": "Project",        "plural": "Projects"      },      "xClarifyAIDescription": "A customer project tracked alongside deals and companies.",      "properties": {        "name": {          "type": "string",          "title": "Name",          "xClarifyPrimary": true        },        "status": {          "type": [            "string",            "null"          ],          "title": "Status",          "enum": [            "Planning",            "In progress",            "Complete"          ]        },        "company_id": {          "type": [            "string",            "null"          ],          "title": "Company",          "xClarifyRelationship": {            "kind": "many-to-one",            "entity": "company",            "field": "projects"          }        }      }    }  }}