Custom Fields API Reference

API ReferenceCustom Fields

Find an endpointAll endpoints

MethodScope

Custom Fields

Manages custom-field definitions and their values on incidents.

GET`/api/v1/custom-fields`List custom fields

Returns one page sorted by sort_order, creation time, and custom-field ID. By default, the response excludes archived definitions.

Operation ID: listCustomFields
Scope: custom_fields:read
Prerequisites: None
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/custom-fields' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns custom-field definitions and pagination fields.

Success response JSON

json

{
  "fields": [
    {
      "id": 50,
      "revision": 2,
      "company_id": 7,
      "name": "Affected Users",
      "slug": "affected_users",
      "field_type": "number",
      "description": "Number of users impacted",
      "default_value": 0,
      "config": {
        "min": 0,
        "precision": 0
      },
      "required": false,
      "sort_order": 1,
      "category": "impact",
      "visibility_level": "prominent",
      "show_on_creation": true,
      "required_on_creation": false,
      "auto_add_to_layout": true,
      "created_at": "2025-01-10T09:00:00Z",
      "updated_at": "2025-01-10T09:00:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "opaque-server-cursor"
  }
}

Request and response contract

Query parameters

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Query parameters
Field	Type	Required	Description
`limit`	integer	No	The maximum number of items in one page. The default is 50, and the maximum is 100. Minimum: 1. · Maximum: 100. · Default: 50.
`cursor`	string	No	The next_cursor value from the previous page. Clients treat this value as opaque and do not create, inspect, or change it. Minimum length: 1 characters. · Maximum length: 4096 characters.
`include_archived`	boolean	No	Controls whether the response includes archived custom fields. The default is false. Default: false.

Response `200`

Returns custom-field definitions and pagination fields.

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response fields
Field	Type	Returned	Description
`fields`	object[]	Always	The custom-field definitions in this page.
`fields[].id`	integer	Always	The positive numeric ID of the custom-field definition. Minimum: 1.
`fields[].revision`	integer	Always	The resource version for concurrency control. Minimum: 1.
`fields[].company_id`	integer	Always	The ID of the workspace that owns the definition. Minimum: 1.
`fields[].name`	string	Always	The display name of the custom field.
`fields[].slug`	string	Always	The permanent key used to identify the custom field.
`fields[].field_type`	string	Always	The value type for this custom field. Possible values: `"string""number""boolean""date""time""datetime""monetary""json""select""multi_select"`
`fields[].description`	string	Optional	The workspace description of the custom field.
`fields[].default_value`	any	Optional	The default field value. Its type depends on field_type.
`fields[].config`	object	Optional	The validation and option configuration for field_type.
`fields[].required`	boolean	Always	Indicates whether each incident must retain a value for this field.
`fields[].sort_order`	integer	Always	The display position of the custom field.
`fields[].category`	string	Always	The workspace category for the custom field. Possible values: `"context""impact""analysis""external""custom"`
`fields[].visibility_level`	string	Always	The configured display prominence for the custom field. Possible values: `"always""prominent""standard""collapsed"`
`fields[].show_on_creation`	boolean	Always	Indicates whether the incident creation form shows this field.
`fields[].required_on_creation`	boolean	Always	Indicates whether a create-incident request must supply this field.
`fields[].auto_add_to_layout`	boolean	Always	Indicates whether Tellagen adds this field to new incident layouts.
`fields[].external_source`	string	Optional	The source identifier for a custom field in the external category.
`fields[].archived_at`	string (RFC 3339)	Optional	The definition archive time. This field is absent for an active definition.
`fields[].created_at`	string (RFC 3339)	Always	The definition creation time.
`fields[].updated_at`	string (RFC 3339)	Always	The time of the latest definition change.
`pagination`	object	Always	Pagination details for a collection response.
`pagination.limit`	integer	Always	The maximum number of items requested for this page. Minimum: 1. · Maximum: 100.
`pagination.has_more`	boolean	Always	Indicates whether another page is available.
`pagination.next_cursor`	string	Optional	The opaque cursor for the next page. This field is absent on the final page.

Errors and recovery (7)

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

POST`/api/v1/custom-fields`Create custom field

Creates a custom-field definition. If slug is omitted, the API creates it from name. Before creation, the API validates config and default_value against field_type.

Operation ID: createCustomField
Scope: custom_fields:write
Prerequisites: Active responder seat Manage workspace settings
Retry guidance: Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/custom-fields' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Affected Users",
  "field_type": "number",
  "description": "Number of users impacted",
  "category": "impact",
  "visibility_level": "prominent",
  "show_on_creation": true,
  "config": {
    "min": 0,
    "precision": 0
  }
}'

