Teams API - ResolveAI

Create, read, update, and delete ResolveAI teams from your own scripts and pipelines. Each team is one JSON document: its name, description, communication channels, and membership.

Preview: the Teams API is enabled per organization. To turn it on, contact help@resolve.ai. Until it is on, every endpoint returns 403 with the code api_disabled.

What you can manage

Part of a team	Teams API
Name and description	Read and write
Membership: directory group bindings and additional members	Read and write
Communication channels (Slack, MS Teams)	Read and write
Alert filters	Read only

Resolve also changes channels and alert filters itself, for example when someone accepts a suggestion in Resolve. Expect those changes when you read a team.

Base URL

https://app.resolve.ai/api/v1

Use the host you sign in to if it differs from app.resolve.ai. All paths below are relative to this URL. Requests and responses use JSON.

Authentication

Send an API token created by an organization admin in the Authorization header:

Authorization: Bearer <your-token>

Create the token in Admin > API Tokens. The token acts with its creator’s current roles:

The token decides the organization. A request never names an organization, and a team of another organization returns 404.
A missing, invalid, or expired token, or one whose creator is deactivated, returns 401.
A token whose creator is not an organization admin returns 403. If the creator loses the admin role or leaves, create a new token and update your pipeline.

Security best practice: Never store credentials in plaintext in configuration files or source control. Keep the token in your CI secret store.

The team document

{
  "id": "Xb2kQ9vLm3TfR7wYc1NpA",
  "version": 7,
  "schemaVersion": 1,
  "spec": {
    "displayName": "Payments",
    "description": "Checkout and ledger services",
    "communicationChannels": {
      "channels": [
        {
          "key": { "integrationInstanceId": "<slack integration id>", "slack": { "channelId": "C07PAYALERTS" } },
          "purposes": ["ALERTS"]
        }
      ]
    },
    "alertFilters": { "filters": [] },
    "membership": {
      "groupBindings": [{ "groupId": "pD7rT2xN9qLs4KvB0cWeJ", "role": "MEMBER" }],
      "additionalMembers": [{ "email": "alice@example.com", "role": "ADMIN" }]
    }
  }
}

Field	Set by	Description
`id`	Resolve	The team id. It never changes, even when the team is renamed.
`version`	Resolve	Changes on every change to the team. Also returned as the `ETag` header.
`schemaVersion`	You	The schema version your client knows. Currently `1`.
`spec.displayName`	You	The team name, unique among your organization’s teams. Required on create.
`spec.description`	You	Free text. Optional; empty if left out.
`spec.communicationChannels`	You	Slack channels (`channelId`) or MS Teams channels (`conversationId`), each with purposes such as `ALERTS`. Optional. Order has no meaning; responses return channels and purposes sorted.
`spec.alertFilters`	Resolve	Read only. A write that contains this section returns `400` with the code `unsupported_section`.
`spec.membership`	You	Group bindings and additional members. See Membership.

Endpoints

Method and path	Purpose	Required headers	Success
`GET /teams`	List teams (`id`, `displayName`, `version`), with paging	—	`200`
`GET /teams?displayName=<name>`	Find the team with this exact name	—	`200`
`POST /teams`	Create a team	—	`201`, `ETag`, `Location`
`GET /teams/{id}`	Read a team	—	`200`, `ETag`
`PATCH /teams/{id}`	Update the sections you send; add `?dryRun=true` to preview	`If-Match`	`200`, new `ETag`
`DELETE /teams/{id}`	Delete a team	`If-Match`	`204`
`GET /groups`	Find directory groups to bind to a team	—	`200`
`GET /integrations?integrationKey=slack`	Find your connected integrations and their ids	—	`200`

List teams

curl -sS -H "Authorization: Bearer $TOKEN" "https://app.resolve.ai/api/v1/teams?limit=50"

{
  "teams": [
    { "id": "Xb2kQ9vLm3TfR7wYc1NpA", "version": 7, "displayName": "Payments" },
    { "id": "Hn4sD8eJq0ZuK6aGt2VmW", "version": 3, "displayName": "Checkout" }
  ],
  "nextCursor": "Y3VycmVudC1wYWdlLTI"
}

limit defaults to 100, with a maximum of 500. Pass nextCursor back as ?cursor= for the next page; it is null on the last page.

Create a team

curl -sS -X POST "https://app.resolve.ai/api/v1/teams" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaVersion": 1,
    "spec": {
      "displayName": "Payments",
      "description": "Checkout and ledger services",
      "membership": {
        "groupBindings": [{ "groupId": "pD7rT2xN9qLs4KvB0cWeJ", "role": "MEMBER" }],
        "additionalMembers": [{ "email": "alice@example.com", "role": "ADMIN" }]
      }
    }
  }'

The response is 201 Created with the whole team document, its ETag, and Location: /api/v1/teams/<id>.

If a team with that name exists, the response is 409 with the code name_conflict and the existing team’s id, so a retried create never makes a duplicate.
Without membership, the token’s creator joins the new team as an admin. With membership, the declared roster is the whole team, so declare the admins you want.

Update part of a team

Send only the sections you want to change. A section you leave out stays as it is; a section you send replaces that section completely.

