Menu
Grafana Cloud

Reference

This page describes the entire API surface in detail.

Services

The Grafana Incident JSON/HTTP RPC API is made up of the following services:

  • ActivityService - ActivityService provides access to incident activity. You can post notes to the timeline, and query and update the individual timeline items.
  • IncidentsService - IncidentsService provides the ability to query, get, declare (create), update, and manage Incidents programatically. You can also assign roles and update labels.
  • IntegrationService - IntegrationService is used to install Integrations, and wire up hooks.
  • RolesService - RolesService defines the interface for interacting with roles, providing CRUD operations and more fatures related to roles.
  • TasksService - TasksService provides methods for managing tasks relating to Incidents.
  • UsersService - UsersService provides services related to people in the system.

ActivityService

ActivityService provides access to incident activity. You can post notes to the timeline, and query and update the individual timeline items.

AddActivity

AddActivity posts an activity item to an Incident.

AddActivityRequest

  • incidentID - string - IncidentID is the unique identifier of the Incident.
  • activityKind - string - options: "userNote" - ActivityKind is the type of activity this item represents.
  • body - string - Body is a human readable description of the ActivityItem. URLs mentioned will be parsed and attached as context.
  • eventTime - string - EventTime is the time when the event occurred. If empty, the current time is used. The string value format should follow RFC 3339.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.AddActivity" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"activityKind": "userNote",
	"body": "Some interesting insights from a third-party system",
	"eventTime": "2021-08-07T11:58:23Z",
	"incidentID": "incident-123"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	activityService := incident.NewActivityService(client)
	// make the request...
	addActivityResp, err := activityService.AddActivity(ctx, main.AddActivityRequest{
		IncidentID: "incident-123",
		ActivityKind: "userNote",
		Body: "Some interesting insights from a third-party system",
		EventTime: "2021-08-07T11:58:23Z",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("ActivityItem: %+v\n", addActivityResp.ActivityItem)
	log.Printf("Error: %+v\n", addActivityResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.AddActivity
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"activityKind": "userNote",
	"body": "Some interesting insights from a third-party system",
	"eventTime": "2021-08-07T11:58:23Z",
	"incidentID": "incident-123"
}
JavaScript
import { GrafanaIncidentClient, ActivityService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const activityService = new ActivityService(client);

// AddActivity posts an activity item to an Incident.
const activityServiceResp = await activityService.addActivity({
	"activityKind": "userNote",
	"body": "Some interesting insights from a third-party system",
	"eventTime": "2021-08-07T11:58:23Z",
	"incidentID": "incident-123"
});

if (!activityServiceResp.success) {
  // handle the error
  throw new Error(activityServiceResp.error);
}

// access the fields of the response
console.info({"activityItem", activityServiceResp.data.activityItem});

AddActivityResponse

A 200 response with an empty error field indicates that the request was successful.

  • activityItem - ActivityItem - ActivityItem is the newly created ActivityItem.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"activityItem": {
		"activityItemID": "activity-item-123",
		"activityKind": "incidentCreated",
		"attachments": [
			{
				"attachedByUserID": "user-123",
				"attachmentErr": "file too large",
				"attachmentID": "attachment-123",
				"contentLength": 123456,
				"contentType": "image/jpeg",
				"deletedTime": "2019-01-01T00:00:00Z",
				"displayType": "list",
				"downloadURL": "https://somewhere.com/path/to/filename.jpg",
				"ext": ".jpg",
				"fileType": "image",
				"hasThumbnail": true,
				"path": "filename.jpg",
				"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
				"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
				"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
				"uploadTime": "2019-01-01T00:00:00Z",
				"useSourceURL": true
			},
			{
				"attachedByUserID": "user-123",
				"attachmentErr": "file too large",
				"attachmentID": "attachment-123",
				"contentLength": 123456,
				"contentType": "image/jpeg",
				"deletedTime": "2019-01-01T00:00:00Z",
				"displayType": "list",
				"downloadURL": "https://somewhere.com/path/to/filename.jpg",
				"ext": ".jpg",
				"fileType": "image",
				"hasThumbnail": true,
				"path": "filename.jpg",
				"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
				"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
				"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
				"uploadTime": "2019-01-01T00:00:00Z",
				"useSourceURL": true
			}
		],
		"body": "The incident was created by user-123",
		"createdTime": "2021-08-07T11:58:23Z",
		"eventTime": "2021-08-07T11:58:23Z",
		"fieldValues": {
			"something-else": true,
			"title": "new title"
		},
		"immutable": true,
		"incidentID": "incident-123",
		"relevance": "low",
		"subjectUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"tags": [
			"important"
		],
		"url": "https://meet.google.com/my-incident-room",
		"user": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		}
	},
	"error": "something went wrong"
}

QueryActivity

QueryActivity gets a selection of activity items.

QueryActivityRequest

  • query - ActivityQuery - Query describes the query to make.
  • cursor - Cursor - Cursor is used to page through results. Empty for the first page. For subsequent pages, use previously returned Cursor values.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.QueryActivity" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"query": {
		"activityKind": [
			"incidentCreated"
		],
		"incidentID": "incident-123",
		"limit": 10,
		"orderDirection": "ASC",
		"tag": "important"
	}
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	activityService := incident.NewActivityService(client)
	// make the request...
	queryActivityResp, err := activityService.QueryActivity(ctx, main.QueryActivityRequest{
		Query: main.ActivityQuery{
			IncidentID: "incident-123",
			Limit: 10,
			Tag: "important",
			OrderDirection: "ASC",
			ActivityKind: ["incidentCreated"],
		},
		Cursor: main.Cursor{
			NextValue: "aaaabbbbccccddddeeeeffffgggg",
			HasMore: true,
		},
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("ActivityItems: %+v\n", queryActivityResp.ActivityItems)
	log.Printf("Query: %+v\n", queryActivityResp.Query)
	log.Printf("Cursor: %+v\n", queryActivityResp.Cursor)
	log.Printf("Error: %+v\n", queryActivityResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.QueryActivity
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"query": {
		"activityKind": [
			"incidentCreated"
		],
		"incidentID": "incident-123",
		"limit": 10,
		"orderDirection": "ASC",
		"tag": "important"
	}
}
JavaScript
import { GrafanaIncidentClient, ActivityService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const activityService = new ActivityService(client);

// QueryActivity gets a selection of activity items.
const activityServiceResp = await activityService.queryActivity({
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"query": {
		"activityKind": [
			"incidentCreated"
		],
		"incidentID": "incident-123",
		"limit": 10,
		"orderDirection": "ASC",
		"tag": "important"
	}
});

if (!activityServiceResp.success) {
  // handle the error
  throw new Error(activityServiceResp.error);
}

// access the fields of the response
console.info({"activityItems", activityServiceResp.data.activityItems});
console.info({"query", activityServiceResp.data.query});
console.info({"cursor", activityServiceResp.data.cursor});

QueryActivityResponse

A 200 response with an empty error field indicates that the request was successful.

  • activityItems - array of ActivityItem - ActivityItems is the list of items.
  • query - ActivityQuery - Query is the query that was used to generate the response.
  • cursor - Cursor - Cursor is used to page through results. Empty for the first page. For subsequent pages, use previously returned Cursor values.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"activityItems": [
		{
			"activityItemID": "activity-item-123",
			"activityKind": "incidentCreated",
			"attachments": [
				{
					"attachedByUserID": "user-123",
					"attachmentErr": "file too large",
					"attachmentID": "attachment-123",
					"contentLength": 123456,
					"contentType": "image/jpeg",
					"deletedTime": "2019-01-01T00:00:00Z",
					"displayType": "list",
					"downloadURL": "https://somewhere.com/path/to/filename.jpg",
					"ext": ".jpg",
					"fileType": "image",
					"hasThumbnail": true,
					"path": "filename.jpg",
					"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
					"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
					"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
					"uploadTime": "2019-01-01T00:00:00Z",
					"useSourceURL": true
				},
				{
					"attachedByUserID": "user-123",
					"attachmentErr": "file too large",
					"attachmentID": "attachment-123",
					"contentLength": 123456,
					"contentType": "image/jpeg",
					"deletedTime": "2019-01-01T00:00:00Z",
					"displayType": "list",
					"downloadURL": "https://somewhere.com/path/to/filename.jpg",
					"ext": ".jpg",
					"fileType": "image",
					"hasThumbnail": true,
					"path": "filename.jpg",
					"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
					"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
					"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
					"uploadTime": "2019-01-01T00:00:00Z",
					"useSourceURL": true
				}
			],
			"body": "The incident was created by user-123",
			"createdTime": "2021-08-07T11:58:23Z",
			"eventTime": "2021-08-07T11:58:23Z",
			"fieldValues": {
				"something-else": true,
				"title": "new title"
			},
			"immutable": true,
			"incidentID": "incident-123",
			"relevance": "low",
			"subjectUser": {
				"name": "Morty Smith",
				"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
				"userID": "user-123"
			},
			"tags": [
				"important"
			],
			"url": "https://meet.google.com/my-incident-room",
			"user": {
				"name": "Morty Smith",
				"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
				"userID": "user-123"
			}
		},
		{
			"activityItemID": "activity-item-123",
			"activityKind": "incidentCreated",
			"attachments": [
				{
					"attachedByUserID": "user-123",
					"attachmentErr": "file too large",
					"attachmentID": "attachment-123",
					"contentLength": 123456,
					"contentType": "image/jpeg",
					"deletedTime": "2019-01-01T00:00:00Z",
					"displayType": "list",
					"downloadURL": "https://somewhere.com/path/to/filename.jpg",
					"ext": ".jpg",
					"fileType": "image",
					"hasThumbnail": true,
					"path": "filename.jpg",
					"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
					"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
					"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
					"uploadTime": "2019-01-01T00:00:00Z",
					"useSourceURL": true
				},
				{
					"attachedByUserID": "user-123",
					"attachmentErr": "file too large",
					"attachmentID": "attachment-123",
					"contentLength": 123456,
					"contentType": "image/jpeg",
					"deletedTime": "2019-01-01T00:00:00Z",
					"displayType": "list",
					"downloadURL": "https://somewhere.com/path/to/filename.jpg",
					"ext": ".jpg",
					"fileType": "image",
					"hasThumbnail": true,
					"path": "filename.jpg",
					"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
					"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
					"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
					"uploadTime": "2019-01-01T00:00:00Z",
					"useSourceURL": true
				}
			],
			"body": "The incident was created by user-123",
			"createdTime": "2021-08-07T11:58:23Z",
			"eventTime": "2021-08-07T11:58:23Z",
			"fieldValues": {
				"something-else": true,
				"title": "new title"
			},
			"immutable": true,
			"incidentID": "incident-123",
			"relevance": "low",
			"subjectUser": {
				"name": "Morty Smith",
				"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
				"userID": "user-123"
			},
			"tags": [
				"important"
			],
			"url": "https://meet.google.com/my-incident-room",
			"user": {
				"name": "Morty Smith",
				"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
				"userID": "user-123"
			}
		}
	],
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"error": "something went wrong",
	"query": {
		"activityKind": [
			"incidentCreated"
		],
		"incidentID": "incident-123",
		"limit": 10,
		"orderDirection": "ASC",
		"tag": "important"
	}
}

RemoveActivity

RemoveActivity removes an activity item.

RemoveActivityRequest

  • incidentID - string - IncidentID is the identifier.
  • activityItemID - string - ActivityItemID is the unique identifier of the ActivityItem.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.RemoveActivity" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"activityItemID": "activity-item-123",
	"incidentID": "incident-123"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	activityService := incident.NewActivityService(client)
	// make the request...
	removeActivityResp, err := activityService.RemoveActivity(ctx, main.RemoveActivityRequest{
		IncidentID: "incident-123",
		ActivityItemID: "activity-item-123",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("ActivityItem: %+v\n", removeActivityResp.ActivityItem)
	log.Printf("Error: %+v\n", removeActivityResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.RemoveActivity
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"activityItemID": "activity-item-123",
	"incidentID": "incident-123"
}
JavaScript
import { GrafanaIncidentClient, ActivityService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const activityService = new ActivityService(client);

// RemoveActivity removes an activity item.
const activityServiceResp = await activityService.removeActivity({
	"activityItemID": "activity-item-123",
	"incidentID": "incident-123"
});

if (!activityServiceResp.success) {
  // handle the error
  throw new Error(activityServiceResp.error);
}

// access the fields of the response
console.info({"activityItem", activityServiceResp.data.activityItem});

RemoveActivityResponse

A 200 response with an empty error field indicates that the request was successful.

  • activityItem - ActivityItem - ActivityItem is the updated ActivityItem.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"activityItem": {
		"activityItemID": "activity-item-123",
		"activityKind": "incidentCreated",
		"attachments": [
			{
				"attachedByUserID": "user-123",
				"attachmentErr": "file too large",
				"attachmentID": "attachment-123",
				"contentLength": 123456,
				"contentType": "image/jpeg",
				"deletedTime": "2019-01-01T00:00:00Z",
				"displayType": "list",
				"downloadURL": "https://somewhere.com/path/to/filename.jpg",
				"ext": ".jpg",
				"fileType": "image",
				"hasThumbnail": true,
				"path": "filename.jpg",
				"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
				"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
				"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
				"uploadTime": "2019-01-01T00:00:00Z",
				"useSourceURL": true
			},
			{
				"attachedByUserID": "user-123",
				"attachmentErr": "file too large",
				"attachmentID": "attachment-123",
				"contentLength": 123456,
				"contentType": "image/jpeg",
				"deletedTime": "2019-01-01T00:00:00Z",
				"displayType": "list",
				"downloadURL": "https://somewhere.com/path/to/filename.jpg",
				"ext": ".jpg",
				"fileType": "image",
				"hasThumbnail": true,
				"path": "filename.jpg",
				"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
				"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
				"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
				"uploadTime": "2019-01-01T00:00:00Z",
				"useSourceURL": true
			}
		],
		"body": "The incident was created by user-123",
		"createdTime": "2021-08-07T11:58:23Z",
		"eventTime": "2021-08-07T11:58:23Z",
		"fieldValues": {
			"something-else": true,
			"title": "new title"
		},
		"immutable": true,
		"incidentID": "incident-123",
		"relevance": "low",
		"subjectUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"tags": [
			"important"
		],
		"url": "https://meet.google.com/my-incident-room",
		"user": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		}
	},
	"error": "something went wrong"
}

UpdateActivityBody

UpdateActivityBody updates the body of a specific activity item.

UpdateActivityBodyRequest

  • incidentID - string - IncidentID is the identifier.
  • activityItemID - string - ActivityItemID is the unique identifier of the ActivityItem.
  • body - string - Body is the new body to use for the given activity item
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.UpdateActivityBody" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"activityItemID": "activity-item-123",
	"body": "New contents",
	"incidentID": "incident-123"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	activityService := incident.NewActivityService(client)
	// make the request...
	updateActivityBodyResp, err := activityService.UpdateActivityBody(ctx, main.UpdateActivityBodyRequest{
		IncidentID: "incident-123",
		ActivityItemID: "activity-item-123",
		Body: "New contents",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("ActivityItem: %+v\n", updateActivityBodyResp.ActivityItem)
	log.Printf("Error: %+v\n", updateActivityBodyResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.UpdateActivityBody
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"activityItemID": "activity-item-123",
	"body": "New contents",
	"incidentID": "incident-123"
}
JavaScript
import { GrafanaIncidentClient, ActivityService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const activityService = new ActivityService(client);

// UpdateActivityBody updates the body of a specific activity item.
const activityServiceResp = await activityService.updateActivityBody({
	"activityItemID": "activity-item-123",
	"body": "New contents",
	"incidentID": "incident-123"
});

if (!activityServiceResp.success) {
  // handle the error
  throw new Error(activityServiceResp.error);
}

// access the fields of the response
console.info({"activityItem", activityServiceResp.data.activityItem});

UpdateActivityBodyResponse

A 200 response with an empty error field indicates that the request was successful.

  • activityItem - ActivityItem - ActivityItem is the updated ActivityItem.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"activityItem": {
		"activityItemID": "activity-item-123",
		"activityKind": "incidentCreated",
		"attachments": [
			{
				"attachedByUserID": "user-123",
				"attachmentErr": "file too large",
				"attachmentID": "attachment-123",
				"contentLength": 123456,
				"contentType": "image/jpeg",
				"deletedTime": "2019-01-01T00:00:00Z",
				"displayType": "list",
				"downloadURL": "https://somewhere.com/path/to/filename.jpg",
				"ext": ".jpg",
				"fileType": "image",
				"hasThumbnail": true,
				"path": "filename.jpg",
				"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
				"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
				"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
				"uploadTime": "2019-01-01T00:00:00Z",
				"useSourceURL": true
			},
			{
				"attachedByUserID": "user-123",
				"attachmentErr": "file too large",
				"attachmentID": "attachment-123",
				"contentLength": 123456,
				"contentType": "image/jpeg",
				"deletedTime": "2019-01-01T00:00:00Z",
				"displayType": "list",
				"downloadURL": "https://somewhere.com/path/to/filename.jpg",
				"ext": ".jpg",
				"fileType": "image",
				"hasThumbnail": true,
				"path": "filename.jpg",
				"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
				"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
				"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
				"uploadTime": "2019-01-01T00:00:00Z",
				"useSourceURL": true
			}
		],
		"body": "The incident was created by user-123",
		"createdTime": "2021-08-07T11:58:23Z",
		"eventTime": "2021-08-07T11:58:23Z",
		"fieldValues": {
			"something-else": true,
			"title": "new title"
		},
		"immutable": true,
		"incidentID": "incident-123",
		"relevance": "low",
		"subjectUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"tags": [
			"important"
		],
		"url": "https://meet.google.com/my-incident-room",
		"user": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		}
	},
	"error": "something went wrong"
}

UpdateActivityEventTime

UpdateActivityEventTime updates the event time of a specific activity item.

UpdateActivityEventTimeRequest

  • incidentID - string - IncidentID is the identifier.
  • activityItemID - string - ActivityItemID is the unique identifier of the ActivityItem.
  • eventTime - string - EventTime is the time when the event occurred. If empty, the created time of the activity item is used. The string value format should follow RFC 3339.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.UpdateActivityEventTime" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"activityItemID": "activity-item-123",
	"eventTime": "2021-08-07T11:58:23Z",
	"incidentID": "incident-123"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	activityService := incident.NewActivityService(client)
	// make the request...
	updateActivityEventTimeResp, err := activityService.UpdateActivityEventTime(ctx, main.UpdateActivityEventTimeRequest{
		IncidentID: "incident-123",
		ActivityItemID: "activity-item-123",
		EventTime: "2021-08-07T11:58:23Z",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("ActivityItem: %+v\n", updateActivityEventTimeResp.ActivityItem)
	log.Printf("Error: %+v\n", updateActivityEventTimeResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.UpdateActivityEventTime
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"activityItemID": "activity-item-123",
	"eventTime": "2021-08-07T11:58:23Z",
	"incidentID": "incident-123"
}
JavaScript
import { GrafanaIncidentClient, ActivityService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const activityService = new ActivityService(client);

// UpdateActivityEventTime updates the event time of a specific activity item.
const activityServiceResp = await activityService.updateActivityEventTime({
	"activityItemID": "activity-item-123",
	"eventTime": "2021-08-07T11:58:23Z",
	"incidentID": "incident-123"
});

if (!activityServiceResp.success) {
  // handle the error
  throw new Error(activityServiceResp.error);
}

// access the fields of the response
console.info({"activityItem", activityServiceResp.data.activityItem});

UpdateActivityEventTimeResponse

A 200 response with an empty error field indicates that the request was successful.

  • activityItem - ActivityItem - ActivityItem is the updated ActivityItem.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"activityItem": {
		"activityItemID": "activity-item-123",
		"activityKind": "incidentCreated",
		"attachments": [
			{
				"attachedByUserID": "user-123",
				"attachmentErr": "file too large",
				"attachmentID": "attachment-123",
				"contentLength": 123456,
				"contentType": "image/jpeg",
				"deletedTime": "2019-01-01T00:00:00Z",
				"displayType": "list",
				"downloadURL": "https://somewhere.com/path/to/filename.jpg",
				"ext": ".jpg",
				"fileType": "image",
				"hasThumbnail": true,
				"path": "filename.jpg",
				"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
				"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
				"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
				"uploadTime": "2019-01-01T00:00:00Z",
				"useSourceURL": true
			},
			{
				"attachedByUserID": "user-123",
				"attachmentErr": "file too large",
				"attachmentID": "attachment-123",
				"contentLength": 123456,
				"contentType": "image/jpeg",
				"deletedTime": "2019-01-01T00:00:00Z",
				"displayType": "list",
				"downloadURL": "https://somewhere.com/path/to/filename.jpg",
				"ext": ".jpg",
				"fileType": "image",
				"hasThumbnail": true,
				"path": "filename.jpg",
				"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
				"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
				"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
				"uploadTime": "2019-01-01T00:00:00Z",
				"useSourceURL": true
			}
		],
		"body": "The incident was created by user-123",
		"createdTime": "2021-08-07T11:58:23Z",
		"eventTime": "2021-08-07T11:58:23Z",
		"fieldValues": {
			"something-else": true,
			"title": "new title"
		},
		"immutable": true,
		"incidentID": "incident-123",
		"relevance": "low",
		"subjectUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"tags": [
			"important"
		],
		"url": "https://meet.google.com/my-incident-room",
		"user": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		}
	},
	"error": "something went wrong"
}

UpdateActivityRelevance

UpdateActivityRelevance sets the relevance of an activity item.

UpdateActivityRelevanceRequest

  • incidentID - string - IncidentID is the identifier.
  • activityItemID - string - ActivityItemID is the unique identifier of the ActivityItem.
  • relevance - string - options: "automatic" "archive" "low" "normal" "high" - Relevance is the preferred relevance of the activity item. if set to ‘automatic’ (the default), the relevance will be guessed automatically.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.UpdateActivityRelevance" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"activityItemID": "activity-item-123",
	"incidentID": "incident-123",
	"relevance": "low"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	activityService := incident.NewActivityService(client)
	// make the request...
	updateActivityRelevanceResp, err := activityService.UpdateActivityRelevance(ctx, main.UpdateActivityRelevanceRequest{
		IncidentID: "incident-123",
		ActivityItemID: "activity-item-123",
		Relevance: "low",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("ActivityItem: %+v\n", updateActivityRelevanceResp.ActivityItem)
	log.Printf("Error: %+v\n", updateActivityRelevanceResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/ActivityService.UpdateActivityRelevance
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"activityItemID": "activity-item-123",
	"incidentID": "incident-123",
	"relevance": "low"
}
JavaScript
import { GrafanaIncidentClient, ActivityService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const activityService = new ActivityService(client);

// UpdateActivityRelevance sets the relevance of an activity item.
const activityServiceResp = await activityService.updateActivityRelevance({
	"activityItemID": "activity-item-123",
	"incidentID": "incident-123",
	"relevance": "low"
});

if (!activityServiceResp.success) {
  // handle the error
  throw new Error(activityServiceResp.error);
}

// access the fields of the response
console.info({"activityItem", activityServiceResp.data.activityItem});

UpdateActivityRelevanceResponse

A 200 response with an empty error field indicates that the request was successful.

  • activityItem - ActivityItem - ActivityItem is the updated ActivityItem.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"activityItem": {
		"activityItemID": "activity-item-123",
		"activityKind": "incidentCreated",
		"attachments": [
			{
				"attachedByUserID": "user-123",
				"attachmentErr": "file too large",
				"attachmentID": "attachment-123",
				"contentLength": 123456,
				"contentType": "image/jpeg",
				"deletedTime": "2019-01-01T00:00:00Z",
				"displayType": "list",
				"downloadURL": "https://somewhere.com/path/to/filename.jpg",
				"ext": ".jpg",
				"fileType": "image",
				"hasThumbnail": true,
				"path": "filename.jpg",
				"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
				"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
				"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
				"uploadTime": "2019-01-01T00:00:00Z",
				"useSourceURL": true
			},
			{
				"attachedByUserID": "user-123",
				"attachmentErr": "file too large",
				"attachmentID": "attachment-123",
				"contentLength": 123456,
				"contentType": "image/jpeg",
				"deletedTime": "2019-01-01T00:00:00Z",
				"displayType": "list",
				"downloadURL": "https://somewhere.com/path/to/filename.jpg",
				"ext": ".jpg",
				"fileType": "image",
				"hasThumbnail": true,
				"path": "filename.jpg",
				"sHA512": "327232b67c88cba87c0a85a32bb192df527c21854d6515144d691f8cf1554f8e9969eed443b85e00d5ea21628c0ca4b6bbc9f26c837815fad6e9b3881cbb5cfd",
				"sourceURL": "https://somewhere-like-slack.com/path/to/filename.jpg",
				"thumbnailURL": "https://somewhere.com/path/to/thumbnail.jpg",
				"uploadTime": "2019-01-01T00:00:00Z",
				"useSourceURL": true
			}
		],
		"body": "The incident was created by user-123",
		"createdTime": "2021-08-07T11:58:23Z",
		"eventTime": "2021-08-07T11:58:23Z",
		"fieldValues": {
			"something-else": true,
			"title": "new title"
		},
		"immutable": true,
		"incidentID": "incident-123",
		"relevance": "low",
		"subjectUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"tags": [
			"important"
		],
		"url": "https://meet.google.com/my-incident-room",
		"user": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		}
	},
	"error": "something went wrong"
}

IncidentsService

IncidentsService provides the ability to query, get, declare (create), update, and manage Incidents programatically. You can also assign roles and update labels.

  • AddLabel - AddLabel adds a label to the Incident.
  • AssignLabel - AssignLabel assigns a key:value label to the incident
  • AssignLabelByUUID - AssignLabelByUUID assigns a keyUUID:valueUUID label to the incident
  • AssignRole - AssignRole assigns a role to a user.
  • CreateIncident - CreateIncident creates a new Incident.
  • GetIncident - GetIncident gets an existing Incident by ID.
  • GetIncidentMembership - GetIncidentMembership will return the full list of people involved in an incident
  • GetLabels - GetLabels get the labels from the incident.
  • QueryIncidentPreviews - QueryIncidentPreviews gets a list of Incident Previews.
  • QueryIncidents - QueryIncidents gets a list of Incidents. (Deprecated: use QueryIncidentPreviews instead.)
  • RemoveLabel - RemoveLabel removes a label from the Incident.
  • UnassignLabel - UnassignLabel unassigns a key:value label from the incident
  • UnassignLabelByUUID - UnassignLabelByUUID unassigns a keyUUID:valueUUID label from the incident
  • UnassignRole - UnassignRole removes a role assignment from a user.
  • UpdateIncidentEventTime - UpdateIncidentEventTime updates the start or end times of an Incident.
  • UpdateIncidentIsDrill - UpdateIncidentIsDrill changes whether an Incident is a drill or not.
  • UpdateSeverity - UpdateSeverity updates the severity of an Incident.
  • UpdateStatus - UpdateStatus updates the status of an Incident.
  • UpdateTitle - UpdateTitle updates the title of an Incident.

AddLabel

AddLabel adds a label to the Incident.

AddLabelRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
  • label - IncidentLabel - Label is the new label of the Incident.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.AddLabel" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"label": {
		"colorHex": "#ff0000",
		"description": "Customers are affected by this incident.",
		"key": "service_name",
		"label": "customers-affected"
	}
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	addLabelResp, err := incidentsService.AddLabel(ctx, main.AddLabelRequest{
		IncidentID: "incident-123",
		Label: main.IncidentLabel{
			Key: "service_name",
			Label: "customers-affected",
			Description: "Customers are affected by this incident.",
			ColorHex: "#ff0000",
		},
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Incident: %+v\n", addLabelResp.Incident)
	log.Printf("Error: %+v\n", addLabelResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.AddLabel
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"label": {
		"colorHex": "#ff0000",
		"description": "Customers are affected by this incident.",
		"key": "service_name",
		"label": "customers-affected"
	}
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// AddLabel adds a label to the Incident.
const incidentsServiceResp = await incidentsService.addLabel({
	"incidentID": "incident-123",
	"label": {
		"colorHex": "#ff0000",
		"description": "Customers are affected by this incident.",
		"key": "service_name",
		"label": "customers-affected"
	}
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incident", incidentsServiceResp.data.incident});

AddLabelResponse

A 200 response with an empty error field indicates that the request was successful.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incident": {
		"closedTime": "2021-08-07T11:58:23Z",
		"createdByUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2021-08-07T11:58:23Z",
		"durationSeconds": 60,
		"heroImagePath": "/relative/path/to/hero/image.png",
		"incidentEnd": "2022-02-11 00:50:20.574137",
		"incidentID": "incident-123",
		"incidentMembership": {
			"assignments": [
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				},
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				}
			],
			"totalAssignments": 5,
			"totalParticipants": 3
		},
		"incidentStart": "2022-02-11 00:50:20.574137",
		"isDrill": true,
		"labels": [
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			},
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			}
		],
		"modifiedTime": "2021-08-07T11:58:23Z",
		"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
		"severity": "minor",
		"status": "active",
		"summary": "Something happened, we found out something interesting, then we fixed it.",
		"taskList": {
			"doneCount": 8,
			"tasks": [
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				},
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				}
			],
			"todoCount": 5
		},
		"title": "high latency in web requests"
	}
}

