Propose a change through the API

From a script or a CI job, preview a change to a diagram without storing anything, then submit it as a proposal that a person reviews and applies in iyedy.

A job that derives a diagram from your code, or that keeps it in step with a repository, should not overwrite the diagram. It previews the change, then submits it as a proposal. The proposal waits in iyedy until someone who can edit the diagram applies it or rejects it.

Before you start

• A token with cartouche.read and cartouche.propose: a personal access token, or a service account for CI.
• At least the contributor role in the diagram's workspace. With the viewer role, the routes below store nothing.
• The ids of the organisation, the workspace and the diagram: see Your first API call. In the text below, W stands for /v1/t/{tenantId}/w/{workspaceId}.

Propose a change

1. Read the diagram and its version

   GET /v1/t/{tenantId}/w/{workspaceId}/diagrams/{did}/source HTTP/1.1
   Host: app.iyedy.com
   Authorization: Bearer crt_pat_…
   

   The answer gives the diagram's did, name, classification, its current version and its whole definition in text. Keep the version: it is the base of your change.

2. Prepare the whole definition

   Your job edits the definition and keeps it whole. A proposal replaces the whole diagram: what it leaves out is removed.

3. Preview the change

   POST /v1/t/{tenantId}/w/{workspaceId}/diagrams/{did}/preview HTTP/1.1
   Host: app.iyedy.com
   Authorization: Bearer crt_pat_…
   Content-Type: application/json
   

   Field	Required	Value
   text	yes	the whole proposed definition
   baseVersion	no	the version read in step 1; if the diagram moved on since, the answer is 409 conflict

   Nothing is stored. The answer says whether the change is valid, with its diagnostics (line and message), the line-by-line differences in patch, the counts and list of elements added, removed and changed in changes, and in findings the check findings before and after, with those the change introduces and resolves. Fix what the diagnostics report and preview again until it is valid.

4. Submit the proposal

   POST /v1/t/{tenantId}/w/{workspaceId}/diagrams/{did}/proposals HTTP/1.1
   Host: app.iyedy.com
   Authorization: Bearer crt_pat_…
   Content-Type: application/json
   

   Field	Required	Value
   text	yes	the whole proposed definition, as previewed
   baseVersion	no	the version the change starts from
   rationale	no	why this change, in a sentence or two, for the reviewer

   iyedy previews the change again and stores it: the answer is 201 with the proposal and its preview. An invalid change, or one that changes nothing, is 422 validation_failed and nothing is stored.

   In iyedy, the diagram's Assistant panel lists your change under Proposals to review, with your name or the service account's.
5. Follow it

   GET /v1/t/{tenantId}/w/{workspaceId}/diagrams/{did}/proposals?status=open&mine=1 HTTP/1.1
   Host: app.iyedy.com
   Authorization: Bearer crt_pat_…
   

   Each proposal has its status (open, accepted, rejected, withdrawn) and says when the diagram moved since it was made. To take back an open proposal of yours, call POST W/diagrams/{did}/proposals/{pid}/withdraw.

Limits

• A person decides. No token can accept or reject a proposal: that is done in the app. See How proposals reach your team.
• 30 days. A proposal nobody handles expires and is deleted after 30 days.
• Open proposals are capped: 50 per diagram and 10 per author. Over that, 429 rate_limited; handle or withdraw some first.
• Recorded without content. In an organisation, each proposal is recorded in the audit log by ids and counts, never with the proposed definition.

If it doesn't work

All the codes: Rate limits and errors.