curl -sS -X PATCH "https://app.resolve.ai/api/v1/teams/Xb2kQ9vLm3TfR7wYc1NpA" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H 'If-Match: "7"' \
  -d '{
    "schemaVersion": 1,
    "spec": {
      "membership": {
        "groupBindings": [{ "groupId": "pD7rT2xN9qLs4KvB0cWeJ", "role": "MEMBER" }],
        "additionalMembers": [
          { "email": "alice@example.com", "role": "ADMIN" },
          { "email": "bob@example.com", "role": "MEMBER" }
        ]
      }
    }
  }'

The response is the updated document with a new ETag. Add ?dryRun=true to see the change without saving it. A dry run returns dryRun: true and the changes per section, and the ETag stays the same. A dry run does not run every check, so a taken name or an unknown channel can still preview as a success. If the team has pending changes in Resolve that are waiting for review and your update touches the same parts, the update succeeds and replaces those pending parts. The response lists them in supersededProposals.

Delete a team

curl -sS -X DELETE "https://app.resolve.ai/api/v1/teams/Xb2kQ9vLm3TfR7wYc1NpA" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'If-Match: "8"'

The response is 204 No Content.

Find a directory group

curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://app.resolve.ai/api/v1/groups?provider=PAGERDUTY&name=Payments%20on-call"

{
  "groups": [
    {
      "id": "pD7rT2xN9qLs4KvB0cWeJ",
      "provider": "PAGERDUTY",
      "integrationInstanceId": "<pagerduty integration id>",
      "providerId": "PXYZ123",
      "name": "Payments on-call",
      "memberCount": 6
    }
  ],
  "nextCursor": null
}

Filter by provider (SCIM, PAGERDUTY, IRM, ROOTLY, DATADOG, INCIDENT_IO), name, providerId, or integrationInstanceId. Use the returned id as groupId.

Membership

A team’s people come from two sources, and you can use both at once.

Group bindings (groupBindings): a directory group and the role its people get. Groups come from SCIM, PagerDuty, Grafana IRM, Rootly, Datadog, or incident.io. Resolve keeps the team in step when people join or leave the group. Bind at most one group per role, all from the same provider.
Additional members (additionalMembers): people you add by email. Each email must match a user in your organization; provision users through SCIM first.
Roles are MEMBER or ADMIN. If a person is in a bound group and is also an additional member, the higher role applies. If they leave the group, the additional-member entry stays.
Directory-managed admins: bind a second group with the role ADMIN. That group then becomes the source of admins, and the team’s additional admins are removed.
Replacing membership: sending membership replaces it. Leaving membership out keeps it as it is. Empty lists remove all bindings or additional members.

Updates and concurrency

Every read returns the team’s version in the ETag header. PATCH and DELETE must send it back unchanged in If-Match. Treat the ETag as opaque.
If the team changed since you read it, the write fails with 412 and the code stale_version. Read the team again and retry.
A missing If-Match returns 428 with the code precondition_required.
The version changes on every change to the team, from any source: the API, the Resolve UI, Slack, or an accepted suggestion. People joining or leaving a bound group do not change it.

Errors

Every error has the same body:

{
  "error": "Another team already has this displayName",
  "code": "name_conflict",
  "details": { "existingTeamId": "Xb2kQ9vLm3TfR7wYc1NpA" }
}

Status	`code`	When
`400`	`invalid_input`	The body or a parameter is not valid. `details` lists each field error.
`400`	`unknown_email`	An additional member’s email matches no user. Nothing is written. `details` lists every unmatched email.
`400`	`unsupported_section`	The write contains a read-only section, such as `alertFilters`.
`401`	`unauthorized`	The token is missing, invalid, or expired.
`403`	`forbidden`	The token’s creator is not an organization admin.
`403`	`api_disabled`	The Teams API is not enabled for your organization.
`404`	`not_found`	No such team or group in your organization.
`409`	`name_conflict`	Another team already has this name. `details.existingTeamId` gives its id.
`412`	`stale_version`	The team changed since your read. `details.currentVersion` gives the new version.
`428`	`precondition_required`	`If-Match` is missing on `PATCH` or `DELETE`.
`429`	`rate_limited`	Too many requests for this token. Wait for the seconds in the `Retry-After` header, then retry.

Limits

Item	Limit
Reads per token	600 per minute
Writes per token	120 per minute
Teams per list page	100 by default, 500 at most
Communication channels per team	50
Group bindings per team	2 (one per role)
Additional members per team	500

Compatibility

Send schemaVersion with every write. Resolve changes only the fields your version knows, so an older client keeps working when new fields are added.
Responses can contain fields your client does not know; ignore them. Requests with unknown fields are refused.
Treat enum values, such as roles and channel purposes, as open strings. New values can appear.
Breaking changes ship only under a new path (/api/v2), with notice before /api/v1 changes.

What’s next

Team and group mapping: how directory groups map to teams in the Resolve UI.
Directory Sync (SCIM): provision the users that additional members refer to.
Resolve REST API: query investigations from scripts.

​What you can manage

​Base URL

​Authentication

​The team document

​Endpoints

​List teams

​Create a team

​Update part of a team

​Delete a team

​Find a directory group

​Membership

​Updates and concurrency

​Errors

​Limits

​Compatibility

​What’s next

What you can manage

Base URL

Authentication

The team document

Endpoints

List teams

Create a team

Update part of a team

Delete a team

Find a directory group

Membership

Updates and concurrency

Errors

Limits

Compatibility

What’s next