API ReferenceWritable configuration

Writable configuration

Lists the workspace-specific keys accepted by incident and service requests. These endpoints also identify the default status, severity, and service tier.

Search API docsAll documentation

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

MethodScope

Endpoints

List available workflow statuses

GET/api/v1/configuration/workflow-statuses

Returns the workflow statuses that incident requests can use. The response lists statuses in workflow order. Exactly one status has is_default set to true. If a create-incident request omits status, the API uses that status.

Required scope: incidents: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/configuration/workflow-statuses' \
  --header 'Authorization: Bearer <token>'

Success: 200

Each entry contains a status key, label, display order, default flag, lifecycle flags, and color.

Success response JSON

json

{
  "workflow_statuses": [
    {
      "key": "open",
      "label": "Open",
      "order": 0,
      "is_default": true,
      "is_terminal": false,
      "is_escalation_threshold": true,
      "color": "bg-amber-500"
    },
    {
      "key": "resolved",
      "label": "Resolved",
      "order": 1,
      "is_default": false,
      "is_terminal": true,
      "is_escalation_threshold": false,
      "color": "bg-moss"
    }
  ]
}

Parameters, headers, and fields

Operation ID: listWorkflowStatuses

Response `200`

Each entry contains a status key, label, display order, default flag, lifecycle flags, and color.

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

Response fields
Field	Description
`workflow_statuses` object[] Always returned	The workflow statuses in configured workflow order.
`workflow_statuses[].key` string Always returned	A workflow-status key accepted by incident requests.
`workflow_statuses[].label` string Always returned	The status name shown to users.
`workflow_statuses[].order` integer Always returned	The zero-based position of the status in the workflow. Minimum: 0.
`workflow_statuses[].is_default` boolean Always returned	Identifies the default workflow status for new incidents.
`workflow_statuses[].is_terminal` boolean Always returned	Indicates whether this status ends the active incident workflow.
`workflow_statuses[].is_escalation_threshold` boolean Always returned	Indicates whether this status is the configured escalation threshold.
`workflow_statuses[].color` string Always returned	The color class used to display the status (for example bg-amber-500).

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.

List available severities

GET/api/v1/configuration/severities

Returns the severity levels that incident requests can use. The response lists severities from the highest score threshold to the lowest. Exactly one severity has is_default set to true. If a create-incident request omits severity, the API uses that severity.

Required scope: incidents: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/configuration/severities' \
  --header 'Authorization: Bearer <token>'

Success: 200

Each entry contains a severity key, label, display order, default flag, score threshold, description, and color.

Success response JSON

json

{
  "severities": [
    {
      "key": "sev1",
      "label": "SEV1",
      "order": 0,
      "is_default": false,
      "min_score": 300,
      "description": "Critical - complete outage",
      "color": "ember"
    },
    {
      "key": "sev2",
      "label": "SEV2",
      "order": 1,
      "is_default": true,
      "min_score": 150,
      "description": "Major - degraded experience",
      "color": "amber-500"
    }
  ]
}

Parameters, headers, and fields

Operation ID: listSeverities

Response `200`

Each entry contains a severity key, label, display order, default flag, score threshold, description, and color.

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

Response fields
Field	Description
`severities` object[] Always returned	The severity levels from the highest score threshold to the lowest.
`severities[].key` string Always returned	A severity key accepted by incident requests.
`severities[].label` string Always returned	The severity name shown to users.
`severities[].order` integer Always returned	The zero-based position of the severity in the response. Minimum: 0.
`severities[].is_default` boolean Always returned	Identifies the default severity for new incidents.
`severities[].min_score` number Always returned	The minimum calculated score for this severity. Minimum: 0.
`severities[].description` string Always returned	The workspace description of this severity.
`severities[].color` string Always returned	The color token used to display the severity.

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.

List available service tiers

GET/api/v1/configuration/service-tiers

Returns the service tiers that service requests can use. The response lists tiers in configured rank order. Exactly one tier has is_default set to true. If a create-service request omits tier, the API uses that tier.

Required scope: services: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/configuration/service-tiers' \
  --header 'Authorization: Bearer <token>'

Success: 200

Each entry contains a tier key, label, display order, default flag, and description.

Success response JSON

json

{
  "service_tiers": [
    {
      "key": "t0",
      "label": "T0 - Mission Critical",
      "order": 0,
      "is_default": false,
      "description": "Mission critical"
    },
    {
      "key": "t2",
      "label": "T2 - Important",
      "order": 2,
      "is_default": true,
      "description": "Important"
    }
  ]
}

Parameters, headers, and fields

Operation ID: listServiceTiers

Response `200`

Each entry contains a tier key, label, display order, default flag, and description.

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

Response fields
Field	Description
`service_tiers` object[] Always returned	The service tiers in configured rank order.
`service_tiers[].key` string Always returned	A service-tier key accepted by service requests.
`service_tiers[].label` string Always returned	The tier name shown to users.
`service_tiers[].order` integer Always returned	The zero-based position of the tier in configured rank order. Minimum: 0.
`service_tiers[].is_default` boolean Always returned	Identifies the default tier for new services.
`service_tiers[].description` string Always returned	The workspace description of this service tier.

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.

Read this resource as Markdown · OpenAPI specification

Writable configuration

Endpoints

List available workflow statuses

Example request

Success: 200

Response 200

Error responses (7)

List available severities

Example request

Success: 200

Response 200

Error responses (7)

List available service tiers

Example request

Success: 200

Response 200

Error responses (7)

Response `200`

Response `200`

Response `200`