Success: 201

Returns the created custom-field definition.

Success response JSON

json

{
  "field": {
    "id": 50,
    "revision": 1,
    "company_id": 7,
    "name": "Affected Users",
    "slug": "affected_users",
    "field_type": "number",
    "description": "Number of users impacted",
    "default_value": null,
    "config": {
      "min": 0,
      "precision": 0
    },
    "required": false,
    "sort_order": 0,
    "category": "impact",
    "visibility_level": "prominent",
    "show_on_creation": true,
    "required_on_creation": false,
    "auto_add_to_layout": false,
    "created_at": "2025-01-30T12:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z"
  }
}

Request and response contract

Request body

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Request body fields
Field	Type	Required	Description
`name`	string	Yes	The field name. The length must be from 1 through 64 characters. Minimum length: 1 characters. · Maximum length: 64 characters.
`slug`	string	No	A permanent URL-safe key. If the request omits slug, the API creates it from name.
`field_type`	string	Yes	The value type. Allowed values: `"string""number""boolean""date""time""datetime""monetary""json""select""multi_select"`
`description`	string	No	The workspace description of the custom field.
`default_value`	any	No	The default field value. Its type must match field_type.
`config`	object	Conditional	Validation options for field_type. String fields accept max_length. Number fields accept min, max, and precision. Monetary fields also accept currency or currencies. Select fields accept options and allow_custom. The API rejects unsupported keys. Required when The accepted keys and value shapes depend on field_type.
`required`	boolean	No	Controls whether each incident must retain a value. If this value is true, the API rejects JSON null and requests to unset the value.
`category`	string	No	The workspace category. Allowed values: `"context""impact""analysis""external""custom"`
`visibility_level`	string	No	The display prominence. Allowed values: `"always""prominent""standard""collapsed"`
`show_on_creation`	boolean	No	Controls whether the incident creation form shows this field.
`required_on_creation`	boolean	No	Controls whether a create-incident request must supply this field. A true value requires show_on_creation to be true.
`auto_add_to_layout`	boolean	No	Controls whether Tellagen adds this field to new incident layouts.
`external_source`	string	Conditional	The source identifier for category external. This field is required for that category and is not valid for other categories. Required when Required when category is "external".

Response `201`

Returns the created custom-field definition.

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response fields
Field	Type	Returned	Description
`field`	object	Always	The complete public definition of a custom field.
`field.id`	integer	Always	The positive numeric ID of the custom-field definition. Minimum: 1.
`field.revision`	integer	Always	The resource version for concurrency control. Minimum: 1.
`field.company_id`	integer	Always	The ID of the workspace that owns the definition. Minimum: 1.
`field.name`	string	Always	The display name of the custom field.
`field.slug`	string	Always	The permanent key used to identify the custom field.
`field.field_type`	string	Always	The value type for this custom field. Possible values: `"string""number""boolean""date""time""datetime""monetary""json""select""multi_select"`
`field.description`	string	Optional	The workspace description of the custom field.
`field.default_value`	any	Optional	The default field value. Its type depends on field_type.
`field.config`	object	Optional	The validation and option configuration for field_type.
`field.required`	boolean	Always	Indicates whether each incident must retain a value for this field.
`field.sort_order`	integer	Always	The display position of the custom field.
`field.category`	string	Always	The workspace category for the custom field. Possible values: `"context""impact""analysis""external""custom"`
`field.visibility_level`	string	Always	The configured display prominence for the custom field. Possible values: `"always""prominent""standard""collapsed"`
`field.show_on_creation`	boolean	Always	Indicates whether the incident creation form shows this field.
`field.required_on_creation`	boolean	Always	Indicates whether a create-incident request must supply this field.
`field.auto_add_to_layout`	boolean	Always	Indicates whether Tellagen adds this field to new incident layouts.
`field.external_source`	string	Optional	The source identifier for a custom field in the external category.
`field.archived_at`	string (RFC 3339)	Optional	The definition archive time. This field is absent for an active definition.
`field.created_at`	string (RFC 3339)	Always	The definition creation time.
`field.updated_at`	string (RFC 3339)	Always	The time of the latest definition change.

