Create a definition

POST

definitions

Create a definition

curl --request POST \
  --url https://api.getarbol.com/v1/definitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "identifier": "<string>",
  "kind": "attribute",
  "subjectKind": "contact",
  "valueType": "option"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    identifier: '<string>',
    kind: 'attribute',
    subjectKind: 'contact',
    valueType: 'option'
  })
};

fetch('https://api.getarbol.com/v1/definitions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.getarbol.com/v1/definitions"

payload = {
    "identifier": "<string>",
    "kind": "attribute",
    "subjectKind": "contact",
    "valueType": "option"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "agentIds": [
    "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"
  ],
  "createdAt": "2026-08-29T14:30:00Z",
  "description": "<string>",
  "id": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "identifier": "<string>",
  "kind": "attribute",
  "prompt": "<string>",
  "revision": 123,
  "schemaVersion": 123,
  "status": "active",
  "subjectKind": "contact",
  "unitCode": "<string>",
  "updatedAt": "2026-08-29T14:30:00Z",
  "valueType": "option",
  "options": [
    {
      "description": "<string>",
      "key": "<string>",
      "label": "<string>",
      "sortOrder": 500,
      "id": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
      "status": "active"
    }
  ],
  "usage": {
    "factCount": 4503599627370495,
    "lastObservedAt": "2026-08-29T14:30:00Z",
    "subjectCount": 4503599627370495
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "<string>",
  "data": {
    "issues": [
      {
        "message": "<string>",
        "path": [
          "<string>"
        ]
      }
    ],
    "truncated": true
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "<string>",
  "data": {
    "missingPermissions": [
      "agents:read"
    ]
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "CONFLICT",
  "status": 409,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "PAYLOAD_TOO_LARGE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "UNPROCESSABLE_CONTENT",
  "status": 422,
  "message": "<string>",
  "data": "<unknown>"
}

Authorizations

Authorization

string

header

required

Organization-scoped Auth0 user access token issued to an approved first-party client or exchanged by a trusted OBO resource server.

Body

application/json

Complete initial Definition, including the closed option set when valueType is option.

identifier

string

required

Required string length: 1 - 100

Pattern: ^[a-z][a-z0-9_]*$

kind

enum<string>

required

Semantic class of an organization-owned Definition.

Available options:

attribute,

assessment,

category,

metric

Example:

"attribute"

subjectKind

enum<string>

required

Resource type to which a Definition may be asserted.

Available options:

contact,

conversation

Example:

"contact"

valueType

enum<string>

required

Validated value representation accepted by a Definition.

Available options:

text,

number,

boolean,

date,

option

Example:

"option"

agentIds

string[]

Maximum array length: 50

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

description

string | null

Maximum string length: 2000

options

Definition option input · object[]

Maximum array length: 100

Show child attributes

prompt

string | null

Maximum string length: 4000

status

enum<string>

default:active

Available options:

draft,

active

unitCode

string | null

Required string length: 1 - 40

Response

agentIds

string[]

required

Maximum array length: 50

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

createdAt

string<date-time>

required

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

description

string | null

required

Maximum string length: 2000

string

required

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

identifier

string

required

Required string length: 1 - 100

kind

enum<string>

required

Semantic class of an organization-owned Definition.

Available options:

attribute,

assessment,

category,

metric

Example:

"attribute"

prompt

string | null

required

Maximum string length: 4000

revision

integer

required

Required range: x <= 9007199254740991

schemaVersion

integer

required

Required range: x <= 9007199254740991

status

enum<string>

required

Lifecycle state of an organization-owned Definition.

Available options:

draft,

active,

retired

Example:

"active"

subjectKind

enum<string>

required

Resource type to which a Definition may be asserted.

Available options:

contact,

conversation

Example:

"contact"

unitCode

string | null

required

Maximum string length: 40

updatedAt

string<date-time>

required

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

valueType

enum<string>

required

Validated value representation accepted by a Definition.

Available options:

text,

number,

boolean,

date,

option

Example:

"option"

options

Definition option · object[]

Maximum array length: 100

Show child attributes

usage

object

Show child attributes

⌘I

Create a definition

curl --request POST \
  --url https://api.getarbol.com/v1/definitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "identifier": "<string>",
  "kind": "attribute",
  "subjectKind": "contact",
  "valueType": "option"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    identifier: '<string>',
    kind: 'attribute',
    subjectKind: 'contact',
    valueType: 'option'
  })
};

fetch('https://api.getarbol.com/v1/definitions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.getarbol.com/v1/definitions"

payload = {
    "identifier": "<string>",
    "kind": "attribute",
    "subjectKind": "contact",
    "valueType": "option"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "agentIds": [
    "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"
  ],
  "createdAt": "2026-08-29T14:30:00Z",
  "description": "<string>",
  "id": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
  "identifier": "<string>",
  "kind": "attribute",
  "prompt": "<string>",
  "revision": 123,
  "schemaVersion": 123,
  "status": "active",
  "subjectKind": "contact",
  "unitCode": "<string>",
  "updatedAt": "2026-08-29T14:30:00Z",
  "valueType": "option",
  "options": [
    {
      "description": "<string>",
      "key": "<string>",
      "label": "<string>",
      "sortOrder": 500,
      "id": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
      "status": "active"
    }
  ],
  "usage": {
    "factCount": 4503599627370495,
    "lastObservedAt": "2026-08-29T14:30:00Z",
    "subjectCount": 4503599627370495
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "<string>",
  "data": {
    "issues": [
      {
        "message": "<string>",
        "path": [
          "<string>"
        ]
      }
    ],
    "truncated": true
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "<string>",
  "data": {
    "missingPermissions": [
      "agents:read"
    ]
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "CONFLICT",
  "status": 409,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "PAYLOAD_TOO_LARGE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "UNPROCESSABLE_CONTENT",
  "status": 422,
  "message": "<string>",
  "data": "<unknown>"
}

Overview

Endpoints

Create a definition

Authorizations

Body

Response