1. API
  2. Records
  3. Record types

Record types: Create

Last updated Open markdown version

Description

Create a new record type.

Retention behavior is set at creation time via ttl_days, retention_column_name, max_records_limit, and on_limit_reached. See Best practices for how to combine these depending on whether you're modelling an enrichment cache, a workflow buffer, or an audit trail.

See the Get Record Type API to learn more about record types.

Request

HTTP Method: POST

Body parameter Description
name The record type name.
description Optional A short description of the record type.
team_id ID of team to which the record type belongs.
fields An array of objects describing the custom record fields defined by the user.
editable Optional Whether the records for this record type are editable or not.
ttl_days Optional Records for this record type will be deleted after this number of days. Accepted values: 0.25 (6 hours), 0.5 (12 hours), 1, 2, 3, 7, 14, 30, 60, 90, 180, 365, 548, 730, 1095, 1460, 1825, 2190, 2555, 2920, 3285, 3650.
retention_column_name Optional The timestamp column used to determine record age for TTL expiry. Accepted values are CREATED_AT (default) and UPDATED_AT. With UPDATED_AT, a record's age resets each time it's updated, so only records that haven't been updated within ttl_days are deleted. Has no effect unless ttl_days is set.
on_limit_reached Optional Behavior when the record type reaches its per-type record limit. Accepted values are REJECT (default; block new writes) and EVICT_OLDEST (delete the oldest record to make room for the new one).
max_records_limit Optional Custom per-record-type record limit. Must be a positive integer no greater than the tenant ceiling. If omitted, the tenant default applies.

Fields parameter

The fields parameter is an array of objects representing the custom record fields defined by the user. A record type can have at most 50 custom fields. Each object accepts:

Field property Description
name The field name.
result_type The field's data type: TEXT, NUMBER, TIMESTAMP, BOOLEAN, TEXT_ENUM (text with a predefined set of values), JSON (100k limit), or ARTIFACT (large text).
fixed_values Required for TEXT_ENUM, otherwise omit. Array of allowed values (max 100 entries).
description Optional A short description of the field. 
curl -X POST \
  https://<tenant-domain>/api/v1/record_types \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>' \
  -d '{
      "name": "Alerts",
      "description": "Alerts from external sources",
      "team_id": "<<META.team.id>>",
      "fields": [
        { "name": "Severity", "result_type": "TEXT_ENUM", "fixed_values": ["low", "medium", "high"] },
        { "name": "Description", "result_type": "TEXT", "description": "Free-form description of the alert" }
      ],
      "editable": true,
      "ttl_days": 3,
      "retention_column_name": "UPDATED_AT",
      "on_limit_reached": "EVICT_OLDEST",
      "max_records_limit": 5000
    }'

Response

A successful request will return a JSON object representing the created record type.

Field description

Parameter Description
id The record type ID.
name The record type name.
description A short description of the record type, or null if not set.
team_id ID of team to which the record type belongs.
editable Whether the records for this record type are editable or not.
ttl_days Records for this record type will be deleted after this number of days.
retention_column_name The timestamp column used to determine record age for TTL expiry. One of CREATED_AT or UPDATED_AT. With UPDATED_AT, a record's age resets each time it's updated.
on_limit_reached Behavior when the record type reaches its per-type record limit. One of REJECT (block new writes) or EVICT_OLDEST (delete the oldest record to make room).
max_records_limit Custom per-record-type record limit, or null if no custom limit is set (in which case the tenant default applies).
record_fields An array of objects describing the custom record fields defined by the user.
default_record_fields An array of objects describing the built-in default record fields.

Sample response

{
  "id": 1,
  "name": "Alerts",
  "description": "Alerts from external sources",
  "team_id": 123,
  "editable": true,
  "ttl_days": 3,
  "retention_column_name": "UPDATED_AT",
  "on_limit_reached": "EVICT_OLDEST",
  "max_records_limit": 5000,
  "record_fields": [
    {
      "id": 1,
      "name": "Severity",
      "description": null,
      "result_type": "TEXT_ENUM",
      "fixed_values": ["low", "medium", "high"]
    },
    {
      "id": 2,
      "name": "Description",
      "description": "Free-form description of the alert",
      "result_type": "TEXT",
      "fixed_values": []
    }
  ],
  "default_record_fields": [
    {
      "id": 3,
      "name": "Record ID",
      "description": null,
      "result_type": "NUMBER",
      "fixed_values": []
    },
    {
      "id": 4,
      "name": "Story name",
      "description": null,
      "result_type": "TEXT",
      "fixed_values": []
    },
    {
      "id": 5,
      "name": "Timestamp",
      "description": null,
      "result_type": "TIMESTAMP",
      "fixed_values": []
    },
    {
      "id": 6,
      "name": "Updated at",
      "description": null,
      "result_type": "TIMESTAMP",
      "fixed_values": []
    }
  ]
}
Was this helpful?