List integrations

API v3 is in preview

Endpoints and response shapes can change before general availability. API v2 is unchanged.

GET https://app.honeybadger.io/v3/projects/{project_id}/integrations

Required scope integrations:read

Returns a list of notification integrations for the project.

Example request

curl "https://app.honeybadger.io/v3/projects/$PROJECT_ID/integrations" \
  -H "Authorization: Bearer $HONEYBADGER_API_TOKEN"

Parameters

3

Path parameters

Field	Type	Description
project_id required	string	Project ID.

Query parameters

Field	Type	Description
page	integer	Page number (1-indexed). Default: 1. Min 1.
per_page	integer	Items per page. Default: 25. Min 1, max 100.

Responses

1

200 Success

Example payload

{
  "data": [
    {
      "id": "Ch9wLp",
      "project_id": "Xk9mZp",
      "type": "Slack",
      "active": true,
      "events": [
        "occurred",
        "resolved",
        "assigned"
      ],
      "site_ids": null,
      "check_in_ids": null,
      "excluded_environments": [
        "development"
      ],
      "included_environments": [],
      "filters": [
        {
          "event": "occurred",
          "query": "environment:production"
        }
      ],
      "alarm_alert_ids": [],
      "alarm_ok_ids": [],
      "threshold": 100,
      "rate": "min",
      "notification_limit": null,
      "connected": true,
      "config": {},
      "error": true,
      "error_reason": "The webhook URL returned 410 Gone",
      "created_at": "2026-01-01T00:00:00Z",
      "links": {
        "web": "https://app.honeybadger.io/projects/Xk9mZp"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25
  },
  "links": {
    "self": "/v3/projects/Xk9mZp/integrations?page=2&per_page=25",
    "first": "/v3/projects/Xk9mZp/integrations?page=1&per_page=25",
    "prev": "/v3/projects/Xk9mZp/integrations?page=1&per_page=25",
    "next": "/v3/projects/Xk9mZp/integrations?page=3&per_page=25"
  },
  "meta": {
    "request_id": "6f1c2b0e-8d4a-4f6e-9b2a-3c5d7e9f1a2b"
  }
}

Response schema35

Field	Type	Description
data required	array<object>
data[].id required	string
data[].project_id required	string	ID of the project this integration belongs to.
data[].type required	string	Integration type.
data[].active required	boolean	Whether to use the integration. An OAuth integration that isn't connected sends nothing until it is.
data[].events required	array<string>	Events this integration notifies on.
data[].site_ids required	array | null	Sites whose up and down events this integration receives. null means every site in the project, including ones added later.
data[].check_in_ids required	array | null	Check-ins whose events this integration receives. null means every check-in in the project, including ones added later.
data[].excluded_environments required	array<string>	Errors from these environments never notify through this integration. Takes precedence over included_environments.
data[].included_environments required	array<string>	When non-empty, only errors from these environments notify through this integration.
data[].filters required	array<object>	An ordered list. Each event that has a filter notifies only for errors matching its query.
data[].filters[].event required	string	An event a filter applies to, or all for every event. Allowed values: occurred, rate_exceeded, assigned, resolved, unresolved, commented, deployed, up, down, cert_will_expire, flooded, check_in_missing, check_in_reporting, alarm_alert, alarm_ok, volume_spike, all.
data[].filters[].query required	string	An error search query, as in the Errors search box. Min length 1.
data[].alarm_alert_ids required	array<string>	IDs of alarms whose alert events this integration receives.
data[].alarm_ok_ids required	array<string>	IDs of alarms whose recovery events this integration receives.
data[].threshold required	integer	Occurrence threshold before rate_exceeded fires.
data[].rate required	string	Period the rate_exceeded threshold counts over: min a minute, hour an hour, wday a day (24 hours, not a weekday), week a week. Allowed values: min, hour, wday, week.
data[].notification_limit required	integer | null	Maximum notifications in a 10-minute window before flood control.
data[].connected	boolean	Present on OAuth integrations (Slack, GitHub, GitLab, Bitbucket, Jira Cloud, Asana, Intercom and the like) and WebSocket integrations. On an OAuth integration it says whether the integration is authenticated, which someone does in the web UI at links.web. Separate from active: an active integration that isn't connected sends nothing until it is, and connecting doesn't change active. GitHub authenticates through the GitHub App: the app is installed on the repo, and the installation is attached when someone with access to it saves the integration. A creator who signed in to Honeybadger with GitHub is connected on create. On a WebSocket integration it says whether a client checked in within the last two minutes.
data[].config required	object	The type's settings, one IntegrationConfig<Type> per type. Unset settings are null. Write-only secrets are never returned. Other settings are, including webhook URLs, which can contain credentials.
data[].error	boolean	Set when a delivery fails in a way that stops the integration; error_reason says why. The integration sends nothing while it's set. A successful update clears it.
data[].error_reason	string	Reason for the error state, if any.
data[].created_at required	date-time	When the integration was created.
data[].links required	object	Links into the Honeybadger web UI.
data[].links.web required	uri	The resource's page in the Honeybadger web UI, as an absolute URL. Resources without a page, such as outages and deploys, don't have links. For a project provisioned through Heroku, error, notice and comment links go through Heroku's single sign-on.
pagination	object	Offset-based pagination information.
pagination.page required	integer	Current page number. Min 1.
pagination.per_page required	integer	Items per page. Min 1, max 100.
links	object	Navigation links for a numbered-page collection. Each link is a root-relative path (/v3/...); resolve it against the API host.
links.self required	uri-reference	This page.
links.first	uri-reference	First page.
links.prev	string | null	Previous page, or null on the first page.
links.next	string | null	Next page, or null on the last page.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

Errors

4

401 Unauthorized

The credential is missing, invalid, expired or revoked (unauthorized), or was sent in a way v3 doesn’t accept (see the examples).

Example payload: unauthorized (Missing, malformed, expired or revoked credential)

{
  "error": {
    "code": "unauthorized",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: unsupported_auth_scheme (Sent as HTTP basic, which v3 does not accept)

{
  "error": {
    "code": "unsupported_auth_scheme",
    "message": "Send the credential as `Authorization: Bearer <token>`; v3 does not accept HTTP basic"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: credential_in_query (Sent as the `auth_token` query parameter)

{
  "error": {
    "code": "credential_in_query",
    "message": "Credentials must be sent in the Authorization header"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

403 Forbidden

The credential isn’t allowed to do this. error.code says why. An account or project the credential doesn’t cover is 404 not_found, not 403.

Example payload: access_denied (The credential isn't allowed to do this to this record)

{
  "error": {
    "code": "access_denied",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: insufficient_scope (The credential lacks the permission this endpoint requires)

{
  "error": {
    "code": "insufficient_scope",
    "message": "Insufficient scope",
    "details": {
      "required_scope": "faults:write",
      "token_scopes": [
        "faults:read",
        "insights:read"
      ]
    }
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: requires_user_token (The endpoint records who acted, and an account token has nobody)

{
  "error": {
    "code": "requires_user_token",
    "message": "This endpoint records the person who acted, so it requires a user credential rather than an account token"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: project_restricted (A project-restricted credential cannot create a project)

{
  "error": {
    "code": "project_restricted",
    "message": "Project-restricted tokens cannot create projects"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

404 Not Found

Resource not found

Example payload

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.

422 Unprocessable Content

No path names the account, so the API token has to. This is returned when the token covers more than one account and the account a request applies to cannot be determined. Use a token bound to a single account.

Example payload

{
  "error": {
    "code": "ambiguous_account",
    "message": "This credential covers more than one account, so the account a request applies to is ambiguous. Use a token bound to a single account."
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
error required	object
error.code required	string	Machine-readable code. Branch on this, not the message. Allowed values: unauthorized, unsupported_auth_scheme, credential_in_query, access_denied, insufficient_scope, requires_user_token, project_restricted, account_inactive, account_parked, feature_unavailable, not_found, validation_error, delete_failed, limit_reached, rate_limit_exceeded, concurrent_request, streams_provisioning, ingestion_key_not_accepted, maintenance_mode, invalid_parameter, forbidden_attributes, service_unavailable, ambiguous_account, fault_merged.
error.message required	string	Human-readable explanation.
error.details	array<object> | object	A list of {field, message} on validation_error and invalid_parameter, and on feature_unavailable or limit_reached when one field caused the refusal; {required_scope, token_scopes} on insufficient_scope; {merged_into, location} on fault_merged. Absent when there's nothing to add.
meta	object
meta.request_id	string	Unique identifier for the request, for correlating with support.