Response headers

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response headers
Field	Type	Returned	Description
`Tellagen-Resource-Version`	integer	Always	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

GET`/api/v1/custom-fields/{id}`Get custom field

Returns one custom-field definition by its positive numeric ID. A definition remains available by ID after it is archived.

Operation ID: getCustomField
Scope: custom_fields:read
Prerequisites: None
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/custom-fields/{id}' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns the custom-field definition.

Success response JSON

json

{
  "field": {
    "id": 50,
    "revision": 2,
    "company_id": 7,
    "name": "Affected Users",
    "slug": "affected_users",
    "field_type": "number",
    "description": "Number of users impacted",
    "default_value": 0,
    "config": {
      "min": 0,
      "precision": 0
    },
    "required": false,
    "sort_order": 1,
    "category": "impact",
    "visibility_level": "prominent",
    "show_on_creation": true,
    "required_on_creation": false,
    "auto_add_to_layout": true,
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-10T09:00:00Z"
  }
}

Request and response contract

Path parameters

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Path parameters
Field	Type	Required	Description
`id`	integer	Yes	A positive numeric custom-field ID returned by this API. Minimum: 1.

Response `200`

Returns the custom-field definition.

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response fields
Field	Type	Returned	Description
`field`	object	Always	The complete public definition of a custom field.
`field.id`	integer	Always	The positive numeric ID of the custom-field definition. Minimum: 1.
`field.revision`	integer	Always	The resource version for concurrency control. Minimum: 1.
`field.company_id`	integer	Always	The ID of the workspace that owns the definition. Minimum: 1.
`field.name`	string	Always	The display name of the custom field.
`field.slug`	string	Always	The permanent key used to identify the custom field.
`field.field_type`	string	Always	The value type for this custom field. Possible values: `"string""number""boolean""date""time""datetime""monetary""json""select""multi_select"`
`field.description`	string	Optional	The workspace description of the custom field.
`field.default_value`	any	Optional	The default field value. Its type depends on field_type.
`field.config`	object	Optional	The validation and option configuration for field_type.
`field.required`	boolean	Always	Indicates whether each incident must retain a value for this field.
`field.sort_order`	integer	Always	The display position of the custom field.
`field.category`	string	Always	The workspace category for the custom field. Possible values: `"context""impact""analysis""external""custom"`
`field.visibility_level`	string	Always	The configured display prominence for the custom field. Possible values: `"always""prominent""standard""collapsed"`
`field.show_on_creation`	boolean	Always	Indicates whether the incident creation form shows this field.
`field.required_on_creation`	boolean	Always	Indicates whether a create-incident request must supply this field.
`field.auto_add_to_layout`	boolean	Always	Indicates whether Tellagen adds this field to new incident layouts.
`field.external_source`	string	Optional	The source identifier for a custom field in the external category.
`field.archived_at`	string (RFC 3339)	Optional	The definition archive time. This field is absent for an active definition.
`field.created_at`	string (RFC 3339)	Always	The definition creation time.
`field.updated_at`	string (RFC 3339)	Always	The time of the latest definition change.

Response headers

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response headers
Field	Type	Returned	Description
`Tellagen-Resource-Version`	integer	Always	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

PATCH`/api/v1/custom-fields/{id}`Update custom field

Updates an active custom-field definition. The API combines supplied and stored values before validation. This validation includes the stored default_value. Omitted fields stay unchanged.

Operation ID: updateCustomField
Scope: custom_fields:write
Prerequisites: Active responder seat Manage workspace settings
Retry guidance: Read the current resource and reconcile changes before retrying with its current version. A stale version returns 412. Retry rules

Example request

Replace {company}, <token>, and any other placeholders with your values.

Use the Tellagen-Resource-Version header from a GET of this resource for <resource-version>.

bash

curl --request PATCH \
  --url 'https://{company}.api.tellagen.com/api/v1/custom-fields/{id}' \
  --header 'Authorization: Bearer <token>' \
  --header 'If-Tellagen-Resource-Version: <resource-version>' \
  --header 'Content-Type: application/json' \
  --data '{
  "required": true,
  "sort_order": 2
}'

Success: 200

Returns the updated custom-field definition.

Success response JSON

json