AssignLabel

AssignLabel assigns a key:value label to the incident

AssignLabelRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
  • key - string - Key is the label key.
  • value - string - Value is the value of the label.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.AssignLabel" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"key": "service_name",
	"value": "customers-affected"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	assignLabelResp, err := incidentsService.AssignLabel(ctx, main.AssignLabelRequest{
		IncidentID: "incident-123",
		Key: "service_name",
		Value: "customers-affected",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Labels: %+v\n", assignLabelResp.Labels)
	log.Printf("Error: %+v\n", assignLabelResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.AssignLabel
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"key": "service_name",
	"value": "customers-affected"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// AssignLabel assigns a key:value label to the incident
const incidentsServiceResp = await incidentsService.assignLabel({
	"incidentID": "incident-123",
	"key": "service_name",
	"value": "customers-affected"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"labels", incidentsServiceResp.data.labels});

AssignLabelResponse

A 200 response with an empty error field indicates that the request was successful.

  • labels - array of IncidentKeyValueLabel - Labels is a list of labels
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"labels": [
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
			"value": "customers-affected",
			"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
		},
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
			"value": "customers-affected",
			"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
		}
	]
}

AssignLabelByUUID

AssignLabelByUUID assigns a keyUUID:valueUUID label to the incident

AssignLabelByUUIDRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
  • keyUUID - string - KeyUUID is the label key uuid.
  • valueUUID - string - ValueUUID is the UUID of the label value.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.AssignLabelByUUID" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
	"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	assignLabelByUUIDResp, err := incidentsService.AssignLabelByUUID(ctx, main.AssignLabelByUUIDRequest{
		IncidentID: "incident-123",
		KeyUUID: "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
		ValueUUID: "3fb1e5d7-3ef2-11ef-b731-deab26f9160f",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Labels: %+v\n", assignLabelByUUIDResp.Labels)
	log.Printf("Error: %+v\n", assignLabelByUUIDResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.AssignLabelByUUID
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
	"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// AssignLabelByUUID assigns a keyUUID:valueUUID label to the incident
const incidentsServiceResp = await incidentsService.assignLabelByUUID({
	"incidentID": "incident-123",
	"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
	"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"labels", incidentsServiceResp.data.labels});

AssignLabelByUUIDResponse

A 200 response with an empty error field indicates that the request was successful.

  • labels - array of IncidentKeyValueLabel - Labels is a list of labels
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"labels": [
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
			"value": "customers-affected",
			"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
		},
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
			"value": "customers-affected",
			"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
		}
	]
}

AssignRole

AssignRole assigns a role to a user.

AssignRoleRequest

  • incidentID - string - IncidentID is the identifier.
  • userID - string - UserID is the identifier of the person to assign the role to.
  • role - string - options: "commander" "investigator" "observer" - Role is the role of this person.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.AssignRole" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"role": "commander",
	"userID": "grafana-incident:user-123"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	assignRoleResp, err := incidentsService.AssignRole(ctx, main.AssignRoleRequest{
		IncidentID: "incident-123",
		UserID: "grafana-incident:user-123",
		Role: "commander",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Incident: %+v\n", assignRoleResp.Incident)
	log.Printf("DidChange: %+v\n", assignRoleResp.DidChange)
	log.Printf("Error: %+v\n", assignRoleResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.AssignRole
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"role": "commander",
	"userID": "grafana-incident:user-123"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// AssignRole assigns a role to a user.
const incidentsServiceResp = await incidentsService.assignRole({
	"incidentID": "incident-123",
	"role": "commander",
	"userID": "grafana-incident:user-123"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incident", incidentsServiceResp.data.incident});
console.info({"didChange", incidentsServiceResp.data.didChange});

AssignRoleResponse

A 200 response with an empty error field indicates that the request was successful.

  • incident - Incident - Incident is the Incident that was just updated.
  • didChange - boolean - DidChange indicates if the role was changed or not. If the role was already assigned, this will be false.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"didChange": true,
	"error": "something went wrong",
	"incident": {
		"closedTime": "2021-08-07T11:58:23Z",
		"createdByUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2021-08-07T11:58:23Z",
		"durationSeconds": 60,
		"heroImagePath": "/relative/path/to/hero/image.png",
		"incidentEnd": "2022-02-11 00:50:20.574137",
		"incidentID": "incident-123",
		"incidentMembership": {
			"assignments": [
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				},
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				}
			],
			"totalAssignments": 5,
			"totalParticipants": 3
		},
		"incidentStart": "2022-02-11 00:50:20.574137",
		"isDrill": true,
		"labels": [
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			},
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			}
		],
		"modifiedTime": "2021-08-07T11:58:23Z",
		"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
		"severity": "minor",
		"status": "active",
		"summary": "Something happened, we found out something interesting, then we fixed it.",
		"taskList": {
			"doneCount": 8,
			"tasks": [
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				},
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				}
			],
			"todoCount": 5
		},
		"title": "high latency in web requests"
	}
}

CreateIncident

CreateIncident creates a new Incident.

CreateIncidentRequest

  • title - string - Title is the headline title of the Incident. Shorter the better, but should contain enough information to be able to identify and refer to this issue.
  • severity - string - Severity expresses how bad the Incident is.
  • labels - array of IncidentLabel - Labels are the labels associated with the Incident. Only the Label string is processed, the other fields are ignored.
  • roomPrefix - string - RoomPrefix is the prefix that will be used to create the Incident room.
  • isDrill - boolean - IsDrill indicates if the Incident is a drill or not. Incidents that are drills do not show up in the dashboards, and may behave subtly differently in other ways too. For example, during drills, more help might be offered to users.
  • status - string - options: "active" "resolved" - Status is the starting status of the Incident. Use “resolved” to open a retrospective incident.
  • attachCaption - string - AttachCaption is the title of associated URL.
  • attachURL - string - AttachURLis the associated URL.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.CreateIncident" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"attachCaption": "Grafana Incident: Powerful incident management, built on top of Grafana",
	"attachURL": "https://grafana.com/products/incident",
	"isDrill": true,
	"labels": [
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"label": "customers-affected"
		},
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"label": "customers-affected"
		}
	],
	"roomPrefix": "incident",
	"severity": "minor",
	"status": "active",
	"title": "High latency in web requests"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	createIncidentResp, err := incidentsService.CreateIncident(ctx, main.CreateIncidentRequest{
		Title: "High latency in web requests",
		Severity: "minor",
		Labels: main.IncidentLabel{
			Key: "service_name",
			Label: "customers-affected",
			Description: "Customers are affected by this incident.",
			ColorHex: "#ff0000",
		},
		RoomPrefix: "incident",
		IsDrill: true,
		Status: "active",
		AttachCaption: "Grafana Incident: Powerful incident management, built on top of Grafana",
		AttachURL: "https://grafana.com/products/incident",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Incident: %+v\n", createIncidentResp.Incident)
	log.Printf("Error: %+v\n", createIncidentResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.CreateIncident
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"attachCaption": "Grafana Incident: Powerful incident management, built on top of Grafana",
	"attachURL": "https://grafana.com/products/incident",
	"isDrill": true,
	"labels": [
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"label": "customers-affected"
		},
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"label": "customers-affected"
		}
	],
	"roomPrefix": "incident",
	"severity": "minor",
	"status": "active",
	"title": "High latency in web requests"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// CreateIncident creates a new Incident.
const incidentsServiceResp = await incidentsService.createIncident({
	"attachCaption": "Grafana Incident: Powerful incident management, built on top of Grafana",
	"attachURL": "https://grafana.com/products/incident",
	"isDrill": true,
	"labels": [
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"label": "customers-affected"
		},
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"label": "customers-affected"
		}
	],
	"roomPrefix": "incident",
	"severity": "minor",
	"status": "active",
	"title": "High latency in web requests"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incident", incidentsServiceResp.data.incident});

CreateIncidentResponse

A 200 response with an empty error field indicates that the request was successful.

  • incident - Incident - Incident is the Incident that was created.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incident": {
		"closedTime": "2021-08-07T11:58:23Z",
		"createdByUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2021-08-07T11:58:23Z",
		"durationSeconds": 60,
		"heroImagePath": "/relative/path/to/hero/image.png",
		"incidentEnd": "2022-02-11 00:50:20.574137",
		"incidentID": "incident-123",
		"incidentMembership": {
			"assignments": [
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				},
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				}
			],
			"totalAssignments": 5,
			"totalParticipants": 3
		},
		"incidentStart": "2022-02-11 00:50:20.574137",
		"isDrill": true,
		"labels": [
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			},
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			}
		],
		"modifiedTime": "2021-08-07T11:58:23Z",
		"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
		"severity": "minor",
		"status": "active",
		"summary": "Something happened, we found out something interesting, then we fixed it.",
		"taskList": {
			"doneCount": 8,
			"tasks": [
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				},
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				}
			],
			"todoCount": 5
		},
		"title": "high latency in web requests"
	}
}

