API ReferenceServices

Services

Manages the service catalog. Create, update, archive, and restore operations require the manage_settings permission. Archived services remain available by ID and retain incident references. They are read-only and absent from default lists.

Search API docsAll documentation

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

MethodScope

Endpoints

List services

GET/api/v1/services

Returns one page sorted by configured tier rank, normalized service name, and service ID. The first page includes up to 100 historical service values from incidents that do not match a catalog service. These values are sorted by incident count. Later pages return an empty unmanaged_references array. If more than 100 unmatched values exist, unmanaged_references_truncated is true.

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/services' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns services, unmanaged incident references, and pagination fields.

Success response JSON

json

{
  "services": [
    {
      "id": 5,
      "revision": 3,
      "company_id": 12,
      "name": "Payment Service",
      "slug": "payment_service",
      "description": "Handles all payment processing",
      "owner_team_id": 42,
      "owner_team_name": "Platform Team",
      "owner_team_slug": "platform_team",
      "tier": "critical",
      "tags": [
        "critical",
        "payments"
      ],
      "external_id": "payments-prod",
      "observability_names": [
        "payments-api",
        "payments-worker"
      ],
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:00:00Z"
    }
  ],
  "unmanaged_references": [
    {
      "value": "Legacy Billing",
      "incident_count": 3
    }
  ],
  "unmanaged_references_truncated": false,
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "opaque-server-cursor"
  }
}

Parameters, headers, and fields

Operation ID: listServices

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 services. The default is false. Default: false.

Response `200`

Returns services, unmanaged incident references, 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
`services` object[] Always returned	The services in this page.
`services[].id` integer Always returned	The positive numeric ID of the service.
`services[].revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`services[].company_id` integer Always returned	The ID of the workspace that owns the service.
`services[].name` string Always returned	The service name after whitespace is removed from both ends. The length is measured in Unicode code points. Minimum length: 1 characters. · Maximum length: 128 characters.
`services[].slug` string Always returned	A permanent lowercase service key. It starts with a Unicode letter and then contains lowercase Unicode letters, digits, or underscores. The maximum size is 64 UTF-8 bytes.
`services[].description` string Sometimes returned	The workspace description of the service.
`services[].owner_team_id` integer Sometimes returned	The positive numeric ID of the owning team. A service without an owning team omits this field.
`services[].owner_team_name` string Sometimes returned	The display name of the owning team. A service without an owning team omits this field.
`services[].owner_team_slug` string Sometimes returned	The permanent key of the owning team. A service without an owning team omits this field.
`services[].tier` string Always returned	The service-tier key from the workspace configuration.
`services[].tags` string[] Always returned	The normalized service tags.
`services[].external_id` string Sometimes returned	The service identifier from an external system.
`services[].observability_names` string[] Sometimes returned	Alternative service names for telemetry systems. The API trims values and removes case-insensitive duplicates.
`services[].created_at` string (RFC 3339) Always returned	The service creation time.
`services[].updated_at` string (RFC 3339) Always returned	The time of the latest service change.
`services[].archived_at` string (RFC 3339) Sometimes returned	The service archive time. This field is absent for an active service.
`unmanaged_references` object[] Always returned	Up to 100 historical incident service values that do not match a catalog service. Later pages return an empty array. Maximum items: 100.
`unmanaged_references[].value` string Always returned	The unmatched service value stored on incidents.
`unmanaged_references[].incident_count` integer Always returned	The number of incidents that contain this value. Minimum: 1.
`unmanaged_references_truncated` boolean Always returned	Indicates whether more than 100 unmatched values exist. This value is false on later pages.
`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 service

POST/api/v1/services

Creates a service. If slug is omitted, the API creates a lowercase slug with underscores. A supplied tier must match a key in the workspace tier configuration. If tier is omitted, the API uses the default tier.

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

Example request

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

For <idempotency-key>, choose a unique key on the first attempt. Reuse it only when retrying the identical request.

bash

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/services' \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Payment Service",
  "tier": "critical",
  "tags": [
    "critical",
    "payments"
  ],
  "external_id": "payments-prod",
  "observability_names": [
    "payments-api",
    "payments-worker"
  ]
}'

Success: 201

Returns the created service.

Success response JSON

json