{
  "field": {
    "id": 50,
    "revision": 3,
    "company_id": 7,
    "name": "Affected Users",
    "slug": "affected_users",
    "field_type": "number",
    "description": "Number of users impacted",
    "config": {
      "min": 0,
      "precision": 0
    },
    "required": true,
    "sort_order": 2,
    "category": "impact",
    "visibility_level": "prominent",
    "show_on_creation": true,
    "required_on_creation": false,
    "auto_add_to_layout": true,
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z"
  }
}

Request and response contract

Path parameters

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Path parameters
Field	Type	Required	Description
`id`	integer	Yes	A positive numeric custom-field ID returned by this API. Minimum: 1.

Request headers

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Request headers
Field	Type	Required	Description
`If-Tellagen-Resource-Version`	integer	Yes	The current positive resource version from the latest response. API-key PATCH requests must send this value. Minimum: 1.

Request body

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Request body fields
Field	Type	Required	Description
`name`	string	No	The field name. The length must be from 1 through 64 characters. Minimum length: 1 characters. · Maximum length: 64 characters.
`description`	string	No	The replacement field description.
`default_value`	any	No	The replacement default value. Its type must match field_type.
`config`	object	No	The replacement validation and option configuration for field_type.
`required`	boolean	No	Controls whether each incident must retain a value for this field.
`sort_order`	integer	No	The new display position of the custom field.
`category`	string	No	The workspace category. Allowed values: `"context""impact""analysis""external""custom"`
`visibility_level`	string	No	The display prominence. Allowed values: `"always""prominent""standard""collapsed"`
`show_on_creation`	boolean	No	Controls whether the incident creation form shows this field.
`required_on_creation`	boolean	No	Controls whether a create-incident request must supply this field.
`auto_add_to_layout`	boolean	No	Controls whether Tellagen adds this field to new incident layouts.
`external_source`	string	No	The replacement source identifier for category external.

Response `200`

Returns the updated custom-field definition.

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response fields
Field	Type	Returned	Description
`field`	object	Always	The complete public definition of a custom field.
`field.id`	integer	Always	The positive numeric ID of the custom-field definition. Minimum: 1.
`field.revision`	integer	Always	The resource version for concurrency control. Minimum: 1.
`field.company_id`	integer	Always	The ID of the workspace that owns the definition. Minimum: 1.
`field.name`	string	Always	The display name of the custom field.
`field.slug`	string	Always	The permanent key used to identify the custom field.
`field.field_type`	string	Always	The value type for this custom field. Possible values: `"string""number""boolean""date""time""datetime""monetary""json""select""multi_select"`
`field.description`	string	Optional	The workspace description of the custom field.
`field.default_value`	any	Optional	The default field value. Its type depends on field_type.
`field.config`	object	Optional	The validation and option configuration for field_type.
`field.required`	boolean	Always	Indicates whether each incident must retain a value for this field.
`field.sort_order`	integer	Always	The display position of the custom field.
`field.category`	string	Always	The workspace category for the custom field. Possible values: `"context""impact""analysis""external""custom"`
`field.visibility_level`	string	Always	The configured display prominence for the custom field. Possible values: `"always""prominent""standard""collapsed"`
`field.show_on_creation`	boolean	Always	Indicates whether the incident creation form shows this field.
`field.required_on_creation`	boolean	Always	Indicates whether a create-incident request must supply this field.
`field.auto_add_to_layout`	boolean	Always	Indicates whether Tellagen adds this field to new incident layouts.
`field.external_source`	string	Optional	The source identifier for a custom field in the external category.
`field.archived_at`	string (RFC 3339)	Optional	The definition archive time. This field is absent for an active definition.
`field.created_at`	string (RFC 3339)	Always	The definition creation time.
`field.updated_at`	string (RFC 3339)	Always	The time of the latest definition change.

Response headers

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response headers
Field	Type	Returned	Description
`Tellagen-Resource-Version`	integer	Always	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (9)

Error responses (9)

400 401 403 404 409 412 428 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
412: The resource changed after the client obtained its If-Tellagen-Resource-Version value.
428: An API-key PATCH request did not include the required If-Tellagen-Resource-Version header.
429: The workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

DELETE`/api/v1/custom-fields/{id}`Archive custom field

Archives a custom-field definition. A repeated request returns 204 without changing the archive time or resource version. Existing incident values remain available as historical data. Values for an archived definition cannot be added, changed, or removed.

