API ReferenceCustom Fields

Custom Fields

Manages custom-field definitions and their values on incidents.

Search API docsAll documentation

Search all guides and API reference text. Method and scope filter endpoints only.

MethodScope

Endpoints

List custom fields

GET/api/v1/custom-fields

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

Required scope: custom_fields:read

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"
  }
}

Parameters, headers, and fields

Operation ID: listCustomFields

Query parameters

Query parameters
Field	Description
`limit` integer Optional	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 Optional	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 Optional	Controls whether the response includes archived custom fields. The default is false. Default: false.

Response `200`

Returns custom-field definitions and pagination fields.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

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

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Create custom field

POST/api/v1/custom-fields

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.

Required scope: custom_fields:write
Also required: Active responder seat Manage workspace settings

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"
  }
}

Parameters, headers, and fields

Operation ID: createCustomField

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`name` string Required	The field name. The length must be from 1 through 64 characters. Minimum length: 1 characters. · Maximum length: 64 characters.
`slug` string Optional	A permanent URL-safe key. If the request omits slug, the API creates it from name.
`field_type` string Required	The value type. Allowed values: `"string""number""boolean""date""time""datetime""monetary""json""select""multi_select"`
`description` string Optional	The workspace description of the custom field.
`default_value` any Optional	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 Optional	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 Optional	The workspace category. Allowed values: `"context""impact""analysis""external""custom"`
`visibility_level` string Optional	The display prominence. Allowed values: `"always""prominent""standard""collapsed"`
`show_on_creation` boolean Optional	Controls whether the incident creation form shows this field.
`required_on_creation` boolean Optional	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 Optional	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 returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

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

Response headers

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

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Get custom field

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

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

Required scope: custom_fields:read

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"
  }
}

Parameters, headers, and fields

Operation ID: getCustomField

Path parameters

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

Response `200`

Returns the custom-field definition.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

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

Response headers

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

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Update custom field

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

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.

Required scope: custom_fields:write
Also required: Active responder seat Manage workspace settings

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"
  }
}

Parameters, headers, and fields

Operation ID: updateCustomField

Path parameters

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

Request headers

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

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

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

Response `200`

Returns the updated custom-field definition.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

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

Response headers

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

Errors and recovery (9)

If the API returns 412, read the resource again. Compare the latest changes before you retry with the new version. Retries and updates

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Archive custom field

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

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.

Required scope: custom_fields:write
Also required: Active responder seat Manage workspace settings

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.

Parameters, headers, and fields

Operation ID: archiveCustomField

Path parameters

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

Returns 204 with no body.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Restore custom field

POST/api/v1/custom-fields/{id}/restore

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.

Required scope: custom_fields:write
Also required: Active responder seat Manage workspace settings

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"
  }
}

Parameters, headers, and fields

Operation ID: restoreCustomField

Path parameters

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

Response `200`

Returns the complete active custom-field definition.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

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

Response headers

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

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

List incident custom-field values

GET/api/v1/incidents/{id}/custom-fields

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.

Required scope: custom_fields:read

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
  }
}

Parameters, headers, and fields

Operation ID: listIncidentCustomFieldValues

Path parameters

Path parameters
Field	Description
`id` integer Required	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

Query parameters
Field	Description
`limit` integer Optional	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 Optional	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 returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

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

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Partially update incident custom-field values

PATCH/api/v1/incidents/{id}/custom-fields

Updates the incident custom fields that you send. The values array needs at least one { field_id, value } item. Each value must match its field type and configuration. A required field rejects JSON null.

Omitted fields keep their values. Identical values leave timestamps, severity, events, and changelog unchanged.

API v1 also accepts PUT for this path. PUT is deprecated and the next major version will remove it.

Required scope: custom_fields:write
Also required: Active responder seat Incident is not archived

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"
    }
  ]
}

Parameters, headers, and fields

Operation ID: updateIncidentCustomFieldValues

Path parameters

Path parameters
Field	Description
`id` integer Required	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

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`values` object[] Required	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 Required	The positive ID of the custom-field definition. Minimum: 1.
`values[].value` any Required	The new field value. Its type must match field_type.

Response `200`

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

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

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

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Unset one incident custom-field value

DELETE/api/v1/incidents/{id}/custom-fields/{fieldId}

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.

Required scope: custom_fields:write
Also required: Active responder seat Incident is not archived

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"
    }
  ]
}

Parameters, headers, and fields

Operation ID: unsetIncidentCustomFieldValue

Path parameters

Path parameters
Field	Description
`id` integer Required	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 Required	A positive numeric custom-field ID returned by this API. Minimum: 1.

Response `200`

Returns all remaining custom-field values for the incident.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

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

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

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 request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Read this resource as Markdown · OpenAPI specification

Custom Fields

Endpoints

List custom fields

Example request

Success: 200

Query parameters

Response 200

Error responses (7)

Create custom field

Example request

Success: 201

Request body

Response 201

Response headers

Error responses (7)

Get custom field

Example request

Success: 200

Path parameters

Response 200

Response headers

Error responses (7)

Update custom field

Example request

Success: 200

Path parameters

Request headers

Request body

Response 200

Response headers

Error responses (9)

Archive custom field

Example request

Success: 204

Path parameters

Error responses (7)

Restore custom field

Example request

Success: 200

Path parameters

Response 200

Response headers

Error responses (7)

List incident custom-field values

Example request

Success: 200

Path parameters

Query parameters

Response 200

Error responses (7)

Partially update incident custom-field values

Example request

Success: 200

Path parameters

Request body

Response 200

Error responses (7)

Unset one incident custom-field value

Example request

Success: 200

Path parameters

Response 200

Error responses (7)

Response `200`

Response `201`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`