GetIncident

GetIncident gets an existing Incident by ID.

GetIncidentRequest

  • incidentID - string - IncidentID is the identifier.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.GetIncident" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	getIncidentResp, err := incidentsService.GetIncident(ctx, main.GetIncidentRequest{
		IncidentID: "incident-123",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Incident: %+v\n", getIncidentResp.Incident)
	log.Printf("Error: %+v\n", getIncidentResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.GetIncident
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// GetIncident gets an existing Incident by ID.
const incidentsServiceResp = await incidentsService.getIncident({
	"incidentID": "incident-123"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incident", incidentsServiceResp.data.incident});

GetIncidentResponse

A 200 response with an empty error field indicates that the request was successful.

  • incident - Incident - Incident is the Incident.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incident": {
		"closedTime": "2021-08-07T11:58:23Z",
		"createdByUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2021-08-07T11:58:23Z",
		"durationSeconds": 60,
		"heroImagePath": "/relative/path/to/hero/image.png",
		"incidentEnd": "2022-02-11 00:50:20.574137",
		"incidentID": "incident-123",
		"incidentMembership": {
			"assignments": [
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				},
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				}
			],
			"totalAssignments": 5,
			"totalParticipants": 3
		},
		"incidentStart": "2022-02-11 00:50:20.574137",
		"isDrill": true,
		"labels": [
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			},
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			}
		],
		"modifiedTime": "2021-08-07T11:58:23Z",
		"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
		"severity": "minor",
		"status": "active",
		"summary": "Something happened, we found out something interesting, then we fixed it.",
		"taskList": {
			"doneCount": 8,
			"tasks": [
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				},
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				}
			],
			"todoCount": 5
		},
		"title": "high latency in web requests"
	}
}

GetIncidentMembership

GetIncidentMembership will return the full list of people involved in an incident

GetIncidentMembershipRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.GetIncidentMembership" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "1"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	getIncidentMembershipResp, err := incidentsService.GetIncidentMembership(ctx, main.GetIncidentMembershipRequest{
		IncidentID: "1",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Assignments: %+v\n", getIncidentMembershipResp.Assignments)
	log.Printf("Error: %+v\n", getIncidentMembershipResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.GetIncidentMembership
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "1"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// GetIncidentMembership will return the full list of people involved in an incident
const incidentsServiceResp = await incidentsService.getIncidentMembership({
	"incidentID": "1"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"assignments", incidentsServiceResp.data.assignments});

GetIncidentMembershipResponse

A 200 response with an empty error field indicates that the request was successful.

  • assignments - array of Assignment - IncidentMembership is the list of people involved in an incident
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"assignments": [
		{
			"role": {
				"archived": true,
				"createdAt": "2020-01-01T00:00:00Z",
				"description": "The commander is the incident commander.",
				"important": true,
				"mandatory": true,
				"name": "commander",
				"orgID": "org-1",
				"roleID": 1,
				"updatedAt": "2020-01-01T00:00:00Z"
			},
			"roleID": 1,
			"user": {
				"name": "Morty Smith",
				"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
				"userID": "user-123"
			}
		},
		{
			"role": {
				"archived": true,
				"createdAt": "2020-01-01T00:00:00Z",
				"description": "The commander is the incident commander.",
				"important": true,
				"mandatory": true,
				"name": "commander",
				"orgID": "org-1",
				"roleID": 1,
				"updatedAt": "2020-01-01T00:00:00Z"
			},
			"roleID": 1,
			"user": {
				"name": "Morty Smith",
				"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
				"userID": "user-123"
			}
		}
	],
	"error": "something went wrong"
}

GetLabels

GetLabels get the labels from the incident.

GetLabelsRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.GetLabels" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	getLabelsResp, err := incidentsService.GetLabels(ctx, main.GetLabelsRequest{
		IncidentID: "incident-123",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Labels: %+v\n", getLabelsResp.Labels)
	log.Printf("Error: %+v\n", getLabelsResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.GetLabels
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// GetLabels get the labels from the incident.
const incidentsServiceResp = await incidentsService.getLabels({
	"incidentID": "incident-123"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"labels", incidentsServiceResp.data.labels});

GetLabelsResponse

A 200 response with an empty error field indicates that the request was successful.

  • labels - array of IncidentKeyValueLabel - Labels is a list of labels
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"labels": [
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
			"value": "customers-affected",
			"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
		},
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
			"value": "customers-affected",
			"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
		}
	]
}

QueryIncidentPreviews

QueryIncidentPreviews gets a list of Incident Previews.

QueryIncidentPreviewsRequest

  • query - IncidentPreviewsQuery - Query describes the query to make.
  • cursor - Cursor - Cursor is used to page through results. Empty for the first page. For subsequent pages, use previously returned Cursor values.
  • includeCustomFieldValues - boolean - IncludeCustomFieldValues if true will include custom field values in the response.
  • includeMembershipPreview - boolean - IncludeMembershipPreview if true will include membership previews in the response.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.QueryIncidentPreviews" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"includeCustomFieldValues": true,
	"includeMembershipPreview": true,
	"query": {
		"limit": 10,
		"orderDirection": "ASC",
		"orderField": "createdTime",
		"queryString": "isdrill:false or(label:security label:important)"
	}
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	queryIncidentPreviewsResp, err := incidentsService.QueryIncidentPreviews(ctx, main.QueryIncidentPreviewsRequest{
		Query: main.IncidentPreviewsQuery{
			Limit: 10,
			OrderDirection: "ASC",
			OrderField: "createdTime",
			QueryString: "isdrill:false or(label:security label:important)",
		},
		Cursor: main.Cursor{
			NextValue: "aaaabbbbccccddddeeeeffffgggg",
			HasMore: true,
		},
		IncludeCustomFieldValues: true,
		IncludeMembershipPreview: true,
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("IncidentPreviews: %+v\n", queryIncidentPreviewsResp.IncidentPreviews)
	log.Printf("Query: %+v\n", queryIncidentPreviewsResp.Query)
	log.Printf("Cursor: %+v\n", queryIncidentPreviewsResp.Cursor)
	log.Printf("Error: %+v\n", queryIncidentPreviewsResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.QueryIncidentPreviews
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"includeCustomFieldValues": true,
	"includeMembershipPreview": true,
	"query": {
		"limit": 10,
		"orderDirection": "ASC",
		"orderField": "createdTime",
		"queryString": "isdrill:false or(label:security label:important)"
	}
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// QueryIncidentPreviews gets a list of Incident Previews.
const incidentsServiceResp = await incidentsService.queryIncidentPreviews({
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"includeCustomFieldValues": true,
	"includeMembershipPreview": true,
	"query": {
		"limit": 10,
		"orderDirection": "ASC",
		"orderField": "createdTime",
		"queryString": "isdrill:false or(label:security label:important)"
	}
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incidentPreviews", incidentsServiceResp.data.incidentPreviews});
console.info({"query", incidentsServiceResp.data.query});
console.info({"cursor", incidentsServiceResp.data.cursor});

QueryIncidentPreviewsResponse

A 200 response with an empty error field indicates that the request was successful.

  • incidentPreviews - array of IncidentPreview - IncidentPreviews is a list of Incident Previews.
  • query - IncidentPreviewsQuery - Query is the query that was used to generate this response.
  • cursor - Cursor - Cursor should be passed back to get the next page of results.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"error": "something went wrong",
	"incidentPreviews": [
		{
			"closedTime": "2021-08-07T11:58:23Z",
			"createdByUser": {
				"name": "Morty Smith",
				"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
				"userID": "user-123"
			},
			"createdTime": "2021-08-07T11:58:23Z",
			"description": "Looks like there is a problem with the load balancers...",
			"fieldValues": [
				{
					"fieldUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
					"value": "value"
				},
				{
					"fieldUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
					"value": "value"
				}
			],
			"heroImagePath": "/incident/api/hero-images/1234/mb6SVYPti2uY1qOokhs2mavgMFOtqDe/v1234/1234.png",
			"incidentEnd": "2022-02-11 00:50:20.574137",
			"incidentID": "incident-123",
			"incidentMembershipPreview": {
				"importantAssignments": [
					{
						"roleID": 1,
						"user": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						}
					},
					{
						"roleID": 1,
						"user": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						}
					}
				],
				"totalAssignments": 5,
				"totalParticipants": 3
			},
			"incidentStart": "2022-02-11 00:50:20.574137",
			"incidentType": "internal",
			"isDrill": true,
			"labels": [
				{
					"colorHex": "#ff0000",
					"description": "Customers are affected by this incident.",
					"key": "service_name",
					"label": "customers-affected"
				},
				{
					"colorHex": "#ff0000",
					"description": "Customers are affected by this incident.",
					"key": "service_name",
					"label": "customers-affected"
				}
			],
			"modifiedTime": "2021-08-07T11:58:23Z",
			"severityID": "severity-123",
			"severityLabel": "major",
			"slug": "high-latency-in-web-requests",
			"status": "active",
			"summary": "Lighting struck the server so we lost some throughput. We sprayed it with an 8-bit fire extinguisher and now it's back to normal.",
			"title": "high latency in web requests",
			"version": 4
		},
		{
			"closedTime": "2021-08-07T11:58:23Z",
			"createdByUser": {
				"name": "Morty Smith",
				"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
				"userID": "user-123"
			},
			"createdTime": "2021-08-07T11:58:23Z",
			"description": "Looks like there is a problem with the load balancers...",
			"fieldValues": [
				{
					"fieldUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
					"value": "value"
				},
				{
					"fieldUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
					"value": "value"
				}
			],
			"heroImagePath": "/incident/api/hero-images/1234/mb6SVYPti2uY1qOokhs2mavgMFOtqDe/v1234/1234.png",
			"incidentEnd": "2022-02-11 00:50:20.574137",
			"incidentID": "incident-123",
			"incidentMembershipPreview": {
				"importantAssignments": [
					{
						"roleID": 1,
						"user": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						}
					},
					{
						"roleID": 1,
						"user": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						}
					}
				],
				"totalAssignments": 5,
				"totalParticipants": 3
			},
			"incidentStart": "2022-02-11 00:50:20.574137",
			"incidentType": "internal",
			"isDrill": true,
			"labels": [
				{
					"colorHex": "#ff0000",
					"description": "Customers are affected by this incident.",
					"key": "service_name",
					"label": "customers-affected"
				},
				{
					"colorHex": "#ff0000",
					"description": "Customers are affected by this incident.",
					"key": "service_name",
					"label": "customers-affected"
				}
			],
			"modifiedTime": "2021-08-07T11:58:23Z",
			"severityID": "severity-123",
			"severityLabel": "major",
			"slug": "high-latency-in-web-requests",
			"status": "active",
			"summary": "Lighting struck the server so we lost some throughput. We sprayed it with an 8-bit fire extinguisher and now it's back to normal.",
			"title": "high latency in web requests",
			"version": 4
		}
	],
	"query": {
		"limit": 10,
		"orderDirection": "ASC",
		"orderField": "createdTime",
		"queryString": "isdrill:false or(label:security label:important)"
	}
}

QueryIncidents

QueryIncidents gets a list of Incidents.
Deprecated: use QueryIncidentPreviews instead.

QueryIncidentsRequest

  • query - IncidentsQuery - Query describes the query to make.
  • cursor - Cursor - Cursor is used to page through results. Empty for the first page. For subsequent pages, use previously returned Cursor values.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.QueryIncidents" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"query": {
		"dateFrom": "2021-01-01T02:07:14+00:00",
		"dateTo": "2021-01-01T02:07:14+00:00",
		"excludeStatuses": [
			"closed"
		],
		"incidentLabels": [
			"security",
			"customersaffected"
		],
		"includeStatuses": [
			"active"
		],
		"limit": 10,
		"onlyDrills": true,
		"orderDirection": "ASC",
		"queryString": "isdrill:false any(label:security label:important)",
		"severity": "major"
	}
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	queryIncidentsResp, err := incidentsService.QueryIncidents(ctx, main.QueryIncidentsRequest{
		Query: main.IncidentsQuery{
			Limit: 10,
			IncludeStatuses: ["active"],
			ExcludeStatuses: ["closed"],
			IncidentLabels: ["security","customersaffected"],
			DateFrom: "2021-01-01T02:07:14+00:00",
			DateTo: "2021-01-01T02:07:14+00:00",
			OnlyDrills: true,
			OrderDirection: "ASC",
			Severity: "major",
			QueryString: "isdrill:false any(label:security label:important)",
		},
		Cursor: main.Cursor{
			NextValue: "aaaabbbbccccddddeeeeffffgggg",
			HasMore: true,
		},
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Incidents: %+v\n", queryIncidentsResp.Incidents)
	log.Printf("Query: %+v\n", queryIncidentsResp.Query)
	log.Printf("Cursor: %+v\n", queryIncidentsResp.Cursor)
	log.Printf("Error: %+v\n", queryIncidentsResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.QueryIncidents
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"query": {
		"dateFrom": "2021-01-01T02:07:14+00:00",
		"dateTo": "2021-01-01T02:07:14+00:00",
		"excludeStatuses": [
			"closed"
		],
		"incidentLabels": [
			"security",
			"customersaffected"
		],
		"includeStatuses": [
			"active"
		],
		"limit": 10,
		"onlyDrills": true,
		"orderDirection": "ASC",
		"queryString": "isdrill:false any(label:security label:important)",
		"severity": "major"
	}
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// QueryIncidents gets a list of Incidents.
const incidentsServiceResp = await incidentsService.queryIncidents({
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"query": {
		"dateFrom": "2021-01-01T02:07:14+00:00",
		"dateTo": "2021-01-01T02:07:14+00:00",
		"excludeStatuses": [
			"closed"
		],
		"incidentLabels": [
			"security",
			"customersaffected"
		],
		"includeStatuses": [
			"active"
		],
		"limit": 10,
		"onlyDrills": true,
		"orderDirection": "ASC",
		"queryString": "isdrill:false any(label:security label:important)",
		"severity": "major"
	}
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incidents", incidentsServiceResp.data.incidents});
console.info({"query", incidentsServiceResp.data.query});
console.info({"cursor", incidentsServiceResp.data.cursor});

QueryIncidentsResponse

A 200 response with an empty error field indicates that the request was successful.

  • incidents - array of Incident - Incidents is a list of Incidents.
  • query - IncidentsQuery - Query is the query that was used to generate this response.
  • cursor - Cursor - Cursor should be passed back to get the next page of results.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"error": "something went wrong",
	"incidents": [
		{
			"closedTime": "2021-08-07T11:58:23Z",
			"createdByUser": {
				"name": "Morty Smith",
				"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
				"userID": "user-123"
			},
			"createdTime": "2021-08-07T11:58:23Z",
			"durationSeconds": 60,
			"heroImagePath": "/relative/path/to/hero/image.png",
			"incidentEnd": "2022-02-11 00:50:20.574137",
			"incidentID": "incident-123",
			"incidentMembership": {
				"assignments": [
					{
						"role": {
							"archived": true,
							"createdAt": "2020-01-01T00:00:00Z",
							"description": "The commander is the incident commander.",
							"important": true,
							"mandatory": true,
							"name": "commander",
							"orgID": "org-1",
							"roleID": 1,
							"updatedAt": "2020-01-01T00:00:00Z"
						},
						"roleID": 1,
						"user": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						}
					},
					{
						"role": {
							"archived": true,
							"createdAt": "2020-01-01T00:00:00Z",
							"description": "The commander is the incident commander.",
							"important": true,
							"mandatory": true,
							"name": "commander",
							"orgID": "org-1",
							"roleID": 1,
							"updatedAt": "2020-01-01T00:00:00Z"
						},
						"roleID": 1,
						"user": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						}
					}
				],
				"totalAssignments": 5,
				"totalParticipants": 3
			},
			"incidentStart": "2022-02-11 00:50:20.574137",
			"isDrill": true,
			"labels": [
				{
					"colorHex": "#ff0000",
					"description": "Customers are affected by this incident.",
					"key": "service_name",
					"label": "customers-affected"
				},
				{
					"colorHex": "#ff0000",
					"description": "Customers are affected by this incident.",
					"key": "service_name",
					"label": "customers-affected"
				}
			],
			"modifiedTime": "2021-08-07T11:58:23Z",
			"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
			"severity": "minor",
			"status": "active",
			"summary": "Something happened, we found out something interesting, then we fixed it.",
			"taskList": {
				"doneCount": 8,
				"tasks": [
					{
						"assignedUser": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						},
						"authorUser": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						},
						"createdTime": "2018-01-01T00:00:00Z",
						"immutable": true,
						"modifiedTime": "2018-01-01T00:00:00Z",
						"status": "todo",
						"taskID": "task-123456",
						"text": "Assign an investigator"
					},
					{
						"assignedUser": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						},
						"authorUser": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						},
						"createdTime": "2018-01-01T00:00:00Z",
						"immutable": true,
						"modifiedTime": "2018-01-01T00:00:00Z",
						"status": "todo",
						"taskID": "task-123456",
						"text": "Assign an investigator"
					}
				],
				"todoCount": 5
			},
			"title": "high latency in web requests"
		},
		{
			"closedTime": "2021-08-07T11:58:23Z",
			"createdByUser": {
				"name": "Morty Smith",
				"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
				"userID": "user-123"
			},
			"createdTime": "2021-08-07T11:58:23Z",
			"durationSeconds": 60,
			"heroImagePath": "/relative/path/to/hero/image.png",
			"incidentEnd": "2022-02-11 00:50:20.574137",
			"incidentID": "incident-123",
			"incidentMembership": {
				"assignments": [
					{
						"role": {
							"archived": true,
							"createdAt": "2020-01-01T00:00:00Z",
							"description": "The commander is the incident commander.",
							"important": true,
							"mandatory": true,
							"name": "commander",
							"orgID": "org-1",
							"roleID": 1,
							"updatedAt": "2020-01-01T00:00:00Z"
						},
						"roleID": 1,
						"user": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						}
					},
					{
						"role": {
							"archived": true,
							"createdAt": "2020-01-01T00:00:00Z",
							"description": "The commander is the incident commander.",
							"important": true,
							"mandatory": true,
							"name": "commander",
							"orgID": "org-1",
							"roleID": 1,
							"updatedAt": "2020-01-01T00:00:00Z"
						},
						"roleID": 1,
						"user": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						}
					}
				],
				"totalAssignments": 5,
				"totalParticipants": 3
			},
			"incidentStart": "2022-02-11 00:50:20.574137",
			"isDrill": true,
			"labels": [
				{
					"colorHex": "#ff0000",
					"description": "Customers are affected by this incident.",
					"key": "service_name",
					"label": "customers-affected"
				},
				{
					"colorHex": "#ff0000",
					"description": "Customers are affected by this incident.",
					"key": "service_name",
					"label": "customers-affected"
				}
			],
			"modifiedTime": "2021-08-07T11:58:23Z",
			"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
			"severity": "minor",
			"status": "active",
			"summary": "Something happened, we found out something interesting, then we fixed it.",
			"taskList": {
				"doneCount": 8,
				"tasks": [
					{
						"assignedUser": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						},
						"authorUser": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						},
						"createdTime": "2018-01-01T00:00:00Z",
						"immutable": true,
						"modifiedTime": "2018-01-01T00:00:00Z",
						"status": "todo",
						"taskID": "task-123456",
						"text": "Assign an investigator"
					},
					{
						"assignedUser": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						},
						"authorUser": {
							"name": "Morty Smith",
							"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
							"userID": "user-123"
						},
						"createdTime": "2018-01-01T00:00:00Z",
						"immutable": true,
						"modifiedTime": "2018-01-01T00:00:00Z",
						"status": "todo",
						"taskID": "task-123456",
						"text": "Assign an investigator"
					}
				],
				"todoCount": 5
			},
			"title": "high latency in web requests"
		}
	],
	"query": {
		"dateFrom": "2021-01-01T02:07:14+00:00",
		"dateTo": "2021-01-01T02:07:14+00:00",
		"excludeStatuses": [
			"closed"
		],
		"incidentLabels": [
			"security",
			"customersaffected"
		],
		"includeStatuses": [
			"active"
		],
		"limit": 10,
		"onlyDrills": true,
		"orderDirection": "ASC",
		"queryString": "isdrill:false any(label:security label:important)",
		"severity": "major"
	}
}

