{
  "openapi": "3.0.0",
  "info": {
    "title": "Atlas API",
    "version": "0.0.0"
  },
  "servers": [
    {
      "url": "https://api.atlaswork.ai"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Organization API key (format `atlas_sk_...`), passed as a bearer token or the x-api-key header. Created and revoked in the dashboard (Better Auth api-key plugin); shown in full only once and stored hashed."
      },
      "oauthJwt": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Better Auth OAuth resource access token. The token audience must match the Atlas MCP resource and include the scope required by the route."
      },
      "signerToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "HMAC-signed envelope token, as a bearer token or a `token` query param."
      },
      "reviewToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "HMAC-signed review token (minted into the envelope's review URL at creation), as a bearer token or a `token` query param. Capabilities are split per token: a read token grants view + draft editing, a send token grants the dispatch action only — so a forwarded review link can be shared read-only. Scoped to exactly one envelope; never valid as a signer credential."
      }
    },
    "schemas": {
      "V1PingResponse": {
        "type": "object",
        "properties": {
          "pong": {
            "type": "boolean",
            "enum": [
              true
            ]
          }
        },
        "required": [
          "pong"
        ]
      },
      "ReviewRedetectResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "requested"
            ]
          }
        },
        "required": [
          "status"
        ]
      }
    },
    "parameters": {}
  },
  "paths": {
    "/api/v1/ping": {
      "get": {
        "tags": [
          "v1"
        ],
        "summary": "Authenticated ping",
        "description": "Proves the /v1 machine-auth boundary. Returns pong for a valid organization API key or scoped OAuth JWT.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "responses": {
          "200": {
            "description": "Credential accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/V1PingResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or OAuth access token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/envelopes": {
      "post": {
        "tags": [
          "envelopes"
        ],
        "summary": "Create an envelope",
        "description": "Creates a draft envelope with its participant and field graph. The document arrives by public URL, inline base64 content, chat-authored text rendered to PDF, a same-organization envelope document, or deferred upload (`{ upload: true }` returns a short-lived signed `uploadUrl`; it is never re-issued after create). Returns immediately with the envelope, a review URL for the web review page, a human/agent-readable `note` describing the next step, and never blocks on field detection. URL and inline documents enqueue field detection asynchronously after the document is stored (the envelope moves draft → detecting → review); deferred-upload envelopes skip detection and remain sendable with manually placed fields. Supports the `Idempotency-Key` header: a replayed completed key returns the envelope's current graph with the original status code and `Idempotency-Replayed: true` (never re-executing); an in-flight duplicate is rejected 409; reusing a key with a different request is rejected 422. A replayed create re-mints the review URL but never the one-shot upload URL.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "document": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "filename": {
                            "type": "string",
                            "minLength": 1
                          }
                        },
                        "required": [
                          "url"
                        ]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "contentBase64": {
                            "type": "string",
                            "minLength": 1
                          },
                          "filename": {
                            "type": "string",
                            "minLength": 1
                          }
                        },
                        "required": [
                          "contentBase64",
                          "filename"
                        ]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "text": {
                            "type": "string",
                            "minLength": 1
                          },
                          "filename": {
                            "type": "string",
                            "minLength": 1
                          }
                        },
                        "required": [
                          "text"
                        ]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "envelopeId": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "required": [
                          "envelopeId"
                        ]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "upload": {
                            "type": "boolean",
                            "enum": [
                              true
                            ]
                          },
                          "filename": {
                            "type": "string",
                            "minLength": 1
                          }
                        },
                        "required": [
                          "upload",
                          "filename"
                        ]
                      }
                    ]
                  },
                  "participants": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1
                        },
                        "email": {
                          "type": "string",
                          "format": "email"
                        },
                        "company": {
                          "type": "string",
                          "nullable": true,
                          "maxLength": 200
                        },
                        "title": {
                          "type": "string",
                          "nullable": true,
                          "maxLength": 200
                        },
                        "detectedPartyIndex": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0
                        }
                      },
                      "required": [
                        "name",
                        "email"
                      ]
                    }
                  },
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "participantIndex": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "partyIndex": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "signature",
                            "initials",
                            "date",
                            "text",
                            "checkbox"
                          ]
                        },
                        "page": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "x": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "y": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "width": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "height": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "label": {
                          "type": "string",
                          "nullable": true
                        },
                        "required": {
                          "type": "boolean"
                        },
                        "prefillValue": {
                          "type": "string",
                          "nullable": true,
                          "description": "Static sender-supplied value for text or date fields. Ignored on checkbox fields, which always remain signer-controlled."
                        },
                        "autoSource": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "signed_date",
                            "participant_name",
                            "participant_email",
                            "participant_company",
                            "participant_title",
                            "sender_org_name",
                            null
                          ],
                          "description": "Derive this field's value server-side when the signer signs: signed_date (date fields) or participant_name / participant_email / participant_company / participant_title / sender_org_name (text fields). Mutually exclusive with prefillValue. The resolved value is recorded in the envelope's audit trail."
                        },
                        "proposedAutoSource": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "signed_date",
                            "participant_name",
                            "participant_email",
                            "participant_company",
                            "participant_title",
                            "sender_org_name",
                            null
                          ],
                          "description": "Detection-proposal echo. On draft updates, echo the proposedAutoSource you read to keep the suggestion; omitting or nulling it dismisses it. Cannot introduce or change a proposal (detection is the only origin); ignored at envelope create."
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "detected",
                            "manual",
                            "template"
                          ]
                        }
                      },
                      "required": [
                        "type",
                        "page",
                        "x",
                        "y",
                        "width",
                        "height"
                      ]
                    }
                  },
                  "displayName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  },
                  "policy": {
                    "type": "object",
                    "properties": {
                      "deliveryMode": {
                        "type": "string",
                        "enum": [
                          "review_first",
                          "auto_send"
                        ]
                      },
                      "legalFramework": {
                        "type": "string",
                        "nullable": true
                      },
                      "consumerDisclosure": {
                        "type": "boolean"
                      },
                      "expiresAt": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "reminderPolicy": {
                        "nullable": true
                      }
                    }
                  },
                  "metadata": {
                    "nullable": true
                  }
                },
                "required": [
                  "document",
                  "participants",
                  "fields"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Envelope created (status draft, version 1)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "envelope": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "organizationId": {
                              "type": "string"
                            },
                            "teamId": {
                              "type": "string"
                            },
                            "templateId": {
                              "type": "string",
                              "nullable": true
                            },
                            "templateContentHash": {
                              "type": "string",
                              "nullable": true
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "draft",
                                "detecting",
                                "review",
                                "in_progress",
                                "completed",
                                "declined",
                                "voided",
                                "expired"
                              ]
                            },
                            "detectionStatus": {
                              "type": "string",
                              "enum": [
                                "none",
                                "running",
                                "succeeded",
                                "failed"
                              ]
                            },
                            "version": {
                              "type": "integer"
                            },
                            "originalFilename": {
                              "type": "string",
                              "nullable": true
                            },
                            "displayName": {
                              "type": "string",
                              "nullable": true
                            },
                            "sourceFormat": {
                              "type": "string",
                              "nullable": true
                            },
                            "contentHash": {
                              "type": "string",
                              "nullable": true
                            },
                            "sizeBytes": {
                              "type": "number",
                              "nullable": true
                            },
                            "deliveryMode": {
                              "type": "string"
                            },
                            "legalFramework": {
                              "type": "string",
                              "nullable": true
                            },
                            "consumerDisclosure": {
                              "type": "boolean"
                            },
                            "expiresAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "scheduledSendAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "reminderPolicy": {
                              "nullable": true
                            },
                            "sentAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "completedAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "declinedAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "voidedAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "expiredAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "metadata": {
                              "nullable": true
                            },
                            "senderUserId": {
                              "type": "string",
                              "nullable": true
                            },
                            "senderName": {
                              "type": "string",
                              "nullable": true
                            },
                            "senderEmail": {
                              "type": "string",
                              "nullable": true
                            },
                            "detectedParties": {
                              "nullable": true
                            },
                            "createdAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "updatedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "required": [
                            "id",
                            "organizationId",
                            "teamId",
                            "templateId",
                            "templateContentHash",
                            "status",
                            "detectionStatus",
                            "version",
                            "originalFilename",
                            "displayName",
                            "sourceFormat",
                            "contentHash",
                            "sizeBytes",
                            "deliveryMode",
                            "legalFramework",
                            "consumerDisclosure",
                            "expiresAt",
                            "scheduledSendAt",
                            "sentAt",
                            "completedAt",
                            "declinedAt",
                            "voidedAt",
                            "expiredAt",
                            "createdAt",
                            "updatedAt"
                          ]
                        },
                        "participants": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "envelopeId": {
                                "type": "string"
                              },
                              "organizationId": {
                                "type": "string"
                              },
                              "orderIndex": {
                                "type": "integer"
                              },
                              "name": {
                                "type": "string"
                              },
                              "email": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string",
                                "nullable": true
                              },
                              "title": {
                                "type": "string",
                                "nullable": true
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "pending",
                                  "signed",
                                  "declined"
                                ]
                              },
                              "detectedPartyIndex": {
                                "type": "integer",
                                "nullable": true
                              },
                              "consentedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "signedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "declinedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "declineReason": {
                                "type": "string",
                                "nullable": true
                              },
                              "lastViewedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "lastIpAddress": {
                                "type": "string",
                                "nullable": true
                              },
                              "lastUserAgent": {
                                "type": "string",
                                "nullable": true
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updatedAt": {
                                "type": "string",
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "id",
                              "envelopeId",
                              "organizationId",
                              "orderIndex",
                              "name",
                              "email",
                              "status",
                              "consentedAt",
                              "signedAt",
                              "declinedAt",
                              "declineReason",
                              "lastViewedAt",
                              "lastIpAddress",
                              "lastUserAgent",
                              "createdAt",
                              "updatedAt"
                            ]
                          }
                        },
                        "fields": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "envelopeId": {
                                "type": "string"
                              },
                              "organizationId": {
                                "type": "string"
                              },
                              "participantId": {
                                "type": "string",
                                "nullable": true
                              },
                              "partyIndex": {
                                "type": "integer",
                                "nullable": true
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "signature",
                                  "initials",
                                  "date",
                                  "text",
                                  "checkbox"
                                ]
                              },
                              "page": {
                                "type": "integer"
                              },
                              "x": {
                                "type": "number"
                              },
                              "y": {
                                "type": "number"
                              },
                              "width": {
                                "type": "number"
                              },
                              "height": {
                                "type": "number"
                              },
                              "label": {
                                "type": "string",
                                "nullable": true
                              },
                              "required": {
                                "type": "boolean"
                              },
                              "source": {
                                "type": "string",
                                "enum": [
                                  "detected",
                                  "manual",
                                  "template"
                                ]
                              },
                              "prefillValue": {
                                "type": "string",
                                "nullable": true
                              },
                              "locked": {
                                "type": "boolean"
                              },
                              "autoSource": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                  "signed_date",
                                  "participant_name",
                                  "participant_email",
                                  "participant_company",
                                  "participant_title",
                                  "sender_org_name",
                                  null
                                ]
                              },
                              "proposedAutoSource": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                  "signed_date",
                                  "participant_name",
                                  "participant_email",
                                  "participant_company",
                                  "participant_title",
                                  "sender_org_name",
                                  null
                                ]
                              },
                              "value": {
                                "type": "string",
                                "nullable": true
                              },
                              "filledAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updatedAt": {
                                "type": "string",
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "id",
                              "envelopeId",
                              "organizationId",
                              "participantId",
                              "type",
                              "page",
                              "x",
                              "y",
                              "width",
                              "height",
                              "label",
                              "required",
                              "source",
                              "prefillValue",
                              "locked",
                              "autoSource",
                              "proposedAutoSource",
                              "value",
                              "filledAt",
                              "createdAt",
                              "updatedAt"
                            ]
                          }
                        }
                      },
                      "required": [
                        "envelope",
                        "participants",
                        "fields"
                      ]
                    },
                    "reviewUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "uploadUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "note": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "envelope",
                    "reviewUrl",
                    "note"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "413": {
            "description": "Raw request body exceeds the pre-parse size limit",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Validation failed: malformed input, document intake rejected (private address, size cap, content type), or duplicate participant emails",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Document storage failed; the draft exists without a stored document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "envelopes"
        ],
        "summary": "List envelopes",
        "description": "Cursor-paginated list of the organization's envelopes, ordered by createdAt descending. Pass `nextCursor` from the previous page as `cursor`; `limit` is capped at 100 (default 50). Filter by lifecycle status with `status` (one or more statuses, comma-separated), and by name with `q` (case-insensitive substring of the display name or the original filename).",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "required": false,
            "name": "q",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "attention",
                "waiting",
                "drafts",
                "completed",
                "all"
              ]
            },
            "required": false,
            "name": "view",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "required": false,
            "name": "sender",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "team",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "required": false,
            "name": "recipient",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "required": false,
            "name": "template",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "from",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "required": false,
            "name": "to",
            "in": "query"
          },
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "attention",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": [
                "created",
                "sent",
                "completed",
                "activity",
                "name",
                "urgency"
              ]
            },
            "required": false,
            "name": "sort",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "One page of envelopes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "teamId": {
                            "type": "string"
                          },
                          "templateId": {
                            "type": "string",
                            "nullable": true
                          },
                          "templateContentHash": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "draft",
                              "detecting",
                              "review",
                              "in_progress",
                              "completed",
                              "declined",
                              "voided",
                              "expired"
                            ]
                          },
                          "detectionStatus": {
                            "type": "string",
                            "enum": [
                              "none",
                              "running",
                              "succeeded",
                              "failed"
                            ]
                          },
                          "version": {
                            "type": "integer"
                          },
                          "originalFilename": {
                            "type": "string",
                            "nullable": true
                          },
                          "displayName": {
                            "type": "string",
                            "nullable": true
                          },
                          "sourceFormat": {
                            "type": "string",
                            "nullable": true
                          },
                          "contentHash": {
                            "type": "string",
                            "nullable": true
                          },
                          "sizeBytes": {
                            "type": "number",
                            "nullable": true
                          },
                          "deliveryMode": {
                            "type": "string"
                          },
                          "legalFramework": {
                            "type": "string",
                            "nullable": true
                          },
                          "consumerDisclosure": {
                            "type": "boolean"
                          },
                          "expiresAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "scheduledSendAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "reminderPolicy": {
                            "nullable": true
                          },
                          "sentAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "completedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declinedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "voidedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "expiredAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "metadata": {
                            "nullable": true
                          },
                          "senderUserId": {
                            "type": "string",
                            "nullable": true
                          },
                          "senderName": {
                            "type": "string",
                            "nullable": true
                          },
                          "senderEmail": {
                            "type": "string",
                            "nullable": true
                          },
                          "detectedParties": {
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "teamName": {
                            "type": "string"
                          },
                          "participantCount": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "signedCount": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "latestActivity": {
                            "type": "object",
                            "nullable": true,
                            "properties": {
                              "label": {
                                "type": "string"
                              },
                              "occurredAt": {
                                "type": "string",
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "label",
                              "occurredAt"
                            ]
                          },
                          "signers": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "participantId": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                },
                                "status": {
                                  "type": "string",
                                  "enum": [
                                    "pending",
                                    "signed",
                                    "declined"
                                  ]
                                },
                                "lastEventLabel": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "lastEventAt": {
                                  "type": "string",
                                  "nullable": true,
                                  "format": "date-time"
                                },
                                "lastRemindedAt": {
                                  "type": "string",
                                  "nullable": true,
                                  "format": "date-time"
                                },
                                "nextReminderAt": {
                                  "type": "string",
                                  "nullable": true,
                                  "format": "date-time"
                                }
                              },
                              "required": [
                                "participantId",
                                "name",
                                "status",
                                "lastEventLabel",
                                "lastEventAt",
                                "lastRemindedAt",
                                "nextReminderAt"
                              ]
                            }
                          },
                          "attention": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "delivery_failed",
                                "expires_soon",
                                "stalled"
                              ]
                            }
                          }
                        },
                        "required": [
                          "id",
                          "organizationId",
                          "teamId",
                          "templateId",
                          "templateContentHash",
                          "status",
                          "detectionStatus",
                          "version",
                          "originalFilename",
                          "displayName",
                          "sourceFormat",
                          "contentHash",
                          "sizeBytes",
                          "deliveryMode",
                          "legalFramework",
                          "consumerDisclosure",
                          "expiresAt",
                          "scheduledSendAt",
                          "sentAt",
                          "completedAt",
                          "declinedAt",
                          "voidedAt",
                          "expiredAt",
                          "createdAt",
                          "updatedAt",
                          "teamName",
                          "participantCount",
                          "signedCount",
                          "latestActivity",
                          "signers",
                          "attention"
                        ]
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "items"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/envelopes/{id}": {
      "get": {
        "tags": [
          "envelopes"
        ],
        "summary": "Get an envelope",
        "description": "Returns the full envelope graph (envelope + participants + fields). Envelopes outside the API key's organization yield 404.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Envelope id"
            },
            "required": true,
            "description": "Envelope id",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "The envelope graph",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "teamId": {
                          "type": "string"
                        },
                        "templateId": {
                          "type": "string",
                          "nullable": true
                        },
                        "templateContentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "detecting",
                            "review",
                            "in_progress",
                            "completed",
                            "declined",
                            "voided",
                            "expired"
                          ]
                        },
                        "detectionStatus": {
                          "type": "string",
                          "enum": [
                            "none",
                            "running",
                            "succeeded",
                            "failed"
                          ]
                        },
                        "version": {
                          "type": "integer"
                        },
                        "originalFilename": {
                          "type": "string",
                          "nullable": true
                        },
                        "displayName": {
                          "type": "string",
                          "nullable": true
                        },
                        "sourceFormat": {
                          "type": "string",
                          "nullable": true
                        },
                        "contentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "sizeBytes": {
                          "type": "number",
                          "nullable": true
                        },
                        "deliveryMode": {
                          "type": "string"
                        },
                        "legalFramework": {
                          "type": "string",
                          "nullable": true
                        },
                        "consumerDisclosure": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "scheduledSendAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "reminderPolicy": {
                          "nullable": true
                        },
                        "sentAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "declinedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "voidedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "expiredAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "metadata": {
                          "nullable": true
                        },
                        "senderUserId": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderName": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderEmail": {
                          "type": "string",
                          "nullable": true
                        },
                        "detectedParties": {
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "organizationId",
                        "teamId",
                        "templateId",
                        "templateContentHash",
                        "status",
                        "detectionStatus",
                        "version",
                        "originalFilename",
                        "displayName",
                        "sourceFormat",
                        "contentHash",
                        "sizeBytes",
                        "deliveryMode",
                        "legalFramework",
                        "consumerDisclosure",
                        "expiresAt",
                        "scheduledSendAt",
                        "sentAt",
                        "completedAt",
                        "declinedAt",
                        "voidedAt",
                        "expiredAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string",
                            "nullable": true
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "signed",
                              "declined"
                            ]
                          },
                          "detectedPartyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "consentedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "signedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declinedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declineReason": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastViewedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "lastIpAddress": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastUserAgent": {
                            "type": "string",
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "orderIndex",
                          "name",
                          "email",
                          "status",
                          "consentedAt",
                          "signedAt",
                          "declinedAt",
                          "declineReason",
                          "lastViewedAt",
                          "lastIpAddress",
                          "lastUserAgent",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "participantId": {
                            "type": "string",
                            "nullable": true
                          },
                          "partyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer"
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "detected",
                              "manual",
                              "template"
                            ]
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "proposedAutoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "value": {
                            "type": "string",
                            "nullable": true
                          },
                          "filledAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "participantId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "source",
                          "prefillValue",
                          "locked",
                          "autoSource",
                          "proposedAutoSource",
                          "value",
                          "filledAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    }
                  },
                  "required": [
                    "envelope",
                    "participants",
                    "fields"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Envelope not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/envelopes/{id}/status": {
      "get": {
        "tags": [
          "envelopes"
        ],
        "summary": "Check signing status",
        "description": "Returns lightweight participant progress and a human-readable lifecycle summary. Deferred-upload drafts also report whether document bytes have arrived.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Envelope id"
            },
            "required": true,
            "description": "Envelope id",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Current signing progress",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelopeId": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "draft",
                        "detecting",
                        "review",
                        "in_progress",
                        "completed",
                        "declined",
                        "voided",
                        "expired"
                      ]
                    },
                    "detectionStatus": {
                      "type": "string",
                      "enum": [
                        "none",
                        "running",
                        "succeeded",
                        "failed"
                      ]
                    },
                    "terminal": {
                      "type": "boolean"
                    },
                    "currentParticipantId": {
                      "type": "string",
                      "nullable": true
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "name": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "signed",
                              "declined"
                            ]
                          },
                          "isCurrent": {
                            "type": "boolean"
                          },
                          "signedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declinedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "lastViewedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "orderIndex",
                          "name",
                          "status",
                          "isCurrent",
                          "signedAt",
                          "declinedAt",
                          "lastViewedAt"
                        ]
                      }
                    },
                    "signedCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "totalParticipants": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "lastEventAt": {
                      "type": "string",
                      "nullable": true,
                      "format": "date-time"
                    },
                    "summary": {
                      "type": "string"
                    },
                    "documentReceived": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "envelopeId",
                    "status",
                    "detectionStatus",
                    "terminal",
                    "currentParticipantId",
                    "participants",
                    "signedCount",
                    "totalParticipants",
                    "lastEventAt",
                    "summary"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or OAuth access token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Credential lacks envelopes:read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Envelope not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/envelopes/{id}/upload/complete": {
      "post": {
        "tags": [
          "envelopes"
        ],
        "summary": "Complete a deferred document upload",
        "description": "Verify that deferred PDF/DOCX bytes reached storage, anchor their hash and size, and enqueue field detection. Repeating a completed upload is safe.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Envelope id"
            },
            "required": true,
            "description": "Envelope id",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Upload anchored and detection requested",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "envelope": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "organizationId": {
                              "type": "string"
                            },
                            "teamId": {
                              "type": "string"
                            },
                            "templateId": {
                              "type": "string",
                              "nullable": true
                            },
                            "templateContentHash": {
                              "type": "string",
                              "nullable": true
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "draft",
                                "detecting",
                                "review",
                                "in_progress",
                                "completed",
                                "declined",
                                "voided",
                                "expired"
                              ]
                            },
                            "detectionStatus": {
                              "type": "string",
                              "enum": [
                                "none",
                                "running",
                                "succeeded",
                                "failed"
                              ]
                            },
                            "version": {
                              "type": "integer"
                            },
                            "originalFilename": {
                              "type": "string",
                              "nullable": true
                            },
                            "displayName": {
                              "type": "string",
                              "nullable": true
                            },
                            "sourceFormat": {
                              "type": "string",
                              "nullable": true
                            },
                            "contentHash": {
                              "type": "string",
                              "nullable": true
                            },
                            "sizeBytes": {
                              "type": "number",
                              "nullable": true
                            },
                            "deliveryMode": {
                              "type": "string"
                            },
                            "legalFramework": {
                              "type": "string",
                              "nullable": true
                            },
                            "consumerDisclosure": {
                              "type": "boolean"
                            },
                            "expiresAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "scheduledSendAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "reminderPolicy": {
                              "nullable": true
                            },
                            "sentAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "completedAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "declinedAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "voidedAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "expiredAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "metadata": {
                              "nullable": true
                            },
                            "senderUserId": {
                              "type": "string",
                              "nullable": true
                            },
                            "senderName": {
                              "type": "string",
                              "nullable": true
                            },
                            "senderEmail": {
                              "type": "string",
                              "nullable": true
                            },
                            "detectedParties": {
                              "nullable": true
                            },
                            "createdAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "updatedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "required": [
                            "id",
                            "organizationId",
                            "teamId",
                            "templateId",
                            "templateContentHash",
                            "status",
                            "detectionStatus",
                            "version",
                            "originalFilename",
                            "displayName",
                            "sourceFormat",
                            "contentHash",
                            "sizeBytes",
                            "deliveryMode",
                            "legalFramework",
                            "consumerDisclosure",
                            "expiresAt",
                            "scheduledSendAt",
                            "sentAt",
                            "completedAt",
                            "declinedAt",
                            "voidedAt",
                            "expiredAt",
                            "createdAt",
                            "updatedAt"
                          ]
                        },
                        "participants": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "envelopeId": {
                                "type": "string"
                              },
                              "organizationId": {
                                "type": "string"
                              },
                              "orderIndex": {
                                "type": "integer"
                              },
                              "name": {
                                "type": "string"
                              },
                              "email": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string",
                                "nullable": true
                              },
                              "title": {
                                "type": "string",
                                "nullable": true
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "pending",
                                  "signed",
                                  "declined"
                                ]
                              },
                              "detectedPartyIndex": {
                                "type": "integer",
                                "nullable": true
                              },
                              "consentedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "signedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "declinedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "declineReason": {
                                "type": "string",
                                "nullable": true
                              },
                              "lastViewedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "lastIpAddress": {
                                "type": "string",
                                "nullable": true
                              },
                              "lastUserAgent": {
                                "type": "string",
                                "nullable": true
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updatedAt": {
                                "type": "string",
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "id",
                              "envelopeId",
                              "organizationId",
                              "orderIndex",
                              "name",
                              "email",
                              "status",
                              "consentedAt",
                              "signedAt",
                              "declinedAt",
                              "declineReason",
                              "lastViewedAt",
                              "lastIpAddress",
                              "lastUserAgent",
                              "createdAt",
                              "updatedAt"
                            ]
                          }
                        },
                        "fields": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "envelopeId": {
                                "type": "string"
                              },
                              "organizationId": {
                                "type": "string"
                              },
                              "participantId": {
                                "type": "string",
                                "nullable": true
                              },
                              "partyIndex": {
                                "type": "integer",
                                "nullable": true
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "signature",
                                  "initials",
                                  "date",
                                  "text",
                                  "checkbox"
                                ]
                              },
                              "page": {
                                "type": "integer"
                              },
                              "x": {
                                "type": "number"
                              },
                              "y": {
                                "type": "number"
                              },
                              "width": {
                                "type": "number"
                              },
                              "height": {
                                "type": "number"
                              },
                              "label": {
                                "type": "string",
                                "nullable": true
                              },
                              "required": {
                                "type": "boolean"
                              },
                              "source": {
                                "type": "string",
                                "enum": [
                                  "detected",
                                  "manual",
                                  "template"
                                ]
                              },
                              "prefillValue": {
                                "type": "string",
                                "nullable": true
                              },
                              "locked": {
                                "type": "boolean"
                              },
                              "autoSource": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                  "signed_date",
                                  "participant_name",
                                  "participant_email",
                                  "participant_company",
                                  "participant_title",
                                  "sender_org_name",
                                  null
                                ]
                              },
                              "proposedAutoSource": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                  "signed_date",
                                  "participant_name",
                                  "participant_email",
                                  "participant_company",
                                  "participant_title",
                                  "sender_org_name",
                                  null
                                ]
                              },
                              "value": {
                                "type": "string",
                                "nullable": true
                              },
                              "filledAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updatedAt": {
                                "type": "string",
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "id",
                              "envelopeId",
                              "organizationId",
                              "participantId",
                              "type",
                              "page",
                              "x",
                              "y",
                              "width",
                              "height",
                              "label",
                              "required",
                              "source",
                              "prefillValue",
                              "locked",
                              "autoSource",
                              "proposedAutoSource",
                              "value",
                              "filledAt",
                              "createdAt",
                              "updatedAt"
                            ]
                          }
                        }
                      },
                      "required": [
                        "envelope",
                        "participants",
                        "fields"
                      ]
                    },
                    "documentReceived": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "detectionRequested": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "envelope",
                    "documentReceived",
                    "detectionRequested"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or OAuth access token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Credential lacks envelopes:write or documents:write",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Envelope not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Document has not arrived or is not a supported PDF/DOCX",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/envelopes/{id}/extract": {
      "get": {
        "tags": [
          "envelopes"
        ],
        "summary": "Extract completed contract data",
        "description": "Returns not_extracted until completion. Completed envelopes return deterministic structured parties, lifecycle dates, labeled signed fields, and semantic date/governing-law values when those labels exist.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Envelope id"
            },
            "required": true,
            "description": "Envelope id",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Extraction status or completed structured contract data",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "not_extracted"
                          ]
                        },
                        "envelopeId": {
                          "type": "string"
                        },
                        "envelopeStatus": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "detecting",
                            "review",
                            "in_progress",
                            "completed",
                            "declined",
                            "voided",
                            "expired"
                          ]
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "status",
                        "envelopeId",
                        "envelopeStatus",
                        "message"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "status": {
                          "type": "string",
                          "enum": [
                            "extracted"
                          ]
                        },
                        "envelopeId": {
                          "type": "string"
                        },
                        "envelopeStatus": {
                          "type": "string",
                          "enum": [
                            "completed"
                          ]
                        },
                        "parties": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "email": {
                                "type": "string",
                                "format": "email"
                              },
                              "company": {
                                "type": "string",
                                "nullable": true
                              },
                              "role": {
                                "type": "string",
                                "nullable": true
                              },
                              "signedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "name",
                              "email",
                              "company",
                              "role",
                              "signedAt"
                            ]
                          }
                        },
                        "dates": {
                          "type": "object",
                          "properties": {
                            "effectiveDate": {
                              "type": "string",
                              "nullable": true
                            },
                            "expirationDate": {
                              "type": "string",
                              "nullable": true
                            },
                            "sentAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "completedAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            }
                          },
                          "required": [
                            "effectiveDate",
                            "expirationDate",
                            "sentAt",
                            "completedAt"
                          ]
                        },
                        "governingLaw": {
                          "type": "string",
                          "nullable": true
                        },
                        "fields": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "label": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "signature",
                                  "initials",
                                  "date",
                                  "text",
                                  "checkbox"
                                ]
                              },
                              "value": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "label",
                              "type",
                              "value"
                            ]
                          }
                        }
                      },
                      "required": [
                        "status",
                        "envelopeId",
                        "envelopeStatus",
                        "parties",
                        "dates",
                        "governingLaw",
                        "fields"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or OAuth access token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Credential lacks envelopes:read or extract:read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Envelope not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/envelopes/{id}/events": {
      "get": {
        "tags": [
          "envelopes"
        ],
        "summary": "Envelope event history",
        "description": "Returns the envelope's hash-chained event log ordered by `seq` ascending — the poll surface for lifecycle progress. Envelopes outside the API key's organization yield 404. Note: `participant.fields_auto_resolved` event payloads carry machine-derived field values in plaintext (signer name/email, signing date, sender org) — treat responses from this endpoint per your data-retention policy.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Envelope id"
            },
            "required": true,
            "description": "Envelope id",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "All events, ordered by seq",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "seq": {
                            "type": "integer"
                          },
                          "actorType": {
                            "type": "string",
                            "enum": [
                              "sender",
                              "signer",
                              "agent",
                              "system",
                              "operator"
                            ]
                          },
                          "actorId": {
                            "type": "string",
                            "nullable": true
                          },
                          "action": {
                            "type": "string",
                            "enum": [
                              "envelope.created",
                              "envelope.display_name_updated",
                              "envelope.participants_updated",
                              "envelope.fields_updated",
                              "envelope.policy_updated",
                              "envelope.sender_updated",
                              "detection.started",
                              "detection.completed",
                              "detection.failed",
                              "envelope.send_scheduled",
                              "envelope.send_schedule_canceled",
                              "envelope.sent",
                              "participant.link_issued",
                              "participant.link_reissued",
                              "participant.viewed",
                              "participant.consented",
                              "participant.details_corrected",
                              "participant.fields_auto_resolved",
                              "participant.signed",
                              "participant.declined",
                              "participant.reminder_sent",
                              "participant.email_updated",
                              "participant.forward_copy_requested",
                              "envelope.artifacts_generated",
                              "envelope.completed",
                              "envelope.voided",
                              "envelope.expired",
                              "extraction.requested",
                              "extraction.completed",
                              "extraction.failed",
                              "notification.sent",
                              "notification.failed",
                              "notification.delivered",
                              "notification.opened",
                              "notification.bounced",
                              "notification.complained"
                            ]
                          },
                          "payload": {
                            "nullable": true
                          },
                          "occurredAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "ipAddress": {
                            "type": "string",
                            "nullable": true
                          },
                          "userAgent": {
                            "type": "string",
                            "nullable": true
                          },
                          "prevHash": {
                            "type": "string"
                          },
                          "hash": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "seq",
                          "actorType",
                          "actorId",
                          "action",
                          "occurredAt",
                          "prevHash",
                          "hash"
                        ]
                      }
                    }
                  },
                  "required": [
                    "items"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Envelope not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/envelopes/{id}/draft": {
      "put": {
        "tags": [
          "envelopes"
        ],
        "summary": "Update a draft envelope's graph",
        "description": "Combined draft update: any subset of `participants`, `fields`, and `policy`, applied in one transaction (allowed in `draft` and `review` status). Replacing participants cascade-deletes fields, so `participants` requires `fields` in the same call. Fields are full-replace: echo each field's `autoSource` and `proposedAutoSource` as read, or the binding is cleared / the detection proposal dismissed. `expectedVersion` is checked strictly when supplied; omitted, the current version is used. Supports the `Idempotency-Key` header: a replayed completed key returns the envelope's current graph with the original status code and `Idempotency-Replayed: true` (never re-executing); an in-flight duplicate is rejected 409; reusing a key with a different request is rejected 422.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Envelope id"
            },
            "required": true,
            "description": "Envelope id",
            "name": "id",
            "in": "path"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "participants": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1
                        },
                        "email": {
                          "type": "string",
                          "format": "email"
                        },
                        "company": {
                          "type": "string",
                          "nullable": true,
                          "maxLength": 200
                        },
                        "title": {
                          "type": "string",
                          "nullable": true,
                          "maxLength": 200
                        },
                        "detectedPartyIndex": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0
                        }
                      },
                      "required": [
                        "name",
                        "email"
                      ]
                    }
                  },
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "participantIndex": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "partyIndex": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "signature",
                            "initials",
                            "date",
                            "text",
                            "checkbox"
                          ]
                        },
                        "page": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "x": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "y": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "width": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "height": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "label": {
                          "type": "string",
                          "nullable": true
                        },
                        "required": {
                          "type": "boolean"
                        },
                        "prefillValue": {
                          "type": "string",
                          "nullable": true,
                          "description": "Static sender-supplied value for text or date fields. Ignored on checkbox fields, which always remain signer-controlled."
                        },
                        "autoSource": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "signed_date",
                            "participant_name",
                            "participant_email",
                            "participant_company",
                            "participant_title",
                            "sender_org_name",
                            null
                          ],
                          "description": "Derive this field's value server-side when the signer signs: signed_date (date fields) or participant_name / participant_email / participant_company / participant_title / sender_org_name (text fields). Mutually exclusive with prefillValue. The resolved value is recorded in the envelope's audit trail."
                        },
                        "proposedAutoSource": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "signed_date",
                            "participant_name",
                            "participant_email",
                            "participant_company",
                            "participant_title",
                            "sender_org_name",
                            null
                          ],
                          "description": "Detection-proposal echo. On draft updates, echo the proposedAutoSource you read to keep the suggestion; omitting or nulling it dismisses it. Cannot introduce or change a proposal (detection is the only origin); ignored at envelope create."
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "detected",
                            "manual",
                            "template"
                          ]
                        }
                      },
                      "required": [
                        "type",
                        "page",
                        "x",
                        "y",
                        "width",
                        "height"
                      ]
                    }
                  },
                  "policy": {
                    "type": "object",
                    "properties": {
                      "deliveryMode": {
                        "type": "string",
                        "enum": [
                          "review_first",
                          "auto_send"
                        ]
                      },
                      "legalFramework": {
                        "type": "string",
                        "nullable": true
                      },
                      "consumerDisclosure": {
                        "type": "boolean"
                      },
                      "expiresAt": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "reminderPolicy": {
                        "nullable": true
                      }
                    }
                  },
                  "sender": {
                    "nullable": true
                  },
                  "displayName": {
                    "type": "string",
                    "nullable": true
                  },
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated envelope graph (final version after all bumps)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "teamId": {
                          "type": "string"
                        },
                        "templateId": {
                          "type": "string",
                          "nullable": true
                        },
                        "templateContentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "detecting",
                            "review",
                            "in_progress",
                            "completed",
                            "declined",
                            "voided",
                            "expired"
                          ]
                        },
                        "detectionStatus": {
                          "type": "string",
                          "enum": [
                            "none",
                            "running",
                            "succeeded",
                            "failed"
                          ]
                        },
                        "version": {
                          "type": "integer"
                        },
                        "originalFilename": {
                          "type": "string",
                          "nullable": true
                        },
                        "displayName": {
                          "type": "string",
                          "nullable": true
                        },
                        "sourceFormat": {
                          "type": "string",
                          "nullable": true
                        },
                        "contentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "sizeBytes": {
                          "type": "number",
                          "nullable": true
                        },
                        "deliveryMode": {
                          "type": "string"
                        },
                        "legalFramework": {
                          "type": "string",
                          "nullable": true
                        },
                        "consumerDisclosure": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "scheduledSendAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "reminderPolicy": {
                          "nullable": true
                        },
                        "sentAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "declinedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "voidedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "expiredAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "metadata": {
                          "nullable": true
                        },
                        "senderUserId": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderName": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderEmail": {
                          "type": "string",
                          "nullable": true
                        },
                        "detectedParties": {
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "organizationId",
                        "teamId",
                        "templateId",
                        "templateContentHash",
                        "status",
                        "detectionStatus",
                        "version",
                        "originalFilename",
                        "displayName",
                        "sourceFormat",
                        "contentHash",
                        "sizeBytes",
                        "deliveryMode",
                        "legalFramework",
                        "consumerDisclosure",
                        "expiresAt",
                        "scheduledSendAt",
                        "sentAt",
                        "completedAt",
                        "declinedAt",
                        "voidedAt",
                        "expiredAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string",
                            "nullable": true
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "signed",
                              "declined"
                            ]
                          },
                          "detectedPartyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "consentedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "signedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declinedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declineReason": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastViewedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "lastIpAddress": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastUserAgent": {
                            "type": "string",
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "orderIndex",
                          "name",
                          "email",
                          "status",
                          "consentedAt",
                          "signedAt",
                          "declinedAt",
                          "declineReason",
                          "lastViewedAt",
                          "lastIpAddress",
                          "lastUserAgent",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "participantId": {
                            "type": "string",
                            "nullable": true
                          },
                          "partyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer"
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "detected",
                              "manual",
                              "template"
                            ]
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "proposedAutoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "value": {
                            "type": "string",
                            "nullable": true
                          },
                          "filledAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "participantId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "source",
                          "prefillValue",
                          "locked",
                          "autoSource",
                          "proposedAutoSource",
                          "value",
                          "filledAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    }
                  },
                  "required": [
                    "envelope",
                    "participants",
                    "fields"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Envelope not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Stale expectedVersion (concurrent modification)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Validation failed: envelope not in draft/review, participants without fields, duplicate emails, or out-of-bounds participantIndex",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/envelopes/{id}/send": {
      "post": {
        "tags": [
          "envelopes"
        ],
        "summary": "Send an envelope",
        "description": "Transitions the envelope to `in_progress` in one transaction: validates the stored document (presence + pdf|docx content type; upload-mode envelopes get their `contentHash`/`sizeBytes` computed from the stored bytes), requires ≥1 participant, appends `envelope.sent` and `participant.link_issued` for the first signer (version bumps twice). Emits the `atlas/envelope.sent` notification event (identifiers only). Supports the `Idempotency-Key` header: a replayed completed key returns the envelope's current graph with the original status code and `Idempotency-Replayed: true` (never re-executing); an in-flight duplicate is rejected 409; reusing a key with a different request is rejected 422.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Envelope id"
            },
            "required": true,
            "description": "Envelope id",
            "name": "id",
            "in": "path"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The sent envelope graph (status in_progress)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "teamId": {
                          "type": "string"
                        },
                        "templateId": {
                          "type": "string",
                          "nullable": true
                        },
                        "templateContentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "detecting",
                            "review",
                            "in_progress",
                            "completed",
                            "declined",
                            "voided",
                            "expired"
                          ]
                        },
                        "detectionStatus": {
                          "type": "string",
                          "enum": [
                            "none",
                            "running",
                            "succeeded",
                            "failed"
                          ]
                        },
                        "version": {
                          "type": "integer"
                        },
                        "originalFilename": {
                          "type": "string",
                          "nullable": true
                        },
                        "displayName": {
                          "type": "string",
                          "nullable": true
                        },
                        "sourceFormat": {
                          "type": "string",
                          "nullable": true
                        },
                        "contentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "sizeBytes": {
                          "type": "number",
                          "nullable": true
                        },
                        "deliveryMode": {
                          "type": "string"
                        },
                        "legalFramework": {
                          "type": "string",
                          "nullable": true
                        },
                        "consumerDisclosure": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "scheduledSendAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "reminderPolicy": {
                          "nullable": true
                        },
                        "sentAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "declinedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "voidedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "expiredAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "metadata": {
                          "nullable": true
                        },
                        "senderUserId": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderName": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderEmail": {
                          "type": "string",
                          "nullable": true
                        },
                        "detectedParties": {
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "organizationId",
                        "teamId",
                        "templateId",
                        "templateContentHash",
                        "status",
                        "detectionStatus",
                        "version",
                        "originalFilename",
                        "displayName",
                        "sourceFormat",
                        "contentHash",
                        "sizeBytes",
                        "deliveryMode",
                        "legalFramework",
                        "consumerDisclosure",
                        "expiresAt",
                        "scheduledSendAt",
                        "sentAt",
                        "completedAt",
                        "declinedAt",
                        "voidedAt",
                        "expiredAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string",
                            "nullable": true
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "signed",
                              "declined"
                            ]
                          },
                          "detectedPartyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "consentedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "signedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declinedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declineReason": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastViewedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "lastIpAddress": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastUserAgent": {
                            "type": "string",
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "orderIndex",
                          "name",
                          "email",
                          "status",
                          "consentedAt",
                          "signedAt",
                          "declinedAt",
                          "declineReason",
                          "lastViewedAt",
                          "lastIpAddress",
                          "lastUserAgent",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "participantId": {
                            "type": "string",
                            "nullable": true
                          },
                          "partyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer"
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "detected",
                              "manual",
                              "template"
                            ]
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "proposedAutoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "value": {
                            "type": "string",
                            "nullable": true
                          },
                          "filledAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "participantId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "source",
                          "prefillValue",
                          "locked",
                          "autoSource",
                          "proposedAutoSource",
                          "value",
                          "filledAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    }
                  },
                  "required": [
                    "envelope",
                    "participants",
                    "fields"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "Out of credits (insufficient_credits): the organization has no credits left to send. Purchase more to continue; nothing else is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Envelope not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Double-send (invalid_transition), terminal state (terminal_state), or stale expectedVersion (conflict)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Validation failed: document not uploaded, disallowed stored content type, or zero participants",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/envelopes/{id}/void": {
      "post": {
        "tags": [
          "envelopes"
        ],
        "summary": "Void an envelope",
        "description": "Appends `envelope.voided` (with the optional `reason` in the event payload). Valid from draft, review, detecting, and in_progress; terminal envelopes (completed, declined, voided, expired) reject with 409. Supports the `Idempotency-Key` header: a replayed completed key returns the envelope's current graph with the original status code and `Idempotency-Replayed: true` (never re-executing); an in-flight duplicate is rejected 409; reusing a key with a different request is rejected 422.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Envelope id"
            },
            "required": true,
            "description": "Envelope id",
            "name": "id",
            "in": "path"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "reason": {
                    "type": "string",
                    "maxLength": 2000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The voided envelope graph",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "teamId": {
                          "type": "string"
                        },
                        "templateId": {
                          "type": "string",
                          "nullable": true
                        },
                        "templateContentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "detecting",
                            "review",
                            "in_progress",
                            "completed",
                            "declined",
                            "voided",
                            "expired"
                          ]
                        },
                        "detectionStatus": {
                          "type": "string",
                          "enum": [
                            "none",
                            "running",
                            "succeeded",
                            "failed"
                          ]
                        },
                        "version": {
                          "type": "integer"
                        },
                        "originalFilename": {
                          "type": "string",
                          "nullable": true
                        },
                        "displayName": {
                          "type": "string",
                          "nullable": true
                        },
                        "sourceFormat": {
                          "type": "string",
                          "nullable": true
                        },
                        "contentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "sizeBytes": {
                          "type": "number",
                          "nullable": true
                        },
                        "deliveryMode": {
                          "type": "string"
                        },
                        "legalFramework": {
                          "type": "string",
                          "nullable": true
                        },
                        "consumerDisclosure": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "scheduledSendAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "reminderPolicy": {
                          "nullable": true
                        },
                        "sentAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "declinedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "voidedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "expiredAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "metadata": {
                          "nullable": true
                        },
                        "senderUserId": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderName": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderEmail": {
                          "type": "string",
                          "nullable": true
                        },
                        "detectedParties": {
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "organizationId",
                        "teamId",
                        "templateId",
                        "templateContentHash",
                        "status",
                        "detectionStatus",
                        "version",
                        "originalFilename",
                        "displayName",
                        "sourceFormat",
                        "contentHash",
                        "sizeBytes",
                        "deliveryMode",
                        "legalFramework",
                        "consumerDisclosure",
                        "expiresAt",
                        "scheduledSendAt",
                        "sentAt",
                        "completedAt",
                        "declinedAt",
                        "voidedAt",
                        "expiredAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string",
                            "nullable": true
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "signed",
                              "declined"
                            ]
                          },
                          "detectedPartyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "consentedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "signedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declinedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declineReason": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastViewedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "lastIpAddress": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastUserAgent": {
                            "type": "string",
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "orderIndex",
                          "name",
                          "email",
                          "status",
                          "consentedAt",
                          "signedAt",
                          "declinedAt",
                          "declineReason",
                          "lastViewedAt",
                          "lastIpAddress",
                          "lastUserAgent",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "participantId": {
                            "type": "string",
                            "nullable": true
                          },
                          "partyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer"
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "detected",
                              "manual",
                              "template"
                            ]
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "proposedAutoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "value": {
                            "type": "string",
                            "nullable": true
                          },
                          "filledAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "participantId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "source",
                          "prefillValue",
                          "locked",
                          "autoSource",
                          "proposedAutoSource",
                          "value",
                          "filledAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    }
                  },
                  "required": [
                    "envelope",
                    "participants",
                    "fields"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Envelope not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Terminal state or stale expectedVersion",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/envelopes/{id}/remind": {
      "post": {
        "tags": [
          "envelopes"
        ],
        "summary": "Remind the current signer",
        "description": "Appends `participant.reminder_sent` for the current participant (lowest orderIndex still pending) and emits the notification event. Only valid while the envelope is in_progress. Rate-limited per participant (default: one reminder per hour) — exceeding the window returns 429. Supports the `Idempotency-Key` header: a replayed completed key returns the envelope's current graph with the original status code and `Idempotency-Replayed: true` (never re-executing); an in-flight duplicate is rejected 409; reusing a key with a different request is rejected 422.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Envelope id"
            },
            "required": true,
            "description": "Envelope id",
            "name": "id",
            "in": "path"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The envelope graph after the reminder event",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "teamId": {
                          "type": "string"
                        },
                        "templateId": {
                          "type": "string",
                          "nullable": true
                        },
                        "templateContentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "detecting",
                            "review",
                            "in_progress",
                            "completed",
                            "declined",
                            "voided",
                            "expired"
                          ]
                        },
                        "detectionStatus": {
                          "type": "string",
                          "enum": [
                            "none",
                            "running",
                            "succeeded",
                            "failed"
                          ]
                        },
                        "version": {
                          "type": "integer"
                        },
                        "originalFilename": {
                          "type": "string",
                          "nullable": true
                        },
                        "displayName": {
                          "type": "string",
                          "nullable": true
                        },
                        "sourceFormat": {
                          "type": "string",
                          "nullable": true
                        },
                        "contentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "sizeBytes": {
                          "type": "number",
                          "nullable": true
                        },
                        "deliveryMode": {
                          "type": "string"
                        },
                        "legalFramework": {
                          "type": "string",
                          "nullable": true
                        },
                        "consumerDisclosure": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "scheduledSendAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "reminderPolicy": {
                          "nullable": true
                        },
                        "sentAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "declinedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "voidedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "expiredAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "metadata": {
                          "nullable": true
                        },
                        "senderUserId": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderName": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderEmail": {
                          "type": "string",
                          "nullable": true
                        },
                        "detectedParties": {
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "organizationId",
                        "teamId",
                        "templateId",
                        "templateContentHash",
                        "status",
                        "detectionStatus",
                        "version",
                        "originalFilename",
                        "displayName",
                        "sourceFormat",
                        "contentHash",
                        "sizeBytes",
                        "deliveryMode",
                        "legalFramework",
                        "consumerDisclosure",
                        "expiresAt",
                        "scheduledSendAt",
                        "sentAt",
                        "completedAt",
                        "declinedAt",
                        "voidedAt",
                        "expiredAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string",
                            "nullable": true
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "signed",
                              "declined"
                            ]
                          },
                          "detectedPartyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "consentedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "signedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declinedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declineReason": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastViewedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "lastIpAddress": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastUserAgent": {
                            "type": "string",
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "orderIndex",
                          "name",
                          "email",
                          "status",
                          "consentedAt",
                          "signedAt",
                          "declinedAt",
                          "declineReason",
                          "lastViewedAt",
                          "lastIpAddress",
                          "lastUserAgent",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "participantId": {
                            "type": "string",
                            "nullable": true
                          },
                          "partyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer"
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "detected",
                              "manual",
                              "template"
                            ]
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "proposedAutoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "value": {
                            "type": "string",
                            "nullable": true
                          },
                          "filledAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "participantId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "source",
                          "prefillValue",
                          "locked",
                          "autoSource",
                          "proposedAutoSource",
                          "value",
                          "filledAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    }
                  },
                  "required": [
                    "envelope",
                    "participants",
                    "fields"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Envelope not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Stale expectedVersion",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Envelope not in_progress or no pending participant",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "A reminder was sent to this participant too recently",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/envelopes/{id}/participants/{participantId}/resend-link": {
      "post": {
        "tags": [
          "envelopes"
        ],
        "summary": "Reissue a participant's signing link",
        "description": "Rotates the participant's link credential (a fresh nonce hash replaces the old one, invalidating every outstanding link), appends `participant.link_reissued`, and emits the notification event. The envelope must be in_progress and the participant pending. No link material appears in the response — delivery happens out of band. Supports the `Idempotency-Key` header: a replayed completed key returns the envelope's current graph with the original status code and `Idempotency-Replayed: true` (never re-executing); an in-flight duplicate is rejected 409; reusing a key with a different request is rejected 422.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Envelope id"
            },
            "required": true,
            "description": "Envelope id",
            "name": "id",
            "in": "path"
          },
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Participant id"
            },
            "required": true,
            "description": "Participant id",
            "name": "participantId",
            "in": "path"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The envelope graph after the link rotation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "teamId": {
                          "type": "string"
                        },
                        "templateId": {
                          "type": "string",
                          "nullable": true
                        },
                        "templateContentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "detecting",
                            "review",
                            "in_progress",
                            "completed",
                            "declined",
                            "voided",
                            "expired"
                          ]
                        },
                        "detectionStatus": {
                          "type": "string",
                          "enum": [
                            "none",
                            "running",
                            "succeeded",
                            "failed"
                          ]
                        },
                        "version": {
                          "type": "integer"
                        },
                        "originalFilename": {
                          "type": "string",
                          "nullable": true
                        },
                        "displayName": {
                          "type": "string",
                          "nullable": true
                        },
                        "sourceFormat": {
                          "type": "string",
                          "nullable": true
                        },
                        "contentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "sizeBytes": {
                          "type": "number",
                          "nullable": true
                        },
                        "deliveryMode": {
                          "type": "string"
                        },
                        "legalFramework": {
                          "type": "string",
                          "nullable": true
                        },
                        "consumerDisclosure": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "scheduledSendAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "reminderPolicy": {
                          "nullable": true
                        },
                        "sentAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "declinedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "voidedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "expiredAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "metadata": {
                          "nullable": true
                        },
                        "senderUserId": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderName": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderEmail": {
                          "type": "string",
                          "nullable": true
                        },
                        "detectedParties": {
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "organizationId",
                        "teamId",
                        "templateId",
                        "templateContentHash",
                        "status",
                        "detectionStatus",
                        "version",
                        "originalFilename",
                        "displayName",
                        "sourceFormat",
                        "contentHash",
                        "sizeBytes",
                        "deliveryMode",
                        "legalFramework",
                        "consumerDisclosure",
                        "expiresAt",
                        "scheduledSendAt",
                        "sentAt",
                        "completedAt",
                        "declinedAt",
                        "voidedAt",
                        "expiredAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string",
                            "nullable": true
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "signed",
                              "declined"
                            ]
                          },
                          "detectedPartyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "consentedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "signedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declinedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declineReason": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastViewedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "lastIpAddress": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastUserAgent": {
                            "type": "string",
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "orderIndex",
                          "name",
                          "email",
                          "status",
                          "consentedAt",
                          "signedAt",
                          "declinedAt",
                          "declineReason",
                          "lastViewedAt",
                          "lastIpAddress",
                          "lastUserAgent",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "participantId": {
                            "type": "string",
                            "nullable": true
                          },
                          "partyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer"
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "detected",
                              "manual",
                              "template"
                            ]
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "proposedAutoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "value": {
                            "type": "string",
                            "nullable": true
                          },
                          "filledAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "participantId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "source",
                          "prefillValue",
                          "locked",
                          "autoSource",
                          "proposedAutoSource",
                          "value",
                          "filledAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    }
                  },
                  "required": [
                    "envelope",
                    "participants",
                    "fields"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Envelope or participant not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Stale expectedVersion",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Envelope not in_progress or participant not pending",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/templates": {
      "post": {
        "tags": [
          "Templates"
        ],
        "summary": "Create a template from an envelope",
        "description": "Supports the optional Idempotency-Key header. Repeating the same key and request replays the original 201 response; a key currently in flight returns 409, and reusing a key with a different request returns 422.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sourceEnvelopeId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1
                  },
                  "roles": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "participantId": {
                          "type": "string",
                          "minLength": 1
                        },
                        "partyIndex": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "name": {
                          "type": "string",
                          "minLength": 1
                        },
                        "isSender": {
                          "type": "boolean"
                        },
                        "optional": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "name"
                      ]
                    }
                  },
                  "lockedFieldIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "required": [
                  "sourceEnvelopeId",
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Template graph created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "teamId": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "originalFilename": {
                          "type": "string"
                        },
                        "sourceFormat": {
                          "type": "string"
                        },
                        "contentHash": {
                          "type": "string"
                        },
                        "sizeBytes": {
                          "type": "number"
                        },
                        "archivedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "useCount": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "lastUsedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "organizationId",
                        "teamId",
                        "name",
                        "originalFilename",
                        "sourceFormat",
                        "contentHash",
                        "sizeBytes",
                        "archivedAt",
                        "useCount",
                        "lastUsedAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "roles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "templateId": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "apiRoleName": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "isSender": {
                            "type": "boolean"
                          },
                          "optional": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "id",
                          "templateId",
                          "name",
                          "apiRoleName",
                          "orderIndex",
                          "isSender",
                          "optional"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "templateId": {
                            "type": "string"
                          },
                          "roleId": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "prefillKey": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "id",
                          "templateId",
                          "roleId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "prefillValue",
                          "autoSource",
                          "prefillKey",
                          "locked"
                        ]
                      }
                    }
                  },
                  "required": [
                    "template",
                    "roles",
                    "fields"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Source envelope not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "An idempotent request with this key is already in flight",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Source envelope or role overrides are not valid for a template",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Document storage copy failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Templates"
        ],
        "summary": "List templates",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string"
            },
            "required": false,
            "name": "cursor",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            },
            "required": false,
            "name": "limit",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Cursor-paginated templates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "teamId": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "originalFilename": {
                            "type": "string"
                          },
                          "sourceFormat": {
                            "type": "string"
                          },
                          "contentHash": {
                            "type": "string"
                          },
                          "sizeBytes": {
                            "type": "number"
                          },
                          "archivedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "useCount": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "lastUsedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "organizationId",
                          "teamId",
                          "name",
                          "originalFilename",
                          "sourceFormat",
                          "contentHash",
                          "sizeBytes",
                          "archivedAt",
                          "useCount",
                          "lastUsedAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "nextCursor": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "items"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/templates/{id}": {
      "get": {
        "tags": [
          "Templates"
        ],
        "summary": "Get a template graph",
        "description": "Returns the template graph plus a self-describing agent contract payload.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Template id"
            },
            "required": true,
            "description": "Template id",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Template graph with agent contract",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "teamId": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "originalFilename": {
                          "type": "string"
                        },
                        "sourceFormat": {
                          "type": "string"
                        },
                        "contentHash": {
                          "type": "string"
                        },
                        "sizeBytes": {
                          "type": "number"
                        },
                        "archivedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "useCount": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "lastUsedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "organizationId",
                        "teamId",
                        "name",
                        "originalFilename",
                        "sourceFormat",
                        "contentHash",
                        "sizeBytes",
                        "archivedAt",
                        "useCount",
                        "lastUsedAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "roles": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "templateId": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "apiRoleName": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "isSender": {
                            "type": "boolean"
                          },
                          "optional": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "id",
                          "templateId",
                          "name",
                          "apiRoleName",
                          "orderIndex",
                          "isSender",
                          "optional"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "templateId": {
                            "type": "string"
                          },
                          "roleId": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "prefillKey": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "id",
                          "templateId",
                          "roleId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "prefillValue",
                          "autoSource",
                          "prefillKey",
                          "locked"
                        ]
                      }
                    },
                    "contract": {
                      "type": "object",
                      "properties": {
                        "partiesForSend": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "roleName": {
                                "type": "string"
                              },
                              "apiRoleName": {
                                "type": "string"
                              },
                              "orderIndex": {
                                "type": "integer",
                                "minimum": 0
                              },
                              "isSender": {
                                "type": "boolean"
                              },
                              "required": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "roleName",
                              "apiRoleName",
                              "orderIndex",
                              "isSender",
                              "required"
                            ]
                          }
                        },
                        "doNotIncludeInParties": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "storedSignatures": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "roleName": {
                                "type": "string"
                              },
                              "signatureImageUrl": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "roleName",
                              "signatureImageUrl"
                            ]
                          }
                        },
                        "pinnedValues": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "fieldId": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string",
                                "nullable": true
                              },
                              "value": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "fieldId",
                              "label",
                              "value"
                            ]
                          }
                        },
                        "prefillKeys": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "key": {
                                "type": "string"
                              },
                              "fieldId": {
                                "type": "string"
                              },
                              "roleName": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string",
                                "nullable": true
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "signature",
                                  "initials",
                                  "date",
                                  "text",
                                  "checkbox"
                                ]
                              },
                              "defaultValue": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "key",
                              "fieldId",
                              "roleName",
                              "label",
                              "type",
                              "defaultValue"
                            ]
                          }
                        },
                        "exampleCreate": {
                          "type": "object",
                          "properties": {
                            "recipients": {
                              "type": "object",
                              "additionalProperties": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string",
                                    "minLength": 1
                                  },
                                  "email": {
                                    "type": "string",
                                    "format": "email"
                                  },
                                  "order": {
                                    "type": "integer",
                                    "minimum": 1
                                  },
                                  "company": {
                                    "type": "string",
                                    "nullable": true,
                                    "maxLength": 200
                                  },
                                  "title": {
                                    "type": "string",
                                    "nullable": true,
                                    "maxLength": 200
                                  }
                                },
                                "required": [
                                  "email"
                                ]
                              }
                            },
                            "prefill": {
                              "type": "object",
                              "additionalProperties": {
                                "type": "string"
                              }
                            },
                            "autoSend": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "recipients",
                            "prefill",
                            "autoSend"
                          ]
                        },
                        "sendPath": {
                          "type": "string"
                        },
                        "contractNote": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "partiesForSend",
                        "doNotIncludeInParties",
                        "storedSignatures",
                        "pinnedValues",
                        "prefillKeys",
                        "exampleCreate",
                        "sendPath",
                        "contractNote"
                      ]
                    }
                  },
                  "required": [
                    "template",
                    "roles",
                    "fields",
                    "contract"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Template not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Templates"
        ],
        "summary": "Rename a template",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Template id"
            },
            "required": true,
            "description": "Template id",
            "name": "id",
            "in": "path"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1
                  }
                },
                "required": [
                  "name"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Renamed template",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "organizationId": {
                      "type": "string"
                    },
                    "teamId": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "originalFilename": {
                      "type": "string"
                    },
                    "sourceFormat": {
                      "type": "string"
                    },
                    "contentHash": {
                      "type": "string"
                    },
                    "sizeBytes": {
                      "type": "number"
                    },
                    "archivedAt": {
                      "type": "string",
                      "nullable": true,
                      "format": "date-time"
                    },
                    "useCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "lastUsedAt": {
                      "type": "string",
                      "nullable": true,
                      "format": "date-time"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "id",
                    "organizationId",
                    "teamId",
                    "name",
                    "originalFilename",
                    "sourceFormat",
                    "contentHash",
                    "sizeBytes",
                    "archivedAt",
                    "useCount",
                    "lastUsedAt",
                    "createdAt",
                    "updatedAt"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Template not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Template name is invalid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Templates"
        ],
        "summary": "Archive a template",
        "description": "Soft-archives the template and retains its document blob for restore.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Template id"
            },
            "required": true,
            "description": "Template id",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "204": {
            "description": "Template archived"
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Template not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/templates/{id}/restore": {
      "post": {
        "tags": [
          "Templates"
        ],
        "summary": "Restore an archived template",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Template id"
            },
            "required": true,
            "description": "Template id",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Restored template",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "organizationId": {
                      "type": "string"
                    },
                    "teamId": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "originalFilename": {
                      "type": "string"
                    },
                    "sourceFormat": {
                      "type": "string"
                    },
                    "contentHash": {
                      "type": "string"
                    },
                    "sizeBytes": {
                      "type": "number"
                    },
                    "archivedAt": {
                      "type": "string",
                      "nullable": true,
                      "format": "date-time"
                    },
                    "useCount": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "lastUsedAt": {
                      "type": "string",
                      "nullable": true,
                      "format": "date-time"
                    },
                    "createdAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "id",
                    "organizationId",
                    "teamId",
                    "name",
                    "originalFilename",
                    "sourceFormat",
                    "contentHash",
                    "sizeBytes",
                    "archivedAt",
                    "useCount",
                    "lastUsedAt",
                    "createdAt",
                    "updatedAt"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Archived template not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/templates/{id}/envelopes": {
      "post": {
        "tags": [
          "Templates"
        ],
        "summary": "Create an envelope from a template",
        "description": "Requires a recipient for every template role. By default auto-sends because the layout was reviewed at save time; pass autoSend: false for a review-first draft. Supports the optional Idempotency-Key header. Repeating the same key and request replays the original 201 response; a key currently in flight returns 409, and reusing a key with a different request returns 422.",
        "security": [
          {
            "apiKey": []
          },
          {
            "oauthJwt": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Template id"
            },
            "required": true,
            "description": "Template id",
            "name": "id",
            "in": "path"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "recipients": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1
                        },
                        "email": {
                          "type": "string",
                          "format": "email"
                        },
                        "order": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "company": {
                          "type": "string",
                          "nullable": true,
                          "maxLength": 200
                        },
                        "title": {
                          "type": "string",
                          "nullable": true,
                          "maxLength": 200
                        }
                      },
                      "required": [
                        "email"
                      ]
                    }
                  },
                  "prefill": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "displayName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  },
                  "autoSend": {
                    "type": "boolean"
                  },
                  "senderOrder": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "required": [
                  "recipients"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Instantiated envelope",
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "envelope": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "organizationId": {
                              "type": "string"
                            },
                            "teamId": {
                              "type": "string"
                            },
                            "templateId": {
                              "type": "string",
                              "nullable": true
                            },
                            "templateContentHash": {
                              "type": "string",
                              "nullable": true
                            },
                            "status": {
                              "type": "string",
                              "enum": [
                                "draft",
                                "detecting",
                                "review",
                                "in_progress",
                                "completed",
                                "declined",
                                "voided",
                                "expired"
                              ]
                            },
                            "detectionStatus": {
                              "type": "string",
                              "enum": [
                                "none",
                                "running",
                                "succeeded",
                                "failed"
                              ]
                            },
                            "version": {
                              "type": "integer"
                            },
                            "originalFilename": {
                              "type": "string",
                              "nullable": true
                            },
                            "displayName": {
                              "type": "string",
                              "nullable": true
                            },
                            "sourceFormat": {
                              "type": "string",
                              "nullable": true
                            },
                            "contentHash": {
                              "type": "string",
                              "nullable": true
                            },
                            "sizeBytes": {
                              "type": "number",
                              "nullable": true
                            },
                            "deliveryMode": {
                              "type": "string"
                            },
                            "legalFramework": {
                              "type": "string",
                              "nullable": true
                            },
                            "consumerDisclosure": {
                              "type": "boolean"
                            },
                            "expiresAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "scheduledSendAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "reminderPolicy": {
                              "nullable": true
                            },
                            "sentAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "completedAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "declinedAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "voidedAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "expiredAt": {
                              "type": "string",
                              "nullable": true,
                              "format": "date-time"
                            },
                            "metadata": {
                              "nullable": true
                            },
                            "senderUserId": {
                              "type": "string",
                              "nullable": true
                            },
                            "senderName": {
                              "type": "string",
                              "nullable": true
                            },
                            "senderEmail": {
                              "type": "string",
                              "nullable": true
                            },
                            "detectedParties": {
                              "nullable": true
                            },
                            "createdAt": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "updatedAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "required": [
                            "id",
                            "organizationId",
                            "teamId",
                            "templateId",
                            "templateContentHash",
                            "status",
                            "detectionStatus",
                            "version",
                            "originalFilename",
                            "displayName",
                            "sourceFormat",
                            "contentHash",
                            "sizeBytes",
                            "deliveryMode",
                            "legalFramework",
                            "consumerDisclosure",
                            "expiresAt",
                            "scheduledSendAt",
                            "sentAt",
                            "completedAt",
                            "declinedAt",
                            "voidedAt",
                            "expiredAt",
                            "createdAt",
                            "updatedAt"
                          ]
                        },
                        "participants": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "envelopeId": {
                                "type": "string"
                              },
                              "organizationId": {
                                "type": "string"
                              },
                              "orderIndex": {
                                "type": "integer"
                              },
                              "name": {
                                "type": "string"
                              },
                              "email": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string",
                                "nullable": true
                              },
                              "title": {
                                "type": "string",
                                "nullable": true
                              },
                              "status": {
                                "type": "string",
                                "enum": [
                                  "pending",
                                  "signed",
                                  "declined"
                                ]
                              },
                              "detectedPartyIndex": {
                                "type": "integer",
                                "nullable": true
                              },
                              "consentedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "signedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "declinedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "declineReason": {
                                "type": "string",
                                "nullable": true
                              },
                              "lastViewedAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "lastIpAddress": {
                                "type": "string",
                                "nullable": true
                              },
                              "lastUserAgent": {
                                "type": "string",
                                "nullable": true
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updatedAt": {
                                "type": "string",
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "id",
                              "envelopeId",
                              "organizationId",
                              "orderIndex",
                              "name",
                              "email",
                              "status",
                              "consentedAt",
                              "signedAt",
                              "declinedAt",
                              "declineReason",
                              "lastViewedAt",
                              "lastIpAddress",
                              "lastUserAgent",
                              "createdAt",
                              "updatedAt"
                            ]
                          }
                        },
                        "fields": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "envelopeId": {
                                "type": "string"
                              },
                              "organizationId": {
                                "type": "string"
                              },
                              "participantId": {
                                "type": "string",
                                "nullable": true
                              },
                              "partyIndex": {
                                "type": "integer",
                                "nullable": true
                              },
                              "type": {
                                "type": "string",
                                "enum": [
                                  "signature",
                                  "initials",
                                  "date",
                                  "text",
                                  "checkbox"
                                ]
                              },
                              "page": {
                                "type": "integer"
                              },
                              "x": {
                                "type": "number"
                              },
                              "y": {
                                "type": "number"
                              },
                              "width": {
                                "type": "number"
                              },
                              "height": {
                                "type": "number"
                              },
                              "label": {
                                "type": "string",
                                "nullable": true
                              },
                              "required": {
                                "type": "boolean"
                              },
                              "source": {
                                "type": "string",
                                "enum": [
                                  "detected",
                                  "manual",
                                  "template"
                                ]
                              },
                              "prefillValue": {
                                "type": "string",
                                "nullable": true
                              },
                              "locked": {
                                "type": "boolean"
                              },
                              "autoSource": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                  "signed_date",
                                  "participant_name",
                                  "participant_email",
                                  "participant_company",
                                  "participant_title",
                                  "sender_org_name",
                                  null
                                ]
                              },
                              "proposedAutoSource": {
                                "type": "string",
                                "nullable": true,
                                "enum": [
                                  "signed_date",
                                  "participant_name",
                                  "participant_email",
                                  "participant_company",
                                  "participant_title",
                                  "sender_org_name",
                                  null
                                ]
                              },
                              "value": {
                                "type": "string",
                                "nullable": true
                              },
                              "filledAt": {
                                "type": "string",
                                "nullable": true,
                                "format": "date-time"
                              },
                              "createdAt": {
                                "type": "string",
                                "format": "date-time"
                              },
                              "updatedAt": {
                                "type": "string",
                                "format": "date-time"
                              }
                            },
                            "required": [
                              "id",
                              "envelopeId",
                              "organizationId",
                              "participantId",
                              "type",
                              "page",
                              "x",
                              "y",
                              "width",
                              "height",
                              "label",
                              "required",
                              "source",
                              "prefillValue",
                              "locked",
                              "autoSource",
                              "proposedAutoSource",
                              "value",
                              "filledAt",
                              "createdAt",
                              "updatedAt"
                            ]
                          }
                        }
                      },
                      "required": [
                        "envelope",
                        "participants",
                        "fields"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "envelope": {
                          "type": "object",
                          "properties": {
                            "envelope": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "organizationId": {
                                  "type": "string"
                                },
                                "teamId": {
                                  "type": "string"
                                },
                                "templateId": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "templateContentHash": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "status": {
                                  "type": "string",
                                  "enum": [
                                    "draft",
                                    "detecting",
                                    "review",
                                    "in_progress",
                                    "completed",
                                    "declined",
                                    "voided",
                                    "expired"
                                  ]
                                },
                                "detectionStatus": {
                                  "type": "string",
                                  "enum": [
                                    "none",
                                    "running",
                                    "succeeded",
                                    "failed"
                                  ]
                                },
                                "version": {
                                  "type": "integer"
                                },
                                "originalFilename": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "displayName": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "sourceFormat": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "contentHash": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "sizeBytes": {
                                  "type": "number",
                                  "nullable": true
                                },
                                "deliveryMode": {
                                  "type": "string"
                                },
                                "legalFramework": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "consumerDisclosure": {
                                  "type": "boolean"
                                },
                                "expiresAt": {
                                  "type": "string",
                                  "nullable": true,
                                  "format": "date-time"
                                },
                                "scheduledSendAt": {
                                  "type": "string",
                                  "nullable": true,
                                  "format": "date-time"
                                },
                                "reminderPolicy": {
                                  "nullable": true
                                },
                                "sentAt": {
                                  "type": "string",
                                  "nullable": true,
                                  "format": "date-time"
                                },
                                "completedAt": {
                                  "type": "string",
                                  "nullable": true,
                                  "format": "date-time"
                                },
                                "declinedAt": {
                                  "type": "string",
                                  "nullable": true,
                                  "format": "date-time"
                                },
                                "voidedAt": {
                                  "type": "string",
                                  "nullable": true,
                                  "format": "date-time"
                                },
                                "expiredAt": {
                                  "type": "string",
                                  "nullable": true,
                                  "format": "date-time"
                                },
                                "metadata": {
                                  "nullable": true
                                },
                                "senderUserId": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "senderName": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "senderEmail": {
                                  "type": "string",
                                  "nullable": true
                                },
                                "detectedParties": {
                                  "nullable": true
                                },
                                "createdAt": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "updatedAt": {
                                  "type": "string",
                                  "format": "date-time"
                                }
                              },
                              "required": [
                                "id",
                                "organizationId",
                                "teamId",
                                "templateId",
                                "templateContentHash",
                                "status",
                                "detectionStatus",
                                "version",
                                "originalFilename",
                                "displayName",
                                "sourceFormat",
                                "contentHash",
                                "sizeBytes",
                                "deliveryMode",
                                "legalFramework",
                                "consumerDisclosure",
                                "expiresAt",
                                "scheduledSendAt",
                                "sentAt",
                                "completedAt",
                                "declinedAt",
                                "voidedAt",
                                "expiredAt",
                                "createdAt",
                                "updatedAt"
                              ]
                            },
                            "participants": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "envelopeId": {
                                    "type": "string"
                                  },
                                  "organizationId": {
                                    "type": "string"
                                  },
                                  "orderIndex": {
                                    "type": "integer"
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "email": {
                                    "type": "string"
                                  },
                                  "company": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "title": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "status": {
                                    "type": "string",
                                    "enum": [
                                      "pending",
                                      "signed",
                                      "declined"
                                    ]
                                  },
                                  "detectedPartyIndex": {
                                    "type": "integer",
                                    "nullable": true
                                  },
                                  "consentedAt": {
                                    "type": "string",
                                    "nullable": true,
                                    "format": "date-time"
                                  },
                                  "signedAt": {
                                    "type": "string",
                                    "nullable": true,
                                    "format": "date-time"
                                  },
                                  "declinedAt": {
                                    "type": "string",
                                    "nullable": true,
                                    "format": "date-time"
                                  },
                                  "declineReason": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "lastViewedAt": {
                                    "type": "string",
                                    "nullable": true,
                                    "format": "date-time"
                                  },
                                  "lastIpAddress": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "lastUserAgent": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "createdAt": {
                                    "type": "string",
                                    "format": "date-time"
                                  },
                                  "updatedAt": {
                                    "type": "string",
                                    "format": "date-time"
                                  }
                                },
                                "required": [
                                  "id",
                                  "envelopeId",
                                  "organizationId",
                                  "orderIndex",
                                  "name",
                                  "email",
                                  "status",
                                  "consentedAt",
                                  "signedAt",
                                  "declinedAt",
                                  "declineReason",
                                  "lastViewedAt",
                                  "lastIpAddress",
                                  "lastUserAgent",
                                  "createdAt",
                                  "updatedAt"
                                ]
                              }
                            },
                            "fields": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "envelopeId": {
                                    "type": "string"
                                  },
                                  "organizationId": {
                                    "type": "string"
                                  },
                                  "participantId": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "partyIndex": {
                                    "type": "integer",
                                    "nullable": true
                                  },
                                  "type": {
                                    "type": "string",
                                    "enum": [
                                      "signature",
                                      "initials",
                                      "date",
                                      "text",
                                      "checkbox"
                                    ]
                                  },
                                  "page": {
                                    "type": "integer"
                                  },
                                  "x": {
                                    "type": "number"
                                  },
                                  "y": {
                                    "type": "number"
                                  },
                                  "width": {
                                    "type": "number"
                                  },
                                  "height": {
                                    "type": "number"
                                  },
                                  "label": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "required": {
                                    "type": "boolean"
                                  },
                                  "source": {
                                    "type": "string",
                                    "enum": [
                                      "detected",
                                      "manual",
                                      "template"
                                    ]
                                  },
                                  "prefillValue": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "locked": {
                                    "type": "boolean"
                                  },
                                  "autoSource": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                      "signed_date",
                                      "participant_name",
                                      "participant_email",
                                      "participant_company",
                                      "participant_title",
                                      "sender_org_name",
                                      null
                                    ]
                                  },
                                  "proposedAutoSource": {
                                    "type": "string",
                                    "nullable": true,
                                    "enum": [
                                      "signed_date",
                                      "participant_name",
                                      "participant_email",
                                      "participant_company",
                                      "participant_title",
                                      "sender_org_name",
                                      null
                                    ]
                                  },
                                  "value": {
                                    "type": "string",
                                    "nullable": true
                                  },
                                  "filledAt": {
                                    "type": "string",
                                    "nullable": true,
                                    "format": "date-time"
                                  },
                                  "createdAt": {
                                    "type": "string",
                                    "format": "date-time"
                                  },
                                  "updatedAt": {
                                    "type": "string",
                                    "format": "date-time"
                                  }
                                },
                                "required": [
                                  "id",
                                  "envelopeId",
                                  "organizationId",
                                  "participantId",
                                  "type",
                                  "page",
                                  "x",
                                  "y",
                                  "width",
                                  "height",
                                  "label",
                                  "required",
                                  "source",
                                  "prefillValue",
                                  "locked",
                                  "autoSource",
                                  "proposedAutoSource",
                                  "value",
                                  "filledAt",
                                  "createdAt",
                                  "updatedAt"
                                ]
                              }
                            }
                          },
                          "required": [
                            "envelope",
                            "participants",
                            "fields"
                          ]
                        },
                        "reviewUrl": {
                          "type": "string"
                        },
                        "note": {
                          "type": "string"
                        },
                        "prefillUnmatched": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "envelope"
                      ]
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "Insufficient send credits",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Template not found in this organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "An idempotent request with this key is already in flight",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Recipients or prefill values are invalid",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "502": {
            "description": "Document storage copy failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/signer/envelope": {
      "get": {
        "tags": [
          "signer"
        ],
        "summary": "Get the envelope as seen by the authenticated signer",
        "description": "Party-scoped read: returns the envelope summary, the signer's own participant record and fields, position/progress slots for every participant (no names or emails), and a short-lived `documentUrl`. For a participant whose turn has not arrived, `fields` is empty and `documentUrl` is null. Records a throttled `participant.viewed` event.",
        "security": [
          {
            "signerToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "The signer-scoped envelope view",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "detecting",
                            "review",
                            "in_progress",
                            "completed",
                            "declined",
                            "voided",
                            "expired"
                          ]
                        },
                        "detectionStatus": {
                          "type": "string",
                          "enum": [
                            "none",
                            "running",
                            "succeeded",
                            "failed"
                          ]
                        },
                        "version": {
                          "type": "integer"
                        },
                        "legalFramework": {
                          "type": "string",
                          "nullable": true
                        },
                        "consumerDisclosure": {
                          "type": "boolean"
                        },
                        "originalFilename": {
                          "type": "string",
                          "nullable": true
                        },
                        "displayName": {
                          "type": "string",
                          "nullable": true
                        },
                        "expiresAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "status",
                        "detectionStatus",
                        "version",
                        "legalFramework",
                        "consumerDisclosure",
                        "originalFilename",
                        "displayName",
                        "expiresAt"
                      ]
                    },
                    "me": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "envelopeId": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "orderIndex": {
                          "type": "integer"
                        },
                        "name": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "company": {
                          "type": "string",
                          "nullable": true
                        },
                        "title": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "pending",
                            "signed",
                            "declined"
                          ]
                        },
                        "detectedPartyIndex": {
                          "type": "integer",
                          "nullable": true
                        },
                        "consentedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "signedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "declinedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "declineReason": {
                          "type": "string",
                          "nullable": true
                        },
                        "lastViewedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "envelopeId",
                        "organizationId",
                        "orderIndex",
                        "name",
                        "email",
                        "status",
                        "consentedAt",
                        "signedAt",
                        "declinedAt",
                        "declineReason",
                        "lastViewedAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "orderIndex": {
                            "type": "integer"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "signed",
                              "declined"
                            ]
                          }
                        },
                        "required": [
                          "orderIndex",
                          "status"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "participantId": {
                            "type": "string",
                            "nullable": true
                          },
                          "partyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer"
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "detected",
                              "manual",
                              "template"
                            ]
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "value": {
                            "type": "string",
                            "nullable": true
                          },
                          "filledAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "participantId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "source",
                          "prefillValue",
                          "locked",
                          "autoSource",
                          "value",
                          "filledAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "completedFields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "participantId": {
                            "type": "string",
                            "nullable": true
                          },
                          "partyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer"
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "detected",
                              "manual",
                              "template"
                            ]
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "value": {
                            "type": "string",
                            "nullable": true
                          },
                          "filledAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "participantId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "source",
                          "prefillValue",
                          "locked",
                          "autoSource",
                          "value",
                          "filledAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "isMyTurn": {
                      "type": "boolean"
                    },
                    "senderName": {
                      "type": "string",
                      "nullable": true
                    },
                    "senderEmail": {
                      "type": "string",
                      "nullable": true
                    },
                    "branding": {
                      "type": "object",
                      "properties": {
                        "displayName": {
                          "type": "string"
                        },
                        "logoUrl": {
                          "type": "string",
                          "nullable": true,
                          "format": "uri"
                        },
                        "logoWidth": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "logoHeight": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0,
                          "exclusiveMinimum": true
                        },
                        "accentColor": {
                          "type": "string",
                          "pattern": "^#[0-9a-f]{6}$"
                        }
                      },
                      "required": [
                        "displayName",
                        "logoUrl",
                        "accentColor"
                      ]
                    },
                    "documentUrl": {
                      "type": "string",
                      "nullable": true,
                      "format": "uri"
                    }
                  },
                  "required": [
                    "envelope",
                    "me",
                    "participants",
                    "fields",
                    "completedFields",
                    "isMyTurn",
                    "senderName",
                    "senderEmail",
                    "branding",
                    "documentUrl"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, or reissued signing link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "The link's envelope or participant no longer exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/signer/consent": {
      "post": {
        "tags": [
          "signer"
        ],
        "summary": "Record the signer's consent to electronic signature",
        "description": "Appends `participant.consented` with the request's IP and user agent as audit facts (spec §7). Idempotent: a participant who already consented gets their original consent timestamp back. Allowed only when it is the signer's turn.",
        "security": [
          {
            "signerToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Consent recorded (or already on record)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "consentedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "consentedAt"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, or reissued signing link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "The link's envelope or participant no longer exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Not the signer's turn, or the envelope is no longer active",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/signer/submit": {
      "post": {
        "tags": [
          "signer"
        ],
        "summary": "Submit the signer's field values and signature",
        "description": "The signing action (spec §5.5): validates ownership and required-field completeness, persists values, appends `participant.signed` with audit facts, and advances to the next participant — or, when this was the final signer, triggers artifact generation (the envelope stays `in_progress` until artifacts exist; §4 status never lies). Replaying after success is an idempotent 200. Requires prior consent. An optional `identity` corrects the sender-provided name/company/title the signer's auto-filled fields derive from, evidenced by `participant.details_corrected`.",
        "security": [
          {
            "signerToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "values": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string",
                      "maxLength": 262144
                    }
                  },
                  "signatureMethods": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string",
                      "enum": [
                        "drawn",
                        "typed",
                        "uploaded"
                      ]
                    }
                  },
                  "identity": {
                    "type": "object",
                    "properties": {
                      "name": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200
                      },
                      "company": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 200
                      },
                      "title": {
                        "type": "string",
                        "nullable": true,
                        "maxLength": 200
                      }
                    }
                  }
                },
                "required": [
                  "values"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signature recorded (or already recorded)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "draft",
                        "detecting",
                        "review",
                        "in_progress",
                        "completed",
                        "declined",
                        "voided",
                        "expired"
                      ]
                    },
                    "allParticipantsSigned": {
                      "type": "boolean"
                    },
                    "alreadySigned": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "status",
                    "allParticipantsSigned",
                    "alreadySigned"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, or reissued signing link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "The link's envelope or participant no longer exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Out-of-order submission, consent missing, terminal envelope, or a concurrent modification",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Values reference fields not assigned to this participant (validation_error), or required fields are incomplete (required_fields_missing)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/signer/decline": {
      "post": {
        "tags": [
          "signer"
        ],
        "summary": "Decline to sign",
        "description": "Terminates the envelope (spec §5.5): appends `participant.declined` with the sanitized reason and the request's audit facts; the envelope status derives to `declined`. Allowed only when it is the signer's turn.",
        "security": [
          {
            "signerToken": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "maxLength": 500
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The envelope was declined",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "draft",
                        "detecting",
                        "review",
                        "in_progress",
                        "completed",
                        "declined",
                        "voided",
                        "expired"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, expired, or reissued signing link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "The link's envelope or participant no longer exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Not the signer's turn, or the envelope is no longer active",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Malformed body or decline reason exceeds 500 characters (validation_error)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/review/envelope": {
      "get": {
        "tags": [
          "review"
        ],
        "summary": "Get the envelope under review",
        "description": "Returns the full envelope graph for the token's envelope, plus a short-lived signed `documentUrl` for the renderable PDF (the converted artifact when one exists, else the original only when it is a PDF; null when nothing renderable is stored) and a curated `detection` summary (parties + matching) derived from the latest completed detection run, or null when detection never completed. Requires a read-capable token.",
        "security": [
          {
            "reviewToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "The envelope graph with review extras",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "teamId": {
                          "type": "string"
                        },
                        "templateId": {
                          "type": "string",
                          "nullable": true
                        },
                        "templateContentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "detecting",
                            "review",
                            "in_progress",
                            "completed",
                            "declined",
                            "voided",
                            "expired"
                          ]
                        },
                        "detectionStatus": {
                          "type": "string",
                          "enum": [
                            "none",
                            "running",
                            "succeeded",
                            "failed"
                          ]
                        },
                        "version": {
                          "type": "integer"
                        },
                        "originalFilename": {
                          "type": "string",
                          "nullable": true
                        },
                        "displayName": {
                          "type": "string",
                          "nullable": true
                        },
                        "sourceFormat": {
                          "type": "string",
                          "nullable": true
                        },
                        "contentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "sizeBytes": {
                          "type": "number",
                          "nullable": true
                        },
                        "deliveryMode": {
                          "type": "string"
                        },
                        "legalFramework": {
                          "type": "string",
                          "nullable": true
                        },
                        "consumerDisclosure": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "scheduledSendAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "reminderPolicy": {
                          "nullable": true
                        },
                        "sentAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "declinedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "voidedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "expiredAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "metadata": {
                          "nullable": true
                        },
                        "senderUserId": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderName": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderEmail": {
                          "type": "string",
                          "nullable": true
                        },
                        "detectedParties": {
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "organizationId",
                        "teamId",
                        "templateId",
                        "templateContentHash",
                        "status",
                        "detectionStatus",
                        "version",
                        "originalFilename",
                        "displayName",
                        "sourceFormat",
                        "contentHash",
                        "sizeBytes",
                        "deliveryMode",
                        "legalFramework",
                        "consumerDisclosure",
                        "expiresAt",
                        "scheduledSendAt",
                        "sentAt",
                        "completedAt",
                        "declinedAt",
                        "voidedAt",
                        "expiredAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string",
                            "nullable": true
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "signed",
                              "declined"
                            ]
                          },
                          "detectedPartyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "consentedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "signedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declinedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declineReason": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastViewedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "orderIndex",
                          "name",
                          "email",
                          "status",
                          "consentedAt",
                          "signedAt",
                          "declinedAt",
                          "declineReason",
                          "lastViewedAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "participantId": {
                            "type": "string",
                            "nullable": true
                          },
                          "partyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer"
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "detected",
                              "manual",
                              "template"
                            ]
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "proposedAutoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "value": {
                            "type": "string",
                            "nullable": true
                          },
                          "filledAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "participantId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "source",
                          "prefillValue",
                          "locked",
                          "autoSource",
                          "proposedAutoSource",
                          "value",
                          "filledAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "documentUrl": {
                      "type": "string",
                      "nullable": true,
                      "format": "uri"
                    },
                    "detection": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "parties": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string",
                                "nullable": true
                              },
                              "signerName": {
                                "type": "string",
                                "nullable": true
                              },
                              "company": {
                                "type": "string",
                                "nullable": true
                              },
                              "title": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "name",
                              "description"
                            ]
                          }
                        },
                        "senderPartyIndex": {
                          "type": "integer",
                          "nullable": true
                        },
                        "matching": {
                          "type": "object",
                          "properties": {
                            "matches": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "partyIndex": {
                                    "type": "integer"
                                  },
                                  "participantId": {
                                    "type": "string",
                                    "nullable": true
                                  }
                                },
                                "required": [
                                  "partyIndex",
                                  "participantId"
                                ]
                              }
                            },
                            "ambiguous": {
                              "type": "boolean"
                            },
                            "assignedFieldCount": {
                              "type": "integer"
                            },
                            "unassignedFieldCount": {
                              "type": "integer"
                            }
                          },
                          "required": [
                            "matches",
                            "ambiguous",
                            "assignedFieldCount",
                            "unassignedFieldCount"
                          ]
                        }
                      },
                      "required": [
                        "parties",
                        "senderPartyIndex",
                        "matching"
                      ]
                    },
                    "sendPreflight": {
                      "type": "object",
                      "properties": {
                        "credits": {
                          "type": "object",
                          "properties": {
                            "balance": {
                              "type": "integer",
                              "minimum": 0
                            },
                            "required": {
                              "type": "number",
                              "enum": [
                                1
                              ]
                            },
                            "sufficient": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "balance",
                            "required",
                            "sufficient"
                          ]
                        },
                        "blockers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "code": {
                                "type": "string",
                                "enum": [
                                  "insufficient_credits"
                                ]
                              },
                              "message": {
                                "type": "string",
                                "minLength": 1
                              }
                            },
                            "required": [
                              "code",
                              "message"
                            ]
                          }
                        }
                      },
                      "required": [
                        "credits",
                        "blockers"
                      ]
                    },
                    "effectiveSender": {
                      "oneOf": [
                        {
                          "type": "object",
                          "properties": {
                            "kind": {
                              "type": "string",
                              "enum": [
                                "user"
                              ]
                            },
                            "userId": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string",
                              "minLength": 1
                            },
                            "email": {
                              "type": "string",
                              "format": "email"
                            }
                          },
                          "required": [
                            "kind",
                            "userId",
                            "name",
                            "email"
                          ]
                        },
                        {
                          "type": "object",
                          "properties": {
                            "kind": {
                              "type": "string",
                              "enum": [
                                "workspace"
                              ]
                            },
                            "name": {
                              "type": "string",
                              "minLength": 1
                            },
                            "email": {
                              "nullable": true
                            }
                          },
                          "required": [
                            "kind",
                            "name",
                            "email"
                          ]
                        }
                      ]
                    }
                  },
                  "required": [
                    "envelope",
                    "participants",
                    "fields",
                    "documentUrl",
                    "detection",
                    "sendPreflight",
                    "effectiveSender"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid review token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Token lacks read capability",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "The token's envelope no longer exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/review/draft": {
      "put": {
        "tags": [
          "review"
        ],
        "summary": "Update the draft graph of the envelope under review",
        "description": "Same contract as `PUT /v1/envelopes/{id}/draft`, scoped to the token's envelope: any subset of `participants`, `fields`, and `policy`, applied in one transaction (allowed in `draft` and `review` status only — envelopes are immutable after send). `participants` requires `fields` in the same call. `expectedVersion` is checked strictly when supplied.",
        "security": [
          {
            "reviewToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "participants": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "minLength": 1
                        },
                        "email": {
                          "type": "string",
                          "format": "email"
                        },
                        "company": {
                          "type": "string",
                          "nullable": true,
                          "maxLength": 200
                        },
                        "title": {
                          "type": "string",
                          "nullable": true,
                          "maxLength": 200
                        },
                        "detectedPartyIndex": {
                          "type": "integer",
                          "nullable": true,
                          "minimum": 0
                        }
                      },
                      "required": [
                        "name",
                        "email"
                      ]
                    }
                  },
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "participantIndex": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "partyIndex": {
                          "type": "integer",
                          "minimum": 0
                        },
                        "type": {
                          "type": "string",
                          "enum": [
                            "signature",
                            "initials",
                            "date",
                            "text",
                            "checkbox"
                          ]
                        },
                        "page": {
                          "type": "integer",
                          "minimum": 1
                        },
                        "x": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "y": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "width": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "height": {
                          "type": "number",
                          "minimum": 0,
                          "maximum": 1
                        },
                        "label": {
                          "type": "string",
                          "nullable": true
                        },
                        "required": {
                          "type": "boolean"
                        },
                        "prefillValue": {
                          "type": "string",
                          "nullable": true,
                          "description": "Static sender-supplied value for text or date fields. Ignored on checkbox fields, which always remain signer-controlled."
                        },
                        "autoSource": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "signed_date",
                            "participant_name",
                            "participant_email",
                            "participant_company",
                            "participant_title",
                            "sender_org_name",
                            null
                          ],
                          "description": "Derive this field's value server-side when the signer signs: signed_date (date fields) or participant_name / participant_email / participant_company / participant_title / sender_org_name (text fields). Mutually exclusive with prefillValue. The resolved value is recorded in the envelope's audit trail."
                        },
                        "proposedAutoSource": {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            "signed_date",
                            "participant_name",
                            "participant_email",
                            "participant_company",
                            "participant_title",
                            "sender_org_name",
                            null
                          ],
                          "description": "Detection-proposal echo. On draft updates, echo the proposedAutoSource you read to keep the suggestion; omitting or nulling it dismisses it. Cannot introduce or change a proposal (detection is the only origin); ignored at envelope create."
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "detected",
                            "manual",
                            "template"
                          ]
                        }
                      },
                      "required": [
                        "type",
                        "page",
                        "x",
                        "y",
                        "width",
                        "height"
                      ]
                    }
                  },
                  "policy": {
                    "type": "object",
                    "properties": {
                      "deliveryMode": {
                        "type": "string",
                        "enum": [
                          "review_first",
                          "auto_send"
                        ]
                      },
                      "legalFramework": {
                        "type": "string",
                        "nullable": true
                      },
                      "consumerDisclosure": {
                        "type": "boolean"
                      },
                      "expiresAt": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "reminderPolicy": {
                        "nullable": true
                      }
                    }
                  },
                  "sender": {
                    "nullable": true
                  },
                  "displayName": {
                    "type": "string",
                    "nullable": true
                  },
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated envelope graph (final version after all bumps)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "teamId": {
                          "type": "string"
                        },
                        "templateId": {
                          "type": "string",
                          "nullable": true
                        },
                        "templateContentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "detecting",
                            "review",
                            "in_progress",
                            "completed",
                            "declined",
                            "voided",
                            "expired"
                          ]
                        },
                        "detectionStatus": {
                          "type": "string",
                          "enum": [
                            "none",
                            "running",
                            "succeeded",
                            "failed"
                          ]
                        },
                        "version": {
                          "type": "integer"
                        },
                        "originalFilename": {
                          "type": "string",
                          "nullable": true
                        },
                        "displayName": {
                          "type": "string",
                          "nullable": true
                        },
                        "sourceFormat": {
                          "type": "string",
                          "nullable": true
                        },
                        "contentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "sizeBytes": {
                          "type": "number",
                          "nullable": true
                        },
                        "deliveryMode": {
                          "type": "string"
                        },
                        "legalFramework": {
                          "type": "string",
                          "nullable": true
                        },
                        "consumerDisclosure": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "scheduledSendAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "reminderPolicy": {
                          "nullable": true
                        },
                        "sentAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "declinedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "voidedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "expiredAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "metadata": {
                          "nullable": true
                        },
                        "senderUserId": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderName": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderEmail": {
                          "type": "string",
                          "nullable": true
                        },
                        "detectedParties": {
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "organizationId",
                        "teamId",
                        "templateId",
                        "templateContentHash",
                        "status",
                        "detectionStatus",
                        "version",
                        "originalFilename",
                        "displayName",
                        "sourceFormat",
                        "contentHash",
                        "sizeBytes",
                        "deliveryMode",
                        "legalFramework",
                        "consumerDisclosure",
                        "expiresAt",
                        "scheduledSendAt",
                        "sentAt",
                        "completedAt",
                        "declinedAt",
                        "voidedAt",
                        "expiredAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string",
                            "nullable": true
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "signed",
                              "declined"
                            ]
                          },
                          "detectedPartyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "consentedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "signedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declinedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declineReason": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastViewedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "lastIpAddress": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastUserAgent": {
                            "type": "string",
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "orderIndex",
                          "name",
                          "email",
                          "status",
                          "consentedAt",
                          "signedAt",
                          "declinedAt",
                          "declineReason",
                          "lastViewedAt",
                          "lastIpAddress",
                          "lastUserAgent",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "participantId": {
                            "type": "string",
                            "nullable": true
                          },
                          "partyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer"
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "detected",
                              "manual",
                              "template"
                            ]
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "proposedAutoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "value": {
                            "type": "string",
                            "nullable": true
                          },
                          "filledAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "participantId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "source",
                          "prefillValue",
                          "locked",
                          "autoSource",
                          "proposedAutoSource",
                          "value",
                          "filledAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    }
                  },
                  "required": [
                    "envelope",
                    "participants",
                    "fields"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid review token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Token lacks read capability",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "The token's envelope no longer exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Stale expectedVersion (concurrent modification)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Validation failed: envelope not in draft/review, participants without fields, duplicate emails, or out-of-bounds participantIndex",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/review/redetect": {
      "post": {
        "tags": [
          "review"
        ],
        "summary": "Re-run detection on the envelope under review",
        "description": "Re-triggers the detection pipeline for the token's envelope — the recovery path after a failed/empty detection or after editing participants. Allowed only in `draft`/`review`; rate-limited to 5 runs per envelope per hour. Manually placed fields survive re-detection (§6.7). Requires a read-capable token.",
        "security": [
          {
            "reviewToken": []
          }
        ],
        "responses": {
          "202": {
            "description": "Detection was requested (runs asynchronously)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReviewRedetectResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid review token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Token lacks read capability",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "The token's envelope no longer exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Envelope is not in draft/review",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Too many detection runs in the last hour",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/review/send": {
      "post": {
        "tags": [
          "review"
        ],
        "summary": "Send the envelope under review",
        "description": "The human approval action (spec §5.3): same contract as `POST /v1/envelopes/{id}/send`, scoped to the token's envelope — validates the stored document, requires ≥1 participant, transitions to `in_progress`, and emits the `atlas/envelope.sent` notification event. Requires a send-capable token (read-only links cannot dispatch).",
        "security": [
          {
            "reviewToken": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedVersion": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The sent envelope graph (status in_progress)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "envelope": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "organizationId": {
                          "type": "string"
                        },
                        "teamId": {
                          "type": "string"
                        },
                        "templateId": {
                          "type": "string",
                          "nullable": true
                        },
                        "templateContentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "draft",
                            "detecting",
                            "review",
                            "in_progress",
                            "completed",
                            "declined",
                            "voided",
                            "expired"
                          ]
                        },
                        "detectionStatus": {
                          "type": "string",
                          "enum": [
                            "none",
                            "running",
                            "succeeded",
                            "failed"
                          ]
                        },
                        "version": {
                          "type": "integer"
                        },
                        "originalFilename": {
                          "type": "string",
                          "nullable": true
                        },
                        "displayName": {
                          "type": "string",
                          "nullable": true
                        },
                        "sourceFormat": {
                          "type": "string",
                          "nullable": true
                        },
                        "contentHash": {
                          "type": "string",
                          "nullable": true
                        },
                        "sizeBytes": {
                          "type": "number",
                          "nullable": true
                        },
                        "deliveryMode": {
                          "type": "string"
                        },
                        "legalFramework": {
                          "type": "string",
                          "nullable": true
                        },
                        "consumerDisclosure": {
                          "type": "boolean"
                        },
                        "expiresAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "scheduledSendAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "reminderPolicy": {
                          "nullable": true
                        },
                        "sentAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "completedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "declinedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "voidedAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "expiredAt": {
                          "type": "string",
                          "nullable": true,
                          "format": "date-time"
                        },
                        "metadata": {
                          "nullable": true
                        },
                        "senderUserId": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderName": {
                          "type": "string",
                          "nullable": true
                        },
                        "senderEmail": {
                          "type": "string",
                          "nullable": true
                        },
                        "detectedParties": {
                          "nullable": true
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updatedAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "id",
                        "organizationId",
                        "teamId",
                        "templateId",
                        "templateContentHash",
                        "status",
                        "detectionStatus",
                        "version",
                        "originalFilename",
                        "displayName",
                        "sourceFormat",
                        "contentHash",
                        "sizeBytes",
                        "deliveryMode",
                        "legalFramework",
                        "consumerDisclosure",
                        "expiresAt",
                        "scheduledSendAt",
                        "sentAt",
                        "completedAt",
                        "declinedAt",
                        "voidedAt",
                        "expiredAt",
                        "createdAt",
                        "updatedAt"
                      ]
                    },
                    "participants": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "orderIndex": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string",
                            "nullable": true
                          },
                          "title": {
                            "type": "string",
                            "nullable": true
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "signed",
                              "declined"
                            ]
                          },
                          "detectedPartyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "consentedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "signedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declinedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "declineReason": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastViewedAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "lastIpAddress": {
                            "type": "string",
                            "nullable": true
                          },
                          "lastUserAgent": {
                            "type": "string",
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "orderIndex",
                          "name",
                          "email",
                          "status",
                          "consentedAt",
                          "signedAt",
                          "declinedAt",
                          "declineReason",
                          "lastViewedAt",
                          "lastIpAddress",
                          "lastUserAgent",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    },
                    "fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "envelopeId": {
                            "type": "string"
                          },
                          "organizationId": {
                            "type": "string"
                          },
                          "participantId": {
                            "type": "string",
                            "nullable": true
                          },
                          "partyIndex": {
                            "type": "integer",
                            "nullable": true
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "signature",
                              "initials",
                              "date",
                              "text",
                              "checkbox"
                            ]
                          },
                          "page": {
                            "type": "integer"
                          },
                          "x": {
                            "type": "number"
                          },
                          "y": {
                            "type": "number"
                          },
                          "width": {
                            "type": "number"
                          },
                          "height": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string",
                            "nullable": true
                          },
                          "required": {
                            "type": "boolean"
                          },
                          "source": {
                            "type": "string",
                            "enum": [
                              "detected",
                              "manual",
                              "template"
                            ]
                          },
                          "prefillValue": {
                            "type": "string",
                            "nullable": true
                          },
                          "locked": {
                            "type": "boolean"
                          },
                          "autoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "proposedAutoSource": {
                            "type": "string",
                            "nullable": true,
                            "enum": [
                              "signed_date",
                              "participant_name",
                              "participant_email",
                              "participant_company",
                              "participant_title",
                              "sender_org_name",
                              null
                            ]
                          },
                          "value": {
                            "type": "string",
                            "nullable": true
                          },
                          "filledAt": {
                            "type": "string",
                            "nullable": true,
                            "format": "date-time"
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time"
                          }
                        },
                        "required": [
                          "id",
                          "envelopeId",
                          "organizationId",
                          "participantId",
                          "type",
                          "page",
                          "x",
                          "y",
                          "width",
                          "height",
                          "label",
                          "required",
                          "source",
                          "prefillValue",
                          "locked",
                          "autoSource",
                          "proposedAutoSource",
                          "value",
                          "filledAt",
                          "createdAt",
                          "updatedAt"
                        ]
                      }
                    }
                  },
                  "required": [
                    "envelope",
                    "participants",
                    "fields"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid review token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "402": {
            "description": "Out of credits (insufficient_credits): the organization has no credits left to send. Purchase more to continue.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "403": {
            "description": "Read-only token cannot send",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "The token's envelope no longer exists",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "409": {
            "description": "Double-send (invalid_transition), terminal state (terminal_state), or stale expectedVersion (conflict)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          },
          "422": {
            "description": "Validation failed: document not uploaded, disallowed stored content type, or zero participants",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {
                      "type": "object",
                      "additionalProperties": {
                        "nullable": true
                      }
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": [
          "system"
        ],
        "summary": "Liveness probe",
        "description": "Returns ok when the api process is serving requests. Does not touch the database or require auth.",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