Operation ID: archiveCustomField
Scope: custom_fields:write
Prerequisites: Active responder seat Manage workspace settings
Retry guidance: Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request DELETE \
  --url 'https://{company}.api.tellagen.com/api/v1/custom-fields/{id}' \
  --header 'Authorization: Bearer <token>'

Success: 204

No response body. Do not try to parse this response as JSON.

Request and response contract

Path parameters

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Path parameters
Field	Type	Required	Description
`id`	integer	Yes	A positive numeric custom-field ID returned by this API. Minimum: 1.

Returns 204 with no body.

Errors and recovery (7)

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

POST`/api/v1/custom-fields/{id}/restore`Restore custom field

Restores an archived custom-field definition and returns the active definition. A repeated request returns the active definition without changing its resource version. The API retains existing incident values.

Operation ID: restoreCustomField
Scope: custom_fields:write
Prerequisites: Active responder seat Manage workspace settings
Retry guidance: Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/custom-fields/{id}/restore' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns the complete active custom-field definition.

Success response JSON

json

{
  "field": {
    "id": 50,
    "revision": 3,
    "company_id": 7,
    "name": "Affected Users",
    "slug": "affected_users",
    "field_type": "number",
    "description": "Number of users impacted",
    "config": {
      "min": 0,
      "precision": 0
    },
    "required": true,
    "sort_order": 2,
    "category": "impact",
    "visibility_level": "prominent",
    "show_on_creation": true,
    "required_on_creation": false,
    "auto_add_to_layout": true,
    "created_at": "2025-01-10T09:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z"
  }
}

Request and response contract

Path parameters

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Path parameters
Field	Type	Required	Description
`id`	integer	Yes	A positive numeric custom-field ID returned by this API. Minimum: 1.

Response `200`

Returns the complete active custom-field definition.

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response fields
Field	Type	Returned	Description
`field`	object	Always	The complete public definition of a custom field.
`field.id`	integer	Always	The positive numeric ID of the custom-field definition. Minimum: 1.
`field.revision`	integer	Always	The resource version for concurrency control. Minimum: 1.
`field.company_id`	integer	Always	The ID of the workspace that owns the definition. Minimum: 1.
`field.name`	string	Always	The display name of the custom field.
`field.slug`	string	Always	The permanent key used to identify the custom field.
`field.field_type`	string	Always	The value type for this custom field. Possible values: `"string""number""boolean""date""time""datetime""monetary""json""select""multi_select"`
`field.description`	string	Optional	The workspace description of the custom field.
`field.default_value`	any	Optional	The default field value. Its type depends on field_type.
`field.config`	object	Optional	The validation and option configuration for field_type.
`field.required`	boolean	Always	Indicates whether each incident must retain a value for this field.
`field.sort_order`	integer	Always	The display position of the custom field.
`field.category`	string	Always	The workspace category for the custom field. Possible values: `"context""impact""analysis""external""custom"`
`field.visibility_level`	string	Always	The configured display prominence for the custom field. Possible values: `"always""prominent""standard""collapsed"`
`field.show_on_creation`	boolean	Always	Indicates whether the incident creation form shows this field.
`field.required_on_creation`	boolean	Always	Indicates whether a create-incident request must supply this field.
`field.auto_add_to_layout`	boolean	Always	Indicates whether Tellagen adds this field to new incident layouts.
`field.external_source`	string	Optional	The source identifier for a custom field in the external category.
`field.archived_at`	string (RFC 3339)	Optional	The definition archive time. This field is absent for an active definition.
`field.created_at`	string (RFC 3339)	Always	The definition creation time.
`field.updated_at`	string (RFC 3339)	Always	The time of the latest definition change.

Response headers

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response headers
Field	Type	Returned	Description
`Tellagen-Resource-Version`	integer	Always	The positive resource version for If-Tellagen-Resource-Version in the next API-key PATCH request. Minimum: 1.

Errors and recovery (7)

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

GET`/api/v1/incidents/{id}/custom-fields`List incident custom-field values

Returns one page sorted by field sort_order, custom-field ID, and value-row ID. Values from archived definitions remain available as historical incident data.

Operation ID: listIncidentCustomFieldValues
Scope: custom_fields:read
Prerequisites: None
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries. Retry rules

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/custom-fields' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns custom-field values and pagination fields.

Success response JSON

json