RemoveLabel

RemoveLabel removes a label from the Incident.

RemoveLabelRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
  • label - string - Label is the label to remove from the Incident.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.RemoveLabel" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"label": "customers-affected"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	removeLabelResp, err := incidentsService.RemoveLabel(ctx, main.RemoveLabelRequest{
		IncidentID: "incident-123",
		Label: "customers-affected",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Incident: %+v\n", removeLabelResp.Incident)
	log.Printf("Error: %+v\n", removeLabelResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.RemoveLabel
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"label": "customers-affected"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// RemoveLabel removes a label from the Incident.
const incidentsServiceResp = await incidentsService.removeLabel({
	"incidentID": "incident-123",
	"label": "customers-affected"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incident", incidentsServiceResp.data.incident});

RemoveLabelResponse

A 200 response with an empty error field indicates that the request was successful.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incident": {
		"closedTime": "2021-08-07T11:58:23Z",
		"createdByUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2021-08-07T11:58:23Z",
		"durationSeconds": 60,
		"heroImagePath": "/relative/path/to/hero/image.png",
		"incidentEnd": "2022-02-11 00:50:20.574137",
		"incidentID": "incident-123",
		"incidentMembership": {
			"assignments": [
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				},
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				}
			],
			"totalAssignments": 5,
			"totalParticipants": 3
		},
		"incidentStart": "2022-02-11 00:50:20.574137",
		"isDrill": true,
		"labels": [
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			},
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			}
		],
		"modifiedTime": "2021-08-07T11:58:23Z",
		"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
		"severity": "minor",
		"status": "active",
		"summary": "Something happened, we found out something interesting, then we fixed it.",
		"taskList": {
			"doneCount": 8,
			"tasks": [
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				},
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				}
			],
			"todoCount": 5
		},
		"title": "high latency in web requests"
	}
}

UnassignLabel

UnassignLabel unassigns a key:value label from the incident

UnassignLabelRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
  • key - string - Key is the label key.
  • value - string - Value is the value of the label.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UnassignLabel" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"key": "service_name",
	"value": "customers-affected"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	unassignLabelResp, err := incidentsService.UnassignLabel(ctx, main.UnassignLabelRequest{
		IncidentID: "incident-123",
		Key: "service_name",
		Value: "customers-affected",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Labels: %+v\n", unassignLabelResp.Labels)
	log.Printf("Error: %+v\n", unassignLabelResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UnassignLabel
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"key": "service_name",
	"value": "customers-affected"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// UnassignLabel unassigns a key:value label from the incident
const incidentsServiceResp = await incidentsService.unassignLabel({
	"incidentID": "incident-123",
	"key": "service_name",
	"value": "customers-affected"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"labels", incidentsServiceResp.data.labels});

UnassignLabelResponse

A 200 response with an empty error field indicates that the request was successful.

  • labels - array of IncidentKeyValueLabel - Labels is a list of labels
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"labels": [
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
			"value": "customers-affected",
			"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
		},
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
			"value": "customers-affected",
			"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
		}
	]
}

UnassignLabelByUUID

UnassignLabelByUUID unassigns a keyUUID:valueUUID label from the incident

UnassignLabelByUUIDRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
  • keyUUID - string - KeyUUID is the label key uuid.
  • valueUUID - string - ValueUUID is the UUID of the label value.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UnassignLabelByUUID" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
	"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	unassignLabelByUUIDResp, err := incidentsService.UnassignLabelByUUID(ctx, main.UnassignLabelByUUIDRequest{
		IncidentID: "incident-123",
		KeyUUID: "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
		ValueUUID: "3fb1e5d7-3ef2-11ef-b731-deab26f9160f",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Labels: %+v\n", unassignLabelByUUIDResp.Labels)
	log.Printf("Error: %+v\n", unassignLabelByUUIDResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UnassignLabelByUUID
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
	"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// UnassignLabelByUUID unassigns a keyUUID:valueUUID label from the incident
const incidentsServiceResp = await incidentsService.unassignLabelByUUID({
	"incidentID": "incident-123",
	"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
	"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"labels", incidentsServiceResp.data.labels});

UnassignLabelByUUIDResponse

A 200 response with an empty error field indicates that the request was successful.

  • labels - array of IncidentKeyValueLabel - Labels is a list of labels
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"labels": [
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
			"value": "customers-affected",
			"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
		},
		{
			"colorHex": "#ff0000",
			"description": "Customers are affected by this incident.",
			"key": "service_name",
			"keyUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9180f",
			"value": "customers-affected",
			"valueUUID": "3fb1e5d7-3ef2-11ef-b731-deab26f9160f"
		}
	]
}

UnassignRole

UnassignRole removes a role assignment from a user.

UnassignRoleRequest

  • incidentID - string - IncidentID is the identifier.
  • userID - string - UserID is the identifier of the person to assign the role to.
  • role - string - options: "commander" "investigator" "observer" - Role is the role of this person.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UnassignRole" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"role": "commander",
	"userID": "grafana-incident:user-123"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	unassignRoleResp, err := incidentsService.UnassignRole(ctx, main.UnassignRoleRequest{
		IncidentID: "incident-123",
		UserID: "grafana-incident:user-123",
		Role: "commander",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Incident: %+v\n", unassignRoleResp.Incident)
	log.Printf("DidChange: %+v\n", unassignRoleResp.DidChange)
	log.Printf("Error: %+v\n", unassignRoleResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UnassignRole
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"role": "commander",
	"userID": "grafana-incident:user-123"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// UnassignRole removes a role assignment from a user.
const incidentsServiceResp = await incidentsService.unassignRole({
	"incidentID": "incident-123",
	"role": "commander",
	"userID": "grafana-incident:user-123"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incident", incidentsServiceResp.data.incident});
console.info({"didChange", incidentsServiceResp.data.didChange});

UnassignRoleResponse

A 200 response with an empty error field indicates that the request was successful.

  • incident - Incident - Incident is the Incident that was just updated.
  • didChange - boolean - DidChange indicates if the role was changed or not. If the role was not assigned, this will be false.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"didChange": true,
	"error": "something went wrong",
	"incident": {
		"closedTime": "2021-08-07T11:58:23Z",
		"createdByUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2021-08-07T11:58:23Z",
		"durationSeconds": 60,
		"heroImagePath": "/relative/path/to/hero/image.png",
		"incidentEnd": "2022-02-11 00:50:20.574137",
		"incidentID": "incident-123",
		"incidentMembership": {
			"assignments": [
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				},
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				}
			],
			"totalAssignments": 5,
			"totalParticipants": 3
		},
		"incidentStart": "2022-02-11 00:50:20.574137",
		"isDrill": true,
		"labels": [
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			},
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			}
		],
		"modifiedTime": "2021-08-07T11:58:23Z",
		"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
		"severity": "minor",
		"status": "active",
		"summary": "Something happened, we found out something interesting, then we fixed it.",
		"taskList": {
			"doneCount": 8,
			"tasks": [
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				},
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				}
			],
			"todoCount": 5
		},
		"title": "high latency in web requests"
	}
}

UpdateIncidentEventTime

UpdateIncidentEventTime updates the start or end times of an Incident.

UpdateIncidentEventTimeRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
  • eventTime - string - EventTime is the new time for the start or end of the incident. The string value format should follow RFC 3339.
  • activityItemKind - string - options: "incidentEnd" "incidentStart" - ActivityItemKind is either the incidentEnd or incidentStart time. deprecated. use EventName instead, ActivityItemKind will be removed soon. (Deprecated: true)
  • eventName - string - options: "incidentEnd" "incidentStart" - EventName is either the incidentEnd or incidentStart time.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UpdateIncidentEventTime" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"activityItemKind": "incidentEnd",
	"eventName": "incidentEnd",
	"eventTime": "2022-02-11 00:50:20.574137",
	"incidentID": "1"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	updateIncidentEventTimeResp, err := incidentsService.UpdateIncidentEventTime(ctx, main.UpdateIncidentEventTimeRequest{
		IncidentID: "1",
		EventTime: "2022-02-11 00:50:20.574137",
		ActivityItemKind: "incidentEnd",
		EventName: "incidentEnd",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Error: %+v\n", updateIncidentEventTimeResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UpdateIncidentEventTime
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"activityItemKind": "incidentEnd",
	"eventName": "incidentEnd",
	"eventTime": "2022-02-11 00:50:20.574137",
	"incidentID": "1"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient('https://your-stack.grafana.net', serviceAccountToken);
const incidentsService = new IncidentsService(client);

// UpdateIncidentEventTime updates the start or end times of an Incident.
const incidentsServiceResp = await incidentsService.updateIncidentEventTime({
  activityItemKind: 'incidentEnd',
  eventName: 'incidentEnd',
  eventTime: '2022-02-11 00:50:20.574137',
  incidentID: '1',
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response

UpdateIncidentEventTimeResponse

A 200 response with an empty error field indicates that the request was successful.

  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong"
}

UpdateIncidentIsDrill

UpdateIncidentIsDrill changes whether an Incident is a drill or not.

UpdateIncidentIsDrillRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
  • isDrill - boolean - IsDrill indicates whether the Incident is a drill or not.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UpdateIncidentIsDrill" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"isDrill": true
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	updateIncidentIsDrillResp, err := incidentsService.UpdateIncidentIsDrill(ctx, main.UpdateIncidentIsDrillRequest{
		IncidentID: "incident-123",
		IsDrill: true,
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Incident: %+v\n", updateIncidentIsDrillResp.Incident)
	log.Printf("Error: %+v\n", updateIncidentIsDrillResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UpdateIncidentIsDrill
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"isDrill": true
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// UpdateIncidentIsDrill changes whether an Incident is a drill or not.
const incidentsServiceResp = await incidentsService.updateIncidentIsDrill({
	"incidentID": "incident-123",
	"isDrill": true
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incident", incidentsServiceResp.data.incident});

UpdateIncidentIsDrillResponse

A 200 response with an empty error field indicates that the request was successful.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incident": {
		"closedTime": "2021-08-07T11:58:23Z",
		"createdByUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2021-08-07T11:58:23Z",
		"durationSeconds": 60,
		"heroImagePath": "/relative/path/to/hero/image.png",
		"incidentEnd": "2022-02-11 00:50:20.574137",
		"incidentID": "incident-123",
		"incidentMembership": {
			"assignments": [
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				},
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				}
			],
			"totalAssignments": 5,
			"totalParticipants": 3
		},
		"incidentStart": "2022-02-11 00:50:20.574137",
		"isDrill": true,
		"labels": [
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			},
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			}
		],
		"modifiedTime": "2021-08-07T11:58:23Z",
		"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
		"severity": "minor",
		"status": "active",
		"summary": "Something happened, we found out something interesting, then we fixed it.",
		"taskList": {
			"doneCount": 8,
			"tasks": [
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				},
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				}
			],
			"todoCount": 5
		},
		"title": "high latency in web requests"
	}
}

UpdateSeverity

UpdateSeverity updates the severity of an Incident.

UpdateSeverityRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
  • severity - string - Severity expresses how bad the Incident is.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UpdateSeverity" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"severity": "minor"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	updateSeverityResp, err := incidentsService.UpdateSeverity(ctx, main.UpdateSeverityRequest{
		IncidentID: "incident-123",
		Severity: "minor",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Incident: %+v\n", updateSeverityResp.Incident)
	log.Printf("Error: %+v\n", updateSeverityResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UpdateSeverity
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"severity": "minor"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// UpdateSeverity updates the severity of an Incident.
const incidentsServiceResp = await incidentsService.updateSeverity({
	"incidentID": "incident-123",
	"severity": "minor"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incident", incidentsServiceResp.data.incident});

UpdateSeverityResponse

A 200 response with an empty error field indicates that the request was successful.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incident": {
		"closedTime": "2021-08-07T11:58:23Z",
		"createdByUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2021-08-07T11:58:23Z",
		"durationSeconds": 60,
		"heroImagePath": "/relative/path/to/hero/image.png",
		"incidentEnd": "2022-02-11 00:50:20.574137",
		"incidentID": "incident-123",
		"incidentMembership": {
			"assignments": [
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				},
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				}
			],
			"totalAssignments": 5,
			"totalParticipants": 3
		},
		"incidentStart": "2022-02-11 00:50:20.574137",
		"isDrill": true,
		"labels": [
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			},
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			}
		],
		"modifiedTime": "2021-08-07T11:58:23Z",
		"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
		"severity": "minor",
		"status": "active",
		"summary": "Something happened, we found out something interesting, then we fixed it.",
		"taskList": {
			"doneCount": 8,
			"tasks": [
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				},
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				}
			],
			"todoCount": 5
		},
		"title": "high latency in web requests"
	}
}

UpdateStatus

UpdateStatus updates the status of an Incident.

UpdateStatusRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
  • status - string - options: "active" "resolved" - Status is the new status of the Incident.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UpdateStatus" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"status": "resolved"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	updateStatusResp, err := incidentsService.UpdateStatus(ctx, main.UpdateStatusRequest{
		IncidentID: "incident-123",
		Status: "resolved",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Incident: %+v\n", updateStatusResp.Incident)
	log.Printf("Error: %+v\n", updateStatusResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UpdateStatus
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"status": "resolved"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// UpdateStatus updates the status of an Incident.
const incidentsServiceResp = await incidentsService.updateStatus({
	"incidentID": "incident-123",
	"status": "resolved"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incident", incidentsServiceResp.data.incident});

UpdateStatusResponse

A 200 response with an empty error field indicates that the request was successful.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incident": {
		"closedTime": "2021-08-07T11:58:23Z",
		"createdByUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2021-08-07T11:58:23Z",
		"durationSeconds": 60,
		"heroImagePath": "/relative/path/to/hero/image.png",
		"incidentEnd": "2022-02-11 00:50:20.574137",
		"incidentID": "incident-123",
		"incidentMembership": {
			"assignments": [
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				},
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				}
			],
			"totalAssignments": 5,
			"totalParticipants": 3
		},
		"incidentStart": "2022-02-11 00:50:20.574137",
		"isDrill": true,
		"labels": [
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			},
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			}
		],
		"modifiedTime": "2021-08-07T11:58:23Z",
		"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
		"severity": "minor",
		"status": "active",
		"summary": "Something happened, we found out something interesting, then we fixed it.",
		"taskList": {
			"doneCount": 8,
			"tasks": [
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				},
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				}
			],
			"todoCount": 5
		},
		"title": "high latency in web requests"
	}
}

UpdateTitle

UpdateTitle updates the title of an Incident.

