# Tellagen API Reference

> Generated from the same canonical API contract as the human-readable reference at https://tellagen.com/api-reference.

Documentation contract: `sha256:898ee484330817a84c170e0e87bf24f27e62e5838635ee4c9daf6a7a3d704ce9`. This fingerprint identifies the generated documentation contract, not the API major version.

## Endpoint index

### Custom Fields

[Custom Fields Markdown export](https://tellagen.com/api-reference/custom-fields/markdown)

- [`GET /api/v1/custom-fields`](https://tellagen.com/api-reference/custom-fields#custom-fields-endpoint-get-api-v1-custom-fields) — List custom fields
- [`POST /api/v1/custom-fields`](https://tellagen.com/api-reference/custom-fields#custom-fields-endpoint-post-api-v1-custom-fields) — Create custom field
- [`GET /api/v1/custom-fields/{id}`](https://tellagen.com/api-reference/custom-fields#custom-fields-endpoint-get-api-v1-custom-fields-id) — Get custom field
- [`PATCH /api/v1/custom-fields/{id}`](https://tellagen.com/api-reference/custom-fields#custom-fields-endpoint-patch-api-v1-custom-fields-id) — Update custom field
- [`DELETE /api/v1/custom-fields/{id}`](https://tellagen.com/api-reference/custom-fields#custom-fields-endpoint-delete-api-v1-custom-fields-id) — Archive custom field
- [`POST /api/v1/custom-fields/{id}/restore`](https://tellagen.com/api-reference/custom-fields#custom-fields-endpoint-post-api-v1-custom-fields-id-restore) — Restore custom field
- [`GET /api/v1/incidents/{id}/custom-fields`](https://tellagen.com/api-reference/custom-fields#custom-fields-endpoint-get-api-v1-incidents-id-custom-fields) — List incident custom-field values
- [`PATCH /api/v1/incidents/{id}/custom-fields`](https://tellagen.com/api-reference/custom-fields#custom-fields-endpoint-patch-api-v1-incidents-id-custom-fields) — Partially update incident custom-field values
- [`DELETE /api/v1/incidents/{id}/custom-fields/{fieldId}`](https://tellagen.com/api-reference/custom-fields#custom-fields-endpoint-delete-api-v1-incidents-id-custom-fields-fieldid) — Unset one incident custom-field value

## Base URL

`https://{company}.api.tellagen.com/api/v1/`

Replace `{company}` with your company subdomain. Requests and JSON responses use `application/json` unless an endpoint documents an empty response.

## Authentication

Create an API token in **Settings > API keys** and send it as a Bearer token:

`Authorization: Bearer tllg_YOUR_TOKEN`

Tokens are shown only once when created. Grant only the scopes the client needs.

## Integration guides

- [Make your first request](https://tellagen.com/api-reference#first-request)
- [Build reliable requests](https://tellagen.com/api-reference#reliable-requests)
- [Filter and paginate collections](https://tellagen.com/api-reference/guides/pagination)
- [Create and move an incident through its workflow](https://tellagen.com/api-reference/guides/workflows)
- [Send custom-field values](https://tellagen.com/api-reference/guides/field-values)

## Versioning

All endpoints in this reference use `/api/v1` and are supported.

**Compatible changes.** Tellagen can add optional response fields or enum values. Ignore response fields that your client does not use.

**Breaking changes.** Tellagen uses a new major version for incompatible changes.

**Deprecated endpoints.** Tellagen marks an endpoint deprecated at least 180 days before removal. Deprecated responses identify the replacement endpoint.

## Scopes

| Scope | Description |
| --- | --- |
| `incidents:read` | List and retrieve incidents, and discover writable workflow statuses and severities |
| `incidents:write` | Create and update incidents and timeline events. Requires an active responder seat for the key owner. |
| `slack_context:read` | Read Slack context collected for incident investigation |
| `services:read` | List and retrieve services, and discover writable service tiers |
| `services:write` | Create, update, and archive services. Requires an active responder seat and the manage_settings role permission. |
| `teams:read` | List and retrieve teams and members |
| `teams:write` | Create, update, and archive teams; manage members. Requires an active responder seat and the manage_teams role permission. |
| `custom_fields:read` | List and retrieve custom field definitions and values |
| `custom_fields:write` | Create, update, and archive custom fields; set incident field values. Definition changes require the manage_settings role permission. Incident value changes require an active responder seat. |

## Prerequisite definitions

- **Active responder seat** (`active_responder`): The API key owner must have an active responder seat.
- **Manage workspace settings** (`manage_settings`): The API key owner must have the manage_settings role permission.
- **Manage teams** (`manage_teams`): The API key owner must have the manage_teams role permission.
- **Incident is not archived** (`mutable_incident`): The incident must not be archived. Workflow-state restrictions are described by each operation.
- **Linked Slack channel** (`slack_channel`): The incident must have a linked Slack channel.

## Errors

Errors always include a stable `code` and a human-readable `message`. They can also include `field`, `details`, and `request_id`.

You can send `X-Request-ID` with a request. If you omit it, the API generates one. The response header and error body return the same value.

### Missing scope (403)

```json
{
  "code": "missing_scope",
  "message": "insufficient scope: incidents:write required",
  "details": {
    "required_scope": "incidents:write"
  },
  "request_id": "01JEXAMPLE8R4N5W6Y7Z"
}
```

### Stale resource version (412)

```json
{
  "code": "precondition_failed",
  "message": "the resource changed; fetch it again and retry with the current resource version",
  "field": "If-Tellagen-Resource-Version",
  "request_id": "01JEXAMPLE8R4N5W6Y7Z"
}
```

### Rate limit (429)

```json
{
  "code": "rate_limited",
  "message": "rate limit exceeded",
  "details": {
    "retry_after_seconds": 1
  },
  "request_id": "01JEXAMPLE8R4N5W6Y7Z"
}
```

When you contact support, include the request ID, method, path, status, and time. Omit tokens and private request bodies.

| Code | Meaning | Next action | Retry |
| --- | --- | --- | --- |
| `authentication_required` | The request has no valid API token or session. | Send an active Bearer token for this workspace. Replace an expired or revoked key. | After correcting authentication. |
| `missing_scope` | The token lacks the scope named in details.required_scope. | Read details.required_scope. Ask a workspace manager for a replacement key with that scope. | After correcting access. |
| `responder_seat_required` | The key owner needs the seat named in details.required_seat. | Ask a workspace manager to review the key owner’s responder seat. | After correcting access. |
| `missing_role_permission` | The key owner lacks details.required_permission or one of details.required_roles. | Ask a workspace manager to review the owner’s role and the permission named in details. | After correcting access. |
| `permission_denied` | Access is denied without exposing private authorization state. | Verify the workspace, key owner, and resource access with a workspace manager. | After correcting access. |
| `invalid_resource_state` | The operation is not valid for the current resource state. | Read the current resource. Restore an archived resource or choose an operation allowed in its current state. | After reconciling state. |
| `invalid_relationship_state` | Restore requires a retained owner or parent relationship to identify an active resource. | Restore the retained parent or owning team before restoring this resource. | After correcting the relationship. |
| `duplicate_slug` | A team already uses the requested slug. | Read the existing team or choose a different slug. | After changing the request. |
| `invalid_json` | The request body is not one valid JSON document. | Send one valid JSON object with Content-Type: application/json. | After correcting the body. |
| `unknown_field` | The request contains an unsupported JSON property named in field. | Remove or correct the property named in field. Use the request schema, not the response schema. | After correcting the body. |
| `request_body_too_large` | The request body is larger than 1 MiB. | Reduce the body to 1 MiB or less. | After reducing the body. |
| `multiple_json_values` | The request body contains more than one JSON document. | Send one JSON document rather than concatenated documents. | After correcting the body. |
| `idempotency_key_reused` | The key was already used with different request content. | Recover the original request for this key. Use a new key only for a different intended operation. | Do not resend changed content with the same key. |
| `idempotency_in_progress` | An equal request with this key is still running. Retry later. | Wait for Retry-After, then resend the identical body with the same key. | After the indicated delay. |
| `idempotency_outcome_unknown` | An earlier request may have completed, but its result could not be stored. Do not retry it automatically. | Read the resource state and contact support with the request ID before deciding whether to create again. | Never retry automatically. |
| `precondition_required` | An API-key PATCH request omitted If-Tellagen-Resource-Version. | Read the resource, then send its Tellagen-Resource-Version as If-Tellagen-Resource-Version. | After adding the current version. |
| `invalid_precondition` | If-Tellagen-Resource-Version is not a positive integer. | Use the positive integer version returned for this resource. Do not use an ETag or a timestamp. | After correcting the header. |
| `precondition_failed` | The resource changed after the client read it. | Read the resource again. Reconcile your intended change with the current state before using its new version. | After reconciling the change. |
| `rate_limited` | Retry after details.retry_after_seconds or the Retry-After header. | Wait for Retry-After or details.retry_after_seconds. Limit concurrency across the workspace. | After the indicated delay, with the original idempotency key where supported. |
| `internal` | The server failed without exposing an internal error. | Keep the request ID. Read current state before retrying a write whose outcome is uncertain. | Retry reads with bounded backoff. Follow operation-specific rules for writes. |
| `invalid_slack_channel_name_request` | The channel-name request is invalid. | Use custom mode with name, or workspace_template mode without name. | After correcting the request. |
| `slack_not_configured` | The workspace has no usable Slack integration. | Ask a workspace manager to connect or repair Slack. | After repairing the integration. |
| `incident_slack_channel_missing` | The incident has no linked Slack channel. | Link a channel through the incident workspace before requesting a rename. | After linking a channel. |
| `slack_channel_not_found` | Slack cannot find the linked channel. | Verify the channel still exists and that the integration can access it. | After repairing channel access. |
| `slack_channel_name_taken` | Another Slack channel uses the requested name. | Choose another custom name or revise the workspace naming template. | After choosing an available name. |
| `invalid_idempotency_key` | The idempotency key has an invalid length or character. | Use 1–128 visible, non-space ASCII characters. A UUID is suitable. | After correcting the key. |

| Status | Meaning |
| --- | --- |
| `400` | Bad Request — invalid input or missing required fields |
| `401` | Unauthorized — missing or invalid token |
| `403` | Forbidden — insufficient scope or responder access |
| `404` | Not Found — resource does not exist |
| `409` | Conflict — resource state prevents the request |
| `412` | Precondition Failed — the supplied resource version is stale |
| `428` | Precondition Required — this operation needs If-Tellagen-Resource-Version |
| `429` | Too Many Requests — rate limit exceeded |
| `500` | Internal Server Error |

Authenticated requests share a workspace limit. Anonymous requests and failed authentication attempts use the trusted client IP. Responses include `X-RateLimit-Limit` and `X-RateLimit-Remaining`. A `429` response also includes `Retry-After`.

## 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.

Required scope: `custom_fields:read`

Operation ID: `listCustomFields`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: None

#### Query parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | 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. |

#### 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 response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

Returns custom-field definitions and pagination fields.

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

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `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.

Required scope: `custom_fields:write`

Operation ID: `createCustomField`
Contract: `supported`
Retry guidance: Do not retry automatically after an uncertain outcome. Read the resource state and follow this operation’s recovery guidance.
Prerequisites: 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
  }
}'
```

#### Request body

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | 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". |

Request JSON:

```json
{
  "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 response

Status: `201 Created`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

Returns the created custom-field definition.

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

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `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.

Required scope: `custom_fields:read`

Operation ID: `getCustomField`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: None

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

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

#### 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 response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

Returns the custom-field definition.

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

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `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.

Required scope: `custom_fields:write`

Operation ID: `updateCustomField`
Contract: `supported`
Retry guidance: Read the current resource and reconcile changes before retrying with its current version. A stale version returns 412.
Prerequisites: Active responder seat, Manage workspace settings

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

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

#### Request headers

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | 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. |

#### 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
}'
```

#### Request body

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | 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. |

Request JSON:

```json
{
  "required": true,
  "sort_order": 2
}
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

Returns the updated custom-field definition.

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

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `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.

Required scope: `custom_fields:write`

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

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

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

#### 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 response

Status: `204 No Content`

No response body.

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `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.

Required scope: `custom_fields:write`

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

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

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

#### 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 response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

Returns the complete active custom-field definition.

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

#### Response headers

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `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.

Required scope: `custom_fields:read`

Operation ID: `listIncidentCustomFieldValues`
Contract: `supported`
Retry guidance: This operation is repeat-safe. Respect Retry-After and use bounded retries.
Prerequisites: None

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

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

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | 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. |

#### 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 response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

Returns custom-field values and pagination fields.

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

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `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.

Required scope: `custom_fields:write`

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

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | 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. |

#### 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"
    }
  ]
}'
```

#### Request body

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | 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. |

Request JSON:

```json
{
  "values": [
    {
      "field_id": 50,
      "value": 1500
    },
    {
      "field_id": 51,
      "value": "enterprise"
    }
  ]
}
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

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

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

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `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.

Required scope: `custom_fields:write`

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

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | 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. |

#### 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 response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | 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. |

Returns all remaining custom-field values for the incident.

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

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `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. |