@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api SIGNL4 API V1
@base https://connect.signl4.com/api
@version 1
@auth ApiKey x-s4-api-key in header | ApiKey x-s4-api-key in query | OAuth2
@endpoints 109
@hint download_for_search
@toc alerts(20), categories(10), events(4), prepaid(5), scripts(11), subscriptions(13), teams(25), users(14), webhooks(7)

@group alerts
@endpoint POST /alerts
@desc Trigger Alert
@required {text: str, title: str}
@optional {attachments: [map{encoding: int(int32), content: str, id: str, name: str, contentType: str}], category: str, externalId: str, flags: int(int32), parameters: [map{name: str, order: int(int32), type: int(int32), value: str}], severity: int(int32)(0/1/2) # 0 = Low1 = Major2 = Critical}
@returns(201) {attachments: [map]?, category: str?, eventSourceId: str?, eventSourceType: int(int32), history: map{alertHistoryEntries: [map]?, acknowledgedgements: [str]?, closed: str(date-time)?, closedBy: str?, acknowledged: str(date-time)?, created: str(date-time), createdBy: str?}, parameters: [map]?, severity: int(int32), categoryId: str?, externalId: str?, eventId: str?, flags: int(int32), id: str?, lastModified: str(date-time), status: int(int32), subscriptionId: str?, teamId: str?, text: str?, title: str?, annotations: [map]?} # Created
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: Internal general error occurred.}

@endpoint GET /alerts/{alertId}
@desc Get Alert
@required {alertId: str # Id of the requested Alert.}
@returns(200) {attachments: [map]?, category: str?, eventSourceId: str?, eventSourceType: int(int32), history: map{alertHistoryEntries: [map]?, acknowledgedgements: [str]?, closed: str(date-time)?, closedBy: str?, acknowledged: str(date-time)?, created: str(date-time), createdBy: str?}, parameters: [map]?, severity: int(int32), categoryId: str?, externalId: str?, eventId: str?, flags: int(int32), id: str?, lastModified: str(date-time), status: int(int32), subscriptionId: str?, teamId: str?, text: str?, title: str?, annotations: [map]?} # OK
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: Internal general error occurred.}

