> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GraphQL API mutation examples

AppSignal's [GraphQL API](/api/graphql) supports mutations as well as queries.
Where a [query](/api/graphql/examples) reads data, a mutation writes it: you can
create a custom marker, close an incident, add an uptime monitor, and more.

Mutations use the same endpoint and personal API token as queries. Read the
[GraphQL API page](/api/graphql) for details on the endpoint and authentication.

Most mutations are app-scoped and take an `appId` argument that scopes the change
to a single app. You can find your app ID in your app's [settings
screen](https://appsignal.com/redirect-to/app?to=admin/api_keys). Some mutations
are organization-scoped and take an `organizationSlug` argument instead, such as
`createApp` and `createStatusPage`.

This page covers the most common mutations. For the complete, auto-generated list
of every mutation and its arguments, see the [GraphQL schema
reference](https://appsignal.com/graphql/docs).

<Note>
  Mutations change data in your account. Test against a non-production app before
  you automate a mutation against production data.
</Note>

## Incidents

### Update an incident

Change an incident's state, severity, assignees, or notification settings. The
`number` is the incident number shown in AppSignal.

`state` accepts `OPEN`, `WIP`, or `CLOSED`. `severity` accepts `UNTRIAGED`,
`CRITICAL`, `HIGH`, `LOW`, `NONE`, or `INFORMATIONAL`.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation UpdateIncident(
    $appId: String!
    $number: Int!
    $state: IncidentStateEnum
    $severity: IncidentSeverityEnum
    $assigneeIds: [String!]
  ) {
    updateIncident(
      appId: $appId
      number: $number
      state: $state
      severity: $severity
      assigneeIds: $assigneeIds
    ) {
      ... on ExceptionIncident {
        id
        number
        state
        severity
      }
      ... on PerformanceIncident {
        id
        number
        state
        severity
      }
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "number": 42,
    "state": "CLOSED",
    "severity": "LOW"
  }
  ```
</CodeGroup>

### Bulk update incidents

Update several incidents in one request. Unlike `updateIncident`, this mutation
takes incident IDs rather than incident numbers.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation BulkUpdateIncidents(
    $appId: String!
    $ids: [String]!
    $state: IncidentStateEnum
    $severity: IncidentSeverityEnum
  ) {
    bulkUpdateIncidents(
      appId: $appId
      ids: $ids
      state: $state
      severity: $severity
    ) {
      ... on ExceptionIncident {
        id
        number
        state
      }
      ... on PerformanceIncident {
        id
        number
        state
      }
      ... on AnomalyIncident {
        id
        number
        state
      }
      ... on LogIncident {
        id
        number
        state
      }
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "ids": ["INCIDENT-ID-1", "INCIDENT-ID-2"],
    "state": "CLOSED"
  }
  ```
</CodeGroup>

### Create a note on an incident

Add a note to an incident's logbook. The same fields are available on
performance, anomaly, and log incidents.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CreateIncidentNote(
    $appId: String!
    $incidentNumber: Int!
    $content: String!
  ) {
    createIncidentNote(
      appId: $appId
      incidentNumber: $incidentNumber
      content: $content
    ) {
      ... on ExceptionIncident {
        id
        number
        logbook {
          items {
            ... on Note {
              id
              content
              createdAt
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "incidentNumber": 42,
    "content": "Investigating, deploy reverted."
  }
  ```
</CodeGroup>

### Create an issue from an incident

Create a linked issue in a connected integration. This example uses GitHub;
equivalent mutations exist for other integrations: `createGitlabIssue`,
`createJiraIssue`, `createLinearIssue`, `createShortcutStory`, `createAsanaTask`,
and `createTrelloCard`.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CreateGithubIssue(
    $appId: String!
    $incidentNumber: Int!
    $title: String!
    $description: String!
  ) {
    createGithubIssue(
      appId: $appId
      incidentNumber: $incidentNumber
      title: $title
      description: $description
    ) {
      ... on ExceptionIncident {
        id
        number
        integrations {
          ... on GitHub {
            name
            issues {
              url
              title
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "incidentNumber": 42,
    "title": "NoMethodError in OrdersController#create",
    "description": "Tracked in AppSignal incident #42."
  }
  ```
</CodeGroup>

### Remove an integration from an incident

Remove a previously linked integration issue from an incident.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation RemoveIntegration(
    $appId: String!
    $incidentNumber: Int!
    $id: String!
  ) {
    removeIntegration(
      appId: $appId
      incidentNumber: $incidentNumber
      id: $id
    ) {
      ... on ExceptionIncident {
        id
        number
      }
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "incidentNumber": 42,
    "id": "YOUR-INTEGRATION-ID"
  }
  ```
</CodeGroup>

## Markers

### Create or update a custom marker

Create a custom marker to annotate a point in time, such as a configuration
change or a manual action. Pass an `id` to update an existing marker. Omit `id`
to create a new marker.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CreateCustomMarker(
    $appId: String!
    $id: String
    $icon: String!
    $message: String
    $createdAt: DateTime
  ) {
    createOrUpdateCustomMarker(
      appId: $appId
      id: $id
      icon: $icon
      message: $message
      createdAt: $createdAt
    ) {
      id
      icon
      message
      createdAt
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "icon": "🚀",
    "message": "Ran database migration"
  }
  ```
</CodeGroup>

### Delete a custom marker

Delete a custom marker by ID.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation DeleteCustomMarker($appId: String!, $id: String!) {
    deleteCustomMarker(appId: $appId, id: $id) {
      id
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "id": "YOUR-MARKER-ID"
  }
  ```
</CodeGroup>

## Alerts and triggers

### Create a trigger

Create a metric-based alert trigger. `field` accepts a value from
`MetricFieldEnum` (such as `MEAN`, `P90`, `P95`, `COUNT`, `GAUGE`, or
`COUNTER`). `kind` is a string describing the trigger type. The GraphQL source
docs name `ExceptionRate` and `Throughput` as examples. The `condition` sets the
threshold to compare against. To replace an existing trigger, pass its ID as
`previousTriggerId`.

`comparisonOperator` accepts `LESS_THAN`, `GREATER_THAN`, `LESS_THAN_OR_EQUAL`,
`GREATER_THAN_OR_EQUAL`, `EQUAL`, or `NOT_EQUAL`.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CreateTrigger(
    $appId: String!
    $previousTriggerId: String
    $name: String
    $metricName: String!
    $kind: String!
    $field: MetricFieldEnum!
    $condition: ThresholdConditionInput!
    $warmupDuration: Int!
    $cooldownDuration: Int!
    $notifierIds: [String!]
  ) {
    createTrigger(
      appId: $appId
      previousTriggerId: $previousTriggerId
      name: $name
      metricName: $metricName
      kind: $kind
      field: $field
      condition: $condition
      warmupDuration: $warmupDuration
      cooldownDuration: $cooldownDuration
      notifierIds: $notifierIds
    ) {
      id
      name
      metricName
      field
      thresholdCondition {
        value
        comparisonOperator
      }
      warmupDuration
      cooldownDuration
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "name": "High error rate",
    "metricName": "transaction_exception_count",
    "kind": "ExceptionRate",
    "field": "COUNTER",
    "condition": { "value": 10, "comparisonOperator": "GREATER_THAN" },
    "warmupDuration": 0,
    "cooldownDuration": 5,
    "notifierIds": ["YOUR-NOTIFIER-ID"]
  }
  ```
</CodeGroup>

### Archive a trigger

Archive a trigger so it no longer evaluates metrics or sends alerts.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation ArchiveTrigger($appId: String!, $id: String!) {
    archiveTrigger(appId: $appId, id: $id) {
      id
      name
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "id": "YOUR-TRIGGER-ID"
  }
  ```
</CodeGroup>

### Archive an alert

Archive a single triggered alert. This mutation returns `true` on success.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation ArchiveAlert($appId: String!, $id: String!) {
    archiveAlert(appId: $appId, id: $id)
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "id": "YOUR-ALERT-ID"
  }
  ```
</CodeGroup>

### Close the last alert for an anomaly incident

Close the most recent open alert for an anomaly incident, identified by its
incident number.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation EndLastAlert($appId: String!, $number: Int!) {
    endLastAlert(appId: $appId, number: $number) {
      id
      number
      alertState
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "number": 42
  }
  ```
</CodeGroup>

## Uptime monitors

### Create an uptime monitor

Create an uptime monitor from a `UptimeMonitorInput`. `regions` accepts one or
more of `EUROPE`, `NORTH_AMERICA`, `ASIA_PACIFIC`, or `SOUTH_AMERICA`.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CreateUptimeMonitor(
    $appId: String!
    $uptimeMonitor: UptimeMonitorInput!
  ) {
    createUptimeMonitor(appId: $appId, uptimeMonitor: $uptimeMonitor) {
      id
      name
      url
      regions
      warmupDuration
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "uptimeMonitor": {
      "name": "Marketing site",
      "url": "https://example.com",
      "regions": ["EUROPE", "NORTH_AMERICA"],
      "warmupDuration": 1,
      "notifierIds": ["YOUR-NOTIFIER-ID"]
    }
  }
  ```
</CodeGroup>

### Update an uptime monitor

Update an existing monitor. The `uptimeMonitor` input takes the same shape as it
does when creating one.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation UpdateUptimeMonitor(
    $appId: String!
    $id: String!
    $uptimeMonitor: UptimeMonitorInput!
  ) {
    updateUptimeMonitor(
      appId: $appId
      id: $id
      uptimeMonitor: $uptimeMonitor
    ) {
      id
      name
      url
      regions
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "id": "YOUR-UPTIME-MONITOR-ID",
    "uptimeMonitor": {
      "name": "Marketing site",
      "url": "https://example.com/health",
      "regions": ["EUROPE"]
    }
  }
  ```
</CodeGroup>

### Delete an uptime monitor

Delete a monitor by ID. This mutation returns the deleted monitor.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation DeleteUptimeMonitor($appId: String!, $id: String!) {
    deleteUptimeMonitor(appId: $appId, id: $id) {
      id
      name
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "id": "YOUR-UPTIME-MONITOR-ID"
  }
  ```
</CodeGroup>

## Check-ins

### Create a check-in trigger

Create a cron or heartbeat check-in trigger. `kind` accepts `CRON` or
`HEARTBEAT`. For a cron trigger, set `syntax` to the cron expression. Use UTC
for `timezone` where possible.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CreateCheckInTrigger(
    $appId: String!
    $identifier: String!
    $kind: CheckInTriggerKindEnum!
    $waitTimeMinutes: Int!
    $syntax: String
    $timezone: String
    $notifierIds: [String!]
  ) {
    createCheckInTrigger(
      appId: $appId
      identifier: $identifier
      kind: $kind
      waitTimeMinutes: $waitTimeMinutes
      syntax: $syntax
      timezone: $timezone
      notifierIds: $notifierIds
    ) {
      id
      identifier
      kind
      syntax
      timezone
      waitTimeMinutes
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "identifier": "nightly-backup",
    "kind": "CRON",
    "syntax": "0 2 * * *",
    "timezone": "UTC",
    "waitTimeMinutes": 5,
    "notifierIds": ["YOUR-NOTIFIER-ID"]
  }
  ```
</CodeGroup>

### Update a check-in trigger

Update an existing check-in trigger. Only the fields you pass are changed.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation UpdateCheckInTrigger(
    $appId: String!
    $id: String!
    $syntax: String
    $waitTimeMinutes: Int
    $notifierIds: [String!]
  ) {
    updateCheckInTrigger(
      appId: $appId
      id: $id
      syntax: $syntax
      waitTimeMinutes: $waitTimeMinutes
      notifierIds: $notifierIds
    ) {
      id
      identifier
      syntax
      waitTimeMinutes
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "id": "YOUR-CHECK-IN-TRIGGER-ID",
    "syntax": "0 3 * * *",
    "waitTimeMinutes": 10
  }
  ```
</CodeGroup>

### Delete a check-in trigger

Delete a check-in trigger by ID.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation DeleteCheckInTrigger($appId: String!, $id: String!) {
    deleteCheckInTrigger(appId: $appId, id: $id) {
      id
      identifier
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "id": "YOUR-CHECK-IN-TRIGGER-ID"
  }
  ```
</CodeGroup>

## Dashboards

### Create a dashboard

Create an empty dashboard. Add visuals to it with the `createVisualTimeseries`
and `createVisualNumber` mutations, or import a complete dashboard with
`importDashboard`.

Dashboard visuals are also managed through `createVisualTimeseries`,
`createVisualNumber`, `updateVisualTimeseries`, `updateVisualNumber`,
`updateVisualLayouts`, and `deleteVisual`. To create a standalone saved visual
for later retrieval through the [saved visuals REST endpoints](/api/v2/saved-visuals),
use `createSavedVisual`.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CreateDashboard(
    $appId: String!
    $title: String!
    $description: String
  ) {
    createDashboard(appId: $appId, title: $title, description: $description) {
      id
      title
      description
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "title": "Background jobs",
    "description": "Throughput and queue time for worker jobs."
  }
  ```
</CodeGroup>

### Update a dashboard

Update a dashboard's title or description. The `title` is required.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation UpdateDashboard(
    $appId: String!
    $id: String!
    $title: String!
    $description: String
  ) {
    updateDashboard(
      appId: $appId
      id: $id
      title: $title
      description: $description
    ) {
      id
      title
      description
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "id": "YOUR-DASHBOARD-ID",
    "title": "Background jobs",
    "description": "Updated description."
  }
  ```
</CodeGroup>

### Delete a dashboard

Delete a dashboard by ID.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation DeleteDashboard($appId: String!, $id: String!) {
    deleteDashboard(appId: $appId, id: $id) {
      id
      title
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "id": "YOUR-DASHBOARD-ID"
  }
  ```
</CodeGroup>

### Import a dashboard

Import a dashboard from a JSON definition. The `json` argument is a
JSON-encoded string, so escape it when sending it as a variable.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation ImportDashboard($appId: String!, $json: String!) {
    importDashboard(appId: $appId, json: $json) {
      id
      title
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "json": "{\"title\":\"Imported dashboard\",\"visuals\":[]}"
  }
  ```
</CodeGroup>

## Logs

### Create a log trigger

Create a trigger that opens an incident when log lines match a query. `severities`
accepts log severity names such as `error`, `warn`, or `info`.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CreateLogTrigger(
    $appId: String!
    $name: String!
    $query: String!
    $sourceIds: [String!]
    $severities: [String!]
    $notifierIds: [String!]
  ) {
    createLogTrigger(
      appId: $appId
      name: $name
      query: $query
      sourceIds: $sourceIds
      severities: $severities
      notifierIds: $notifierIds
    ) {
      id
      name
      query
      severities
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "appId": "YOUR-APP-ID",
    "name": "Payment errors",
    "query": "payment failed",
    "severities": ["error"],
    "notifierIds": ["YOUR-NOTIFIER-ID"]
  }
  ```
</CodeGroup>

Logs are also managed through GraphQL beyond triggers. Use `createLogSource`,
`updateLogSource`, and `deleteLogSource` for sources; `createLogView`,
`updateLogView`, and `deleteLogView` for saved views; `createLogLineAction`,
`updateLogLineAction`, `deleteLogLineAction`, and `reorderLogLineActions` for
ingestion rules; `updateLogTrigger` and `deleteLogTrigger` for log triggers; and
`createLogExport`, `updateLogExport`, and `deleteLogExport` for S3 exports.

## Organization-scoped mutations

Some mutations act on an organization rather than a single app, so they take an
`organizationSlug` argument instead of `appId`. You can find the slug in the URL
of your organization in AppSignal.

### Create an app

Create a new app within an organization.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CreateApp(
    $organizationSlug: String!
    $name: String!
    $environment: String!
  ) {
    createApp(
      organizationSlug: $organizationSlug
      name: $name
      environment: $environment
    ) {
      id
      name
      environment
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "organizationSlug": "YOUR-ORGANIZATION-SLUG",
    "name": "My app",
    "environment": "production"
  }
  ```
</CodeGroup>

### Create a status page

Create a public status page from a `CreateStatusPageInput`. `title` and
`hostname` are required.

<CodeGroup>
  ```graphql Mutation theme={null}
  mutation CreateStatusPage(
    $organizationSlug: String!
    $statusPage: CreateStatusPageInput!
  ) {
    createStatusPage(
      organizationSlug: $organizationSlug
      statusPage: $statusPage
    ) {
      id
      title
      hostname
      state
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Variables theme={null}
  {
    "organizationSlug": "YOUR-ORGANIZATION-SLUG",
    "statusPage": {
      "title": "Service status",
      "hostname": "status.example.com",
      "uptimeMonitorIds": ["YOUR-UPTIME-MONITOR-ID"],
      "threshold": 1
    }
  }
  ```
</CodeGroup>

Status pages also support `createStatusPageUpdate`, `updateStatusPage`,
`updateStatusPageUpdate`, `deleteStatusPage`, and `deleteStatusPageUpdate`. For
CSV exports, use `createCsvExport` to start an export and `createCsvExportUrl`
to generate a download URL for a completed export.

## More mutations

These examples cover the most common operations. The API includes more, grouped
in the schema reference under Core (app and hosted collector management),
Dashboards (visuals and layouts), Logs (sources, views, and exports), Exports
(CSV), Status pages (updates), and User preferences. For the full list of
mutations and their arguments, see the [GraphQL schema
reference](https://appsignal.com/graphql/docs).