{
  "service": {
    "id": 5,
    "revision": 3,
    "company_id": 12,
    "name": "Payment Service",
    "slug": "payment_service",
    "description": "Handles all payment processing",
    "owner_team_id": 42,
    "owner_team_name": "Platform Team",
    "owner_team_slug": "platform_team",
    "tier": "critical",
    "tags": [
      "critical",
      "payments"
    ],
    "external_id": "payments-prod",
    "observability_names": [
      "payments-api",
      "payments-worker"
    ],
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Related operations: List available service tiers

Parameters, headers, and fields

Operation ID: createService

Request headers

Request headers
Field	Description
`Idempotency-Key` string Optional	A key for safe retries of a create request. It must contain 1–128 visible, non-space ASCII characters. The same key applies only to an identical request. Minimum length: 1 characters. · Maximum length: 128 characters. · Pattern: ^[\x21-\x7E]+$.

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 service name. The length must be from 1 through 128 Unicode characters. Minimum length: 1 characters. · Maximum length: 128 characters.
`slug` string Optional	A permanent lowercase service key. It must start with a Unicode letter and use at most 64 UTF-8 bytes. Later characters can be lowercase Unicode letters, digits, or underscores.
`description` string Optional	The workspace description of the service.
`owner_team_id` integer Optional	The positive ID of an active owning team. Minimum: 1.
`tier` string Optional	A service-tier key from the workspace configuration. If tier is omitted, the API uses the configured default tier.
`tags` string[] Optional	The service tags. The API trims each value and removes blank values.
`external_id` string Optional	The service identifier from an external system. The API removes whitespace from both ends.
`observability_names` string[] Optional	Alternative service names for telemetry systems. The API trims values and removes case-insensitive duplicates.

Response `201`

Returns the created service.

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

Response fields
Field	Description
`service` object Always returned	The complete public record for a service.
`service.id` integer Always returned	The positive numeric ID of the service.
`service.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`service.company_id` integer Always returned	The ID of the workspace that owns the service.
`service.name` string Always returned	The service name after whitespace is removed from both ends. The length is measured in Unicode code points. Minimum length: 1 characters. · Maximum length: 128 characters.
`service.slug` string Always returned	A permanent lowercase service key. It starts with a Unicode letter and then contains lowercase Unicode letters, digits, or underscores. The maximum size is 64 UTF-8 bytes.
`service.description` string Sometimes returned	The workspace description of the service.
`service.owner_team_id` integer Sometimes returned	The positive numeric ID of the owning team. A service without an owning team omits this field.
`service.owner_team_name` string Sometimes returned	The display name of the owning team. A service without an owning team omits this field.
`service.owner_team_slug` string Sometimes returned	The permanent key of the owning team. A service without an owning team omits this field.
`service.tier` string Always returned	The service-tier key from the workspace configuration.
`service.tags` string[] Always returned	The normalized service tags.
`service.external_id` string Sometimes returned	The service identifier from an external system.
`service.observability_names` string[] Sometimes returned	Alternative service names for telemetry systems. The API trims values and removes case-insensitive duplicates.
`service.created_at` string (RFC 3339) Always returned	The service creation time.
`service.updated_at` string (RFC 3339) Always returned	The time of the latest service change.
`service.archived_at` string (RFC 3339) Sometimes returned	The service archive time. This field is absent for an active service.

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)

Within 24 hours, retry with the original Idempotency-Key and identical body. If the result is unknown, do not retry automatically. Check whether the resource exists. 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.

idempotency_key_reused idempotency_in_progress idempotency_outcome_unknown

Get service

GET/api/v1/services/{id}

Returns one service. The response contains the same service fields as the list operation. A service remains available by ID after it is archived.

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/services/{id}' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns the service.

Success response JSON

json

{
  "service": {
    "id": 5,
    "revision": 3,
    "company_id": 12,
    "name": "Payment Service",
    "slug": "payment_service",
    "description": "Handles all payment processing",
    "owner_team_id": 42,
    "owner_team_name": "Platform Team",
    "owner_team_slug": "platform_team",
    "tier": "critical",
    "tags": [
      "critical",
      "payments"
    ],
    "external_id": "payments-prod",
    "observability_names": [
      "payments-api",
      "payments-worker"
    ],
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Parameters, headers, and fields

Operation ID: getService

Path parameters

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

Response `200`

Returns the service.

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

Response fields
Field	Description
`service` object Always returned	The complete public record for a service.
`service.id` integer Always returned	The positive numeric ID of the service.
`service.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`service.company_id` integer Always returned	The ID of the workspace that owns the service.
`service.name` string Always returned	The service name after whitespace is removed from both ends. The length is measured in Unicode code points. Minimum length: 1 characters. · Maximum length: 128 characters.
`service.slug` string Always returned	A permanent lowercase service key. It starts with a Unicode letter and then contains lowercase Unicode letters, digits, or underscores. The maximum size is 64 UTF-8 bytes.
`service.description` string Sometimes returned	The workspace description of the service.
`service.owner_team_id` integer Sometimes returned	The positive numeric ID of the owning team. A service without an owning team omits this field.
`service.owner_team_name` string Sometimes returned	The display name of the owning team. A service without an owning team omits this field.
`service.owner_team_slug` string Sometimes returned	The permanent key of the owning team. A service without an owning team omits this field.
`service.tier` string Always returned	The service-tier key from the workspace configuration.
`service.tags` string[] Always returned	The normalized service tags.
`service.external_id` string Sometimes returned	The service identifier from an external system.
`service.observability_names` string[] Sometimes returned	Alternative service names for telemetry systems. The API trims values and removes case-insensitive duplicates.
`service.created_at` string (RFC 3339) Always returned	The service creation time.
`service.updated_at` string (RFC 3339) Always returned	The time of the latest service change.
`service.archived_at` string (RFC 3339) Sometimes returned	The service archive time. This field is absent for an active service.

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 service

PATCH/api/v1/services/{id}

Updates an active service. If a field is omitted, its current value remains unchanged. JSON null clears description, owner_team_id, or external_id. An empty tags or observability_names array removes all values from that field. The slug cannot change. An archived service returns 409.

Required scope: services: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/services/{id}' \
  --header 'Authorization: Bearer <token>' \
  --header 'If-Tellagen-Resource-Version: <resource-version>' \
  --header 'Content-Type: application/json' \
  --data '{
  "tier": "important",
  "tags": [],
  "external_id": null,
  "observability_names": [
    "payments-v2"
  ]
}'

Success: 200

Returns the updated service.

Success response JSON

json

{
  "service": {
    "id": 5,
    "revision": 3,
    "company_id": 12,
    "name": "Payment Service",
    "slug": "payment_service",
    "description": "Handles all payment processing",
    "owner_team_id": 42,
    "owner_team_name": "Platform Team",
    "owner_team_slug": "platform_team",
    "tier": "important",
    "tags": [],
    "external_id": "payments-prod",
    "observability_names": [
      "payments-v2"
    ],
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-30T12:00:00Z"
  }
}

Parameters, headers, and fields

Operation ID: updateService

Path parameters

Path parameters
Field	Description
`id` integer Required	A positive numeric service 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 service name. The length must be from 1 through 128 Unicode characters. Minimum length: 1 characters. · Maximum length: 128 characters.
`description` string \| null Optional	The replacement service description. A null value removes the description.
`owner_team_id` integer \| null Optional	The positive ID of an active owning team. A null value removes team ownership. Minimum: 1.
`tier` string Optional	A service-tier key from the workspace configuration.
`tags` string[] Optional	The complete replacement list of tags. An empty array removes all tags.
`external_id` string \| null Optional	The replacement external identifier. A null or blank value removes the identifier.
`observability_names` string[] Optional	The complete replacement list of telemetry names. An empty array removes all telemetry names.

Response `200`

Returns the updated service.

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

Response fields
Field	Description
`service` object Always returned	The complete public record for a service.
`service.id` integer Always returned	The positive numeric ID of the service.
`service.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`service.company_id` integer Always returned	The ID of the workspace that owns the service.
`service.name` string Always returned	The service name after whitespace is removed from both ends. The length is measured in Unicode code points. Minimum length: 1 characters. · Maximum length: 128 characters.
`service.slug` string Always returned	A permanent lowercase service key. It starts with a Unicode letter and then contains lowercase Unicode letters, digits, or underscores. The maximum size is 64 UTF-8 bytes.
`service.description` string Sometimes returned	The workspace description of the service.
`service.owner_team_id` integer Sometimes returned	The positive numeric ID of the owning team. A service without an owning team omits this field.
`service.owner_team_name` string Sometimes returned	The display name of the owning team. A service without an owning team omits this field.
`service.owner_team_slug` string Sometimes returned	The permanent key of the owning team. A service without an owning team omits this field.
`service.tier` string Always returned	The service-tier key from the workspace configuration.
`service.tags` string[] Always returned	The normalized service tags.
`service.external_id` string Sometimes returned	The service identifier from an external system.
`service.observability_names` string[] Sometimes returned	Alternative service names for telemetry systems. The API trims values and removes case-insensitive duplicates.
`service.created_at` string (RFC 3339) Always returned	The service creation time.
`service.updated_at` string (RFC 3339) Always returned	The time of the latest service change.
`service.archived_at` string (RFC 3339) Sometimes returned	The service archive time. This field is absent for an active service.

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 service

DELETE/api/v1/services/{id}

Archives a service. A repeated request returns 204 without changing the archive time or resource version. By default, list operations exclude archived services. The include_archived=true parameter includes them. Archived services remain available by ID and retain incident references. They cannot be updated.

Required scope: services: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/services/{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: archiveService

Path parameters

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

POST/api/v1/services/{id}/restore

Restores an archived service and returns the active service. A repeated request returns the active service without changing its resource version. If the service has owner_team_id, that team must be active. Otherwise, the API returns 409 invalid_relationship_state.

Required scope: services: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/services/{id}/restore' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns the complete active service.

Success response JSON

json

{
  "service": {
    "id": 5,
    "revision": 3,
    "company_id": 12,
    "name": "Payment Service",
    "slug": "payment_service",
    "description": "Handles all payment processing",
    "owner_team_id": 42,
    "owner_team_name": "Platform Team",
    "owner_team_slug": "platform_team",
    "tier": "critical",
    "tags": [
      "critical",
      "payments"
    ],
    "external_id": "payments-prod",
    "observability_names": [
      "payments-api",
      "payments-worker"
    ],
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Parameters, headers, and fields

Operation ID: restoreService

Path parameters

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

Response `200`

Returns the complete active service.

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

Response fields
Field	Description
`service` object Always returned	The complete public record for a service.
`service.id` integer Always returned	The positive numeric ID of the service.
`service.revision` integer Always returned	The resource version for concurrency control. Minimum: 1.
`service.company_id` integer Always returned	The ID of the workspace that owns the service.
`service.name` string Always returned	The service name after whitespace is removed from both ends. The length is measured in Unicode code points. Minimum length: 1 characters. · Maximum length: 128 characters.
`service.slug` string Always returned	A permanent lowercase service key. It starts with a Unicode letter and then contains lowercase Unicode letters, digits, or underscores. The maximum size is 64 UTF-8 bytes.
`service.description` string Sometimes returned	The workspace description of the service.
`service.owner_team_id` integer Sometimes returned	The positive numeric ID of the owning team. A service without an owning team omits this field.
`service.owner_team_name` string Sometimes returned	The display name of the owning team. A service without an owning team omits this field.
`service.owner_team_slug` string Sometimes returned	The permanent key of the owning team. A service without an owning team omits this field.
`service.tier` string Always returned	The service-tier key from the workspace configuration.
`service.tags` string[] Always returned	The normalized service tags.
`service.external_id` string Sometimes returned	The service identifier from an external system.
`service.observability_names` string[] Sometimes returned	Alternative service names for telemetry systems. The API trims values and removes case-insensitive duplicates.
`service.created_at` string (RFC 3339) Always returned	The service creation time.
`service.updated_at` string (RFC 3339) Always returned	The time of the latest service change.
`service.archived_at` string (RFC 3339) Sometimes returned	The service archive time. This field is absent for an active service.

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.

invalid_relationship_state

Read this resource as Markdown · OpenAPI specification

Services

Endpoints

List services

Example request

Success: 200

Query parameters

Response 200

Error responses (7)

Create service

Example request

Success: 201

Request headers

Request body

Response 201

Response headers

Error responses (7)

Get service

Example request

Success: 200

Path parameters

Response 200

Response headers

Error responses (7)

Update service

Example request

Success: 200

Path parameters

Request headers

Request body

Response 200

Response headers

Error responses (9)

Archive service

Example request

Success: 204

Path parameters

Error responses (7)

Restore service

Example request

Success: 200

Path parameters

Response 200

Response headers

Error responses (7)

Response `200`

Response `201`

Response `200`

Response `200`

Response `200`