> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/developer-docs/rest-api/api-reference/services.md).
# Services
## GET /services
> Get services.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"Service":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"alias":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"description":{"type":"string"},"oneOpenIncidentOnly":{"type":"boolean"},"showUptimeHistory":{"type":"boolean"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}},"subscribed":{"type":"boolean","readOnly":true},"uptime":{"$ref":"#/components/schemas/ServiceUptime"},"managedBy":{"$ref":"#/components/schemas/ManagedBy"},"publicStatus":{"$ref":"#/components/schemas/ServiceStatus"},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Free-form key-value labels assigned to this service."},"iconUrl":{"type":"string"},"links":{"type":"array","items":{"$ref":"#/components/schemas/ServiceLink"}},"createdBy":{"$ref":"#/components/schemas/ManagedBy"},"dependencies":{"type":"array","items":{"$ref":"#/components/schemas/ServiceDependency"},"description":"This is an include field, it is not available in the list resource"}}},"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"ServiceUptime":{"type":"object","properties":{"rangeStart":{"type":"string","format":"date-time"},"rangeEnd":{"type":"string","format":"date-time"},"outages":{"type":"array","items":{"$ref":"#/components/schemas/ServiceOutage"}},"uptimePercentage":{"$ref":"#/components/schemas/ServiceUptimePercentage"}}},"ServiceOutage":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/ServiceStatus"},"from":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"}}},"ServiceUptimePercentage":{"type":"object","properties":{"uptimePercentage":{"type":"object","properties":{"p90":{"maximum":100,"minimum":0,"type":"number","format":"float","readOnly":true},"p60":{"maximum":100,"minimum":0,"type":"number","format":"float","readOnly":true},"p30":{"maximum":100,"minimum":0,"type":"number","format":"float","readOnly":true}}}}},"ManagedBy":{"type":"object","readOnly":true,"description":"Present when this entity is managed outside of the ilert web app, for example through Terraform, Pulumi or the API. Read-only.","properties":{"type":{"type":"string","enum":["API","TERRAFORM","PULUMI","ILERT"]},"source":{"type":"string","description":"Identifier of the system managing this entity."}}},"ServiceLink":{"type":"object","properties":{"href":{"type":"string","format":"uri"},"text":{"type":"string"}}},"ServiceDependency":{"type":"object","required":["targetServiceId"],"properties":{"id":{"type":"integer","format":"int64","readOnly":true},"sourceServiceId":{"type":"integer","format":"int64","description":"The service that depends on the target service."},"targetServiceId":{"type":"integer","format":"int64","description":"The service that is being depended upon."},"notes":{"type":"string"},"invalidAfter":{"type":"string","format":"date-time","description":"Point in time after which this dependency is no longer considered valid."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"$ref":"#/components/schemas/ManagedBy"},"managedBy":{"$ref":"#/components/schemas/ManagedBy"}}}}},"paths":{"/services":{"get":{"tags":["Services"],"summary":"Get services.","parameters":[{"name":"start-index","in":"query","description":"an integer specifying the starting point (beginning with 0) when paging through a list of entities","schema":{"type":"integer","format":"int32","default":0}},{"name":"max-results","in":"query","description":"the maximum number of results when paging through a list of services. (Note: when using ?include maximum is reduced to 25)","schema":{"maximum":100,"type":"integer","format":"int32","default":10}},{"name":"include","in":"query","description":"Describes optional properties that should be included in the response. You may declare multiple. (subscribed, uptime, links, dependencies, publicStatus)","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["subscribed","uptime","links","dependencies","publicStatus"]}}},{"name":"query","in":"query","description":"Free-text search on the name of the entity.","schema":{"type":"string"}},{"name":"labels","in":"query","description":"Filter by labels using a condition expression. Supports the operators `==`, `!=`, `in` and `not_in`, combined with `and` (up to 20 conditions). Values must be url-encoded. An invalid expression returns 400. Examples: `environment == 'production'`, `region in [\"us-east\", \"us-west\"]`, `environment == 'production' and severity != 'low'`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The services","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Service"}}}}}}}}}}
```
## POST /services
> Create a new service.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"ServiceNoIncludes":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"alias":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"description":{"type":"string"},"oneOpenIncidentOnly":{"type":"boolean"},"showUptimeHistory":{"type":"boolean"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}},"managedBy":{"$ref":"#/components/schemas/ManagedBy"},"publicStatus":{"$ref":"#/components/schemas/ServiceStatus"},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Free-form key-value labels assigned to this service."},"iconUrl":{"type":"string"},"links":{"type":"array","items":{"$ref":"#/components/schemas/ServiceLink"}},"createdBy":{"$ref":"#/components/schemas/ManagedBy"}}},"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"ManagedBy":{"type":"object","readOnly":true,"description":"Present when this entity is managed outside of the ilert web app, for example through Terraform, Pulumi or the API. Read-only.","properties":{"type":{"type":"string","enum":["API","TERRAFORM","PULUMI","ILERT"]},"source":{"type":"string","description":"Identifier of the system managing this entity."}}},"ServiceLink":{"type":"object","properties":{"href":{"type":"string","format":"uri"},"text":{"type":"string"}}}}},"paths":{"/services":{"post":{"tags":["Services"],"summary":"Create a new service.","requestBody":{"description":"the service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceNoIncludes"}}},"required":true},"responses":{"200":{"description":"The newly created service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceNoIncludes"}}}}}}}}}
```
## List the distinct label keys used by the services of this account.
> Fixed page size of 100. \`start-index\` must be 0 or a multiple of 100 and \`max-results\` must be 100; any other value returns 400.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"LabelKey":{"type":"object","properties":{"key":{"type":"string"}}}}},"paths":{"/services/labels":{"get":{"tags":["Services"],"summary":"List the distinct label keys used by the services of this account.","description":"Fixed page size of 100. `start-index` must be 0 or a multiple of 100 and `max-results` must be 100; any other value returns 400.","parameters":[{"name":"query","in":"query","description":"Filter the returned label keys by prefix.","schema":{"type":"string"}},{"name":"start-index","in":"query","description":"must be 0 or a multiple of 100","schema":{"type":"integer","default":0}},{"name":"max-results","in":"query","description":"must be 100","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"the list of distinct label keys","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LabelKey"}}}}}}}}}}
```
## List the distinct values used for a label key by the services of this account.
> Fixed page size of 100. \`start-index\` must be 0 or a multiple of 100 and \`max-results\` must be 100; any other value returns 400.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"LabelValue":{"type":"object","properties":{"value":{"type":"string"}}}}},"paths":{"/services/labels/{key}/values":{"get":{"tags":["Services"],"summary":"List the distinct values used for a label key by the services of this account.","description":"Fixed page size of 100. `start-index` must be 0 or a multiple of 100 and `max-results` must be 100; any other value returns 400.","parameters":[{"name":"key","in":"path","description":"the label key","required":true,"schema":{"type":"string"}},{"name":"query","in":"query","description":"Filter the returned label values by prefix.","schema":{"type":"string"}},{"name":"start-index","in":"query","description":"must be 0 or a multiple of 100","schema":{"type":"integer","default":0}},{"name":"max-results","in":"query","description":"must be 100","schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"the list of distinct label values","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LabelValue"}}}}}}}}}}
```
## GET /services/topology
> Get the service dependency graph of the account.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"ServiceGraph":{"type":"object","properties":{"nodes":{"type":"array","items":{"$ref":"#/components/schemas/ServiceNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/ServiceDependency"},"description":"Rendering projection of the edges. Only id, sourceServiceId, targetServiceId and type are populated; fetch the full edge from the dependency endpoints of a service."}}},"ServiceNode":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"distance":{"type":"integer","format":"int32","description":"Number of edges between this node and the seed service. Not set for the whole graph."},"restricted":{"type":"boolean","description":"True when the caller may not see the details of this service."}}},"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"ServiceDependency":{"type":"object","required":["targetServiceId"],"properties":{"id":{"type":"integer","format":"int64","readOnly":true},"sourceServiceId":{"type":"integer","format":"int64","description":"The service that depends on the target service."},"targetServiceId":{"type":"integer","format":"int64","description":"The service that is being depended upon."},"notes":{"type":"string"},"invalidAfter":{"type":"string","format":"date-time","description":"Point in time after which this dependency is no longer considered valid."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"$ref":"#/components/schemas/ManagedBy"},"managedBy":{"$ref":"#/components/schemas/ManagedBy"}}},"ManagedBy":{"type":"object","readOnly":true,"description":"Present when this entity is managed outside of the ilert web app, for example through Terraform, Pulumi or the API. Read-only.","properties":{"type":{"type":"string","enum":["API","TERRAFORM","PULUMI","ILERT"]},"source":{"type":"string","description":"Identifier of the system managing this entity."}}}}},"paths":{"/services/topology":{"get":{"tags":["Services"],"summary":"Get the service dependency graph of the account.","parameters":[{"name":"labels","in":"query","description":"Filter by labels using a condition expression. Supports the operators `==`, `!=`, `in` and `not_in`, combined with `and` (up to 20 conditions). Values must be url-encoded. An invalid expression returns 400. Examples: `environment == 'production'`, `region in [\"us-east\", \"us-west\"]`, `environment == 'production' and severity != 'low'`.","schema":{"type":"string"}}],"responses":{"200":{"description":"the service dependency graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceGraph"}}}}}}}}}
```
## GET /services/{id}
> Get a specific service.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"Service":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"alias":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"description":{"type":"string"},"oneOpenIncidentOnly":{"type":"boolean"},"showUptimeHistory":{"type":"boolean"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}},"subscribed":{"type":"boolean","readOnly":true},"uptime":{"$ref":"#/components/schemas/ServiceUptime"},"managedBy":{"$ref":"#/components/schemas/ManagedBy"},"publicStatus":{"$ref":"#/components/schemas/ServiceStatus"},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Free-form key-value labels assigned to this service."},"iconUrl":{"type":"string"},"links":{"type":"array","items":{"$ref":"#/components/schemas/ServiceLink"}},"createdBy":{"$ref":"#/components/schemas/ManagedBy"},"dependencies":{"type":"array","items":{"$ref":"#/components/schemas/ServiceDependency"},"description":"This is an include field, it is not available in the list resource"}}},"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"ServiceUptime":{"type":"object","properties":{"rangeStart":{"type":"string","format":"date-time"},"rangeEnd":{"type":"string","format":"date-time"},"outages":{"type":"array","items":{"$ref":"#/components/schemas/ServiceOutage"}},"uptimePercentage":{"$ref":"#/components/schemas/ServiceUptimePercentage"}}},"ServiceOutage":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/ServiceStatus"},"from":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"}}},"ServiceUptimePercentage":{"type":"object","properties":{"uptimePercentage":{"type":"object","properties":{"p90":{"maximum":100,"minimum":0,"type":"number","format":"float","readOnly":true},"p60":{"maximum":100,"minimum":0,"type":"number","format":"float","readOnly":true},"p30":{"maximum":100,"minimum":0,"type":"number","format":"float","readOnly":true}}}}},"ManagedBy":{"type":"object","readOnly":true,"description":"Present when this entity is managed outside of the ilert web app, for example through Terraform, Pulumi or the API. Read-only.","properties":{"type":{"type":"string","enum":["API","TERRAFORM","PULUMI","ILERT"]},"source":{"type":"string","description":"Identifier of the system managing this entity."}}},"ServiceLink":{"type":"object","properties":{"href":{"type":"string","format":"uri"},"text":{"type":"string"}}},"ServiceDependency":{"type":"object","required":["targetServiceId"],"properties":{"id":{"type":"integer","format":"int64","readOnly":true},"sourceServiceId":{"type":"integer","format":"int64","description":"The service that depends on the target service."},"targetServiceId":{"type":"integer","format":"int64","description":"The service that is being depended upon."},"notes":{"type":"string"},"invalidAfter":{"type":"string","format":"date-time","description":"Point in time after which this dependency is no longer considered valid."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"$ref":"#/components/schemas/ManagedBy"},"managedBy":{"$ref":"#/components/schemas/ManagedBy"}}}}},"paths":{"/services/{id}":{"get":{"tags":["Services"],"summary":"Get a specific service.","parameters":[{"name":"id","in":"path","description":"entity ID","required":true,"schema":{"type":"number"}},{"name":"include","in":"query","description":"Describes optional properties that should be included in the response. You may declare multiple. (subscribed, uptime, links, dependencies, publicStatus)","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["subscribed","uptime","links","dependencies","publicStatus"]}}}],"responses":{"200":{"description":"The requested service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}}}}}}}
```
## PUT /services/{id}
> Update the specific service
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"ServiceNoIncludes":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"alias":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"description":{"type":"string"},"oneOpenIncidentOnly":{"type":"boolean"},"showUptimeHistory":{"type":"boolean"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}},"managedBy":{"$ref":"#/components/schemas/ManagedBy"},"publicStatus":{"$ref":"#/components/schemas/ServiceStatus"},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Free-form key-value labels assigned to this service."},"iconUrl":{"type":"string"},"links":{"type":"array","items":{"$ref":"#/components/schemas/ServiceLink"}},"createdBy":{"$ref":"#/components/schemas/ManagedBy"}}},"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"ManagedBy":{"type":"object","readOnly":true,"description":"Present when this entity is managed outside of the ilert web app, for example through Terraform, Pulumi or the API. Read-only.","properties":{"type":{"type":"string","enum":["API","TERRAFORM","PULUMI","ILERT"]},"source":{"type":"string","description":"Identifier of the system managing this entity."}}},"ServiceLink":{"type":"object","properties":{"href":{"type":"string","format":"uri"},"text":{"type":"string"}}}}},"paths":{"/services/{id}":{"put":{"tags":["Services"],"summary":"Update the specific service","parameters":[{"name":"id","in":"path","description":"entity ID","required":true,"schema":{"type":"number"}}],"requestBody":{"description":"the service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceNoIncludes"}}},"required":true},"responses":{"200":{"description":"The updated service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceNoIncludes"}}}}}}}}}
```
## DELETE /services/{id}
> Remove a specific service.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}}},"paths":{"/services/{id}":{"delete":{"tags":["Services"],"summary":"Remove a specific service.","parameters":[{"name":"id","in":"path","description":"entity ID","required":true,"schema":{"type":"number"}}],"responses":{"204":{"description":"Empty body delete response","content":{}}}}}}}
```
## Publish the latest status change of the specific service
> Makes the latest status change of the service visible on status pages, when it was kept internal. The API reports such a change by returning a 'publicStatus' that differs from 'status'. The 'status' query param must match the current status of the service and the status of its latest change, otherwise nothing is published and the request is rejected with 409, so a status change that happened in the meantime is never published by accident.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"ServiceNoIncludes":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"alias":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"description":{"type":"string"},"oneOpenIncidentOnly":{"type":"boolean"},"showUptimeHistory":{"type":"boolean"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}},"managedBy":{"$ref":"#/components/schemas/ManagedBy"},"publicStatus":{"$ref":"#/components/schemas/ServiceStatus"},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Free-form key-value labels assigned to this service."},"iconUrl":{"type":"string"},"links":{"type":"array","items":{"$ref":"#/components/schemas/ServiceLink"}},"createdBy":{"$ref":"#/components/schemas/ManagedBy"}}},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"ManagedBy":{"type":"object","readOnly":true,"description":"Present when this entity is managed outside of the ilert web app, for example through Terraform, Pulumi or the API. Read-only.","properties":{"type":{"type":"string","enum":["API","TERRAFORM","PULUMI","ILERT"]},"source":{"type":"string","description":"Identifier of the system managing this entity."}}},"ServiceLink":{"type":"object","properties":{"href":{"type":"string","format":"uri"},"text":{"type":"string"}}}}},"paths":{"/services/{id}/publish-status":{"put":{"tags":["Services"],"summary":"Publish the latest status change of the specific service","description":"Makes the latest status change of the service visible on status pages, when it was kept internal. The API reports such a change by returning a 'publicStatus' that differs from 'status'. The 'status' query param must match the current status of the service and the status of its latest change, otherwise nothing is published and the request is rejected with 409, so a status change that happened in the meantime is never published by accident.","parameters":[{"name":"id","in":"path","description":"entity ID","required":true,"schema":{"type":"number"}},{"name":"status","in":"query","description":"the status that is expected to be published, must match the current status of the service","required":true,"schema":{"$ref":"#/components/schemas/ServiceStatus"}}],"responses":{"200":{"description":"The service whose latest status change is now public","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceNoIncludes"}}}},"409":{"description":"The latest status change of the service is not an internal change to the given status"}}}}}}
```
## List the dependencies of a service.
> Returns the direct downstream dependencies of the service, unless a transitive lookup is requested.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"ServiceDependency":{"type":"object","required":["targetServiceId"],"properties":{"id":{"type":"integer","format":"int64","readOnly":true},"sourceServiceId":{"type":"integer","format":"int64","description":"The service that depends on the target service."},"targetServiceId":{"type":"integer","format":"int64","description":"The service that is being depended upon."},"notes":{"type":"string"},"invalidAfter":{"type":"string","format":"date-time","description":"Point in time after which this dependency is no longer considered valid."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"$ref":"#/components/schemas/ManagedBy"},"managedBy":{"$ref":"#/components/schemas/ManagedBy"}}},"ManagedBy":{"type":"object","readOnly":true,"description":"Present when this entity is managed outside of the ilert web app, for example through Terraform, Pulumi or the API. Read-only.","properties":{"type":{"type":"string","enum":["API","TERRAFORM","PULUMI","ILERT"]},"source":{"type":"string","description":"Identifier of the system managing this entity."}}}}},"paths":{"/services/{id}/dependencies":{"get":{"tags":["Services"],"summary":"List the dependencies of a service.","description":"Returns the direct downstream dependencies of the service, unless a transitive lookup is requested.","parameters":[{"name":"id","in":"path","description":"the id of the service","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"transitive","in":"query","description":"Also return dependencies reachable through other services.","schema":{"type":"boolean","default":false}},{"name":"depth","in":"query","description":"Maximum number of edges to follow when a transitive lookup is requested.","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"the dependencies of the service","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ServiceDependency"}}}}}}}}}}
```
## POST /services/{id}/dependencies
> Create a dependency on a service.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"ServiceDependency":{"type":"object","required":["targetServiceId"],"properties":{"id":{"type":"integer","format":"int64","readOnly":true},"sourceServiceId":{"type":"integer","format":"int64","description":"The service that depends on the target service."},"targetServiceId":{"type":"integer","format":"int64","description":"The service that is being depended upon."},"notes":{"type":"string"},"invalidAfter":{"type":"string","format":"date-time","description":"Point in time after which this dependency is no longer considered valid."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"$ref":"#/components/schemas/ManagedBy"},"managedBy":{"$ref":"#/components/schemas/ManagedBy"}}},"ManagedBy":{"type":"object","readOnly":true,"description":"Present when this entity is managed outside of the ilert web app, for example through Terraform, Pulumi or the API. Read-only.","properties":{"type":{"type":"string","enum":["API","TERRAFORM","PULUMI","ILERT"]},"source":{"type":"string","description":"Identifier of the system managing this entity."}}}}},"paths":{"/services/{id}/dependencies":{"post":{"tags":["Services"],"summary":"Create a dependency on a service.","parameters":[{"name":"id","in":"path","description":"the id of the service","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"description":"the dependency","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceDependency"}}}},"responses":{"201":{"description":"the created dependency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceDependency"}}}}}}}}}
```
## Replace all dependencies of a service.
> Dependencies that are not part of the request body are removed from the service.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"ServiceDependency":{"type":"object","required":["targetServiceId"],"properties":{"id":{"type":"integer","format":"int64","readOnly":true},"sourceServiceId":{"type":"integer","format":"int64","description":"The service that depends on the target service."},"targetServiceId":{"type":"integer","format":"int64","description":"The service that is being depended upon."},"notes":{"type":"string"},"invalidAfter":{"type":"string","format":"date-time","description":"Point in time after which this dependency is no longer considered valid."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"$ref":"#/components/schemas/ManagedBy"},"managedBy":{"$ref":"#/components/schemas/ManagedBy"}}},"ManagedBy":{"type":"object","readOnly":true,"description":"Present when this entity is managed outside of the ilert web app, for example through Terraform, Pulumi or the API. Read-only.","properties":{"type":{"type":"string","enum":["API","TERRAFORM","PULUMI","ILERT"]},"source":{"type":"string","description":"Identifier of the system managing this entity."}}}}},"paths":{"/services/{id}/dependencies":{"put":{"tags":["Services"],"summary":"Replace all dependencies of a service.","description":"Dependencies that are not part of the request body are removed from the service.","parameters":[{"name":"id","in":"path","description":"the id of the service","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"description":"the complete set of dependencies","required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ServiceDependency"}}}}},"responses":{"200":{"description":"the dependencies of the service","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ServiceDependency"}}}}}}}}}}
```
## GET /services/{id}/dependencies/{edgeId}
> Get a single dependency of a service.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"ServiceDependency":{"type":"object","required":["targetServiceId"],"properties":{"id":{"type":"integer","format":"int64","readOnly":true},"sourceServiceId":{"type":"integer","format":"int64","description":"The service that depends on the target service."},"targetServiceId":{"type":"integer","format":"int64","description":"The service that is being depended upon."},"notes":{"type":"string"},"invalidAfter":{"type":"string","format":"date-time","description":"Point in time after which this dependency is no longer considered valid."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"$ref":"#/components/schemas/ManagedBy"},"managedBy":{"$ref":"#/components/schemas/ManagedBy"}}},"ManagedBy":{"type":"object","readOnly":true,"description":"Present when this entity is managed outside of the ilert web app, for example through Terraform, Pulumi or the API. Read-only.","properties":{"type":{"type":"string","enum":["API","TERRAFORM","PULUMI","ILERT"]},"source":{"type":"string","description":"Identifier of the system managing this entity."}}}}},"paths":{"/services/{id}/dependencies/{edgeId}":{"get":{"tags":["Services"],"summary":"Get a single dependency of a service.","parameters":[{"name":"id","in":"path","description":"the id of the service","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"edgeId","in":"path","description":"the id of the dependency","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"the dependency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceDependency"}}}}}}}}}
```
## DELETE /services/{id}/dependencies/{edgeId}
> Delete a dependency of a service.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}}},"paths":{"/services/{id}/dependencies/{edgeId}":{"delete":{"tags":["Services"],"summary":"Delete a dependency of a service.","parameters":[{"name":"id","in":"path","description":"the id of the service","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"edgeId","in":"path","description":"the id of the dependency","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"204":{"description":"Empty body delete response","content":{}}}}}}}
```
## GET /services/name/{name}
> Get the service with the specified name.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"Service":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"alias":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"description":{"type":"string"},"oneOpenIncidentOnly":{"type":"boolean"},"showUptimeHistory":{"type":"boolean"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}},"subscribed":{"type":"boolean","readOnly":true},"uptime":{"$ref":"#/components/schemas/ServiceUptime"},"managedBy":{"$ref":"#/components/schemas/ManagedBy"},"publicStatus":{"$ref":"#/components/schemas/ServiceStatus"},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Free-form key-value labels assigned to this service."},"iconUrl":{"type":"string"},"links":{"type":"array","items":{"$ref":"#/components/schemas/ServiceLink"}},"createdBy":{"$ref":"#/components/schemas/ManagedBy"},"dependencies":{"type":"array","items":{"$ref":"#/components/schemas/ServiceDependency"},"description":"This is an include field, it is not available in the list resource"}}},"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"ServiceUptime":{"type":"object","properties":{"rangeStart":{"type":"string","format":"date-time"},"rangeEnd":{"type":"string","format":"date-time"},"outages":{"type":"array","items":{"$ref":"#/components/schemas/ServiceOutage"}},"uptimePercentage":{"$ref":"#/components/schemas/ServiceUptimePercentage"}}},"ServiceOutage":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/ServiceStatus"},"from":{"type":"string","format":"date-time"},"until":{"type":"string","format":"date-time"}}},"ServiceUptimePercentage":{"type":"object","properties":{"uptimePercentage":{"type":"object","properties":{"p90":{"maximum":100,"minimum":0,"type":"number","format":"float","readOnly":true},"p60":{"maximum":100,"minimum":0,"type":"number","format":"float","readOnly":true},"p30":{"maximum":100,"minimum":0,"type":"number","format":"float","readOnly":true}}}}},"ManagedBy":{"type":"object","readOnly":true,"description":"Present when this entity is managed outside of the ilert web app, for example through Terraform, Pulumi or the API. Read-only.","properties":{"type":{"type":"string","enum":["API","TERRAFORM","PULUMI","ILERT"]},"source":{"type":"string","description":"Identifier of the system managing this entity."}}},"ServiceLink":{"type":"object","properties":{"href":{"type":"string","format":"uri"},"text":{"type":"string"}}},"ServiceDependency":{"type":"object","required":["targetServiceId"],"properties":{"id":{"type":"integer","format":"int64","readOnly":true},"sourceServiceId":{"type":"integer","format":"int64","description":"The service that depends on the target service."},"targetServiceId":{"type":"integer","format":"int64","description":"The service that is being depended upon."},"notes":{"type":"string"},"invalidAfter":{"type":"string","format":"date-time","description":"Point in time after which this dependency is no longer considered valid."},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"createdBy":{"$ref":"#/components/schemas/ManagedBy"},"managedBy":{"$ref":"#/components/schemas/ManagedBy"}}}}},"paths":{"/services/name/{name}":{"get":{"tags":["Services"],"summary":"Get the service with the specified name.","parameters":[{"name":"name","in":"path","description":"unique name of the service","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Describes optional properties that should be included in the response. You may declare multiple. (subscribed, uptime, links, dependencies, publicStatus)","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["subscribed","uptime","links","dependencies","publicStatus"]}}}],"responses":{"200":{"description":"The requested service","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Service"}}}}}}}}}
```
## GET /services/{id}/private-subscribers
> Get the subscribers (users and teams) of a service
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"TeamUserOption":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"type":{"type":"string","enum":["USER","TEAM"]}}}}},"paths":{"/services/{id}/private-subscribers":{"get":{"tags":["Services"],"summary":"Get the subscribers (users and teams) of a service","parameters":[{"name":"id","in":"path","description":"entity ID","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"The subscribers of the service","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TeamUserOption"}}}}}}}}}}
```
## Set subscribers (users and teams) of a service
> Note: this is an in place update
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.9-r.4"},"tags":[{"name":"Services"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"TeamUserOption":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"type":{"type":"string","enum":["USER","TEAM"]}}}}},"paths":{"/services/{id}/private-subscribers":{"put":{"tags":["Services"],"summary":"Set subscribers (users and teams) of a service","description":"Note: this is an in place update","parameters":[{"name":"id","in":"path","description":"entity ID","required":true,"schema":{"type":"number"}}],"requestBody":{"description":"subscribers that should be adjusted","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TeamUserOption"}}}},"required":true},"responses":{"204":{"description":"the response","content":{}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.ilert.com/developer-docs/rest-api/api-reference/services.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.