{
  "values": [
    {
      "id": 1,
      "incident_id": 1,
      "custom_field_id": 50,
      "value": 1500,
      "created_at": "2025-01-30T12:05:00Z",
      "updated_at": "2025-01-30T12:05:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": false
  }
}

Request and response contract

Path parameters

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Path parameters
Field	Type	Required	Description
`id`	integer	Yes	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Query parameters

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Query parameters
Field	Type	Required	Description
`limit`	integer	No	The maximum number of items in one page. The default is 50, and the maximum is 100. Minimum: 1. · Maximum: 100. · Default: 50.
`cursor`	string	No	The next_cursor value from the previous page. Clients treat this value as opaque and do not create, inspect, or change it. Minimum length: 1 characters. · Maximum length: 4096 characters.

Response `200`

Returns custom-field values and pagination fields.

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response fields
Field	Type	Returned	Description
`values`	object[]	Always	The custom-field values in this page.
`values[].id`	integer	Always	The positive numeric ID of the stored value. Minimum: 1.
`values[].incident_id`	integer	Always	The positive numeric ID of the incident. Minimum: 1.
`values[].custom_field_id`	integer	Always	The positive numeric ID of the custom-field definition. Minimum: 1.
`values[].value`	any	Optional	The stored field value. Its type depends on field_type.
`values[].created_at`	string (RFC 3339)	Always	The initial value storage time.
`values[].updated_at`	string (RFC 3339)	Always	The time of the latest value change.
`pagination`	object	Always	Pagination details for a collection response.
`pagination.limit`	integer	Always	The maximum number of items requested for this page. Minimum: 1. · Maximum: 100.
`pagination.has_more`	boolean	Always	Indicates whether another page is available.
`pagination.next_cursor`	string	Optional	The opaque cursor for the next page. This field is absent on the final page.

Errors and recovery (7)

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

PATCH`/api/v1/incidents/{id}/custom-fields`Partially update incident custom-field values

Updates one or more custom-field values for an incident. The request must contain at least one { field_id, value } item. Each value must match its field type and configured limits or options. A required field rejects JSON null. Omitted fields stay unchanged. An unchanged value does not update timestamps or create severity, event, or changelog changes. API v1 still accepts deprecated PUT requests for this path. The next major API version will not accept PUT.

Operation ID: updateIncidentCustomFieldValues
Scope: custom_fields:write
Prerequisites: Active responder seat Incident is not archived
Retry guidance: Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request PATCH \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/custom-fields' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "values": [
    {
      "field_id": 50,
      "value": 1500
    },
    {
      "field_id": 51,
      "value": "enterprise"
    }
  ]
}'

Success: 200

Returns all custom-field values for the incident after the update.

Success response JSON

json

{
  "values": [
    {
      "id": 1,
      "incident_id": 1,
      "custom_field_id": 50,
      "value": 1500,
      "created_at": "2025-01-30T12:05:00Z",
      "updated_at": "2025-01-30T12:10:00Z"
    },
    {
      "id": 2,
      "incident_id": 1,
      "custom_field_id": 51,
      "value": "enterprise",
      "created_at": "2025-01-30T12:10:00Z",
      "updated_at": "2025-01-30T12:10:00Z"
    }
  ]
}

Request and response contract

Path parameters

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Path parameters
Field	Type	Required	Description
`id`	integer	Yes	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.

Request body

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Request body fields
Field	Type	Required	Description
`values`	object[]	Yes	A non-empty array of { field_id, value } objects. Each field_id must be unique. The API validates each value against field_type and its configuration. Supported types include strings, numbers, booleans, dates, times, monetary objects, JSON values, and configured selections. Minimum items: 1.
`values[].field_id`	integer	Yes	The positive ID of the custom-field definition. Minimum: 1.
`values[].value`	any	Yes	The new field value. Its type must match field_type.

Response `200`

Returns all custom-field values for the incident after the update.

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response fields
Field	Type	Returned	Description
`values`	object[]	Always	All current custom-field values for the incident.
`values[].id`	integer	Always	The positive numeric ID of the stored value. Minimum: 1.
`values[].incident_id`	integer	Always	The positive numeric ID of the incident. Minimum: 1.
`values[].custom_field_id`	integer	Always	The positive numeric ID of the custom-field definition. Minimum: 1.
`values[].value`	any	Optional	The stored field value. Its type depends on field_type.
`values[].created_at`	string (RFC 3339)	Always	The initial value storage time.
`values[].updated_at`	string (RFC 3339)	Always	The time of the latest value change.

