---
title: "Revise a suite"
method: PUT
path: "/v1/suites/{suiteId}"
tags: ["Suites"]
---

# Revise a suite

`PUT /v1/suites/{suiteId}`

## Request

- Base URL: `https://api.ironfang.com/rig`
- URL: `https://api.ironfang.com/rig/v1/suites/{suiteId}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Records a new version when the definition changed and answers the current version unchanged when it did not, so sending the same document twice creates one version. Existing runs keep the version they were created from. Needs rig.write.

## Request body

- object
  - `definition` Definition, required: A suite's content. Resources are named identities a run receives; expectations are deterministic conditions on the run's events, stored and validated now and evaluated once the platform observes the events they name.
    - `defaults` object
      - `run_ttl` string: Default run lifetime, 1m to 24h ("30m").
    - `expectations` ExpectationSpec[]
      - `event` string, required: An event type from the catalogue, such as email.received or callback.forwarded.
      - `id` string, required
      - `match` object
      - `resource` string, required: A declared resource name.
    - `resources` object, required
    - `version` 1, required
  - `name` string: A new display name; omit to keep the current one.

## Response `200`

The suite and the version now current

- object
  - `suite` Suite, required
    - `archived_at` string, date-time
    - `created_at` string, date-time, required
    - `current_version` integer, required
    - `id` string, uuid, required
    - `name` string, required
    - `organisation_id` string, uuid, required
    - `project_id` string, uuid, required
    - `slug` string, required
  - `version` SuiteVersion, required
    - `created_at` string, date-time, required
    - `created_by` string
    - `definition` Definition, required: A suite's content. Resources are named identities a run receives; expectations are deterministic conditions on the run's events, stored and validated now and evaluated once the platform observes the events they name.
      - `defaults` object
        - `run_ttl` string: Default run lifetime, 1m to 24h ("30m").
      - `expectations` ExpectationSpec[]
        - `event` string, required: An event type from the catalogue, such as email.received or callback.forwarded.
        - `id` string, required
        - `match` object
        - `resource` string, required: A declared resource name.
      - `resources` object, required
      - `version` 1, required
    - `definition_sha256` string, required: SHA-256 of the canonical definition.
    - `id` string, uuid, required
    - `organisation_id` string, uuid, required
    - `suite_id` string, uuid, required
    - `version` integer, required
  - `revised` boolean: Whether anything changed.

## Other responses

- `400`: The body is not one strict JSON value of the documented shape (`invalid_json`).
- `401`: No credential, an invalid one, or a delegated token where none is accepted (`unauthorized`, `invalid_api_key`, `delegated_not_allowed`).
- `403`: The credential lacks the permission or scope, or names another organisation (`forbidden`, `insufficient_scope`).
- `404`: No such object in this organisation (`not_found`).
- `409`: A name is already taken, or the target is archived (`conflict`, `archived`).
- `422`: A field is invalid; the message names it (`invalid_request`).

---

[API](https://skmtc.dev/ironfang/apis/ironfang-rig-api.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-rig-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-rig-api/revisions/3e86a312dad1?raw)