UpdateTitleRequest

  • incidentID - string - IncidentID is the identifier of the Incident.
  • title - string - Title is the new title of the Incident.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UpdateTitle" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123",
	"title": "High latency in web requests"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	incidentsService := incident.NewIncidentsService(client)
	// make the request...
	updateTitleResp, err := incidentsService.UpdateTitle(ctx, main.UpdateTitleRequest{
		IncidentID: "incident-123",
		Title: "High latency in web requests",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Incident: %+v\n", updateTitleResp.Incident)
	log.Printf("Error: %+v\n", updateTitleResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IncidentsService.UpdateTitle
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123",
	"title": "High latency in web requests"
}
JavaScript
import { GrafanaIncidentClient, IncidentsService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const incidentsService = new IncidentsService(client);

// UpdateTitle updates the title of an Incident.
const incidentsServiceResp = await incidentsService.updateTitle({
	"incidentID": "incident-123",
	"title": "High latency in web requests"
});

if (!incidentsServiceResp.success) {
  // handle the error
  throw new Error(incidentsServiceResp.error);
}

// access the fields of the response
console.info({"incident", incidentsServiceResp.data.incident});

UpdateTitleResponse

A 200 response with an empty error field indicates that the request was successful.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incident": {
		"closedTime": "2021-08-07T11:58:23Z",
		"createdByUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2021-08-07T11:58:23Z",
		"durationSeconds": 60,
		"heroImagePath": "/relative/path/to/hero/image.png",
		"incidentEnd": "2022-02-11 00:50:20.574137",
		"incidentID": "incident-123",
		"incidentMembership": {
			"assignments": [
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				},
				{
					"role": {
						"archived": true,
						"createdAt": "2020-01-01T00:00:00Z",
						"description": "The commander is the incident commander.",
						"important": true,
						"mandatory": true,
						"name": "commander",
						"orgID": "org-1",
						"roleID": 1,
						"updatedAt": "2020-01-01T00:00:00Z"
					},
					"roleID": 1,
					"user": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					}
				}
			],
			"totalAssignments": 5,
			"totalParticipants": 3
		},
		"incidentStart": "2022-02-11 00:50:20.574137",
		"isDrill": true,
		"labels": [
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			},
			{
				"colorHex": "#ff0000",
				"description": "Customers are affected by this incident.",
				"key": "service_name",
				"label": "customers-affected"
			}
		],
		"modifiedTime": "2021-08-07T11:58:23Z",
		"overviewURL": "/a/grafana-incident-app/incidents/incident-123/title",
		"severity": "minor",
		"status": "active",
		"summary": "Something happened, we found out something interesting, then we fixed it.",
		"taskList": {
			"doneCount": 8,
			"tasks": [
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				},
				{
					"assignedUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"authorUser": {
						"name": "Morty Smith",
						"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
						"userID": "user-123"
					},
					"createdTime": "2018-01-01T00:00:00Z",
					"immutable": true,
					"modifiedTime": "2018-01-01T00:00:00Z",
					"status": "todo",
					"taskID": "task-123456",
					"text": "Assign an investigator"
				}
			],
			"todoCount": 5
		},
		"title": "high latency in web requests"
	}
}

IntegrationService

IntegrationService is used to install Integrations, and wire up hooks.

  • GetHookRuns - GetHookRuns gets a list of HookRuns for a given Incident.

GetHookRuns

GetHookRuns gets a list of HookRuns for a given Incident.