Errors and recovery (7)

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

DELETE`/api/v1/incidents/{id}/custom-fields/{fieldId}`Unset one incident custom-field value

Removes one stored custom-field value from an incident. A required field cannot be unset. If the incident has no stored value, the request still succeeds without a change.

Operation ID: unsetIncidentCustomFieldValue
Scope: custom_fields:write
Prerequisites: Active responder seat Incident is not archived
Retry guidance: Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance. Retry rules

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request DELETE \
  --url 'https://{company}.api.tellagen.com/api/v1/incidents/{id}/custom-fields/{fieldId}' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns all remaining custom-field values for the incident.

Success response JSON

json

{
  "values": [
    {
      "id": 2,
      "incident_id": 1,
      "custom_field_id": 51,
      "value": "enterprise",
      "created_at": "2025-01-30T12:10:00Z",
      "updated_at": "2025-01-30T12:10:00Z"
    }
  ]
}

Request and response contract

Path parameters

Nested fields apply when their parent is supplied. Optional does not imply nullable. Read each field’s clearing rules.

Path parameters
Field	Type	Required	Description
`id`	integer	Yes	A positive numeric incident ID returned by this API. The permanent incident reference is suitable for stored references and external links. Minimum: 1.
`fieldId`	integer	Yes	A positive numeric custom-field ID returned by this API. Minimum: 1.

Response `200`

Returns all remaining custom-field values for the incident.

Always means present when the parent object exists. A present field can be null. Child fields apply to each array item.

Response fields
Field	Type	Returned	Description
`values`	object[]	Always	All current custom-field values for the incident.
`values[].id`	integer	Always	The positive numeric ID of the stored value. Minimum: 1.
`values[].incident_id`	integer	Always	The positive numeric ID of the incident. Minimum: 1.
`values[].custom_field_id`	integer	Always	The positive numeric ID of the custom-field definition. Minimum: 1.
`values[].value`	any	Optional	The stored field value. Its type depends on field_type.
`values[].created_at`	string (RFC 3339)	Always	The initial value storage time.
`values[].updated_at`	string (RFC 3339)	Always	The time of the latest value change.

Errors and recovery (7)

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

Read this resource as Markdown · OpenAPI contract

Custom Fields

GET/api/v1/custom-fieldsList custom fields

Example request

Success: 200

Query parameters

Response 200

Error responses (7)

POST/api/v1/custom-fieldsCreate custom field

Example request

Success: 201

Request body

Response 201

Response headers

Error responses (7)

GET/api/v1/custom-fields/{id}Get custom field

Example request

Success: 200

Path parameters

Response 200

Response headers

Error responses (7)

PATCH/api/v1/custom-fields/{id}Update custom field

Example request

Success: 200

Path parameters

Request headers

Request body

Response 200

Response headers

Error responses (9)

DELETE/api/v1/custom-fields/{id}Archive custom field

Example request

Success: 204

Path parameters

Error responses (7)

POST/api/v1/custom-fields/{id}/restoreRestore custom field

Example request

Success: 200

Path parameters

Response 200

Response headers

Error responses (7)

GET/api/v1/incidents/{id}/custom-fieldsList incident custom-field values

Example request

Success: 200

Path parameters

Query parameters

Response 200

Error responses (7)

PATCH/api/v1/incidents/{id}/custom-fieldsPartially update incident custom-field values

Example request

Success: 200

Path parameters

Request body

Response 200

Error responses (7)

DELETE/api/v1/incidents/{id}/custom-fields/{fieldId}Unset one incident custom-field value

Example request

Success: 200

Path parameters

Response 200

Error responses (7)

GET`/api/v1/custom-fields`List custom fields

Response `200`

POST`/api/v1/custom-fields`Create custom field

Response `201`

GET`/api/v1/custom-fields/{id}`Get custom field

Response `200`

PATCH`/api/v1/custom-fields/{id}`Update custom field

Response `200`

DELETE`/api/v1/custom-fields/{id}`Archive custom field

POST`/api/v1/custom-fields/{id}/restore`Restore custom field

Response `200`

GET`/api/v1/incidents/{id}/custom-fields`List incident custom-field values

Response `200`

PATCH`/api/v1/incidents/{id}/custom-fields`Partially update incident custom-field values

Response `200`

DELETE`/api/v1/incidents/{id}/custom-fields/{fieldId}`Unset one incident custom-field value

Response `200`