@endpoint POST /alerts/{alertId}/acknowledge
@desc Acknowledge an alert
@required {alertId: str # Id to acknowledge an alert., uid: str}
@optional {descr: str}
@returns(200) {attachments: [map]?, category: str?, eventSourceId: str?, eventSourceType: int(int32), history: map{alertHistoryEntries: [map]?, acknowledgedgements: [str]?, closed: str(date-time)?, closedBy: str?, acknowledged: str(date-time)?, created: str(date-time), createdBy: str?}, parameters: [map]?, severity: int(int32), categoryId: str?, externalId: str?, eventId: str?, flags: int(int32), id: str?, lastModified: str(date-time), status: int(int32), subscriptionId: str?, teamId: str?, text: str?, title: str?, annotations: [map]?} # OK
@errors {400: Required information could not be found in the request/claims., 404: No alert with id was found., 409: Alert can't be acknowledged because it is against the defined alert lifecycle., 500: Internal general error occurred.}

@endpoint POST /alerts/{alertId}/annotate
@desc Annotate Alert
@required {alertId: str # Id of the alert to annotate.}
@optional {type: int(int32), text: str, timestamp: str(date-time), userId: str, id: str, teamId: str}
@returns(200) {type: int(int32), text: str?, timestamp: str(date-time), userId: str?, id: str?, teamId: str?} # OK
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: Internal general error occurred.}

@endpoint GET /alerts/{alertId}/annotations
@desc Get annotations of an alert
@required {alertId: str # Id of the requested Alert.}
@returns(200) OK
@returns(204) No annotations were found for the alert.
@errors {400: Required information could not be found in the request/claims., 404: Not Found, 500: Internal Server Error}

@endpoint GET /alerts/{alertId}/attachments
@desc Get attachments of an alert
@required {alertId: str # Id of the requested Alert.}
@returns(200) OK
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: Internal general error occurred.}

@endpoint GET /alerts/{alertId}/attachments/{attachmentId}
@desc Gets a specified attachment of a specified alert.
@required {alertId: str # Id of the alert that contains the wanted attachment., attachmentId: str # Id of the attachment, that you want to retrieve.}
@optional {width: int(int32) # Optional parameter defining the wanted width of the picture that is retrieved., height: int(int32) # Optional parameter defining the wanted height of the picture that is retrieved., scale: bool=true # Optional parameter defining whether it's wanted to scale the retrieved image. Default is set to
 true.}
@returns(200) Returns the attachment image with additional meta information.
@returns(204) The image of the attachment was not uploaded yet.
@errors {400: A passed parameter was either empty or invalid., 403: Authorization failed., 404: The attachment image was not found., 500: Internal general error occurred.}

@endpoint POST /alerts/{alertId}/close
@desc Close an alert
@required {alertId: str # Id to acknowledge an alert., uid: str}
@optional {descr: str}
@returns(200) {attachments: [map]?, category: str?, eventSourceId: str?, eventSourceType: int(int32), history: map{alertHistoryEntries: [map]?, acknowledgedgements: [str]?, closed: str(date-time)?, closedBy: str?, acknowledged: str(date-time)?, created: str(date-time), createdBy: str?}, parameters: [map]?, severity: int(int32), categoryId: str?, externalId: str?, eventId: str?, flags: int(int32), id: str?, lastModified: str(date-time), status: int(int32), subscriptionId: str?, teamId: str?, text: str?, title: str?, annotations: [map]?} # OK
@errors {400: Required information could not be found in the request/claims., 404: No alert with id was found., 409: Alert can't be closed because it is against the defined alert lifecycle., 500: Internal general error occurred.}

@endpoint GET /alerts/{alertId}/notifications
@desc Get alert notifications
@required {alertId: str # Id of the requested Alert.}
@returns(200) OK
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: Internal general error occurred.}

@endpoint GET /alerts/{alertId}/overview
@desc Get an overview alert.
@required {alertId: str # Id of the requested Alert.}
@returns(200) {alertDeliveryStatus: map{alertDeliveryStatusCode: int(int32), userDeliveryStatusInfos: [map]?}, detailedHistory: map{alertHistoryEntries: [map]?, acknowledgedgements: [str]?, closed: str(date-time)?, closedBy: str?, acknowledged: str(date-time)?, created: str(date-time), createdBy: str?}, requiredAcknowledgements: int(int32), categoryId: str?, externalId: str?, eventId: str?, flags: int(int32), id: str?, lastModified: str(date-time), status: int(int32), subscriptionId: str?, teamId: str?, text: str?, title: str?, annotations: [map]?} # Returns alert with all information attached.
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: Internal Server Error}

@endpoint POST /alerts/{alertId}/undoAcknowledge
@desc Undo the acknowledgement of an alert.
@required {alertId: str, uid: str}
@optional {descr: str}
@returns(200) {alertDeliveryStatus: map{alertDeliveryStatusCode: int(int32), userDeliveryStatusInfos: [map]?}, detailedHistory: map{alertHistoryEntries: [map]?, acknowledgedgements: [str]?, closed: str(date-time)?, closedBy: str?, acknowledged: str(date-time)?, created: str(date-time), createdBy: str?}, requiredAcknowledgements: int(int32), categoryId: str?, externalId: str?, eventId: str?, flags: int(int32), id: str?, lastModified: str(date-time), status: int(int32), subscriptionId: str?, teamId: str?, text: str?, title: str?, annotations: [map]?} # Returns updated alert.
@errors {400: Required information could not be found in the request/claims., 403: User is not allowed to undo the acknowledgement., 500: Internal general error occurred.}

@endpoint POST /alerts/{alertId}/undoClose
@desc Undo the closure of an alert.
@required {alertId: str, uid: str}
@optional {descr: str}
@returns(200) {alertDeliveryStatus: map{alertDeliveryStatusCode: int(int32), userDeliveryStatusInfos: [map]?}, detailedHistory: map{alertHistoryEntries: [map]?, acknowledgedgements: [str]?, closed: str(date-time)?, closedBy: str?, acknowledged: str(date-time)?, created: str(date-time), createdBy: str?}, requiredAcknowledgements: int(int32), categoryId: str?, externalId: str?, eventId: str?, flags: int(int32), id: str?, lastModified: str(date-time), status: int(int32), subscriptionId: str?, teamId: str?, text: str?, title: str?, annotations: [map]?} # OK
@errors {400: Required information could not be found in the request/claims., 403: User is not allowed to undo the close., 500: Internal general error occurred.}

@endpoint POST /alerts/acknowledgeAll
@desc Confirms all visible alerts
@optional {userId: str # User ID of the user to be used to acknowledge the alarms., maxDate: str(date-time), minDate: str(date-time), categoryIds: [str], scope: int(int32)(0/1/2) # 0 = Default1 = AllTeams2 = SpecificTeams, teamIds: [str]}
@returns(204) No Content
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: Internal general error occurred.}

@endpoint POST /alerts/acknowledgeMultiple
@desc Acknowlegde multiple alerts
@required {uid: str, alertIds: [str]}
@optional {descr: str}
@returns(204) No Content
@errors {400: Required information could not be found in the request/claims., 404: Not Found, 500: Internal general error occurred.}

@endpoint POST /alerts/closeAll
@desc Close all acknowledged alerts.
@optional {userId: str # User ID of the user to be used to close the alarms., maxDate: str(date-time), minDate: str(date-time), categoryIds: [str], scope: int(int32)(0/1/2) # 0 = Default1 = AllTeams2 = SpecificTeams, teamIds: [str]}
@returns(204) No Content
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: Internal general error occurred.}

@endpoint POST /alerts/closeMultiple
@desc Close multiple alerts
@required {uid: str, alertIds: [str]}
@optional {descr: str}
@returns(204) No Content
@errors {400: Required information could not be found in the request/claims., 404: Not Found, 500: Internal general error occurred.}

@endpoint POST /alerts/paged
@desc Gets alerts paged
@optional {maxResults: int(int32) # Defines the limit of retrieved alert details per request. 1 to 100 are allowed per request.
 Number of alerts could be less if filtered but at least 1., userId: str # User ID of the user you want to get alerts for., teamid: str, alertIds: [str], afterId: str, categoryIds: [str], continuationToken: map{nextPartitionKey: str, nextRowKey: str, nextTableName: str}, maxCreated: str(date-time), minCreated: str(date-time), modSince: str(date-time), showPersonalHiddenCategories: bool, userCreatedAlertsFilterMode: int(int32)(0/1/2) # 0 = ExcludeUserCreatedAlerts1 = IncludeUserCreatedAlerts2 = OnlyUserCreatedAlerts, alertStatusCodes: int(int32)(0/1/2/4/8/16/32) # 0 = None1 = Open2 = Acknowledged4 = Closed8 = NoReply16 = Failed32 = Error, textToSearch: str}
@returns(200) {continuationToken: map{nextPartitionKey: str?, nextRowKey: str?, nextTableName: str?}, hasMore: bool, results: [map]?} # Returns a paged result with found alerts and continuation token if more alerts are in the
 database.
@returns(204) There were no alerts found for the specified filter.
@errors {400: Required parameters could not be found in the request/claims., 403: Authorization failed, 404: Not Found, 500: Internal general error occurred.}

@endpoint GET /alerts/report
@desc Get Alert Report
@optional {userId: str # User ID of the user for whom you want a report.}
@returns(200) {last24Hours: map{acknowledged: int(int64), end: str(date-time)?, lastModified: str(date-time)?, start: str(date-time)?, unhandled: int(int64), closed: int(int64)}, subscriptionId: str, teamCurrentDuty: map{acknowledged: int(int64), end: str(date-time)?, lastModified: str(date-time)?, start: str(date-time)?, unhandled: int(int64), closed: int(int64)}, teamId: str, teamLastDuty: map{acknowledged: int(int64), end: str(date-time)?, lastModified: str(date-time)?, start: str(date-time)?, unhandled: int(int64), closed: int(int64)}, userId: str?, userLastDutyChange: map{acknowledged: int(int64), end: str(date-time)?, lastModified: str(date-time)?, start: str(date-time)?, unhandled: int(int64), closed: int(int64)}} # OK
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: Internal general error occurred.}

@endpoint POST /alerts/undoAcknowledgeMultiple
@desc Queue undo of multiple acknowledgments.
@required {uid: str, alertIds: [str]}
@optional {descr: str}
@returns(204) No Content
@errors {400: Required information could not be found in the request/claims., 403: Forbidden, 500: Internal general error occurred.}

@endpoint POST /alerts/undoCloseMultiple
@desc Withdraw closure of multiple alerts
@required {uid: str, alertIds: [str]}
@optional {descr: str}
@returns(204) No Content
@errors {400: Required information could not be found in the request/claims., 404: Not Found, 500: Internal general error occurred.}

@endgroup

@group categories
@endpoint GET /categories/{teamId}
@desc Get all categories
@required {teamId: str # ID of the team the categories belong to}
@returns(200) Returns the category infos
@errors {400: If the input is not valid, 403: If you have no permission to access this resource, 404: If the resource was not found, 500: If any server side errors occur}

@endpoint POST /categories/{teamId}
@desc Create a new category
@required {teamId: str # ID of the team the category belongs to, name: str, color: str, imageName: str, keywords: [str], keywordMatching: int(int32)(0/1) # 0 = Any1 = All}
@optional {id: str, teamId: str, isDefault: bool, options: int(int32)(0/1/2/4/8) # 0 = None1 = Hidden2 = DenyDelete4 = HideOptOut8 = HideKeywords, keywordsExcluded: [str], augmentations: [map{enabled: bool, name: str, type!: int(int32), value: str, id: str, parameters: [map]}], enrichments: [map{id: str, name: str, type!: int(int32), value: str}], order: int(int32)}
@returns(201) {id: str?, teamId: str?, isDefault: bool, options: int(int32), name: str, color: str, imageName: str, keywords: [str], keywordsExcluded: [str]?, keywordMatching: int(int32), augmentations: [map]?, enrichments: [map]?, order: int(int32)} # Returns the newly created category
@errors {400: If the input is not valid, 403: If you have no permission to access this resource, 404: If the resource was not found, 500: If any server side errors occur}

@endpoint GET /categories/{teamId}/{categoryId}
@desc Get a specific category
@required {teamId: str # ID of the team the category belongs to, categoryId: str # ID of the category to get}
@returns(200) {id: str?, teamId: str?, isDefault: bool, options: int(int32), name: str, color: str, imageName: str, keywords: [str], keywordsExcluded: [str]?, keywordMatching: int(int32), augmentations: [map]?, enrichments: [map]?, order: int(int32)} # Returns the category details
@errors {400: If the input is not valid, 403: If you have no permission to access this resource, 404: If the resource was not found, 500: If any server side errors occur}

@endpoint PUT /categories/{teamId}/{categoryId}
@desc Update an existing category
@required {teamId: str # ID of the team the category belongs to, categoryId: str, name: str, color: str, imageName: str, keywords: [str], keywordMatching: int(int32)(0/1) # 0 = Any1 = All}
@optional {id: str, teamId: str, isDefault: bool, options: int(int32)(0/1/2/4/8) # 0 = None1 = Hidden2 = DenyDelete4 = HideOptOut8 = HideKeywords, keywordsExcluded: [str], augmentations: [map{enabled: bool, name: str, type!: int(int32), value: str, id: str, parameters: [map]}], enrichments: [map{id: str, name: str, type!: int(int32), value: str}], order: int(int32)}
@returns(200) {id: str?, teamId: str?, isDefault: bool, options: int(int32), name: str, color: str, imageName: str, keywords: [str], keywordsExcluded: [str]?, keywordMatching: int(int32), augmentations: [map]?, enrichments: [map]?, order: int(int32)} # Returns the updated category
@errors {400: If the input is not valid, 403: If you have no permission to access this resource, 404: If the resource was not found, 500: If any server side errors occur}

@endpoint DELETE /categories/{teamId}/{categoryId}
@desc Delete an existing category
@required {teamId: str # ID of the team the category belongs to, categoryId: str # ID of the category to delete}
@returns(200) If the delete operation was successful
@returns(204) No Content
@errors {400: If the input is not valid, 403: If you have no permission to access this resource, 404: If the resource was not found, 500: If any server side errors occur}

@endpoint GET /categories/{teamId}/{categoryId}/metrics
@desc Get metrics for a specific category
@required {teamId: str # ID of the team the category belongs to, categoryId: str # ID of the category to get}
@returns(200) {categoryId: str?, last24h: int(int64), lastAlert: str(date-time)?, subscriberCount: int(int32)} # Returns the category metrics
@errors {400: If the input is not valid, 403: If you have no permission to access this resource, 404: If the resource was not found, 500: If any server side errors occur}

@endpoint GET /categories/{teamId}/{categoryId}/subscriptions
@desc Get category subscriptions
@required {teamId: str # ID of the team the category belongs to, categoryId: str # Category to get subscriptions for}
@returns(200) Returns the category subscriptions
@errors {400: If the input is not valid, 403: If you have no permission to access this resource, 404: If the resource was not found, 500: If any server side errors occur}

@endpoint POST /categories/{teamId}/{categoryId}/subscriptions
@desc Set category subscriptions
@required {teamId: str # ID of the team the category belongs to, categoryId: str # Category to be updated}
@returns(200) Returns the updated category subscriptions
@errors {400: If the input is not valid, 403: If you have no permission to access this resource, 404: If the resource was not found, 500: If any server side errors occur}

@endpoint GET /categories/{teamId}/metrics
@desc Get metrics for all categories
@required {teamId: str # ID of the team the categories belongs to}
@returns(200) Returns a list of category metrics
@errors {400: If the input is not valid, 403: If you have no permission to access this resource, 404: If the resource was not found, 500: If any server side errors occur}

@endpoint GET /categories/images
@desc Gets the names of all alert category images.
@returns(200) Return names of all category images
@returns(204) Request was canceled.
@errors {403: If you have no permission to access this resource, 404: No category images found., 500: If any server side errors occur}

@endgroup

@group events
@endpoint GET /events/{eventId}/overview
@desc Get overview event
@required {eventId: str # Id of event to get.}
@returns(200) {teamId: str?, alertId: str?, categoryId: str?, acknowledgedAlerts: [str]?, closedAlerts: [str]?, creationTime: str(date-time), createdByUserId: str?, eventSourceType: int(int32), eventSourceGroupId: str?, eventSourceId: str?, eventSourceTeamId: str?, eventStatus: int(int32), id: str?, lastModified: str(date-time), severity: int(int32), text: str?, title: str?} # Returns overview event with specific id.
@errors {400: Required parameters could not be found in the request/claims., 404: Event with specified id could not be found., 500: Internal general error occurred.}

@endpoint GET /events/{eventId}/parameters
@desc Get event parameters
@required {eventId: str # Event Id of the requested Alert.}
@returns(200) OK
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: Internal general error occurred.}

@endpoint POST /events/{webhookIdOrTeamId}
@desc Create new event
@required {webhookIdOrTeamId: str # Use team id to send an event straight to the team or an inbound webhook identifier (https://connect.signl4.com/webhook/{Identifier}) to use distribution rules}
@optional {ExtIdParam: str, ExtStatusParam: str, NewStatus: str, ResolvedStatus: str, AckStatus: str}
@returns(201) {teamId: str?, alertId: str?, categoryId: str?, acknowledgedAlerts: [str]?, closedAlerts: [str]?, creationTime: str(date-time), createdByUserId: str?, eventSourceType: int(int32), eventSourceGroupId: str?, eventSourceId: str?, eventSourceTeamId: str?, eventStatus: int(int32), id: str?, lastModified: str(date-time), severity: int(int32), text: str?, title: str?} # Created
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint POST /events/paged
@desc Get overview event paged.
@optional {maxResults: int(int32) # Defines the limit of retrieved alert details per request. 1 to 100 are allowed per request.
 Number of alerts could be less if filtered but at least 1., teamid: str, continuationToken: map{nextPartitionKey: str, nextRowKey: str, nextTableName: str}, eventStatusCode: int(int32)(0/1/2/3/4/5/6/7/8/9/21/22/23/30/1000) # 0 = None1 = Processing2 = Signled3 = Filtered4 = Resolved5 = Discarded6 = Acknowledged7 = Suppressed8 = NoRuleApplied9 = MultipleTargetStatus21 = WaitingForAutoClose22 = NotEnoughOccurrences23 = DuplicateSuppressed30 = NoTarget1000 = Error, maxCreationDate: str(date-time), minCreationDate: str(date-time), modifiedSince: str(date-time), textToSearch: str, eventSourceId: str, eventCreatorFilter: map{userId!: str, userCreatedFilterMode: int(int32)}}
@returns(200) {continuationToken: map{nextPartitionKey: str?, nextRowKey: str?, nextTableName: str?}, hasMore: bool, results: [map]?} # Returns paged result with found events and continuation token, if database holds more events.
@returns(204) No event could be found (with passed filter)
@errors {400: Required parameters could not be found in the request/claims., 404: Not Found, 500: Internal general error occurred.}

@endgroup

@group prepaid
@endpoint PUT /prepaid/{subscriptionId}/prepaidSettings
@desc Update a subscription's current prepaid settings.
@required {subscriptionId: str # ID of the subscription}
@optional {topUpAmount: int(int32), topUpEnabled: bool, topUpLimit: int(int32)}
@returns(200) {topUpAmount: int(int32), topUpEnabled: bool, topUpLimit: int(int32)} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /prepaid/balance
@desc Get your subscription's current prepaid balance.
@returns(200) {balance: int(int32), latestTopUp: str(date-time)?, pendingTransactions: bool} # OK
@errors {400: Bad Request, 404: Not Found, 500: Internal Server Error}

@endpoint GET /prepaid/settings
@desc Get your subscription's current prepaid settings.
@returns(200) {topUpAmount: int(int32), topUpEnabled: bool, topUpLimit: int(int32)} # OK
@errors {400: Bad Request, 404: Not Found, 500: Internal Server Error}

@endpoint PUT /prepaid/settings
@desc Update your subscription's current prepaid settings.
@optional {topUpAmount: int(int32), topUpEnabled: bool, topUpLimit: int(int32)}
@returns(200) {topUpAmount: int(int32), topUpEnabled: bool, topUpLimit: int(int32)} # OK
@errors {400: Bad Request, 404: Not Found, 500: Internal Server Error}

@endpoint GET /prepaid/transactions
@desc Get your subscription's prepaid transactions.
@returns(200) OK
@errors {400: Bad Request, 404: Not Found, 500: Internal Server Error}

@endgroup

@group scripts
@endpoint GET /scripts/instances
@desc Returns all script instances of the SIGNL4 team
@optional {teamId: [str], modifiedSince: str(date-time)}
@returns(200) OK
@errors {400: Required information could not be found in the request/claims.}

@endpoint POST /scripts/instances
@desc Creates a new script instance in the in the SIGNL4 team.
@optional {instanceId: str, scriptId: str, scriptName: str, customScriptName: str, customScriptDescription: str, teamId: str, sharedTeams: [str], enabled: bool, config: any}
@returns(200) {config: any?, webhookUrl: str?, eventSourceId: str?, instanceId: str?, scriptId: str?, scriptName: str?, customScriptName: str?, customScriptDescription: str?, subscriptionId: str?, teamId: str?, eventPattern: any?, lastModified: str(date-time)?, enabled: bool, runtimeInformation: map{runtimeStatus: int(int32), runtimeStatusMessage: str?}} # Existing script instance was updated as specified in body.
@returns(201) {config: any?, webhookUrl: str?, eventSourceId: str?, instanceId: str?, scriptId: str?, scriptName: str?, customScriptName: str?, customScriptDescription: str?, subscriptionId: str?, teamId: str?, eventPattern: any?, lastModified: str(date-time)?, enabled: bool, runtimeInformation: map{runtimeStatus: int(int32), runtimeStatusMessage: str?}} # New script instance was updated as specified in body.
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: An internal error has occurred during instance creation.}

@endpoint GET /scripts/instances/{instanceId}
@desc Returns all information about a given script instance which includes its runtime status.
@required {instanceId: str # Instance Id of script instance to be returned.}
@returns(200) {config: any?, webhookUrl: str?, eventSourceId: str?, instanceId: str?, scriptId: str?, scriptName: str?, customScriptName: str?, customScriptDescription: str?, subscriptionId: str?, teamId: str?, eventPattern: any?, lastModified: str(date-time)?, enabled: bool, runtimeInformation: map{runtimeStatus: int(int32), runtimeStatusMessage: str?}} # OK
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database or in memory.}

@endpoint PUT /scripts/instances/{instanceId}
@desc Updates a given script instance, typically used for updating the configuration of a script.
@required {instanceId: str # InstanceId of the script to be updated.}
@optional {customScriptName: str, customScriptDescription: str, teamId: str, enabled: bool, config: any}
@returns(200) {config: any?, webhookUrl: str?, eventSourceId: str?, instanceId: str?, scriptId: str?, scriptName: str?, customScriptName: str?, customScriptDescription: str?, subscriptionId: str?, teamId: str?, eventPattern: any?, lastModified: str(date-time)?, enabled: bool, runtimeInformation: map{runtimeStatus: int(int32), runtimeStatusMessage: str?}} # OK
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: An internal error has occurred during instance creation.}

@endpoint DELETE /scripts/instances/{instanceId}
@desc Deletes a script instance.
@required {instanceId: str # Instance Id of script instance to be returned.}
@returns(200) OK
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database or in memory.}

@endpoint PUT /scripts/instances/{instanceId}/data
@desc Updates custom data of a given script instance which includes its display name.
@required {instanceId: str # InstanceId of the script to be updated.}
@optional {instanceId: str, scriptName: str, customScriptName: str, customScriptDescription: str}
@returns(200) {config: any?, webhookUrl: str?, eventSourceId: str?, instanceId: str?, scriptId: str?, scriptName: str?, customScriptName: str?, customScriptDescription: str?, subscriptionId: str?, teamId: str?, eventPattern: any?, lastModified: str(date-time)?, enabled: bool, runtimeInformation: map{runtimeStatus: int(int32), runtimeStatusMessage: str?}} # OK
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database., 500: An internal error has occurred during instance creation.}

@endpoint POST /scripts/instances/{instanceId}/disable
@desc Disables a given script instance.
@required {instanceId: str # Id of the instance to be disabled.}
@returns(200) {config: any?, webhookUrl: str?, eventSourceId: str?, instanceId: str?, scriptId: str?, scriptName: str?, customScriptName: str?, customScriptDescription: str?, subscriptionId: str?, teamId: str?, eventPattern: any?, lastModified: str(date-time)?, enabled: bool, runtimeInformation: map{runtimeStatus: int(int32), runtimeStatusMessage: str?}} # OK
@errors {400: Bad Request, 404: Not Found, 500: Internal Server Error}

@endpoint POST /scripts/instances/{instanceId}/enable
@desc Enables a script instance.
@required {instanceId: str # Id of the instance to be enabled.}
@returns(200) {config: any?, webhookUrl: str?, eventSourceId: str?, instanceId: str?, scriptId: str?, scriptName: str?, customScriptName: str?, customScriptDescription: str?, subscriptionId: str?, teamId: str?, eventPattern: any?, lastModified: str(date-time)?, enabled: bool, runtimeInformation: map{runtimeStatus: int(int32), runtimeStatusMessage: str?}} # OK
@errors {400: Bad Request, 404: Not Found, 500: Internal Server Error}

@endpoint GET /scripts/inventory
@desc Returns all available inventory scripts which can be added to a SIGNL4 subscription.
@returns(200) OK
@errors {400: Required information could not be found in the request/claims., 500: An internal error occurred while loading all inventory scripts.}

@endpoint GET /scripts/inventory/parsed
@desc Returns all inventory scripts.
@optional {language: str}
@returns(200) OK
@errors {400: Bad Request, 500: Internal Server Error}

@endpoint GET /scripts/inventory/parsed/{scriptId}
@desc Returns an inventory script by its id.
@required {scriptId: str # The Id of the script to be returned.}
@optional {language: str}
@returns(200) {config: any?, webhookUrl: str?, eventSourceId: str?, instanceId: str?, scriptId: str?, scriptName: str?, customScriptName: str?, customScriptDescription: str?, subscriptionId: str?, teamId: str?, eventPattern: any?, lastModified: str(date-time)?, enabled: bool, runtimeInformation: map{runtimeStatus: int(int32), runtimeStatusMessage: str?}} # OK
@errors {400: Required information could not be found in the request/claims., 404: Required entities could not be found in the database or in memory.}

@endgroup

@group subscriptions
@endpoint GET /subscriptions
@desc Get infos of all available/managed subscriptions.
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /subscriptions/{subscriptionId}
@desc Get infos of a specific subscription.
@required {subscriptionId: str # ID of the subscription that's to be retrieved.}
@returns(200) {branchId: str?, country: str?, createdAt: str(date-time), currency: str?, externalAccountId: str?, id: str?, name: str?, nextBilling: str(date-time)?, ownerId: str?, planCode: str?, planState: int(int32), referralEnabled: bool, isBetaMember: bool, elmEnabled: bool, status: int(int32)} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /subscriptions/{subscriptionId}/channelPrices
@desc Returns the subscription's channel price information.
@required {subscriptionId: str # ID of the subscription that needs to be retrieved.}
@returns(200) {sms: int(int32), voicePerMinute: int(int32)} # OK
@errors {400: Bad Request, 404: Not Found, 500: Internal Server Error}

@endpoint GET /subscriptions/{subscriptionId}/features
@desc Returns the features of a specified subscription.
@required {subscriptionId: str # ID of the subscription from which the features need to be retrieved.}
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /subscriptions/{subscriptionId}/inboundVoiceNumberLicenses
@desc Gets a subscription's voice number licenses.
@required {subscriptionId: str # ID of the subscription}
@returns(200) {currentUsers: int(int32), licensedUsers: int(int32), planCode: str?, isTrial: bool, isFree: bool} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /subscriptions/{subscriptionId}/prepaidBalance
@desc Get a subscription's current prepaid balance.
@required {subscriptionId: str}
@returns(200) {balance: int(int32), latestTopUp: str(date-time)?, pendingTransactions: bool} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /subscriptions/{subscriptionId}/prepaidSettings
@desc Get a subscription's current prepaid settings.
@required {subscriptionId: str}
@returns(200) {topUpAmount: int(int32), topUpEnabled: bool, topUpLimit: int(int32)} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /subscriptions/{subscriptionId}/prepaidTransactions
@desc Get a subscription's prepaid transactions.
@required {subscriptionId: str # ID of the subscription to get transactions for}
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint PUT /subscriptions/{subscriptionId}/profile
@desc Updates a subscriptions profile.
@required {subscriptionId: str # ID of the subscription to be updated}
@optional {name: str}
@returns(200) {branchId: str?, country: str?, createdAt: str(date-time), currency: str?, externalAccountId: str?, id: str?, name: str?, nextBilling: str(date-time)?, ownerId: str?, planCode: str?, planState: int(int32), referralEnabled: bool, isBetaMember: bool, elmEnabled: bool, status: int(int32)} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /subscriptions/{subscriptionId}/settings
@desc Gets a subscription's global settings.
@required {subscriptionId: str # ID of the subscription}
@returns(200) {currentUsers: int(int32), licensedUsers: int(int32), planCode: str?, isTrial: bool, isFree: bool} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint PUT /subscriptions/{subscriptionId}/settings
@desc Updates a subscriptions global settings.
@required {subscriptionId: str # ID of the subscription to be updated}
@optional {socialFeed: int(int32)(0/1/2) # 0 = Disabled1 = Twitter2 = Reddit, customRetention: map{days: int(int32), enabled: bool}, allowedIdProviders: int(int32)(0/1/2/4/8/14/15) # 0 = None1 = Custom2 = EntraID4 = Google8 = Apple14 = ExternalOnly15 = All, sms: map{rcsEnabled: bool}, disableInvites: bool}
@returns(200) {socialFeed: int(int32), customRetention: map{days: int(int32)?, enabled: bool}, allowedIdProviders: int(int32), sms: map{rcsEnabled: bool}, disableInvites: bool?} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /subscriptions/{subscriptionId}/teams
@desc Get infos for all teams of the subscription.
@required {subscriptionId: str}
@returns(200) OK
@errors {400: Bad Request, 404: Not Found, 500: Internal Server Error}

@endpoint GET /subscriptions/{subscriptionId}/userLicenses
@desc Gets a subscription's user licenses.
@required {subscriptionId: str # ID of the subscription}
@returns(200) {currentUsers: int(int32), licensedUsers: int(int32), planCode: str?, isTrial: bool, isFree: bool} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endgroup

@group teams
@endpoint GET /teams
@desc Get infos of all teams.
@returns(200) OK
@errors {400: Bad Request, 404: Not Found, 500: Internal Server Error}

@endpoint POST /teams
@desc Adds another team to the subscription of the user
@optional {language: str, name: str, description: str, timezone: str, createWebhookEndpoint: bool, createEmailEndpoint: bool}
@returns(200) {id: str?, memberIds: [str]?, name: str?, externalName: str?, description: str?, subscriptionId: str?, timezone: str?, imageLastModified: str(date-time)?, imageWebLastModified: str(date-time)?, options: int(int32)} # OK
@errors {400: Bad Request, 403: Forbidden, 500: Internal Server Error}

@endpoint GET /teams/{teamId}
@desc Gets infos of a specific team.
@required {teamId: str # ID of the team that should be retrieved.}
@returns(200) {id: str?, memberIds: [str]?, name: str?, externalName: str?, description: str?, subscriptionId: str?, timezone: str?, imageLastModified: str(date-time)?, imageWebLastModified: str(date-time)?, options: int(int32)} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint DELETE /teams/{teamId}
@desc Deletes a team from the subscription.
@required {teamId: str # ID of the team which should be deleted}
@returns(200) {id: str?, memberIds: [str]?, name: str?, externalName: str?, description: str?, subscriptionId: str?, timezone: str?, imageLastModified: str(date-time)?, imageWebLastModified: str(date-time)?, options: int(int32)} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /teams/{teamId}/alertReports
@desc Get information about downloadable alert reports
@required {teamId: str # ID of team you want to download reports from.}
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /teams/{teamId}/alertReports/{fileName}
@desc Returns Alert Report
@required {teamId: str # ID of team you want to get the duty report file infos for., fileName: str # File name of file you want to download.}
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /teams/{teamId}/alertSettings
@desc Gets alert settings of a specific team.
@required {teamId: str # ID of the team the settings should be retrieved for.}
@returns(200) {escEnabled: bool, escMode: int(int32), escRefId: str?, filterMode: int(int32), filterAction: int(int32), responseMode: int(int32), responseTime: int(int32), tierResponseTime: int(int32), persNotMode: int(int32), persNotInterval: int(int32), optOut: int(int32), overrideNotificationProfiles: bool, notificationProfileOverrides: [map]?, signalingMode: int(int32)} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint POST /teams/{teamId}/alertSettings
@desc Sets alert settings of a specific team.
@required {teamId: str # ID of the team the settings should be set for.}
@optional {escEnabled: bool, escMode: int(int32)(0/1) # 0 = Manager1 = Team, escRefId: str, filterMode: int(int32)(0/1) # 0 = Off1 = WhiteListAllCategories, filterAction: int(int32)(0/1/2) # 0 = Suppress1 = Hide2 = Mute, responseMode: int(int32)(2/4) # 2 = SingleAcknowledge4 = MultiAcknowledge, responseTime: int(int32), tierResponseTime: int(int32), persNotMode: int(int32)(0/1) # 0 = Off1 = Summary, persNotInterval: int(int32), optOut: int(int32)(0/1/2) # 0 = None1 = Disabled2 = Personal, overrideNotificationProfiles: bool, notificationProfileOverrides: [map{channel: int(int32), delay: int(int32), enabled: bool}], signalingMode: int(int32)(0/1) # 0 = Suppressed1 = Full}
@returns(200) {escEnabled: bool, escMode: int(int32), escRefId: str?, filterMode: int(int32), filterAction: int(int32), responseMode: int(int32), responseTime: int(int32), tierResponseTime: int(int32), persNotMode: int(int32), persNotInterval: int(int32), optOut: int(int32), overrideNotificationProfiles: bool, notificationProfileOverrides: [map]?, signalingMode: int(int32)} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /teams/{teamId}/dutyReports
@desc Get Information about downloadable reports
@required {teamId: str # ID of team you want to get the duty report file infos for.}
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /teams/{teamId}/dutyReports/{fileName}
@desc Download duty report with a specific fileName
@required {teamId: str # ID of team you want to download the duty report for., fileName: str # Filename of the csv to download.}
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /teams/{teamId}/dutysummary
@desc Get duty assistant info for a team
@required {teamId: str # ID of the team the duty belongs to.}
@optional {lastTwoDuties: bool}
@returns(200) {dutyAssistEnabled: bool, dutySummaries: [map]?, teamId: str?} # OK
@errors {400: Bad Request, 500: Internal Server Error}

@endpoint GET /teams/{teamId}/eventSources
@desc Gets event sources of a specific team.
@required {teamId: str # ID of the team the sources should be retrieved for.}
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /teams/{teamId}/memberships
@desc Get all invites of a team.
@required {teamId: str # Team ID of team you want to request.}
@returns(200) User invitations are returned.
@returns(204) Request was canceled.
@errors {400: Required parameters or authentication info could not be found in the request/claims., 403: You're not allowed to request the access all required entities., 404: Required entities could not be found in the database., 500: Internal Server Error}

@endpoint POST /teams/{teamId}/memberships
@desc Invite users to a team
@required {teamId: str # Id of team the user should be invited to., invites: [map{email: str, roleId: str}]}
@optional {inviterId: str}
@returns(200) User invitation results are returned.
@returns(204) Request was canceled.
@errors {400: Required parameters or authentication info could not be found in the request/claims., 403: You're not allowed to request the access all required entities., 404: Required entities could not be found in the database., 500: Internal Server Error}

@endpoint PUT /teams/{teamId}/memberships/{userId}
@desc Update user's team membership.
@required {teamId: str # Team the user you want to update belongs to at the moment., userId: str # User ID of user you want to update.}
@optional {requesterUserId: str # User ID of user which you want to change role with. This must be provided when using an
 api key. This user must have role administrator (for setting administrator role) or team administrator (for setting
 rights., setUserOnDuty: bool=true # Sets new duty status for user if user is moved to a different team. User is on duty be default., teamId: str, roleId: str, isValid: bool}
@returns(200) {colorIndex: int(int32), contactAddresses: [any]?, dutyInfos: map{lastChange: str(date-time)?, onDuty: bool, onManagerDuty: bool, overdue: bool, teamId: str?, userId: str?}, isDeactivated: bool, isEnabled: bool, subscriptionId: str?, userImageLastModified: str(date-time)?, timeZone: str?, lastSeen: str(date-time)?, isRemoteActionPinSet: bool, externalAuthProvider: str?, webLanguage: int(int32), options: int(int32), id: str?, name: str?, isInvite: bool, mail: str?, roleId: str?} # User was successfully updated.
@returns(204) Request was canceled.
@errors {400: Required parameters or authentication info could not be found in the request/claims., 403: You're not allowed to request the access all required entities., 404: Required entities could not be found in the database., 500: Internal Server Error}

@endpoint DELETE /teams/{teamId}/memberships/{userId}
@desc Removes a user or invitation from a team
@required {teamId: str # ID of the team the user should be deleted from, userId: str # ID of the user that should be deleted}
@optional {requesterUserId: str # User ID of user which will remove the other user.}
@returns(200) Success message
@returns(204) Request was canceled.
@errors {400: Required parameters or authentication info could not be found in the request/claims., 403: You're not allowed to request the access all required entities., 404: Required entities could not be found in the database., 500: Internal Server Error}

@endpoint POST /teams/{teamId}/memberships/resendInviteMail
@desc Sends invite email again if an invite exists
@required {teamId: str # Team ID of team with invited user., userMail: str}
@optional {inviterId: str}
@returns(200) OK
@errors {403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint PUT /teams/{teamId}/profile
@desc Updates team profile of a team
@required {teamId: str # Team ID of team which should be updated.}
@optional {name: str, description: str}
@returns(200) {id: str?, memberIds: [str]?, name: str?, externalName: str?, description: str?, subscriptionId: str?, timezone: str?, imageLastModified: str(date-time)?, imageWebLastModified: str(date-time)?, options: int(int32)} # OK
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 500: Internal Server Error}

@endpoint GET /teams/{teamId}/schedules
@desc Returns information about all duties that belong to the team.
@required {teamId: str # Id of the team the schedules user belongs to}
@optional {UserId: str, MinDate: str(date-time), Limit: int(int32), MergeOverlap: bool}
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint POST /teams/{teamId}/schedules
@desc Create/Update given duty schedule.
@required {teamId: str # Id of the team the duty is to be assigned to.}
@optional {end: str(date-time), id: str, options: int(int32), start: str(date-time), userId: str}
@returns(200) {end: str(date-time), id: str?, options: int(int32), start: str(date-time), userId: str?} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 409: Conflict, 500: Internal Server Error}

@endpoint DELETE /teams/{teamId}/schedules/{dutyId}
@desc Delete a specific duty.
@required {teamId: str # ID of the team the duty belongs to., dutyId: str # ID of the duty to be deleted.}
@returns(204) No Content
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint GET /teams/{teamId}/schedules/{scheduleId}
@desc Returns information of the duty schedule with the specified Id.
@required {teamId: str # Id of the team the duty belongs to, scheduleId: str # Id of the requested duty schedule.}
@returns(200) {end: str(date-time), id: str?, options: int(int32), start: str(date-time), userId: str?} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint POST /teams/{teamId}/schedules/deleteRange
@desc Delete duty schedules in range
@required {teamId: str # Team ID you want to delete}
@optional {from: str(date-time), to: str(date-time)}
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 409: Conflict, 500: Internal Server Error}

@endpoint POST /teams/{teamId}/schedules/multiple
@desc Save multiple schedules. It is possible to override existing schedules if you wish
@required {teamId: str # Team ID to set}
@optional {overrideExisting: bool # Override or cut existing schedules if set to true.}
@returns(200) OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 409: Conflict, 500: Internal Server Error}

@endpoint GET /teams/{teamId}/setupProgress
@desc Gets setup progress of a specific team.
@required {teamId: str # ID of the team the progress should be retrieved for.}
@returns(200) {teamId: str?, timestamp: str(date-time), completedSteps: [str]?} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endgroup

@group users
@endpoint GET /users
@desc Get all Users
@returns(200) User could be successfully identified.
@errors {400: Required authentifaction info could not be found in the request/claims., 403: You're not allowed to request the users with their information., 404: Required entities could not be found in the database.}

@endpoint GET /users/{userId}
@desc Get User by Id
@required {userId: str # Identifier of the user to get. Use 'Me' to get information about the currently logged in user. This is not possible
 with an api key.
 Can also be an email address of a user in the team or the unique id of an according user object.”}
@returns(200) {colorIndex: int(int32), contactAddresses: [any]?, dutyInfos: map{lastChange: str(date-time)?, onDuty: bool, onManagerDuty: bool, overdue: bool, teamId: str?, userId: str?}, isDeactivated: bool, isEnabled: bool, subscriptionId: str?, userImageLastModified: str(date-time)?, timeZone: str?, lastSeen: str(date-time)?, isRemoteActionPinSet: bool, externalAuthProvider: str?, webLanguage: int(int32), options: int(int32), id: str?, name: str?, isInvite: bool, mail: str?, roleId: str?} # User could be successfully identified.
@errors {400: Required authentication info could not be found in the request/claims., 403: You're not allowed to request that user's information., 404: Required entities could not be found in the database.}

@endpoint DELETE /users/{userId}
@desc Deletes user account.
@required {userId: str # ID of the user to be deleted.}
@returns(204) No Content
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endpoint PUT /users/{userId}/changePassword
@desc Updates the password of a user
@required {userId: str # User ID of user whose password should be changed.}
@optional {currentPassword: str, newPassword: str}
@returns(200) OK
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 500: Internal Server Error}

@endpoint POST /users/{userId}/checkPermissions
@desc Checks if a user has the provided permission.
@required {userId: str # ID of the user to check permissions for.}
@optional {teamId: str, items: [str]}
@returns(200) {items: [map]?} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found}

@endpoint GET /users/{userId}/dutyStatus
@desc Get duty status by user Id
@required {userId: str # Identifier of the user to get. Use 'Me' to get information about the currently logged in user. This is not possible
 with an api key.
 Can also be an email address of a user in the team or the unique id of an according user object.”}
@returns(200) {lastChange: str(date-time)?, onDuty: bool, onManagerDuty: bool, overdue: bool, teamId: str?, userId: str?} # Duty successfully loaded.
@errors {400: Required authentifaction info could not be found in the request/claims., 403: You're not allowed to request that duty information., 404: Required entities could not be found in the database.}

@endpoint GET /users/{userId}/image
@required {userId: str}
@optional {height: int(int32), width: int(int32)}
@returns(200) {content: str(byte)?, contentDispostion: str?, contentEncoding: str?, contentType: str?, lastModified: str(date-time)?, name: str?} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found}

@endpoint POST /users/{userId}/image
@desc Uploaded a profile image for a specified user.
@required {userId: str # Id of the user.}
@returns(204) The image was successfully uploaded.
@errors {400: Either a passed parameter was either empty/null or the request's multipart does not contain a
 file., 403: User is not allowed to upload an image for the specified user., 404: Either the user was not found or they aren't activated yet., 500: Internal general error occured.}

@endpoint POST /users/{userId}/location
@desc Set location of an user
@required {userId: str # ID of user.}
@optional {latitude: num(double), longitude: num(double), timestamp: str(date-time)}
@returns(200) {latitude: num(double), longitude: num(double), timestamp: str(date-time)?} # OK
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 500: Internal Server Error}

@endpoint PUT /users/{userId}/profile
@desc Updates user profile of an user
@required {userId: str # ID of user to update.}
@optional {name: str, timeZone: str, language: int(int32)(0/1/2) # 0 = BrowserBased1 = EN2 = DE}
@returns(200) {colorIndex: int(int32), contactAddresses: [any]?, dutyInfos: map{lastChange: str(date-time)?, onDuty: bool, onManagerDuty: bool, overdue: bool, teamId: str?, userId: str?}, isDeactivated: bool, isEnabled: bool, subscriptionId: str?, userImageLastModified: str(date-time)?, timeZone: str?, lastSeen: str(date-time)?, isRemoteActionPinSet: bool, externalAuthProvider: str?, webLanguage: int(int32), options: int(int32), id: str?, name: str?, isInvite: bool, mail: str?, roleId: str?} # OK
@errors {400: Bad Request, 401: Unauthorized, 403: Forbidden, 500: Internal Server Error}

@endpoint POST /users/{userId}/punchIn
@desc Punch User in
@required {userId: str # Identifier of the user to punch in. Use 'Me' to get information about the currently logged in
 user. This is not possible with an api key. Can also be an email address of a user in the team or the unique id of
 an according user object.”}
@returns(200) {lastChange: str(date-time)?, onDuty: bool, onManagerDuty: bool, overdue: bool, teamId: str?, userId: str?} # OK
@errors {400: Required information could not be found in the request/claims., 403: The user tried to change the punch in a different user., 404: Required entities could not be found in the database.}

@endpoint POST /users/{userId}/punchInAsManager
@desc Punch User in as Manager
@required {userId: str # Identifier of the user to punch in. Use 'Me' to get information about the currently logged in
 user. This is not possible with an api key. Can also be an email address of a user in the team or the unique id of
 an according user object.”}
@returns(200) {lastChange: str(date-time)?, onDuty: bool, onManagerDuty: bool, overdue: bool, teamId: str?, userId: str?} # OK
@errors {400: Required information could not be found in the request/claims., 403: The user tried to change the punch in a different user., 404: Required entities could not be found in the database.}

@endpoint POST /users/{userId}/punchOut
@required {userId: str}
@returns(200) {lastChange: str(date-time)?, onDuty: bool, onManagerDuty: bool, overdue: bool, teamId: str?, userId: str?} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 409: Conflict}

@endpoint GET /users/{userId}/setupProgress
@desc Gets setup progress of a specific user.
@required {userId: str # ID of the user the progress should be retrieved for.}
@returns(200) {userId: str?, timestamp: str(date-time), completedSteps: [str]?} # OK
@errors {400: Bad Request, 403: Forbidden, 404: Not Found, 500: Internal Server Error}

@endgroup

@group webhooks
@endpoint GET /webhooks
@desc Get Webhooks
@optional {teamId: str}
@returns(200) Request was successful and response body contains information about all outbound webhooks in the subscription.
@errors {404: The subscription does not have any outbound webhooks., 500: Internal has occured. The response body may contain more information.}

@endpoint POST /webhooks
@desc Create Webhook
@required {extUrl: str, name: str}
@optional {teamId: str, description: str, enabled: bool}
@returns(201) Action was successful and response contains the id of the newly created webhook.
@errors {400: Either the webhook object or a necessary property was invalid or empty., 500: Internal has occured. The response body may contain more information.}

@endpoint GET /webhooks/{webhookId}
@desc Get Webhook by Id
@required {webhookId: str # Id of the outbound webhook to be retrieved.}
@returns(200) {id: str?, subId: str?, teamId: str?, extUrl: str, name: str, description: str?, enabled: bool} # Request was successful and response body contains information about the requested webhook.
@errors {400: The passed webhook id was either empty or null., 404: The webhook was not found., 500: Internal has occured. The response body may contain more information.}

@endpoint PUT /webhooks/{webhookId}
@desc Update Webhook by Id
@required {webhookId: str # Id of the outbound webhook to be updated., extUrl: str, name: str}
@optional {teamId: str, description: str, enabled: bool}
@returns(200) {id: str?, subId: str?, teamId: str?, extUrl: str, name: str, description: str?, enabled: bool} # Update was successful and response body contains the updated webhook details.
@errors {400: A passed parameter was either empty or null., 404: Webhook with specified id was not found., 500: Internal has occured. The response body may contain more information.}

@endpoint DELETE /webhooks/{webhookId}
@desc Delete Webhook by Id
@required {webhookId: str # Id of the outbound webhook that will be deleted.}
@returns(200) Webhook was successfully deleted.
@errors {400: The passed webhook id was invalid or empty., 404: Webhook with specified id was not found., 500: Internal has occured. The response body may contain more information.}

@endpoint POST /webhooks/{webhookId}/disable
@desc Ability to enable a webHook.
@required {webhookId: str # Webhook ID for webhook which should be disabled.}
@returns(200) {id: str?, subId: str?, teamId: str?, extUrl: str, name: str, description: str?, enabled: bool} # Disable was successful and response body contains the webhook details.
@errors {400: A passed parameter was either empty or null., 404: Webhook with specified id was not found., 500: Internal has occured. The response body may contain more information.}

@endpoint POST /webhooks/{webhookId}/enable
@desc Ability to disable a webHook.
@required {webhookId: str # Webhook ID for webhook which should be enabled.}
@returns(200) {id: str?, subId: str?, teamId: str?, extUrl: str, name: str, description: str?, enabled: bool} # OK
@errors {400: Bad Request, 404: Not Found, 500: Internal Server Error}

@endgroup

@end