GetHookRunsRequest

  • incidentID - string - IncidentID is the identifier of the incident to get hook runs for.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IntegrationService.GetHookRuns" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	integrationService := incident.NewIntegrationService(client)
	// make the request...
	getHookRunsResp, err := integrationService.GetHookRuns(ctx, main.GetHookRunsRequest{
		IncidentID: "incident-123",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("HookRuns: %+v\n", getHookRunsResp.HookRuns)
	log.Printf("Error: %+v\n", getHookRunsResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/IntegrationService.GetHookRuns
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123"
}
JavaScript
import { GrafanaIncidentClient, IntegrationService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const integrationService = new IntegrationService(client);

// GetHookRuns gets a list of HookRuns for a given Incident.
const integrationServiceResp = await integrationService.getHookRuns({
	"incidentID": "incident-123"
});

if (!integrationServiceResp.success) {
  // handle the error
  throw new Error(integrationServiceResp.error);
}

// access the fields of the response
console.info({"hookRuns", integrationServiceResp.data.hookRuns});

GetHookRunsResponse

A 200 response with an empty error field indicates that the request was successful.

  • hookRuns - array of HookRun - HookRuns is a list of HookRuns for this Incident.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"hookRuns": [
		{
			"enabledHookID": "enabled-hook-123",
			"error": "Something went wrong",
			"eventKind": "updatedRole",
			"eventName": "incidentCreated",
			"hookID": "hook-123",
			"integrationID": "integration-123",
			"lastRun": "2020-01-01T00:00:00Z",
			"lastUpdate": "2020-01-01T00:00:00Z",
			"metadata": {
				"explanation": "A meeting was created.",
				"title": "Meeting Created",
				"url": "https://somewhere.com/123"
			},
			"status": "todo",
			"updateError": "failed to connect",
			"updateStatus": "todo"
		},
		{
			"enabledHookID": "enabled-hook-123",
			"error": "Something went wrong",
			"eventKind": "updatedRole",
			"eventName": "incidentCreated",
			"hookID": "hook-123",
			"integrationID": "integration-123",
			"lastRun": "2020-01-01T00:00:00Z",
			"lastUpdate": "2020-01-01T00:00:00Z",
			"metadata": {
				"explanation": "A meeting was created.",
				"title": "Meeting Created",
				"url": "https://somewhere.com/123"
			},
			"status": "todo",
			"updateError": "failed to connect",
			"updateStatus": "todo"
		}
	]
}

RolesService

RolesService defines the interface for interacting with roles, providing CRUD operations and more fatures related to roles.

ArchiveRole

ArchiveRole archives a role.

ArchiveRoleRequest

  • roleID - number - Role to be archived to the organization
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.ArchiveRole" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"roleID": 1
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	rolesService := incident.NewRolesService(client)
	// make the request...
	archiveRoleResp, err := rolesService.ArchiveRole(ctx, main.ArchiveRoleRequest{
		RoleID: 1,
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Error: %+v\n", archiveRoleResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.ArchiveRole
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"roleID": 1
}
JavaScript
import { GrafanaIncidentClient, RolesService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient('https://your-stack.grafana.net', serviceAccountToken);
const rolesService = new RolesService(client);

// ArchiveRole archives a role.
const rolesServiceResp = await rolesService.archiveRole({
  roleID: 1,
});

if (!rolesServiceResp.success) {
  // handle the error
  throw new Error(rolesServiceResp.error);
}

// access the fields of the response

ArchiveRoleResponse

A 200 response with an empty error field indicates that the request was successful.

  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong"
}

CreateRole

CreateRole creates a role.

CreateRoleRequest

  • role - Role - Role to be created to the organization
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.CreateRole" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"role": {
		"archived": true,
		"createdAt": "2020-01-01T00:00:00Z",
		"description": "The commander is the incident commander.",
		"important": true,
		"mandatory": true,
		"name": "commander",
		"orgID": "org-1",
		"roleID": 1,
		"updatedAt": "2020-01-01T00:00:00Z"
	}
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	rolesService := incident.NewRolesService(client)
	// make the request...
	createRoleResp, err := rolesService.CreateRole(ctx, main.CreateRoleRequest{
		Role: main.Role{
			RoleID: 1,
			OrgID: "org-1",
			Name: "commander",
			Description: "The commander is the incident commander.",
			Important: true,
			Mandatory: true,
			Archived: true,
			CreatedAt: "2020-01-01T00:00:00Z",
			UpdatedAt: "2020-01-01T00:00:00Z",
		},
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Role: %+v\n", createRoleResp.Role)
	log.Printf("Error: %+v\n", createRoleResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.CreateRole
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"role": {
		"archived": true,
		"createdAt": "2020-01-01T00:00:00Z",
		"description": "The commander is the incident commander.",
		"important": true,
		"mandatory": true,
		"name": "commander",
		"orgID": "org-1",
		"roleID": 1,
		"updatedAt": "2020-01-01T00:00:00Z"
	}
}
JavaScript
import { GrafanaIncidentClient, RolesService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const rolesService = new RolesService(client);

// CreateRole creates a role.
const rolesServiceResp = await rolesService.createRole({
	"role": {
		"archived": true,
		"createdAt": "2020-01-01T00:00:00Z",
		"description": "The commander is the incident commander.",
		"important": true,
		"mandatory": true,
		"name": "commander",
		"orgID": "org-1",
		"roleID": 1,
		"updatedAt": "2020-01-01T00:00:00Z"
	}
});

if (!rolesServiceResp.success) {
  // handle the error
  throw new Error(rolesServiceResp.error);
}

// access the fields of the response
console.info({"role", rolesServiceResp.data.role});

CreateRoleResponse

A 200 response with an empty error field indicates that the request was successful.

  • role - Role - Role is the newly created role.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"role": {
		"archived": true,
		"createdAt": "2020-01-01T00:00:00Z",
		"description": "The commander is the incident commander.",
		"important": true,
		"mandatory": true,
		"name": "commander",
		"orgID": "org-1",
		"roleID": 1,
		"updatedAt": "2020-01-01T00:00:00Z"
	}
}

DeleteRole

DeleteRole deletes a role.

DeleteRoleRequest

  • roleID - number - Role to be deleted to the organization
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.DeleteRole" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"roleID": 1
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	rolesService := incident.NewRolesService(client)
	// make the request...
	deleteRoleResp, err := rolesService.DeleteRole(ctx, main.DeleteRoleRequest{
		RoleID: 1,
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Error: %+v\n", deleteRoleResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.DeleteRole
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"roleID": 1
}
JavaScript
import { GrafanaIncidentClient, RolesService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient('https://your-stack.grafana.net', serviceAccountToken);
const rolesService = new RolesService(client);

// DeleteRole deletes a role.
const rolesServiceResp = await rolesService.deleteRole({
  roleID: 1,
});

if (!rolesServiceResp.success) {
  // handle the error
  throw new Error(rolesServiceResp.error);
}

// access the fields of the response

DeleteRoleResponse

A 200 response with an empty error field indicates that the request was successful.

  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong"
}

GetRoles

GetRoles gets all roles.

GetRolesRequest

  • No fields
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.GetRoles" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	rolesService := incident.NewRolesService(client)
	// make the request...
	getRolesResp, err := rolesService.GetRoles(ctx, main.GetRolesRequest{
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Roles: %+v\n", getRolesResp.Roles)
	log.Printf("Error: %+v\n", getRolesResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.GetRoles
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{}
JavaScript
import { GrafanaIncidentClient, RolesService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const rolesService = new RolesService(client);

// GetRoles gets all roles.
const rolesServiceResp = await rolesService.getRoles({});

if (!rolesServiceResp.success) {
  // handle the error
  throw new Error(rolesServiceResp.error);
}

// access the fields of the response
console.info({"roles", rolesServiceResp.data.roles});

GetRolesResponse

A 200 response with an empty error field indicates that the request was successful.

  • roles - array of Role - Roles is the list of roles.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"roles": [
		{
			"archived": true,
			"createdAt": "2020-01-01T00:00:00Z",
			"description": "The commander is the incident commander.",
			"important": true,
			"mandatory": true,
			"name": "commander",
			"orgID": "org-1",
			"roleID": 1,
			"updatedAt": "2020-01-01T00:00:00Z"
		},
		{
			"archived": true,
			"createdAt": "2020-01-01T00:00:00Z",
			"description": "The commander is the incident commander.",
			"important": true,
			"mandatory": true,
			"name": "commander",
			"orgID": "org-1",
			"roleID": 1,
			"updatedAt": "2020-01-01T00:00:00Z"
		}
	]
}

UnarchiveRole

UnarchiveRole unarchives a role.

UnarchiveRoleRequest

  • roleID - number - Role to be unarchived to the organization
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.UnarchiveRole" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"roleID": 1
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	rolesService := incident.NewRolesService(client)
	// make the request...
	unarchiveRoleResp, err := rolesService.UnarchiveRole(ctx, main.UnarchiveRoleRequest{
		RoleID: 1,
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Error: %+v\n", unarchiveRoleResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.UnarchiveRole
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"roleID": 1
}
JavaScript
import { GrafanaIncidentClient, RolesService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient('https://your-stack.grafana.net', serviceAccountToken);
const rolesService = new RolesService(client);

// UnarchiveRole unarchives a role.
const rolesServiceResp = await rolesService.unarchiveRole({
  roleID: 1,
});

if (!rolesServiceResp.success) {
  // handle the error
  throw new Error(rolesServiceResp.error);
}

// access the fields of the response

UnarchiveRoleResponse

A 200 response with an empty error field indicates that the request was successful.

  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong"
}

UpdateRole

UpdateRole updates a role.

UpdateRoleRequest

  • role - Role - Role to be updated to the organization
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.UpdateRole" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"role": {
		"archived": true,
		"createdAt": "2020-01-01T00:00:00Z",
		"description": "The commander is the incident commander.",
		"important": true,
		"mandatory": true,
		"name": "commander",
		"orgID": "org-1",
		"roleID": 1,
		"updatedAt": "2020-01-01T00:00:00Z"
	}
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	rolesService := incident.NewRolesService(client)
	// make the request...
	updateRoleResp, err := rolesService.UpdateRole(ctx, main.UpdateRoleRequest{
		Role: main.Role{
			RoleID: 1,
			OrgID: "org-1",
			Name: "commander",
			Description: "The commander is the incident commander.",
			Important: true,
			Mandatory: true,
			Archived: true,
			CreatedAt: "2020-01-01T00:00:00Z",
			UpdatedAt: "2020-01-01T00:00:00Z",
		},
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Role: %+v\n", updateRoleResp.Role)
	log.Printf("Error: %+v\n", updateRoleResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/RolesService.UpdateRole
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"role": {
		"archived": true,
		"createdAt": "2020-01-01T00:00:00Z",
		"description": "The commander is the incident commander.",
		"important": true,
		"mandatory": true,
		"name": "commander",
		"orgID": "org-1",
		"roleID": 1,
		"updatedAt": "2020-01-01T00:00:00Z"
	}
}
JavaScript
import { GrafanaIncidentClient, RolesService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const rolesService = new RolesService(client);

// UpdateRole updates a role.
const rolesServiceResp = await rolesService.updateRole({
	"role": {
		"archived": true,
		"createdAt": "2020-01-01T00:00:00Z",
		"description": "The commander is the incident commander.",
		"important": true,
		"mandatory": true,
		"name": "commander",
		"orgID": "org-1",
		"roleID": 1,
		"updatedAt": "2020-01-01T00:00:00Z"
	}
});

if (!rolesServiceResp.success) {
  // handle the error
  throw new Error(rolesServiceResp.error);
}

// access the fields of the response
console.info({"role", rolesServiceResp.data.role});

UpdateRoleResponse

A 200 response with an empty error field indicates that the request was successful.

  • role - Role - Role is the newly updated role.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"role": {
		"archived": true,
		"createdAt": "2020-01-01T00:00:00Z",
		"description": "The commander is the incident commander.",
		"important": true,
		"mandatory": true,
		"name": "commander",
		"orgID": "org-1",
		"roleID": 1,
		"updatedAt": "2020-01-01T00:00:00Z"
	}
}

TasksService

TasksService provides methods for managing tasks relating to Incidents.

  • AddTask - AddTask adds a task to an Incident.
  • DeleteTask - DeleteTask deletes a task.
  • UpdateTaskStatus - UpdateTaskStatus updates the task's Status.
  • UpdateTaskText - UpdateTaskText updates the task's text.
  • UpdateTaskUser - UpdateTaskUser updates the task's assigned user. Passing an empty user ID will clear the assigned user.

AddTask

AddTask adds a task to an Incident.

AddTaskRequest

  • incidentID - string - IncidentID is the ID of the Incident to add the Task to.
  • text - string - Text is the todo item.
  • assignToUserID - string - AssignToUserId is the user the task wil be assigned to
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/TasksService.AddTask" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"assignToUserID": "User123",
	"incidentID": "incident-123456",
	"text": "Assign an investigator"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	tasksService := incident.NewTasksService(client)
	// make the request...
	addTaskResp, err := tasksService.AddTask(ctx, main.AddTaskRequest{
		IncidentID: "incident-123456",
		Text: "Assign an investigator",
		AssignToUserId: "User123",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("IncidentID: %+v\n", addTaskResp.IncidentID)
	log.Printf("Task: %+v\n", addTaskResp.Task)
	log.Printf("TaskList: %+v\n", addTaskResp.TaskList)
	log.Printf("Error: %+v\n", addTaskResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/TasksService.AddTask
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"assignToUserID": "User123",
	"incidentID": "incident-123456",
	"text": "Assign an investigator"
}
JavaScript
import { GrafanaIncidentClient, TasksService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const tasksService = new TasksService(client);

// AddTask adds a task to an Incident.
const tasksServiceResp = await tasksService.addTask({
	"assignToUserID": "User123",
	"incidentID": "incident-123456",
	"text": "Assign an investigator"
});

if (!tasksServiceResp.success) {
  // handle the error
  throw new Error(tasksServiceResp.error);
}

// access the fields of the response
console.info({"incidentID", tasksServiceResp.data.incidentID});
console.info({"task", tasksServiceResp.data.task});
console.info({"taskList", tasksServiceResp.data.taskList});

AddTaskResponse

A 200 response with an empty error field indicates that the request was successful.

  • incidentID - string - IncidentID is the ID of the incident these tasks relate to.
  • task - Task - Task is the newly added Task. It will also appear in Tasks.
  • taskList - TaskList - TaskList is the tasks list.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incidentID": "incident-123456",
	"task": {
		"assignedUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"authorUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2018-01-01T00:00:00Z",
		"immutable": true,
		"modifiedTime": "2018-01-01T00:00:00Z",
		"status": "todo",
		"taskID": "task-123456",
		"text": "Assign an investigator"
	},
	"taskList": {
		"doneCount": 8,
		"tasks": [
			{
				"assignedUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"authorUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"createdTime": "2018-01-01T00:00:00Z",
				"immutable": true,
				"modifiedTime": "2018-01-01T00:00:00Z",
				"status": "todo",
				"taskID": "task-123456",
				"text": "Assign an investigator"
			},
			{
				"assignedUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"authorUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"createdTime": "2018-01-01T00:00:00Z",
				"immutable": true,
				"modifiedTime": "2018-01-01T00:00:00Z",
				"status": "todo",
				"taskID": "task-123456",
				"text": "Assign an investigator"
			}
		],
		"todoCount": 5
	}
}

DeleteTask

DeleteTask deletes a task.

DeleteTaskRequest

  • incidentID - string - IncidentID is the ID of the Incident.
  • taskID - string - TaskID is the ID of the task.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/TasksService.DeleteTask" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "inccident-123456",
	"taskID": "task-123456"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	tasksService := incident.NewTasksService(client)
	// make the request...
	deleteTaskResp, err := tasksService.DeleteTask(ctx, main.DeleteTaskRequest{
		IncidentID: "inccident-123456",
		TaskID: "task-123456",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("IncidentID: %+v\n", deleteTaskResp.IncidentID)
	log.Printf("TaskList: %+v\n", deleteTaskResp.TaskList)
	log.Printf("Error: %+v\n", deleteTaskResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/TasksService.DeleteTask
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "inccident-123456",
	"taskID": "task-123456"
}
JavaScript
import { GrafanaIncidentClient, TasksService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const tasksService = new TasksService(client);

// DeleteTask deletes a task.
const tasksServiceResp = await tasksService.deleteTask({
	"incidentID": "inccident-123456",
	"taskID": "task-123456"
});

if (!tasksServiceResp.success) {
  // handle the error
  throw new Error(tasksServiceResp.error);
}

// access the fields of the response
console.info({"incidentID", tasksServiceResp.data.incidentID});
console.info({"taskList", tasksServiceResp.data.taskList});

DeleteTaskResponse

A 200 response with an empty error field indicates that the request was successful.

  • incidentID - string - IncidentID is the ID of the incident these tasks relate to.
  • taskList - TaskList - TaskList is the tasks list.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incidentID": "incident-123456",
	"taskList": {
		"doneCount": 8,
		"tasks": [
			{
				"assignedUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"authorUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"createdTime": "2018-01-01T00:00:00Z",
				"immutable": true,
				"modifiedTime": "2018-01-01T00:00:00Z",
				"status": "todo",
				"taskID": "task-123456",
				"text": "Assign an investigator"
			},
			{
				"assignedUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"authorUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"createdTime": "2018-01-01T00:00:00Z",
				"immutable": true,
				"modifiedTime": "2018-01-01T00:00:00Z",
				"status": "todo",
				"taskID": "task-123456",
				"text": "Assign an investigator"
			}
		],
		"todoCount": 5
	}
}

UpdateTaskStatus

UpdateTaskStatus updates the task's Status.

UpdateTaskStatusRequest

  • incidentID - string - IncidentID is the ID of the Incident to add the Task to.
  • taskID - string - TaskID is the ID of the Task to update.
  • status - string - options: "todo" "progress" "done" - Status is the new status of this task.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/TasksService.UpdateTaskStatus" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123456",
	"status": "todo",
	"taskID": "task-12345"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	tasksService := incident.NewTasksService(client)
	// make the request...
	updateTaskStatusResp, err := tasksService.UpdateTaskStatus(ctx, main.UpdateTaskStatusRequest{
		IncidentID: "incident-123456",
		TaskID: "task-12345",
		Status: "todo",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("IncidentID: %+v\n", updateTaskStatusResp.IncidentID)
	log.Printf("Task: %+v\n", updateTaskStatusResp.Task)
	log.Printf("TaskList: %+v\n", updateTaskStatusResp.TaskList)
	log.Printf("Error: %+v\n", updateTaskStatusResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/TasksService.UpdateTaskStatus
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123456",
	"status": "todo",
	"taskID": "task-12345"
}
JavaScript
import { GrafanaIncidentClient, TasksService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const tasksService = new TasksService(client);

// UpdateTaskStatus updates the task's Status.
const tasksServiceResp = await tasksService.updateTaskStatus({
	"incidentID": "incident-123456",
	"status": "todo",
	"taskID": "task-12345"
});

if (!tasksServiceResp.success) {
  // handle the error
  throw new Error(tasksServiceResp.error);
}

// access the fields of the response
console.info({"incidentID", tasksServiceResp.data.incidentID});
console.info({"task", tasksServiceResp.data.task});
console.info({"taskList", tasksServiceResp.data.taskList});

UpdateTaskStatusResponse

A 200 response with an empty error field indicates that the request was successful.

  • incidentID - string - IncidentID is the ID of the incident these tasks relate to.
  • task - Task - Task is the newly added Task. It will also appear in Tasks.
  • taskList - TaskList - TaskList is the tasks list.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incidentID": "incident-123456",
	"task": {
		"assignedUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"authorUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2018-01-01T00:00:00Z",
		"immutable": true,
		"modifiedTime": "2018-01-01T00:00:00Z",
		"status": "todo",
		"taskID": "task-123456",
		"text": "Assign an investigator"
	},
	"taskList": {
		"doneCount": 8,
		"tasks": [
			{
				"assignedUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"authorUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"createdTime": "2018-01-01T00:00:00Z",
				"immutable": true,
				"modifiedTime": "2018-01-01T00:00:00Z",
				"status": "todo",
				"taskID": "task-123456",
				"text": "Assign an investigator"
			},
			{
				"assignedUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"authorUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"createdTime": "2018-01-01T00:00:00Z",
				"immutable": true,
				"modifiedTime": "2018-01-01T00:00:00Z",
				"status": "todo",
				"taskID": "task-123456",
				"text": "Assign an investigator"
			}
		],
		"todoCount": 5
	}
}

UpdateTaskText

UpdateTaskText updates the task's text.

UpdateTaskTextRequest

  • incidentID - string - IncidentID is the ID of the Incident to add the Task to.
  • taskID - string - TaskID is the ID of the task.
  • text - string - Text is the string that describes the Task.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/TasksService.UpdateTaskText" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123456",
	"taskID": "task-123456",
	"text": "Check the logs"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	tasksService := incident.NewTasksService(client)
	// make the request...
	updateTaskTextResp, err := tasksService.UpdateTaskText(ctx, main.UpdateTaskTextRequest{
		IncidentID: "incident-123456",
		TaskID: "task-123456",
		Text: "Check the logs",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("IncidentID: %+v\n", updateTaskTextResp.IncidentID)
	log.Printf("Task: %+v\n", updateTaskTextResp.Task)
	log.Printf("TaskList: %+v\n", updateTaskTextResp.TaskList)
	log.Printf("Error: %+v\n", updateTaskTextResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/TasksService.UpdateTaskText
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123456",
	"taskID": "task-123456",
	"text": "Check the logs"
}
JavaScript
import { GrafanaIncidentClient, TasksService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const tasksService = new TasksService(client);

// UpdateTaskText updates the task's text.
const tasksServiceResp = await tasksService.updateTaskText({
	"incidentID": "incident-123456",
	"taskID": "task-123456",
	"text": "Check the logs"
});

if (!tasksServiceResp.success) {
  // handle the error
  throw new Error(tasksServiceResp.error);
}

// access the fields of the response
console.info({"incidentID", tasksServiceResp.data.incidentID});
console.info({"task", tasksServiceResp.data.task});
console.info({"taskList", tasksServiceResp.data.taskList});

UpdateTaskTextResponse

A 200 response with an empty error field indicates that the request was successful.

  • incidentID - string - IncidentID is the ID of the incident these tasks relate to.
  • task - Task - Task is the newly added Task. It will also appear in Tasks.
  • taskList - TaskList - TaskList is the tasks list.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incidentID": "incident-123456",
	"task": {
		"assignedUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"authorUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2018-01-01T00:00:00Z",
		"immutable": true,
		"modifiedTime": "2018-01-01T00:00:00Z",
		"status": "todo",
		"taskID": "task-123456",
		"text": "Assign an investigator"
	},
	"taskList": {
		"doneCount": 8,
		"tasks": [
			{
				"assignedUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"authorUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"createdTime": "2018-01-01T00:00:00Z",
				"immutable": true,
				"modifiedTime": "2018-01-01T00:00:00Z",
				"status": "todo",
				"taskID": "task-123456",
				"text": "Assign an investigator"
			},
			{
				"assignedUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"authorUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"createdTime": "2018-01-01T00:00:00Z",
				"immutable": true,
				"modifiedTime": "2018-01-01T00:00:00Z",
				"status": "todo",
				"taskID": "task-123456",
				"text": "Assign an investigator"
			}
		],
		"todoCount": 5
	}
}

UpdateTaskUser

UpdateTaskUser updates the task's assigned user. Passing an empty user ID will clear the assigned user.

UpdateTaskUserRequest

  • incidentID - string - IncidentID is the ID of the Incident to add the Task to.
  • taskID - string - TaskID is the ID of the Task to update.
  • userID - string - UserID is the ID of the User to assign to the Task.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/TasksService.UpdateTaskUser" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"incidentID": "incident-123456",
	"taskID": "task-12345",
	"userID": "user-id"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	tasksService := incident.NewTasksService(client)
	// make the request...
	updateTaskUserResp, err := tasksService.UpdateTaskUser(ctx, main.UpdateTaskUserRequest{
		IncidentID: "incident-123456",
		TaskID: "task-12345",
		UserID: "user-id",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("IncidentID: %+v\n", updateTaskUserResp.IncidentID)
	log.Printf("Task: %+v\n", updateTaskUserResp.Task)
	log.Printf("TaskList: %+v\n", updateTaskUserResp.TaskList)
	log.Printf("Error: %+v\n", updateTaskUserResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/TasksService.UpdateTaskUser
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"incidentID": "incident-123456",
	"taskID": "task-12345",
	"userID": "user-id"
}
JavaScript
import { GrafanaIncidentClient, TasksService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const tasksService = new TasksService(client);

// UpdateTaskUser updates the task's assigned user.
Passing an empty user ID will clear the assigned user.
const tasksServiceResp = await tasksService.updateTaskUser({
	"incidentID": "incident-123456",
	"taskID": "task-12345",
	"userID": "user-id"
});

if (!tasksServiceResp.success) {
  // handle the error
  throw new Error(tasksServiceResp.error);
}

// access the fields of the response
console.info({"incidentID", tasksServiceResp.data.incidentID});
console.info({"task", tasksServiceResp.data.task});
console.info({"taskList", tasksServiceResp.data.taskList});

UpdateTaskUserResponse

A 200 response with an empty error field indicates that the request was successful.

  • incidentID - string - IncidentID is the ID of the incident these tasks relate to.
  • task - Task - Task is the newly added Task. It will also appear in Tasks.
  • taskList - TaskList - TaskList is the tasks list.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"incidentID": "incident-123456",
	"task": {
		"assignedUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"authorUser": {
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"userID": "user-123"
		},
		"createdTime": "2018-01-01T00:00:00Z",
		"immutable": true,
		"modifiedTime": "2018-01-01T00:00:00Z",
		"status": "todo",
		"taskID": "task-123456",
		"text": "Assign an investigator"
	},
	"taskList": {
		"doneCount": 8,
		"tasks": [
			{
				"assignedUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"authorUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"createdTime": "2018-01-01T00:00:00Z",
				"immutable": true,
				"modifiedTime": "2018-01-01T00:00:00Z",
				"status": "todo",
				"taskID": "task-123456",
				"text": "Assign an investigator"
			},
			{
				"assignedUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"authorUser": {
					"name": "Morty Smith",
					"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
					"userID": "user-123"
				},
				"createdTime": "2018-01-01T00:00:00Z",
				"immutable": true,
				"modifiedTime": "2018-01-01T00:00:00Z",
				"status": "todo",
				"taskID": "task-123456",
				"text": "Assign an investigator"
			}
		],
		"todoCount": 5
	}
}

UsersService

UsersService provides services related to people in the system.

  • GetUser - GetUser returns the information about a specific user.
  • QueryUsers - QueryUsers gets a list of users.

GetUser

GetUser returns the information about a specific user.

GetUserRequest

  • userID - string - UserID is the user ID to find the user for. All ids are in the format “provider:user-id” which allows you to refer to users from different providers. “grafana-incident:” is preferred, but all are accepted.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/UsersService.GetUser" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"userID": "grafana-incident:123"
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	usersService := incident.NewUsersService(client)
	// make the request...
	getUserResp, err := usersService.GetUser(ctx, main.GetUserRequest{
		UserID: "grafana-incident:123",
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("User: %+v\n", getUserResp.User)
	log.Printf("Error: %+v\n", getUserResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/UsersService.GetUser
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"userID": "grafana-incident:123"
}
JavaScript
import { GrafanaIncidentClient, UsersService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const usersService = new UsersService(client);

// GetUser returns the information about a specific user.
const usersServiceResp = await usersService.getUser({
	"userID": "grafana-incident:123"
});

if (!usersServiceResp.success) {
  // handle the error
  throw new Error(usersServiceResp.error);
}

// access the fields of the response
console.info({"user", usersServiceResp.data.user});

GetUserResponse

A 200 response with an empty error field indicates that the request was successful.

  • user - User - User is the user
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"error": "something went wrong",
	"user": {
		"email": "you@company.com",
		"grafanaLogin": "admin",
		"grafanaUserID": "123",
		"internalUserID": "user-12345",
		"modifiedTime": "2021-08-07T11:58:23Z",
		"msTeamsUserID": "26e2b619-b955-483f-a519-c8950aacbaa9",
		"name": "Morty Smith",
		"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
		"slackTeamID": "DEF123456",
		"slackUserID": "ABC123456",
		"userID": "grafana-incident:123"
	}
}

QueryUsers

QueryUsers gets a list of users.

QueryUsersRequest

  • query - UsersQuery - Query describes the query to make
  • cursor - Cursor - Cursor is used to page through results. Empty for the first page. For subsequent pages, use previously returned Cursor values.
curl
curl "https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/UsersService.QueryUsers" \
  --request POST \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...' \
  --data '{
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"query": {
		"limit": 10
	}
}'
Go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	incident "github.com/grafana/incident-go"
)

func main() {
	ctx := context.Background()
	// create a client, and required services...
	serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
	client := incident.NewClient("https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1", serviceAccountToken)
	usersService := incident.NewUsersService(client)
	// make the request...
	queryUsersResp, err := usersService.QueryUsers(ctx, main.QueryUsersRequest{
		Query: main.UsersQuery{
			Limit: 10,
		},
		Cursor: main.Cursor{
			NextValue: "aaaabbbbccccddddeeeeffffgggg",
			HasMore: true,
		},
	})
	if err != nil {
		// something went wrong
		fmt.Errorf(os.Stderr, "%s\n", err)
		os.Exit(1)
	}
	// use the output fields...
	log.Printf("Users: %+v\n", queryUsersResp.Users)
	log.Printf("Query: %+v\n", queryUsersResp.Query)
	log.Printf("Cursor: %+v\n", queryUsersResp.Cursor)
	log.Printf("Error: %+v\n", queryUsersResp.Error)

}
json
POST https://your-stack.grafana.net/api/plugins/grafana-incident-app/resources/api/v1/UsersService.QueryUsers
Content-Type="application/json; charset=utf-8"
Authorization: Bearer glsa_HOruNAb7SOiCdshU9algkrq7F...

{
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"query": {
		"limit": 10
	}
}
JavaScript
import { GrafanaIncidentClient, UsersService } from '@grafana/incident-node';

// https://grafana.com/docs/grafana-cloud/incident/api/auth/#get-a-service-account-token
const serviceAccountToken = process.env.GRAFANA_CLOUD_SERVICE_ACCOUNT_TOKEN;
const client = new GrafanaIncidentClient(
  "https://your-stack.grafana.net",
  serviceAccountToken
);
const usersService = new UsersService(client);

// QueryUsers gets a list of users.
const usersServiceResp = await usersService.queryUsers({
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"query": {
		"limit": 10
	}
});

if (!usersServiceResp.success) {
  // handle the error
  throw new Error(usersServiceResp.error);
}

// access the fields of the response
console.info({"users", usersServiceResp.data.users});
console.info({"query", usersServiceResp.data.query});
console.info({"cursor", usersServiceResp.data.cursor});

QueryUsersResponse

A 200 response with an empty error field indicates that the request was successful.

  • users - array of User - Users is a list of Users.
  • query - UsersQuery - Query is the query that was used to generate this response.
  • cursor - Cursor - Cursor should be passed back to get the next page of results.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.
JSON
{
	"cursor": {
		"hasMore": true,
		"nextValue": "aaaabbbbccccddddeeeeffffgggg"
	},
	"error": "something went wrong",
	"query": {
		"limit": 10
	},
	"users": [
		{
			"email": "you@company.com",
			"grafanaLogin": "admin",
			"grafanaUserID": "123",
			"internalUserID": "user-12345",
			"modifiedTime": "2021-08-07T11:58:23Z",
			"msTeamsUserID": "26e2b619-b955-483f-a519-c8950aacbaa9",
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"slackTeamID": "DEF123456",
			"slackUserID": "ABC123456",
			"userID": "grafana-incident:123"
		},
		{
			"email": "you@company.com",
			"grafanaLogin": "admin",
			"grafanaUserID": "123",
			"internalUserID": "user-12345",
			"modifiedTime": "2021-08-07T11:58:23Z",
			"msTeamsUserID": "26e2b619-b955-483f-a519-c8950aacbaa9",
			"name": "Morty Smith",
			"photoURL": "https://upload.wikimedia.org/wikipedia/en/c/c3/Morty_Smith.png",
			"slackTeamID": "DEF123456",
			"slackUserID": "ABC123456",
			"userID": "grafana-incident:123"
		}
	]
}

Objects

Various other structures (objects) are described throughtout the API reference, and a complete list of them is included here. They included the various Request and Response pairs for each method.

  • ActivityItem - ActivityItem describes an event that occurred related to an Incident.
  • ActivityQuery - ActivityQuery is the response from the QueryActivity method.
  • Assignment - Relation between a User and a Role inside the incident
  • AssignmentPreview - AssignmentPreview describes a person assigned to an incident without the Role object.
  • Attachment - Attachment is a file attached to something.
  • Cursor - Cursor describes the position in a result set. It is passed back into the same API to get the next page of results.
  • CustomMetadataFieldValue - CustomMetadataFieldValue is a custom metadata field value.
  • Field - Field represents a key/value pair, with additional metadata. Fields are used to represent dynamic data structures.
  • GetHomescreenVersionRequest - GetHomescreenVersionRequest is the request for the GetHomescreenVersion method.
  • GetHomescreenVersionResponse - GetHomescreenVersionResponse is the response for the GetHomescreenVersion method.
  • GetIncidentVersionRequest - GetIncidentVersionRequest is the request for the GetIncidentVersion method.
  • GetIncidentVersionResponse - GetIncidentVersionResponse is the response for the GetIncidentVersion method.
  • HookMetadata - HookMetadata contains metadata about the Run and Update of a Hook.
  • HookRun - HookRun describes the result of executing a Hook.
  • Incident - Incident is a single incident.
  • IncidentKeyValueLabel - IncidentKeyValueLabel is a key:value label associated with an Incident.
  • IncidentLabel - IncidentLabel is a label associated with an Incident.
  • IncidentMembership - IncidentMembership represents a list of people involved in an Incident.
  • IncidentMembershipPreview - IncidentMembershipPreview is a summary of the people involved in an Incident.
  • IncidentPreview - IncidentPreview is a minimal preview of a full Incident (omitting structured children) meant for lightweight listings or getting basic metadata.
  • IncidentPreviewsQuery - IncidentPreviewsQuery describes the query to make.
  • IncidentsQuery - IncidentsQuery is the query for the QueryIncidentsRequest.
  • IncomingWebhookResponse - IncomingWebhookResponse is the response sent back to the webhook caller when an incoming webhook has been received.
  • OutgoingWebhookPayload - OutgoingWebhookPayload represents the webhook HTTP POST body and contains metadata for the webhook.
  • Role - Role represents a role that will be used to assign people in the incident.
  • Task - Task is an individual task that somebody will do to resolve an Incident.
  • TaskList - TaskList is a list of tasks.
  • User - User contains the details of a person.
  • UserPreview - UserPreview is a user involved in an Incident.
  • UsersQuery - UsersQuery is the request for getting a list of users.

ActivityItem

ActivityItem describes an event that occurred related to an Incident.

  • activityItemID - string - The unique identifier of the ActivityItem.
  • incidentID - string - IncidentID is the unique identifier of the Incident.
  • user - UserPreview - User is the person who caused the ActivityItem.
  • subjectUser - UserPreview - SubjectUser is the person who was affected by the ActivityItem (not the person who caused it).
  • createdTime - string - CreatedTime is the time when the ActivityItem was created. The string value format should follow RFC 3339.
  • eventTime - string - EventTime is the time when the event occurred. It is configurable by the user. The string value format should follow RFC 3339.
  • activityKind - string - options: "incidentUpdated" "incidentTitleChanged" "incidentStatusChanged" "incidentSeverityChanged" "incidentCreated" "incidentDeleted" "incidentClosed" "roleAssigned" "roleUnassigned" "actionRun" "userNote" "dataQuery" "hookRunMetadata" "taskAdded" "taskUpdated" "taskCompleted" "taskDeleted" "messageReaction" "contextAttached" "incidentIsDrillChanged" "incidentStart" "incidentEnd" "incidentSummary" "labelAdded" "labelRemoved" "siftResult" - ActivityKind is the type of activity this item represents.
  • body - string - Body is a human readable description of the ActivityItem.
  • url - string - URL is an url related with this activity
  • tags - array of string - Tags contains a list of tags associated with this activity.
  • immutable - boolean - Immutable indicates if the activity is immutable.
  • fieldValues - object - FieldValues is an object of field values associated with the ActivityItem. The structure is determined by the ActivityKind.
  • attachments - array of Attachment - Attachments is a list of files attached to this item.
  • relevance - string - options: "automatic" "archive" "low" "normal" "high" - Relevance is the preferred relevance of the activity item. if set to ‘automatic’ (the default), the relevance will be guessed automatically.

ActivityQuery

ActivityQuery is the response from the QueryActivity method.

  • incidentID - string - IncidentID is the unique identifier of the Incident.
  • limit - number - Limit is the number of Incidents to return.
  • tag - string - Tag is the tag to filter by.
  • orderDirection - string - options: "ASC" "DESC" - OrderDirection is the direction to order the results.
  • activityKind - array of string - ActivityKind filters by a list of allowed ActivityKind’s.

AddActivityRequest

AddActivityRequest is the request for the AddActivity method.

  • incidentID - string - IncidentID is the unique identifier of the Incident.
  • activityKind - string - options: "userNote" - ActivityKind is the type of activity this item represents.
  • body - string - Body is a human readable description of the ActivityItem. URLs mentioned will be parsed and attached as context.
  • eventTime - string - EventTime is the time when the event occurred. If empty, the current time is used. The string value format should follow RFC 3339.

AddActivityResponse

AddActivityResponse is the response from the AddActivity method.

  • activityItem - ActivityItem - ActivityItem is the newly created ActivityItem.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

AddLabelRequest

AddLabelRequest is the request for the AddLabel method.

  • incidentID - string - IncidentID is the identifier of the Incident.
  • label - IncidentLabel - Label is the new label of the Incident.

AddLabelResponse

AddLabelResponse is the response for the AddLabel method.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

AddTaskRequest

AddTaskRequest is the request for the AddTask method.

  • incidentID - string - IncidentID is the ID of the Incident to add the Task to.
  • text - string - Text is the todo item.
  • assignToUserID - string - AssignToUserId is the user the task wil be assigned to

AddTaskResponse

AddTaskResponse is the response from the AddTask method.

  • incidentID - string - IncidentID is the ID of the incident these tasks relate to.
  • task - Task - Task is the newly added Task. It will also appear in Tasks.
  • taskList - TaskList - TaskList is the tasks list.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

ArchiveRoleRequest

ArchiveRoleRequest is the request to archive a role.

  • roleID - number - Role to be archived to the organization

ArchiveRoleResponse

ArchiveRoleResponse is the response to archive a role.

  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

AssignLabelByUUIDRequest

AssignLabelByUUIDRequest is the request for the AssignLabelByUUID method.

  • incidentID - string - IncidentID is the identifier of the Incident.
  • keyUUID - string - KeyUUID is the label key uuid.
  • valueUUID - string - ValueUUID is the UUID of the label value.

AssignLabelByUUIDResponse

AssignLabelByUUIDResponse is the response from the AssignLabelByUUID method.

  • labels - array of IncidentKeyValueLabel - Labels is a list of labels
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

AssignLabelRequest

AssignLabelRequest is the request for the AssignLabel method.

  • incidentID - string - IncidentID is the identifier of the Incident.
  • key - string - Key is the label key.
  • value - string - Value is the value of the label.

AssignLabelResponse

AssignLabelResponse is the response from the AssignLabel method.

  • labels - array of IncidentKeyValueLabel - Labels is a list of labels
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

AssignRoleRequest

AssignRoleRequest is the request for the AssignRole method.

  • incidentID - string - IncidentID is the identifier.
  • userID - string - UserID is the identifier of the person to assign the role to.
  • role - string - options: "commander" "investigator" "observer" - Role is the role of this person.

AssignRoleResponse

AssignRoleResponse is the response for the AssignRole method.

  • incident - Incident - Incident is the Incident that was just updated.
  • didChange - boolean - DidChange indicates if the role was changed or not. If the role was already assigned, this will be false.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

Assignment

Relation between a User and a Role inside the incident

  • user - UserPreview - User is the person who holds this role.
  • role - Role - Role is the role string.
  • roleID - number - RoleID is the identifier of the role.

AssignmentPreview

AssignmentPreview describes a person assigned to an incident without the Role object.

  • user - UserPreview - User is the person who holds this role.
  • roleID - number - RoleID is the identifier of the role.

Attachment

Attachment is a file attached to something.

  • attachmentID - string - AttachmentID is the unique ID of this attachment.
  • attachedByUserID - string - AttachedByUserID is the ID of the user who attached this.
  • sourceURL - string - SourceURL is the URL of the file.
  • useSourceURL - boolean - UseSourceURL is true if the file should be downloaded from the source URL.
  • path - string - Path is the full path of the file.
  • uploadTime - string - UploadTime is the time the file was uploaded.
  • deletedTime - string - DeletedTime is the time the file was deleted. Empty string means the file hasn’t been deleted.
  • contentType - string - ContentType is the type of the file.
  • fileType - string - options: "file" "video" "image" "audio" "screenshare" - FileType is the type of file.
  • ext - string - Ext is the file extension.
  • contentLength - number - ContentLength is the ContentLength of the file in bytes.
  • displayType - string - options: "list" "embed" - DisplayType is how the file will be displayed.
  • downloadURL - string - DownloadURL for download
  • hasThumbnail - boolean - HasThumbnail is true if the file has a thumbnail.
  • thumbnailURL - string - ThumbnailURL for previews
  • sHA512 - string - SHA512 is the hash of the file contents.
  • attachmentErr - string - AttachmentErr is a string describing an error that occurred while processing the attachment.

CreateIncidentRequest

CreateIncidentRequest is the request for the CreateIncident method.

  • title - string - Title is the headline title of the Incident. Shorter the better, but should contain enough information to be able to identify and refer to this issue.
  • severity - string - Severity expresses how bad the Incident is.
  • labels - array of IncidentLabel - Labels are the labels associated with the Incident. Only the Label string is processed, the other fields are ignored.
  • roomPrefix - string - RoomPrefix is the prefix that will be used to create the Incident room.
  • isDrill - boolean - IsDrill indicates if the Incident is a drill or not. Incidents that are drills do not show up in the dashboards, and may behave subtly differently in other ways too. For example, during drills, more help might be offered to users.
  • status - string - options: "active" "resolved" - Status is the starting status of the Incident. Use “resolved” to open a retrospective incident.
  • attachCaption - string - AttachCaption is the title of associated URL.
  • attachURL - string - AttachURLis the associated URL.

CreateIncidentResponse

CreateIncidentResponse is the response for the CreateIncident method.

  • incident - Incident - Incident is the Incident that was created.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

CreateRoleRequest

CreateRoleRequest is the request to create a role.

  • role - Role - Role to be created to the organization

CreateRoleResponse

CreateRoleResponse is the response to create a role.

  • role - Role - Role is the newly created role.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

Cursor

Cursor describes the position in a result set. It is passed back into the same API to get the next page of results.

  • nextValue - string - NextValue is the start position of the next set of results. The implementation may change, so clients should not rely on this value.
  • hasMore - boolean - HasMore indicates whether there are more results or not. If HasMore is true, you can make the same request again (except using this Cursor instead) to get the next page of results.

CustomMetadataFieldValue

CustomMetadataFieldValue is a custom metadata field value.

  • fieldUUID - string - FieldUUID is the ID of the field.
  • value - string - Value is the json encoded value of the field.

DeleteRoleRequest

DeleteRoleRequest is the request to delete a role.

  • roleID - number - Role to be deleted to the organization

DeleteRoleResponse

DeleteRoleResponse is the response to delete a role.

  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

DeleteTaskRequest

DeleteTaskRequest is the request for the DeleteTask method.

  • incidentID - string - IncidentID is the ID of the Incident.
  • taskID - string - TaskID is the ID of the task.

DeleteTaskResponse

DeleteTaskResponse is the response from the DeleteTask method.

  • incidentID - string - IncidentID is the ID of the incident these tasks relate to.
  • taskList - TaskList - TaskList is the tasks list.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

Field

Field represents a key/value pair, with additional metadata. Fields are used to represent dynamic data structures.

  • key - string - Key is the name of the field.
  • type - string - options: "string" "string[grafana.apiKey:viewer]" "string[grafana.apiKey:admin]" "bool" - Type describes acceptable data for Value.
  • description - string - Description is the description of the field.
  • value - string - Value is the value of the field when running an action.
  • secret - boolean - Secret is a marker that the field contains secret data and should not be visible to users.
  • checked - boolean - Checked is true if the bool field has been checked.
  • hidden - boolean - Hidden indicates that a field should not be shown in the UI. It is not secret, just noisy, so hidden and out of the way.

GetHomescreenVersionRequest

GetHomescreenVersionRequest is the request for the GetHomescreenVersion method.

  • No fields

GetHomescreenVersionResponse

GetHomescreenVersionResponse is the response for the GetHomescreenVersion method.

  • version - number - Version is the refresh value of the home screen. A higher value than last time indicates that the home screen should be refreshed.

GetHookRunsRequest

GetHookRunsRequest is the request for the GetHookRuns method.

  • incidentID - string - IncidentID is the identifier of the incident to get hook runs for.

GetHookRunsResponse

GetHookRunsResponse is the response for the GetHookRuns method.

  • hookRuns - array of HookRun - HookRuns is a list of HookRuns for this Incident.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

GetIncidentMembershipRequest

GetIncidentMembershipRequest is the request for the GetIncidentMembership method.

  • incidentID - string - IncidentID is the identifier of the Incident.

GetIncidentMembershipResponse

GetIncidentMembershipResponse is the response for the GetIncidentMembership method.

  • assignments - array of Assignment - IncidentMembership is the list of people involved in an incident
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

GetIncidentRequest

GetIncidentRequest is the request for the GetIncident method.

  • incidentID - string - IncidentID is the identifier.

GetIncidentResponse

GetIncidentResponse is the response for the GetIncident method.

  • incident - Incident - Incident is the Incident.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

GetIncidentVersionRequest

GetIncidentVersionRequest is the request for the GetIncidentVersion method.

  • incidentID - string - IncidentID is the identifier of the Incident. A higher value than last time indicates that the dashboard should be refreshed.

GetIncidentVersionResponse

GetIncidentVersionResponse is the response for the GetIncidentVersion method.

  • version - number - Version is the refresh value of the Incident.

GetLabelsRequest

GetLabelsRequest is the request for the GetLabels method.

  • incidentID - string - IncidentID is the identifier of the Incident.

GetLabelsResponse

GetLabelsResponse is the response from the GetLabels method.

  • labels - array of IncidentKeyValueLabel - Labels is a list of labels
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

GetRolesRequest

GetRolesRequest is the request to get all roles.

  • No fields

GetRolesResponse

GetRolesResponse is the response to get all roles.

  • roles - array of Role - Roles is the list of roles.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

GetUserRequest

GetUserRequest is the request for GetUser.

  • userID - string - UserID is the user ID to find the user for. All ids are in the format “provider:user-id” which allows you to refer to users from different providers. “grafana-incident:” is preferred, but all are accepted.

GetUserResponse

GetUserResponse contains the information about a user.

  • user - User - User is the user
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

HookMetadata

HookMetadata contains metadata about the Run and Update of a Hook.

  • title - string - Title is a title that relates to this Hook’s run.
  • explanation - string - Explanation is a brief description about what action was taken.
  • url - string - URL is an optional URL to a place users can go for more information.

HookRun

HookRun describes the result of executing a Hook.

  • integrationID - string - IntegrationID is the ID of the installed Integration that the Hook belongs to.
  • hookID - string - HookID is the ID of the Hook that was run.
  • enabledHookID - string - EnabledHookID is the ID of the enabled hook instance.
  • lastRun - string - LastRun is the time the hook was last run.
  • lastUpdate - string - LastUpdate is the time the hook was last updated.
  • metadata - HookMetadata - Metadata holds Hook specific key/value pairs.
  • eventName - string - options: "incidentCreated" "incidentDeleted" "incidentUpdated" "incidentClosed" "manuallyTriggered" "incidentFilter" - EventName is the name of the event that triggered the Hook to run.
  • eventKind - string - EventKind gives more detail about the type of event.
  • updateStatus - string - options: "todo" "success" "failed" - UpdateStatus is the status of the Hook update.
  • updateError - string - UpdateError is an error string to show the end-user for when UpdateStatus is “failed”.
  • status - string - options: "todo" "success" "failed" - Status is the status of the Hook run.
  • error - string - Error is an error string to show the end-user for when Status is “failed”.

Incident

Incident is a single incident.

  • incidentID - string - IncidentID is the identifier.
  • severity - string - Severity expresses how bad the Incident is.
  • labels - array of IncidentLabel - Labels is a list of strings associated with this Incident.
  • isDrill - boolean - IsDrill indicates if the Incident is a drill or not. Incidents that are drills do not show up in the dashboards, and may behave subtly differently in other ways too. For example, during drills, more help might be offered to users.
  • createdTime - string - CreatedTime is when the Incident was created. The string value format should follow RFC 3339.
  • modifiedTime - string - ModifiedTime is when the Incident was last modified. The string value format should follow RFC 3339.
  • createdByUser - UserPreview - CreatedByUser is the UserPreview that created the Incident.
  • closedTime - string - ClosedTime is when the Incident was closed. The string value format should follow RFC 3339.
  • durationSeconds - number - DurationSeconds is the number of seconds this Incident was (or is) open for.
  • status - string - options: "active" "resolved" - Status is the current status of the Incident.
  • title - string - Title is the high level description of the Incident.
  • overviewURL - string - OverviewURL is the URL to the overview page for the Incident.
  • incidentMembership - IncidentMembership - Assignments describes the individuals involved in the Incident.
  • taskList - TaskList - TaskList is the list of tasks associated with the Incident.
  • summary - string - Summary is as short recap of the Incident.
  • heroImagePath - string - HeroImagePath is the path to the hero image for this Incident.
  • incidentStart - string - IncidentStart is when the Incident began. The string value format should follow RFC 3339.
  • incidentEnd - string - IncidentEnd is when the Incident ended. The string value format should follow RFC 3339.

IncidentKeyValueLabel

IncidentKeyValueLabel is a key:value label associated with an Incident.

  • key - string - Key is the label key.
  • keyUUID - string - KeyUUID is the UUID of the label key.
  • valueUUID - string - ValueUUID is the UUID of the label value.
  • value - string - Value is the value of the label.
  • description - string - Description is a short explanation of the label.
  • colorHex - string - Color is the CSS hex color of the label. Labels show up in both light and dark modes, and this should be taken into consideration when selecting a color.

IncidentLabel

IncidentLabel is a label associated with an Incident.

  • key - string - Key is the label key. If not provided, we’ll default to ’tags’.
  • label - string - Label is the text of the label.
  • description - string - Description is a short explanation of the label.
  • colorHex - string - Color is the CSS hex color of the label. Labels show up in both light and dark modes, and this should be taken into consideration when selecting a color.

IncidentMembership

IncidentMembership represents a list of people involved in an Incident.

  • assignments - array of Assignment - List of all assignments done for that incident
  • totalAssignments - number - Total of assignments including hidden roles in the incident
  • totalParticipants - number - Total of participants in the incident excluding the assigned roles

IncidentMembershipPreview

IncidentMembershipPreview is a summary of the people involved in an Incident.

  • importantAssignments - array of AssignmentPreview - ImportantAssignments is a list of all assignments done for that incident that are marked as important.
  • totalAssignments - number - Total of assignments including hidden roles in the incident
  • totalParticipants - number - Total of hidden roles (like observers) related with that incident

IncidentPreview

IncidentPreview is a minimal preview of a full Incident (omitting structured children) meant for lightweight listings or getting basic metadata.

  • incidentID - string - IncidentID is the identifier.
  • severityID - string - Severity expresses how bad the incident is.
  • severityLabel - string - SeverityLabel is the label of the severity.
  • incidentType - string - options: "internal" "private" - IncidentType indicates the kind of incident to create.
  • labels - array of IncidentLabel - Labels is a list of strings associated with this Incident.
  • isDrill - boolean - IsDrill indicates if the incident is a drill or not. Incidents that are drills do not show up in the dashboards, and may behave subtly differently in other ways too. For example, during drills, more help might be offered to users.
  • createdTime - string - CreatedTime is when the Incident was created. The string value format should follow RFC 3339.
  • modifiedTime - string - ModifiedTime is when the Incident was last modified. The string value format should follow RFC 3339.
  • closedTime - string - ClosedTime is when the Incident was closed. The string value format should follow RFC 3339.
  • createdByUser - UserPreview - CreatedByUser is the UserPreview that created the Incident.
  • title - string - Title is the high level description of the Incident.
  • description - string - Description is a brief description of the Incident.
  • summary - string - Summary is as short recap of the incident.
  • heroImagePath - string - HeroImagePath is the path to the hero image for this Incident.
  • status - string - options: "active" "resolved" - Status is the current status of the Incident.
  • slug - string - Slug is a URL friendly path segment for the Incident.
  • incidentStart - string - IncidentStart is when the Incident began. The string value format should follow RFC 3339.
  • incidentEnd - string - IncidentEnd is when the Incident ended. The string value format should follow RFC 3339.
  • fieldValues - array of CustomMetadataFieldValue - FieldValues is the list of fields associated with the Incident and their values.
  • incidentMembershipPreview - IncidentMembershipPreview - IncidentMembershipPreview is a summary of the people involved in the Incident.
  • version - number - Version is the times that the incident has been updated

IncidentPreviewsQuery

IncidentPreviewsQuery describes the query to make.

  • limit - number - Limit is the number of Incidents to return.
  • orderDirection - string - options: "ASC" "DESC" - OrderDirection is the direction to order the results.
  • orderField - string - options: "incidentID" "createdTime" "modifiedTime" "title" "status" "severity" "prefix" "isDrill" "incidentStart" "incidentEnd" "closedTime" - OrderField is the field on which to order the results. If empty, createdTime will be used.
  • queryString - string - QueryString is the query string to search for. If provided, the query will be filtered by the query string and the other query parameters will be ignored.

IncidentsQuery

IncidentsQuery is the query for the QueryIncidentsRequest.

  • limit - number - Limit is the number of Incidents to return.
  • includeStatuses - array of string - options: "active" "resolved" - IncludeStatuses is a list of statuses to include. Only Incidents with the listed statuses will be returned.
  • excludeStatuses - array of string - options: "active" "resolved" - ExcludeStatuses is a list of statuses to exclude. All Incidents that do not match any of these values will be returned.
  • incidentLabels - array of string - IncidentLabels is a list of labels to include. An empty list will not filter by labels.
  • dateFrom - string - DateFrom if is not empty would filter by the Incidents created since that date (time.RFC3339)
  • dateTo - string - DateTo if is not empty would filter by incidents created before that date (time.RFC3339)
  • onlyDrills - boolean - OnlyDrills if is not empty filters by whether an incident is a drill or not.
  • orderDirection - string - options: "ASC" "DESC" - OrderDirection is the direction to order the results.
  • severity - string - Severity is a list of statuses to include. Only Incidents with the listed statuses will be returned.
  • queryString - string - QueryString is the query string to search for. If provided, the query will be filtered by the query string and the other query parameters will be ignored.

IncomingWebhookResponse

IncomingWebhookResponse is the response sent back to the webhook caller when an incoming webhook has been received.

  • incident - *Incident - Incident is the newly declared incident. Only included if the incoming webhook has the include=incident URL parameter.
  • processingErrors - array of string - ProcessingErrors is a list of errors that occurred while processing the webhook. If there are items in this list it does not mean the incident wasn’t created. But you should check to make sure everything was successfully processed before shipping to production.

OutgoingWebhookPayload

OutgoingWebhookPayload represents the webhook HTTP POST body and contains metadata for the webhook.

  • version - string - Version of this structure, following semantic versioning.
  • id - string - ID of event.
  • source - string - Source is a URI that identifies the context in which an event happened.
  • time - string - Time that event was generated (RFC 3339).
  • event - string - Event describes the (namespaced) event
  • incident - *Incident - Incident is the data payload, contains details about the data that was changed.

QueryActivityRequest

QueryActivityRequest is the request for the QueryActivity method.

  • query - ActivityQuery - Query describes the query to make.
  • cursor - Cursor - Cursor is used to page through results. Empty for the first page. For subsequent pages, use previously returned Cursor values.

QueryActivityResponse

QueryActivityResponse is the response from the QueryActivity method.

  • activityItems - array of ActivityItem - ActivityItems is the list of items.
  • query - ActivityQuery - Query is the query that was used to generate the response.
  • cursor - Cursor - Cursor is used to page through results. Empty for the first page. For subsequent pages, use previously returned Cursor values.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

QueryIncidentPreviewsRequest

QueryIncidentPreviews is the request for the QueryIncidentPreviews method.

  • query - IncidentPreviewsQuery - Query describes the query to make.
  • cursor - Cursor - Cursor is used to page through results. Empty for the first page. For subsequent pages, use previously returned Cursor values.
  • includeCustomFieldValues - boolean - IncludeCustomFieldValues if true will include custom field values in the response.
  • includeMembershipPreview - boolean - IncludeMembershipPreview if true will include membership previews in the response.

QueryIncidentPreviewsResponse

QueryIncidentPreviewsResponse is the response for the QueryIncidentPreviews method.

  • incidentPreviews - array of IncidentPreview - IncidentPreviews is a list of Incident Previews.
  • query - IncidentPreviewsQuery - Query is the query that was used to generate this response.
  • cursor - Cursor - Cursor should be passed back to get the next page of results.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

QueryIncidentsRequest

QueryIncidentsRequest is the request for the QueryIncidents method.

  • query - IncidentsQuery - Query describes the query to make.
  • cursor - Cursor - Cursor is used to page through results. Empty for the first page. For subsequent pages, use previously returned Cursor values.

QueryIncidentsResponse

QueryIncidentsResponse is the response for the QueryIncidents method.

  • incidents - array of Incident - Incidents is a list of Incidents.
  • query - IncidentsQuery - Query is the query that was used to generate this response.
  • cursor - Cursor - Cursor should be passed back to get the next page of results.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

QueryUsersRequest

QueryUsersRequest is the request for getting a list of users.

  • query - UsersQuery - Query describes the query to make
  • cursor - Cursor - Cursor is used to page through results. Empty for the first page. For subsequent pages, use previously returned Cursor values.

QueryUsersResponse

QueryUsersResponse is the response from QueryUsers.

  • users - array of User - Users is a list of Users.
  • query - UsersQuery - Query is the query that was used to generate this response.
  • cursor - Cursor - Cursor should be passed back to get the next page of results.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

RemoveActivityRequest

RemoveActivityRequest is the request for the RemoveActivity method.

  • incidentID - string - IncidentID is the identifier.
  • activityItemID - string - ActivityItemID is the unique identifier of the ActivityItem.

RemoveActivityResponse

RemoveActivityResponse is the response from the RemoveActivity method.

  • activityItem - ActivityItem - ActivityItem is the updated ActivityItem.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

RemoveLabelRequest

RemoveLabelRequest is the request for the RemoveLabel method.

  • incidentID - string - IncidentID is the identifier of the Incident.
  • label - string - Label is the label to remove from the Incident.

RemoveLabelResponse

RemoveLabelResponse is the response for the RemoveLabel method.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

Role

Role represents a role that will be used to assign people in the incident.

  • roleID - number - RoleID is the unique ID of this role.
  • orgID - string - OrgID is the unique ID of the organization this role belongs to.
  • name - string - Name is the name of the role.
  • description - string - Description is the description of the role.
  • important - boolean - Important is whether this role is important.
  • mandatory - boolean - Mandatory is whether this role is mandatory.
  • archived - boolean - Archived is whether this role is archived. Archived roles are not allowed to be assigned to people in the new incidents. But the historical data is still kept.
  • createdAt - string - CreatedAt is the time this role was created at.
  • updatedAt - string - UpdatedAt is the time this role was updated at.

Task

Task is an individual task that somebody will do to resolve an Incident.

  • taskID - string - TaskID is the ID of the task.
  • immutable - boolean - Immutable is true if the task cannot be changed. Used for tasks created and maintained by the system (like role assignment tasks).
  • createdTime - string - CreatedTime is the time the task was created.
  • modifiedTime - string - ModifiedTime is the time
  • text - string - Text is the string that describes the Task.
  • status - string - options: "todo" "progress" "done" - Status os the status of this task.
  • authorUser - *UserPreview - AuthorUser is the person who created this task.
  • assignedUser - *UserPreview - AssignedUser is the person this task is assigned to.

TaskList

TaskList is a list of tasks.

  • tasks - array of Task - Tasks is a list of tasks.
  • todoCount - number - TodoCount is the number of items in the list that are not yet done.
  • doneCount - number - DoneCount is the number of items in the list that are done.

UnarchiveRoleRequest

UnarchiveRoleRequest is the request to unarchive a role.

  • roleID - number - Role to be unarchived to the organization

UnarchiveRoleResponse

UnarchiveRoleResponse is the response to unarchive a role.

  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UnassignLabelByUUIDRequest

UnassignLabelByUUIDRequest is the request for the UnassignLabelByUUID method.

  • incidentID - string - IncidentID is the identifier of the Incident.
  • keyUUID - string - KeyUUID is the label key uuid.
  • valueUUID - string - ValueUUID is the UUID of the label value.

UnassignLabelByUUIDResponse

UnassignLabelByUUIDResponse is the response from the UnassignLabelByUUID method.

  • labels - array of IncidentKeyValueLabel - Labels is a list of labels
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UnassignLabelRequest

UnassignLabelRequest is the request for the UnassignLabel method.

  • incidentID - string - IncidentID is the identifier of the Incident.
  • key - string - Key is the label key.
  • value - string - Value is the value of the label.

UnassignLabelResponse

UnassignLabelResponse is the response from the UnassignLabel method.

  • labels - array of IncidentKeyValueLabel - Labels is a list of labels
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UnassignRoleRequest

UnassignRoleRequest is the request for the UnassignRole method.

  • incidentID - string - IncidentID is the identifier.
  • userID - string - UserID is the identifier of the person to assign the role to.
  • role - string - options: "commander" "investigator" "observer" - Role is the role of this person.

UnassignRoleResponse

UnassignRoleResponse is the response for the UnassignRole method.

  • incident - Incident - Incident is the Incident that was just updated.
  • didChange - boolean - DidChange indicates if the role was changed or not. If the role was not assigned, this will be false.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateActivityBodyRequest

UpdateActivityBodyRequest is the request for the UpdateActivityBody method.

  • incidentID - string - IncidentID is the identifier.
  • activityItemID - string - ActivityItemID is the unique identifier of the ActivityItem.
  • body - string - Body is the new body to use for the given activity item

UpdateActivityBodyResponse

UpdateActivityBodyResponse is the response from the UpdateActivityBody method.

  • activityItem - ActivityItem - ActivityItem is the updated ActivityItem.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateActivityEventTimeRequest

UpdateActivityEventTimeRequest is the request for the UpdateActivityEventTime method.

  • incidentID - string - IncidentID is the identifier.
  • activityItemID - string - ActivityItemID is the unique identifier of the ActivityItem.
  • eventTime - string - EventTime is the time when the event occurred. If empty, the created time of the activity item is used. The string value format should follow RFC 3339.

UpdateActivityEventTimeResponse

UpdateActivityEventTimeResponse is the response from the UpdateActivityEventTime method.

  • activityItem - ActivityItem - ActivityItem is the updated ActivityItem.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateActivityRelevanceRequest

UpdateActivityRelevanceRequest is the request for the UpdateActivityRelevance method.

  • incidentID - string - IncidentID is the identifier.
  • activityItemID - string - ActivityItemID is the unique identifier of the ActivityItem.
  • relevance - string - options: "automatic" "archive" "low" "normal" "high" - Relevance is the preferred relevance of the activity item. if set to ‘automatic’ (the default), the relevance will be guessed automatically.

UpdateActivityRelevanceResponse

UpdateActivityRelevanceResponse is the response from the UpdateActivityRelevance method.

  • activityItem - ActivityItem - ActivityItem is the updated ActivityItem.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateIncidentEventTimeRequest

UpdateIncidentEventTimeRequest is the request for the UpdateIncidentEventTime method.

  • incidentID - string - IncidentID is the identifier of the Incident.
  • eventTime - string - EventTime is the new time for the start or end of the incident. The string value format should follow RFC 3339.
  • activityItemKind - string - options: "incidentEnd" "incidentStart" - ActivityItemKind is either the incidentEnd or incidentStart time. deprecated. use EventName instead, ActivityItemKind will be removed soon.
  • eventName - string - options: "incidentEnd" "incidentStart" - EventName is either the incidentEnd or incidentStart time.

UpdateIncidentEventTimeResponse

UpdateIncidentEventTimeResponse is the response for the UpdateIncidentEventTime method.

  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateIncidentIsDrillRequest

UpdateIncidentIsDrillRequest is the request for the UpdateIncidentIsDrill method.

  • incidentID - string - IncidentID is the identifier of the Incident.
  • isDrill - boolean - IsDrill indicates whether the Incident is a drill or not.

UpdateIncidentIsDrillResponse

UpdateIncidentIsDrillResponse is the response for the UpdateIncidentIsDrill method.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateRoleRequest

UpdateRoleRequest is the request to update a role.

  • role - Role - Role to be updated to the organization

UpdateRoleResponse

UpdateRoleResponse is the response to update a role.

  • role - Role - Role is the newly updated role.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateSeverityRequest

UpdateSeverityRequest is the request for the UpdateSeverity method.

  • incidentID - string - IncidentID is the identifier of the Incident.
  • severity - string - Severity expresses how bad the Incident is.

UpdateSeverityResponse

UpdateSeverityResponse is the response for the UpdateSeverity method.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateStatusRequest

UpdateStatusRequest is the request for the UpdateStatus method.

  • incidentID - string - IncidentID is the identifier of the Incident.
  • status - string - options: "active" "resolved" - Status is the new status of the Incident.

UpdateStatusResponse

UpdateStatusResponse is the response for the UpdateStatus method.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateTaskStatusRequest

UpdateTaskStatusRequest is the request for the UpdateTaskStatus method.

  • incidentID - string - IncidentID is the ID of the Incident to add the Task to.
  • taskID - string - TaskID is the ID of the Task to update.
  • status - string - options: "todo" "progress" "done" - Status is the new status of this task.

UpdateTaskStatusResponse

UpdateTaskStatusResponse is the response from the UpdateTaskStatus method.

  • incidentID - string - IncidentID is the ID of the incident these tasks relate to.
  • task - Task - Task is the newly added Task. It will also appear in Tasks.
  • taskList - TaskList - TaskList is the tasks list.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateTaskTextRequest

UpdateTaskTextRequest is the request for the UpdateTaskText method.

  • incidentID - string - IncidentID is the ID of the Incident to add the Task to.
  • taskID - string - TaskID is the ID of the task.
  • text - string - Text is the string that describes the Task.

UpdateTaskTextResponse

UpdateTaskTextResponse is the response from the UpdateTaskText method.

  • incidentID - string - IncidentID is the ID of the incident these tasks relate to.
  • task - Task - Task is the newly added Task. It will also appear in Tasks.
  • taskList - TaskList - TaskList is the tasks list.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateTaskUserRequest

UpdateTaskUserRequest is the request for the UpdateTaskUser method.

  • incidentID - string - IncidentID is the ID of the Incident to add the Task to.
  • taskID - string - TaskID is the ID of the Task to update.
  • userID - string - UserID is the ID of the User to assign to the Task.

UpdateTaskUserResponse

UpdateTaskUserResponse is the response from the UpdateTaskUser method.

  • incidentID - string - IncidentID is the ID of the incident these tasks relate to.
  • task - Task - Task is the newly added Task. It will also appear in Tasks.
  • taskList - TaskList - TaskList is the tasks list.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

UpdateTitleRequest

UpdateTitleRequest is the request for the UpdateTitle method.

  • incidentID - string - IncidentID is the identifier of the Incident.
  • title - string - Title is the new title of the Incident.

UpdateTitleResponse

UpdateTitleResponse is the response for the UpdateTitle method.

  • incident - Incident - Incident is the Incident that was just modified.
  • error - string - Error is string explaining what went wrong. Empty if everything was fine.

User

User contains the details of a person.

  • userID - string - UserID is the identifier. It is in the format “provider:user-id” which allows you to refer to users from different providers. Sometimes, the same user is represented by multiple identifiers. You may always use this field whenever you need to refer to a user, the server will resolve them for you. “grafana-incident:{id}” is preferred.
  • internalUserID - string - InternalUserID is the internal user ID as stored in the database.
  • email - string - Email is the user’s email address.
  • modifiedTime - string - ModifiedTime is when this user was last modified. The string value format should follow RFC 3339.
  • name - string - Name is the user full name.
  • photoURL - string - PhotoURL is the user’s photo URL.
  • grafanaUserID - string - GrafanaUserID is the Grafana user ID.
  • grafanaLogin - string - GrafanaLogin is the Grafana login.
  • slackUserID - string - SlackUserID is the Slack user ID.
  • slackTeamID - string - SlackTeamID is the Slack organization ID.
  • msTeamsUserID - string - MsTeamsUserID is the MS Teams organization ID.

UserPreview

UserPreview is a user involved in an Incident.

  • userID - string - UserID is the identifier for the user.
  • name - string - Name is a human readable string that represents the user.
  • photoURL - string - PhotoURL is the URL to the profile picture of the user.

UsersQuery

UsersQuery is the request for getting a list of users.

  • limit - number - Limit is the max number of users to return.

This documentation was dynamically generated, please report any issues.