---
title: "Get started | Grafana Cloud documentation"
description: "Introduction and get started guide for the Grafana Incident JSON/HTTP RPC API"
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Get started

You can programmatically control Grafana Incident via the Grafana Incident JSON/HTTP RPC API.

Grafana Incident provides a simple JSON/HTTP RPC request/reply API, that exposes a series of useful methods for you to call remotely from your own code.

The endpoint is available at the following URL:

![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
https://your-stack.grafana.net/api/plugins/grafana-irm-app/resources/api/v1
```

**Note:** You will need to replace `your-stack.grafana.net` with your own instance.

You can explore the entire API surface in the [reference documentation](/docs/grafana-cloud/alerting-and-irm/incident/api/reference/) or continue reading for an introduction.

## Use cases

You can use the API along with the [Incoming](/docs/grafana-cloud/alerting-and-irm/irm/integrations/custom-integrations/incoming-webhooks) and [Outgoing](/docs/grafana-cloud/alerting-and-irm/irm/integrations/custom-integrations/outgoing-webhooks) webhooks to solve a wide range of integration use cases.

Some examples include:

- Trigger a ServiceNow workflow whenever an incident is declared
- Automatically add some common tasks whenever a specific label is added
- Send the Incident summary in an email when it is resolved
- Send a Slack DM to the Security Team if somebody adds the `security` label
- Trigger a custom tool whenever an incident is declared, and use the API to write an update to the activity feed

## How it works

To make calls into the API, you can use one of the [official client libraries](/docs/grafana-cloud/alerting-and-irm/incident/api/client-libraries/) or [construct your own HTTP requests](#make-your-own-http-requests%22).

You will need to use a [Service account token in the Authorization header](/docs/grafana-cloud/alerting-and-irm/incident/api/auth/) in order to authenticate your request.

An RPC API is like calling remote methods. For every request you make, you get a response.

## Examples

This section provides some real-world examples of how you will typically interact with the Grafana Incident JSON/HTTP RPC API.

> Although the examples are in Go, your code will likely look very similar regardless of your language choice.

### Declare an incident

Programmatically declare an incident in Go using the [Grafana Incident Go client library](https://github.com/grafana/incident-go):

Go ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```go
import (
  "fmt"
  "os"
  incident "github.com/grafana/incident-go"
)

func main() {
  // create a client, and the services you need
  serviceAccountToken := os.Getenv("SERVICE_ACCOUNT_TOKEN")
  client := incident.NewClient(
    "https://your-stack.grafana.net/api/plugins/grafana-irm-app/resources/api/v1",
    serviceAccountToken,
  )
  incidentsService := incident.NewIncidentsService(client)

  // declare an incident
  createIncidentResp, err := incidentsService.CreateIncident(ctx, incident.CreateIncidentRequest{
    Title: "short description explaining what's going wrong",
  })
  if err != nil {
    // if something goes wrong, the error will help you
    return fmt.Errorf("create incident: %w", err)
  }

  // success, get the details from the createIncidentResp object
  incidentID := createIncidentResp.Incident.IncidentID
  fmt.Println("declared Incident", createIncidentResp.Incident.IncidentID)
}
```

### Automatically add a task

To add a task to the above Incident, we can use the `*incident.TasksService` with the same `client`:

Go ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```go
tasksService := incident.NewTasksService(client)
addTaskResp, err := tasksService.AddTask(ctx, incident.AddTaskRequest{
    IncidentID: incidentID,
    Text:       "Consider tweeting to let people know",
})
if err != nil {
    // if something goes wrong, the error will help you
    return fmt.Errorf("add task: %w", err)
}
// success, print the result
fmt.Println("added task %s to incident %s", addTaskResp.Task.TaskID, incidentID)
```

### Post a Slack message if a specific label is added

By using webhooks when an incident is declared or updated,

Go ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```go
getIncidentResp, err := incidentsService.GetIncident(ctx, incident.GetIncidentRequest{
    IncidentID: incidentID,
})
if err != nil {
    return fmt.Errorf("get incident %s: %w", incidentID, err)
}

for _, item := range getIncidentResp.Incident.Labels {
    if item.Label == "specific-label" {
        postToSlack(ctx, "An incident has been flagged with the security label.")
        return
    }
}
```

You would write your own `postToSlack` method to interact with Slack’s API.

> **Note** It is possible for webhooks to fire multiple times as the Incident changes. It is up to you to make sure you don’t spam people.

## Make your own HTTP requests

You can interact with the Grafana Incident JSON/HTTP RPC API by making HTTP POST requests.

1. Figure out the correct endpoint by combining your host, API path, service and methods.
   
   For example, `https://your-stack.grafana.net/api/plugins/grafana-irm-app/resources/api/v1/IncidentsService.CreateIncident`, replacing `your-stack.grafana.net`.
2. Look up the relevant request and response objects from the [reference documentation](/docs/grafana-cloud/alerting-and-irm/incident/api/reference/) (they match the method name, for example, `CreateIncidentRequest` and `CreateIncidentResponse`).
3. Construct a JSON object representing the request object and set that as the body of the request.
4. Set the `Authorization` header to `Bearer your_service_account_token_here`.
   
   Learn more about [how to get your Service account token](/docs/grafana-cloud/alerting-and-irm/incident/api/auth/#get-a-service-account-token).
5. Set the `Content-Type` and `Accept` headers to `application/json; charset=utf-8`.
6. Make a `POST` request.
7. Parse the appropriate response object.