{ "openapi": "3.0.0", "info": { "title": "Unified Approvals API", "version": "1.0", "description": "The Unified Approvals Connector is the HTTP API for managing approvals on Workfront document versions. Use it to create approvals, build multi-stage workflows with conditional stage triggers, add and remind participants, record decisions, manage reusable approval templates, search across every approval the requesting user can see, and retrieve AI brand-review results captured by bot reviewers on a stage.\n\n## Authentication\n\nThe connector supports one authentication method:\n\n| Method | Header/Cookie | Use case |\n|--------|--------------|----------|\n| **Bearer** | `Authorization: Bearer ` | IMS Bearer token from Adobe IO / Developer Console |\n\nAll endpoints accept Bearer token auth.\n\n> **Note on auth error codes:** The AIO gateway performs credential pre-flight before routing to the service.\n> \n> | Condition | HTTP status | `error_code` |\n> |-----------|-------------|---------------|\n> | `Authorization` header absent | 403 | `403010` \u2014 \"Oauth token is missing.\" |\n> | `x-api-key` header absent (valid Bearer present) | 403 | `403000` \u2014 \"Api Key is missing.\" |\n> | Token present but invalid or expired | 401 | `401013` |\n> \n> The first two cases are caught by the gateway and never reach the service. The 401 case is handled by the service itself.\n\n## Asset Types\n\nEndpoints currently only support `DOCV` (Workfront document version) as the `assetType` path parameter.\n\n\n## Base URL\n\n`https://workfront.adobe.io/workfront-approvals/`\n\n## Endpoint Groups\n\n| Tag | Base path | Auth |\n|-----|-----------|------|\n| Approvals | `/api/v1/approvals` | Complex |\n| Grouped Approvals | `/api/v1/grouped-approvals` | Complex |\n| Templates | `/api/v1/templates` | Complex |\n| Bots | `/api/v1/bots` | Complex |\n| Bot Reviews | `/api/v1/bot-reviews` | Complex |\n", "contact": { "name": "", "email": "", "url": "" } }, "servers": [ { "url": "https://workfront.adobe.io/workfront-approvals/", "description": "Production" } ], "tags": [ { "name": "Approvals", "description": "Approval lifecycle: create, read, delete" }, { "name": "Stages", "description": "Stage management within an approval" }, { "name": "Decisions", "description": "Make and delete decisions on approval stages" }, { "name": "Participants", "description": "Add, remove, and remind participants" }, { "name": "Grouped Approvals", "description": "Create and manage grouped approvals - many document versions moving together through a shared, multi-stage approval workflow." }, { "name": "Templates", "description": "Approval template CRUD" }, { "name": "Bots", "description": "Retrieve Workfront bot users that are eligible to be added as reviewer participants on an approval. A bot reviewer is invoked automatically when its assigned stage becomes active." }, { "name": "Bot Reviews", "description": "AI brand review results from the Bot Registry" } ], "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "IMS Bearer token from Adobe IO / Developer Console." } }, "parameters": { "AssetType": { "name": "assetType", "in": "path", "required": true, "description": "The type of asset", "schema": { "type": "string", "enum": [ "DOCV" ], "example": "DOCV" } }, "AssetId": { "name": "assetId", "in": "path", "required": true, "description": "The ID of the asset", "schema": { "type": "string", "example": "673fc29b0006af515e33732d1ebdc39a" } }, "StageId": { "name": "stageId", "in": "path", "required": true, "description": "The ID of the approval stage", "schema": { "type": "string", "example": "design-review" } }, "ParticipantId": { "name": "participantId", "in": "path", "required": true, "description": "The ID of the participant", "schema": { "type": "string" } }, "ParticipantType": { "name": "participantType", "in": "path", "required": true, "description": "The type of participant", "schema": { "type": "string", "enum": [ "USER", "TEAMOB" ] } }, "TemplateId": { "name": "templateId", "in": "path", "required": true, "description": "The ID of the approval template", "schema": { "type": "string" } }, "ImsOrgId": { "name": "imsOrgId", "in": "path", "required": true, "description": "IMS Organization ID", "schema": { "type": "string" } }, "XRequestId": { "name": "x-request-id", "in": "header", "required": false, "description": "Unique identifier for request tracing. Auto-generated if not provided.", "schema": { "type": "string", "format": "uuid" } }, "XCorrelationId": { "name": "x-correlation-id", "in": "header", "required": false, "description": "Unique identifier for correlation across multiple service calls. Auto-generated if not provided.", "schema": { "type": "string" } }, "XApiKey": { "name": "x-api-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`client_id` of the Adobe Developer Console technical account. Identifies the calling integration to the AIO gateway." }, "XGwSubdomain": { "name": "x-gw-subdomain", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Workfront customer subdomain (e.g. `mycompany`). Must match the subdomain of the Workfront instance being accessed. Passing an incorrect or unrecognized subdomain will result in a `502 Bad Gateway` response from the AIO gateway." }, "WfCustomerId": { "name": "wf-customerid", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Workfront customer ID." }, "WfUserId": { "name": "wf-userid", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Workfront user ID of the acting user." }, "WfLane": { "name": "wf-lane", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "prod", "preview", "hub", "staging", "devtest" ] }, "description": "Workfront deployment lane." }, "GroupGuid": { "name": "groupGuid", "in": "path", "required": true, "description": "GUID of the grouped approval.", "example": "9f8b60820000462ecf66c409d1248fa9", "schema": { "type": "string", "example": "9f8b60820000462ecf66c409d1248fa9" } } }, "schemas": { "Approval": { "type": "object", "description": "An approval record for an asset", "properties": { "approvalGuid": { "type": "string", "description": "Unique identifier for the approval" }, "assetId": { "type": "string" }, "assetType": { "type": "string", "enum": [ "DOCV" ] }, "creatorId": { "type": "string" }, "realCreatorId": { "type": "string", "nullable": true, "description": "ID of the proxy user who actually created the approval. When the approval is created on behalf of another user (e.g. via a technical account or another proxying integration), this is the ID of the actual user making the call (the technical-account / proxy user). The companion `creatorId` field still reflects the user the action is attributed to. When no proxying takes place, this matches the companion field." }, "customerDomain": { "type": "string" }, "eauthTenantId": { "type": "string" }, "templateId": { "type": "string", "description": "ID of the template used to create this approval, if any." }, "productId": { "type": "string", "enum": [ "workfront" ], "default": "workfront", "example": "workfront", "description": "Identifier of the Workfront product the approval is associated with. Always `workfront` for the Unified Approvals Connector." }, "status": { "type": "string", "enum": [ "in review", "pending review", "approved", "approved with changes", "needs work", "reviewed", "withdrawn" ], "description": "Overall lifecycle status of the approval, derived from the rolled-up stage and participant decisions.\n\n- `in review` \u2014 At least one stage is active and waiting for decisions.\n- `pending review` \u2014 Approval exists but no stage has been activated yet.\n- `approved` \u2014 All required participants have approved.\n- `approved with changes` \u2014 All required participants have decided; at least one with changes.\n- `needs work` \u2014 At least one required participant has returned needs work.\n- `reviewed` \u2014 All reviewer-role participants have reviewed (no approver decisions required).\n- `withdrawn` \u2014 The approval has been retracted; no further actions are possible." }, "isLocked": { "type": "boolean", "description": "Whether the approval is currently locked. Mirrors the lock state of the active stage (a stage being manually locked sets the approval inactive)." }, "isLockOverridden": { "type": "boolean", "description": "Whether the approval lock was overridden by an admin." }, "decisionDate": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true }, "isApprovalActive": { "type": "boolean", "description": "Computed flag that indicates whether the version being accessed is still the document's active (head) version. Compares the document's `currentVersionID` against the `assetId` of the requested version: when they match, the version is current and `isApprovalActive` is `true`; when the document has been superseded by a newer upload, it is `false`." }, "isEsmAsset": { "type": "boolean", "description": "Whether the asset is an ESM (Experience Storage Manager) asset" }, "frameSyncStatus": { "type": "boolean", "nullable": true, "description": "Whether the Frame.io asset sync is complete" }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalStage" }, "description": "Ordered list of stages on this approval." }, "structure": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalStructure" }, "description": "Stage dependency graph. Each entry maps a `stageId` to its `parentIds`, defining the order in which stages activate." }, "paths": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalPath" }, "description": "Parallel approval paths on this approval. Each path has its own `stages` and `structure`, allowing independent stage sequences to run side by side. Empty for single-path approvals." }, "userInfo": { "type": "object", "description": "Contextual information about the authenticated user's relationship to this approval", "properties": { "isEditable": { "type": "boolean", "nullable": true, "description": "Whether the requesting user can make changes to this approval. Computed per request as `canEdit AND isActive AND hasLicenseAccess` \u2014 the user must have edit permission on the underlying asset, the approval must be in an active state, and the user must have a Workfront license tier that grants edit access. Used by write-path middleware to gate mutating requests and surfaced on every approval response so consumers can mirror the same gate in the UI." }, "hasLicenseAccess": { "type": "boolean", "nullable": true, "description": "Whether the requesting user's Workfront license tier grants the access needed to edit this approval. One of the inputs to `isEditable`." }, "activeDecision": { "type": "string", "nullable": true, "description": "The current user's most recent decision", "enum": [ "approved", "needs work", "approved with changes", "reviewed", null ] }, "action": { "type": "string", "nullable": true, "enum": [ "approve", "review", "revoke", null ], "description": "The next decision-related action the requesting user can take on this approval, derived from the user's `participantRole` and current `activeDecision`. Frontends typically render this as a button label.\n\n| Role / Decision | `userInfo.action` |\n|---|---|\n| `approver` (no decision yet) | `approve` |\n| `reviewer` (no decision yet) | `review` |\n| Decision = `approved` | `revoke` |\n| Decision = `needs work` | `approve` |\n| Decision = `reviewed` | `review` |" }, "availableDecisions": { "type": "object", "nullable": true, "description": "Map of decision key to display label for the current user", "additionalProperties": { "type": "string" } }, "currentUserMadeDecision": { "type": "boolean", "nullable": true } } } }, "example": { "approvalGuid": "6744feadafbbfb97a7c1c325", "assetId": "673fc29b0006af515e33732d1ebdc39a", "assetType": "DOCV", "creatorId": "15401B8A66C8F9CB0A49423C@13cc192466c8c9a949410f.e", "customerDomain": "mycompany", "status": "in review", "isLocked": false, "isApprovalActive": true, "isEsmAsset": true, "createdAt": "2024-11-25T22:48:13.598Z", "updatedAt": "2024-11-25T22:48:13.598Z", "stages": [ { "stageId": "design-review", "name": "Design Review", "status": "in review", "isLocked": false, "isActive": true, "isStarted": true, "isCompleted": false, "participants": [ { "participantId": "66cf5cec0002204507c8ce6d532dfc08", "participantType": "USER", "participantRole": "approver", "status": "notified", "createdAt": "2024-11-25T22:48:13.598Z", "updatedAt": "2024-11-25T22:48:13.598Z" } ], "createdAt": "2024-11-25T22:48:13.598Z", "updatedAt": "2024-11-25T22:48:13.598Z" } ], "structure": [ { "stageId": "design-review", "parentIds": [] } ], "paths": [], "userInfo": { "isEditable": true, "hasLicenseAccess": true, "activeDecision": null, "availableDecisions": { "approved": "Approve", "needs work": "Request changes" }, "currentUserMadeDecision": false } } }, "ApprovalStage": { "type": "object", "properties": { "stageId": { "type": "string", "example": "design-review", "description": "Identifier for this stage. Must be unique across all stages on the approval. Can be a short, human-readable slug (e.g. `design-review`)." }, "pathId": { "type": "string", "example": "design-path", "description": "ID of the path this stage belongs to, when the stage is part of a multi-path approval." }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "not started", "pending review", "in review", "approved", "approved with changes", "needs work", "reviewed" ], "description": "Lifecycle status of the stage.\n\n- `not started` \u2014 Stage has not yet been triggered to `isActive`. Set on creation and remains until the stage's activation trigger fires (typically when its parent stages complete).\n- `pending review` \u2014 Stage is active and awaiting participant decisions.\n- `in review` \u2014 Stage is active and at least one participant has not yet decided.\n- `approved` \u2014 All required participants on this stage have approved.\n- `approved with changes` \u2014 All required participants have decided, at least one has chosen `approved with changes`, and the rest have chosen `approved` or `approved with changes`. If any required participant has returned `needs work`, the stage rolls up to `needs work` instead.\n- `needs work` \u2014 At least one required participant has responded with `needs work`. `needs work` outranks `approved` and `approved with changes`, so the stage rolls up to this status whenever any required participant has returned `needs work`.\n- `reviewed` \u2014 All reviewer participants have reviewed." }, "deadlineDate": { "type": "string", "format": "date-time", "nullable": true }, "deadlineBusinessDays": { "type": "number", "nullable": true }, "deadlineTime": { "type": "string", "nullable": true, "example": "17:00", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Deadline time of day in 24-hour `HH:MM` format (e.g. `\"17:00\"`)." }, "deadlineTimeOfDay": { "type": "object", "nullable": true, "description": "Time-of-day component of the stage deadline. An object with two numeric properties \u2014 `hours` (0\u201323) and `minutes` (0\u201359) \u2014 that, paired with the date derived from `deadlineBusinessDays`, pins the deadline to a specific moment. Set to `null` when no time-of-day is configured.\n\nExample: `{ \"hours\": 17, \"minutes\": 0 }` for 5:00 PM.", "properties": { "hours": { "type": "number", "minimum": 0, "maximum": 23, "description": "Hour of the day (0\u201323)." }, "minutes": { "type": "number", "minimum": 0, "maximum": 59, "description": "Minute of the hour (0\u201359)." } }, "example": { "hours": 17, "minutes": 0 } }, "decisionDate": { "type": "string", "format": "date-time" }, "isLocked": { "type": "boolean", "description": "Stage has been manually locked (set inactive)." }, "isActive": { "type": "boolean", "description": "Stage is currently accepting decisions." }, "isLockOverridden": { "type": "boolean", "description": "Stage lock was overridden by an admin." }, "isStarted": { "type": "boolean", "description": "Stage has been started at least once." }, "isCompleted": { "type": "boolean", "description": "Stage has reached a terminal state." }, "stageMetadata": { "type": "object", "additionalProperties": true, "description": "Almost entirely a Frame.io integration artifact \u2014 when a Frame.io share is created for the stage it holds the generated review link and comments link. Defaults to `{}` if no Frame share was created (for example, on non-ESM or non-Frame assets).", "default": {} }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalStageParticipant" } }, "config": { "$ref": "#/components/schemas/ApprovalStageConfig" }, "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/StageTrigger" } }, "parentIds": { "type": "array", "description": "IDs of stages that must complete before this stage activates.", "items": { "type": "string" } }, "customMessage": { "type": "string", "maxLength": 500, "description": "Optional message sent to participants when this stage is activated" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "ApprovalStageParticipant": { "type": "object", "properties": { "participantId": { "type": "string" }, "participantType": { "type": "string", "enum": [ "USER", "TEAMOB" ] }, "participantRole": { "type": "string", "enum": [ "approver", "reviewer" ], "description": "Role this participant plays on the stage.\n\n- `approver` \u2014 Has a binding vote; their decision directly affects stage and approval status.\n- `reviewer` \u2014 Non-binding; can mark reviewed but does not block approval progression.\n\nThe role, combined with the participant's current decision, also drives the `userInfo.action` value on every approval response \u2014 see [`Approval.userInfo.action`](#section/Schemas/Approval) for the role/decision \u2192 action mapping." }, "participantMetadata": { "$ref": "#/components/schemas/ParticipantMetadata" }, "requesterId": { "type": "string", "description": "ID of the user who added this participant" }, "realRequesterId": { "type": "string", "nullable": true, "description": "ID of the proxy user who actually added this participant to the stage. When the participant is added on behalf of another user (e.g. via a technical account or another proxying integration), this is the ID of the actual user making the call (the technical-account / proxy user). The companion `requesterId` field still reflects the user the action is attributed to. When no proxying takes place, this matches the companion field." }, "status": { "type": "string", "enum": [ "not started", "notified", "opened", "commented", "approved", "approved with changes", "needs work", "reviewed" ], "description": "Lifecycle status of this participant on the stage.\n\n- `notified` \u2014 Participant has been sent a notification but has not yet opened or decided.\n- `opened` \u2014 Participant has opened the review but has not yet decided.\n- `commented` \u2014 Participant has left a comment but has not made a final decision.\n- `approved` \u2014 Participant has approved.\n- `approved with changes` \u2014 Participant has approved with changes requested.\n- `needs work` \u2014 Participant returned needs work.\n- `reviewed` \u2014 Participant has marked the review complete (reviewer role only).\n- `not started` \u2014 Participant is on a stage that has not yet become active; no notification has been sent." }, "activities": { "type": "array", "items": { "$ref": "#/components/schemas/ParticipantActivity" } }, "firstDecisionAt": { "type": "string", "format": "date-time" }, "decisionDate": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "wfMetadata": { "$ref": "#/components/schemas/ParticipantWfMetadata" } } }, "ParticipantActivity": { "type": "object", "properties": { "userId": { "type": "string" }, "realUserId": { "type": "string", "description": "ID of the proxy user who actually performed the activity. When the activity is performed on behalf of another user (e.g. via a technical account or another proxying integration), this is the ID of the actual user making the call (the technical-account / proxy user). The companion `userId` field still reflects the user the action is attributed to. When no proxying takes place, this matches the companion field." }, "decision": { "type": "string", "description": "Decision made (e.g. 'approved', 'needs work', 'approved with changes', 'reviewed')", "enum": [ "approved", "needs work", "approved with changes", "reviewed" ] }, "decisionDate": { "type": "string", "format": "date-time" }, "openedAt": { "type": "string", "format": "date-time" }, "notifiedAt": { "type": "string", "format": "date-time" }, "userName": { "type": "string" } } }, "ApprovalStageConfig": { "type": "object", "properties": { "autoLockEnabled": { "type": "boolean", "description": "Automatically lock the stage when all participants have decided" }, "decisionRules": { "type": "string", "nullable": true, "enum": [ "onlyOneDecisionRequired" ], "description": "Override rule for when the stage is considered decided. `onlyOneDecisionRequired` marks the stage complete when any one participant decides." } } }, "StageTrigger": { "type": "object", "required": [ "type", "when" ], "description": "Defines when and how a stage is automatically activated", "properties": { "type": { "type": "string", "enum": [ "activation" ], "description": "Type of trigger action" }, "when": { "type": "string", "enum": [ "onCreate", "onStagesComplete" ], "description": "`onCreate` activates the stage immediately when the approval is created. `onStagesComplete` activates after specified parent stages complete." }, "parameters": { "type": "object", "properties": { "stages": { "type": "array", "items": { "type": "string" }, "description": "Stage IDs that must complete to fire this trigger (used with `onStagesComplete`)" }, "allowedDecisions": { "type": "array", "items": { "type": "string", "enum": [ "approved", "approved with changes", "reviewed" ] }, "description": "Decisions that count as 'complete' for this trigger" } } } }, "example": { "type": "activation", "when": "onStagesComplete", "parameters": { "stages": [ "design-review" ], "allowedDecisions": [ "approved", "approved with changes" ] } } }, "ApprovalStructure": { "type": "object", "description": "Represents one node in the stage dependency graph", "properties": { "stageId": { "type": "string", "example": "design-review", "description": "Identifier of the stage this structure node represents. Matches the `stageId` on one of the approval's `stages[]` entries; must be unique across all stages on the approval (e.g. `design-review`)." }, "parentIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of stages that must complete before this stage activates." }, "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/StageTrigger" } } } }, "ApprovalPath": { "type": "object", "description": "One parallel path on an approval that has multiple independent stage sequences. Each path carries its own `stages` and `structure`, scoped the same way as the top-level fields of the same name on `Approval`.", "properties": { "pathId": { "type": "string", "example": "design-path", "description": "Identifier for this path. Must be unique across all paths on the approval." }, "name": { "type": "string", "example": "Design Path", "description": "Display name for this path." }, "status": { "type": "string", "enum": [ "not started", "pending review", "in review", "approved", "approved with changes", "needs work", "reviewed" ], "description": "Rollup status of this path, derived the same way as the approval-level `status` but scoped to this path's stages." }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalStage" }, "description": "Ordered list of stages on this path." }, "structure": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalStructure" }, "description": "Stage dependency graph for this path. Each entry maps a `stageId` to its `parentIds`, defining the order in which this path's stages activate." } } }, "StageBody": { "type": "object", "required": [ "participants" ], "description": "Stage definition used when creating or updating an approval", "properties": { "stageId": { "type": "string", "description": "Optional client-assigned identifier for this stage, unique within the approval. If omitted, the server generates one. Use human-readable values (e.g. \"legal-review\") when referencing this stage in another stage's parentIds for sequential approval flows." }, "name": { "type": "string" }, "deadlineDate": { "type": "string", "format": "date-time", "nullable": true }, "deadlineBusinessDays": { "type": "number", "nullable": true }, "deadlineTime": { "type": "string", "nullable": true, "example": "17:00", "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "description": "Deadline time of day in 24-hour `HH:MM` format (e.g. `\"17:00\"`)." }, "stageMetadata": { "type": "object", "additionalProperties": true, "description": "Almost entirely a Frame.io integration artifact \u2014 when a Frame.io share is created for the stage it holds the generated review link and comments link. Defaults to `{}` if no Frame share was created (for example, on non-ESM or non-Frame assets).", "default": {} }, "participants": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "participantId", "participantType", "participantRole" ], "properties": { "participantId": { "type": "string" }, "participantType": { "type": "string", "enum": [ "USER", "TEAMOB" ] }, "participantRole": { "type": "string", "enum": [ "approver", "reviewer" ], "description": "Role this participant plays on the stage.\n\n- `approver` \u2014 Has a binding vote; their decision directly affects stage and approval status.\n- `reviewer` \u2014 Non-binding; can mark reviewed but does not block approval progression.\n\nThe role, combined with the participant's current decision, also drives the `userInfo.action` value on every approval response \u2014 see [`Approval.userInfo.action`](#section/Schemas/Approval) for the role/decision \u2192 action mapping." }, "participantMetadata": { "$ref": "#/components/schemas/ParticipantMetadata" } } } }, "config": { "$ref": "#/components/schemas/ApprovalStageConfig" }, "parentIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of stages that must complete before this stage activates." }, "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/StageTrigger" } }, "customMessage": { "type": "string", "maxLength": 500, "description": "Optional message for participants when this stage activates" }, "pathId": { "type": "string", "example": "design-path", "description": "ID of the path this stage belongs to, when the stage is part of a multi-path approval." } } }, "ApprovalPathCreate": { "type": "object", "description": "One parallel path used when creating a multi-path approval.", "required": [ "stages" ], "properties": { "pathId": { "type": "string", "example": "design-path", "description": "Identifier for this path. Must be unique across all paths on the approval." }, "name": { "type": "string", "example": "Design Path", "description": "Display name for this path." }, "stages": { "type": "array", "minItems": 1, "description": "Stage definitions for this path.", "items": { "$ref": "#/components/schemas/StageBody" } } } }, "ApprovalPathUpdate": { "type": "object", "description": "One parallel path used when replacing all stages on an existing multi-path approval.", "required": [ "stages" ], "properties": { "pathId": { "type": "string", "example": "design-path", "description": "Identifier for this path. Must be unique across all paths on the approval." }, "name": { "type": "string", "example": "Design Path", "description": "Display name for this path." }, "stages": { "type": "array", "minItems": 1, "description": "Replacement stage definitions for this path.", "items": { "$ref": "#/components/schemas/StageBody" } } } }, "ParticipantBody": { "type": "object", "description": "Participant definition used in request bodies", "properties": { "stageId": { "type": "string", "example": "design-review", "description": "ID of an existing stage on the approval to attach this participant to (e.g. `design-review`)." }, "participantId": { "type": "string" }, "participantType": { "type": "string", "enum": [ "USER", "TEAMOB" ] }, "participantRole": { "type": "string", "enum": [ "approver", "reviewer" ], "description": "Role this participant plays on the stage.\n\n- `approver` \u2014 Has a binding vote; their decision directly affects stage and approval status.\n- `reviewer` \u2014 Non-binding; can mark reviewed but does not block approval progression.\n\nThe role, combined with the participant's current decision, also drives the `userInfo.action` value on every approval response \u2014 see [`Approval.userInfo.action`](#section/Schemas/Approval) for the role/decision \u2192 action mapping." }, "participantMetadata": { "$ref": "#/components/schemas/ParticipantMetadata" } } }, "Template": { "type": "object", "properties": { "templateId": { "type": "string" }, "name": { "type": "string" }, "assetType": { "type": "string", "enum": [ "DOCV" ] }, "timeframeEstimate": { "type": "integer", "description": "Computed timeframe estimate, in business days, derived from the sum of each stage's `deadlineBusinessDays` value. Read-only.", "readOnly": true }, "usageCount": { "type": "integer" }, "lastUsedOnDate": { "type": "string", "format": "date-time" }, "creatorId": { "type": "string" }, "createdBy": { "type": "string", "description": "Display name of the creator" }, "createdByAvatarDate": { "type": "string", "nullable": true }, "createdByLinkTo": { "type": "string", "description": "Profile URL path, e.g. `/USER/{id}/detail`" }, "createdByMetadata": { "type": "object", "additionalProperties": true }, "customerId": { "type": "string" }, "companyId": { "type": "string", "nullable": true }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateStage" } }, "structure": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalStructure" }, "description": "Workflow structure defining stage ordering and trigger dependencies." }, "paths": { "type": "array", "items": { "$ref": "#/components/schemas/TemplatePath" }, "description": "Parallel paths on this template. Each path has its own `stages` and `structure`, allowing independent stage sequences to run side by side. Empty for single-path templates." }, "sharedWith": { "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "accessLevel": { "type": "string", "enum": [ "EDIT_ACCESS", "VIEW_ACCESS" ] } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "timeframe": { "type": "integer", "deprecated": true, "description": "**Deprecated.** Use `timeframeEstimate` instead. Previously used to store the expected duration of the approval in days." } }, "example": { "templateId": "template-id", "name": "Test Template", "assetType": "DOCV", "creatorId": "user-id", "customerId": "customer-id", "stages": [ { "stageId": "stage-1", "name": "Stage 1", "deadlineBusinessDays": 3, "deadlineTimeOfDay": { "hours": 17, "minutes": 0 }, "participants": [ { "participantId": "user-123", "participantType": "USER", "participantRole": "approver", "participantMetadata": {} } ] }, { "stageId": "stage-2", "name": "Stage 2", "deadlineBusinessDays": 2, "deadlineTimeOfDay": { "hours": 12, "minutes": 30 }, "participants": [] } ], "structure": [ { "stageId": "stage-1", "parentIds": [], "triggers": [ { "type": "activation", "when": "onCreate" } ] }, { "stageId": "stage-2", "parentIds": [ "stage-1" ], "triggers": [ { "type": "activation", "when": "onStagesComplete", "parameters": { "stages": [ "stage-1" ], "allowedDecisions": [ "approved" ] } } ] } ], "paths": [], "usageCount": 0, "createdAt": "2026-01-15T17:00:00.000Z", "updatedAt": "2026-01-15T17:00:00.000Z" } }, "TemplateStage": { "type": "object", "properties": { "stageId": { "type": "string", "example": "design-review", "description": "Identifier for this template stage. Must be unique across all stages within the template (e.g. `design-review`)." }, "name": { "type": "string" }, "deadlineBusinessDays": { "type": "integer" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateStageParticipant" } }, "deadlineTimeOfDay": { "type": "object", "nullable": true, "description": "Time-of-day component of the stage deadline. An object with two numeric properties \u2014 `hours` (0\u201323) and `minutes` (0\u201359) \u2014 that, paired with the date derived from `deadlineBusinessDays`, pins the deadline to a specific moment. Set to `null` when no time-of-day is configured.\n\nExample: `{ \"hours\": 17, \"minutes\": 0 }` for 5:00 PM.", "properties": { "hours": { "type": "number", "minimum": 0, "maximum": 23, "description": "Hour of the day (0\u201323)." }, "minutes": { "type": "number", "minimum": 0, "maximum": 59, "description": "Minute of the hour (0\u201359)." } }, "example": { "hours": 17, "minutes": 0 } } } }, "TemplatePath": { "type": "object", "description": "One parallel path on a template that has multiple independent stage sequences. Each path carries its own `stages` and `structure`, scoped the same way as the top-level fields of the same name on `Template`.", "properties": { "pathId": { "type": "string", "example": "design-path", "description": "Identifier for this path. Must be unique across all paths on the template." }, "name": { "type": "string", "example": "Design Path", "description": "Display name for this path." }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateStage" }, "description": "Stages on this path." }, "structure": { "type": "array", "items": { "$ref": "#/components/schemas/ApprovalStructure" }, "description": "Stage dependency graph for this path. Each entry maps a `stageId` to its `parentIds`, defining the order in which this path's stages activate." } } }, "TemplateStageParticipant": { "type": "object", "properties": { "participantId": { "type": "string" }, "participantType": { "type": "string", "enum": [ "USER", "TEAMOB" ], "description": "Type of participant.\n\n- `USER` \u2014 Individual Workfront user (or AI bot user).\n- `TEAMOB` \u2014 Workfront team." }, "participantRole": { "type": "string", "enum": [ "approver", "reviewer" ], "description": "Role this participant plays on the stage.\n\n- `approver` \u2014 Has a binding vote; their decision directly affects stage and approval status.\n- `reviewer` \u2014 Non-binding; can mark reviewed but does not block approval progression.\n\nThe role, combined with the participant's current decision, also drives the `userInfo.action` value on every approval response \u2014 see [`Approval.userInfo.action`](#section/Schemas/Approval) for the role/decision \u2192 action mapping." }, "participantMetadata": { "$ref": "#/components/schemas/ParticipantMetadata" }, "name": { "type": "string" }, "emailAddr": { "type": "string", "nullable": true, "description": "User's email address. Populated only when `participantType` is `USER`." }, "licenseType": { "type": "string", "nullable": true, "description": "Workfront license tier of the user. Populated only when `participantType` is `USER`." }, "eauthUserID": { "type": "string", "nullable": true, "description": "IMS-bound external authentication user ID. Populated only when `participantType` is `USER`." }, "avatarDate": { "type": "string", "nullable": true, "description": "Avatar version timestamp used to bust the avatar image cache. Populated only when `participantType` is `USER`." }, "linkTo": { "type": "string", "nullable": true }, "teamMembers": { "type": "array", "description": "Members of the team. Populated only when `participantType` is `TEAMOB`.", "items": { "$ref": "#/components/schemas/TeamMember" } } } }, "TemplateBody": { "type": "object", "description": "Request body for creating or updating a template.", "required": [ "name", "stages" ], "properties": { "name": { "type": "string", "description": "Display name of the template." }, "assetType": { "type": "string", "enum": [ "DOCV" ], "description": "Asset type the template applies to." }, "companyId": { "type": "string", "nullable": true }, "stages": { "type": "array", "minItems": 1, "description": "Stages that make up the template, in graph form.", "items": { "$ref": "#/components/schemas/TemplateStageBody" } }, "paths": { "type": "array", "description": "Parallel paths that make up the template, each with its own stages in graph form. Omit for single-path templates.", "items": { "$ref": "#/components/schemas/TemplatePathBody" } }, "sharedWith": { "type": "array", "description": "Optional list of users the template is shared with.", "items": { "type": "object", "properties": { "userId": { "type": "string" }, "accessLevel": { "type": "string", "enum": [ "EDIT_ACCESS", "VIEW_ACCESS" ] } } } } }, "example": { "name": "Test Template", "stages": [ { "stageId": "stage-1", "name": "Stage 1", "parentIds": [], "triggers": [ { "type": "activation", "when": "onCreate" } ], "deadlineBusinessDays": 3, "deadlineTimeOfDay": { "hours": 17, "minutes": 0 }, "participants": [ { "participantId": "user-123", "participantType": "USER", "participantRole": "approver", "participantMetadata": {} } ] }, { "stageId": "stage-2", "name": "Stage 2", "parentIds": [ "stage-1" ], "triggers": [ { "type": "activation", "when": "onStagesComplete", "parameters": { "stages": [ "stage-1" ], "allowedDecisions": [ "approved" ] } } ], "deadlineBusinessDays": 2, "deadlineTimeOfDay": { "hours": 12, "minutes": 30 }, "participants": [ { "participantId": "user-456", "participantType": "USER", "participantRole": "reviewer", "participantMetadata": {} } ] } ], "paths": [] } }, "TemplateStageBody": { "type": "object", "description": "A single stage in graph form, used when creating or updating a template (either directly under `stages`, or nested under one of `paths[].stages`).", "required": [ "stageId", "name" ], "properties": { "stageId": { "type": "string", "example": "design-review", "description": "Identifier for this template stage. Must be unique across all stages within the template (e.g. `design-review`)." }, "name": { "type": "string" }, "parentIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of stages that must complete before this stage activates." }, "triggers": { "type": "array", "description": "Activation triggers for the stage. Each entry defines when and how the stage becomes active relative to other stages on the template.", "items": { "$ref": "#/components/schemas/StageTrigger" } }, "deadlineBusinessDays": { "type": "integer", "description": "Number of business days from stage activation to its deadline." }, "deadlineTimeOfDay": { "type": "object", "nullable": true, "description": "Time-of-day component of the stage deadline. An object with two numeric properties — `hours` (0–23) and `minutes` (0–59) — that, paired with the date derived from `deadlineBusinessDays`, pins the deadline to a specific moment. Set to `null` when no time-of-day is configured.\n\nExample: `{ \"hours\": 17, \"minutes\": 0 }` for 5:00 PM.", "properties": { "hours": { "type": "number", "minimum": 0, "maximum": 23, "description": "Hour of the day (0–23)." }, "minutes": { "type": "number", "minimum": 0, "maximum": 59, "description": "Minute of the hour (0–59)." } }, "example": { "hours": 17, "minutes": 0 } }, "participants": { "type": "array", "items": { "type": "object", "required": [ "participantId", "participantType", "participantRole" ], "properties": { "participantId": { "type": "string" }, "participantType": { "type": "string", "enum": [ "USER", "TEAMOB" ], "description": "Type of participant.\n\n- `USER` — Individual Workfront user (or AI bot user).\n- `TEAMOB` — Workfront team." }, "participantRole": { "type": "string", "enum": [ "approver", "reviewer" ], "description": "Role this participant plays on the stage.\n\n- `approver` — Has a binding vote; their decision directly affects stage and approval status.\n- `reviewer` — Non-binding; can mark reviewed but does not block approval progression." }, "participantMetadata": { "$ref": "#/components/schemas/ParticipantMetadata" } } } } } }, "TemplatePathBody": { "type": "object", "description": "One parallel path in graph form, used when creating or updating a multi-path template.", "required": [ "pathId", "stages" ], "properties": { "pathId": { "type": "string", "example": "design-path", "description": "Identifier for this path. Must be unique across all paths on the template." }, "name": { "type": "string", "example": "Design Path", "description": "Display name for this path." }, "stages": { "type": "array", "minItems": 1, "description": "Stages that make up this path, in graph form.", "items": { "$ref": "#/components/schemas/TemplateStageBody" } } } }, "ErrorResponse": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "message": { "type": "string" }, "errors": { "type": "array", "description": "Validation error details (present on 400 FST_ERR_VALIDATION errors)", "items": { "type": "object" } }, "response": { "type": "object", "description": "Upstream service error response, if applicable" } } }, "GuidelineCheckResult": { "type": "object", "properties": { "guideline": { "type": "string", "description": "Guideline identifier." }, "guidelineAttribute": { "type": "string", "description": "Attribute of the guideline being evaluated." }, "guidelineTrait": { "type": "string", "description": "Specific trait under the attribute." }, "guidelineTraitType": { "type": "string", "description": "Trait type (e.g. critical, non-critical)." }, "passed": { "type": "boolean" }, "score": { "type": "number" }, "reason": { "type": "string", "description": "Explanation for the pass/fail outcome." } } }, "ParticipantUserMetadata": { "type": "object", "description": "Metadata fields populated when `participantType` is `USER`.", "additionalProperties": true, "properties": { "isBot": { "type": "boolean", "description": "Whether this user is an AI bot participant." }, "participantIdType": { "type": "string", "enum": [ "wf_guid", "ims", "email" ], "description": "How `participantId` is typed:\n- `wf_guid` \u2014 non-ESM assets.\n- `ims` \u2014 ESM assets with an IMS `eauthUserID`.\n- `email` \u2014 ESM assets without an IMS `eauthUserID`." }, "wfUserId": { "type": "string", "description": "The Workfront internal user ID (32-character hex)." }, "emailAddr": { "type": "string", "description": "User's email address. Omitted when not available from Workfront." } } }, "ParticipantTeamMetadata": { "type": "object", "description": "Metadata fields populated when `participantType` is `TEAMOB`.", "additionalProperties": true, "properties": { "isBot": { "type": "boolean", "description": "Whether this team is an AI bot participant." } } }, "ParticipantMetadata": { "type": "object", "additionalProperties": true, "description": "Free-form metadata about the participant. The shape varies by `participantType`:\n\n**`USER` participants**\n```\n{\n \"isBot\": boolean,\n \"participantIdType\": \"wf_guid\" | \"ims\" | \"email\",\n \"wfUserId\": \"string\",\n \"emailAddr\": \"string\" // omitted when not available\n}\n```\n\n**`TEAMOB` (team) participants**\n```\n{\n \"isBot\": boolean\n}\n```\n\nSee `ParticipantUserMetadata` and `ParticipantTeamMetadata` for the typed shapes. Additional context-specific properties may be present; consumers should treat unknown keys as informational.", "oneOf": [ { "$ref": "#/components/schemas/ParticipantUserMetadata" }, { "$ref": "#/components/schemas/ParticipantTeamMetadata" } ] }, "TeamMember": { "type": "object", "description": "Workfront user that is a member of a team participant.", "properties": { "ID": { "type": "string", "description": "Workfront user ID." }, "name": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "emailAddr": { "type": "string", "nullable": true }, "avatarDate": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" } } }, "ParticipantUserWfMetadata": { "type": "object", "description": "Workfront-derived enrichment fields populated when `participantType` is `USER`.", "properties": { "name": { "type": "string", "description": "Display name of the user." }, "emailAddr": { "type": "string", "nullable": true, "description": "User's email address." }, "licenseType": { "type": "string", "nullable": true, "description": "Workfront license tier." }, "wfUserId": { "type": "string", "description": "Workfront internal user ID." }, "eauthUserID": { "type": "string", "nullable": true, "description": "IMS-bound external authentication user ID." }, "avatarDate": { "type": "string", "nullable": true, "description": "Avatar version timestamp used to bust avatar cache." } } }, "ParticipantTeamWfMetadata": { "type": "object", "description": "Workfront-derived enrichment fields populated when `participantType` is `TEAMOB`.", "properties": { "name": { "type": "string", "description": "Team display name." }, "avatarDate": { "type": "string", "nullable": true }, "teamMembers": { "type": "array", "description": "Members of the team.", "items": { "$ref": "#/components/schemas/TeamMember" } } } }, "ParticipantWfMetadata": { "type": "object", "additionalProperties": true, "description": "Workfront-derived enrichment fields for the participant. The shape depends on `participantType` \u2014 see `ParticipantUserWfMetadata` and `ParticipantTeamWfMetadata`.", "oneOf": [ { "$ref": "#/components/schemas/ParticipantUserWfMetadata" }, { "$ref": "#/components/schemas/ParticipantTeamWfMetadata" } ] }, "ApprovalDeletedResponse": { "type": "object", "description": "Returned when removing the last remaining participant on the approval causes the approval itself to be deleted. The body contains user-context flags only (no approval payload), with `deleted: true` to signal the cascading delete.", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean", "enum": [ true ], "description": "Always `true` on this response shape; the approval no longer exists." }, "isApprovalActive": { "type": "boolean", "description": "Whether the version being accessed is the document's active head version." }, "userInfo": { "type": "object", "properties": { "isEditable": { "type": "boolean", "nullable": true }, "hasLicenseAccess": { "type": "boolean", "nullable": true } } }, "frameSyncStatus": { "type": "string", "nullable": true }, "isEsmAsset": { "type": "boolean" } } }, "BotReviewFieldResult": { "type": "object", "properties": { "fieldSummary": { "type": "object", "properties": { "totalGuidelineTraitsChecked": { "type": "integer", "description": "Total guideline traits evaluated." }, "totalGuidelineTraitsPassed": { "type": "integer", "description": "Number of guideline traits that passed." }, "totalCriticalGuidelineTraitsChecked": { "type": "integer", "description": "Total critical guideline traits evaluated." }, "totalCriticalGuidelineTraitsPassed": { "type": "integer", "description": "Number of critical guideline traits that passed." }, "totalNonCriticalGuidelineTraitsChecked": { "type": "integer", "description": "Total non-critical guideline traits evaluated." }, "totalNonCriticalGuidelineTraitsPassed": { "type": "integer", "description": "Number of non-critical guideline traits that passed." } } }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/GuidelineCheckResult" } } } }, "BotReviewValidationResult": { "type": "object", "properties": { "validationSummary": { "type": "object", "description": "Aggregate result across all checks for the asset (or page).", "properties": { "passed": { "type": "boolean", "description": "Whether the asset passed validation overall." }, "imageGuidelines": { "type": "object", "description": "Aggregate guideline-trait counts plus an overall pass flag and score.", "properties": { "totalGuidelineTraitsChecked": { "type": "integer", "description": "Total guideline traits evaluated." }, "totalGuidelineTraitsPassed": { "type": "integer", "description": "Number of guideline traits that passed." }, "totalCriticalGuidelineTraitsChecked": { "type": "integer", "description": "Total critical guideline traits evaluated." }, "totalCriticalGuidelineTraitsPassed": { "type": "integer", "description": "Number of critical guideline traits that passed." }, "totalNonCriticalGuidelineTraitsChecked": { "type": "integer", "description": "Total non-critical guideline traits evaluated." }, "totalNonCriticalGuidelineTraitsPassed": { "type": "integer", "description": "Number of non-critical guideline traits that passed." }, "passed": { "type": "boolean" }, "score": { "type": "number" } } } } }, "fieldResults": { "type": "object", "description": "Per-field validation results, keyed by field name.", "additionalProperties": { "$ref": "#/components/schemas/BotReviewFieldResult" } } } }, "BotReview": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique review ID." }, "botId": { "type": "string", "description": "ID of the bot that produced this review." }, "brandId": { "type": "string", "description": "ID of the brand associated with the bot." }, "categoryId": { "type": "string", "nullable": true, "description": "Category for this review, if any." }, "validationTypes": { "type": "array", "items": { "type": "string" }, "description": "Validation types applied to this asset." }, "parentObjType": { "type": "string", "description": "Type of the parent object (e.g. `DOCU`)." }, "parentObjId": { "type": "string", "description": "ID of the parent object." }, "objType": { "type": "string", "description": "Type of the object reviewed (e.g. `DOCV`)." }, "objId": { "type": "string", "description": "ID of the object reviewed." }, "stageId": { "type": "string", "description": "ID of the approval stage this review is attached to." }, "pdfDownloadUrl": { "type": "string", "nullable": true, "description": "Pre-signed URL to download a PDF of the review, when available." }, "bot": { "type": "string", "description": "Display name of the bot at the time of review." }, "status": { "type": "string", "description": "Lifecycle status of the review (e.g. completed, failed)." }, "failureCode": { "type": "string", "description": "Machine-readable failure code when the review could not complete." }, "failureMessage": { "type": "string", "description": "Human-readable failure message paired with `failureCode`." }, "createdAt": { "type": "string", "format": "date-time" }, "validationResult": { "$ref": "#/components/schemas/BotReviewValidationResult" }, "multiPageValidationResult": { "type": "object", "description": "Per-page validation results for multi-page assets, keyed by page identifier. Each value follows the same shape as `validationResult`.", "additionalProperties": { "$ref": "#/components/schemas/BotReviewValidationResult" } } } }, "PartialApproval": { "type": "object", "description": "Returned by GET approval when no approval exists for the asset yet. Contains only the contextual fields that can be computed without an approval record.", "properties": { "isApprovalActive": { "type": "boolean", "description": "Always `true` in this partial shape \u2014 no active approval exists but the asset is eligible." }, "isEsmAsset": { "type": "boolean", "description": "Whether the asset is stored in external storage (ESM)." }, "frameSyncStatus": { "type": "string", "nullable": true, "description": "Frame sync status for the asset. `null` when no approval exists." }, "userInfo": { "type": "object", "properties": { "isEditable": { "type": "boolean", "description": "Whether the requesting user can create or modify an approval for this asset." }, "hasLicenseAccess": { "type": "boolean", "description": "Whether the requesting user's license tier grants edit access." } } } }, "example": { "isApprovalActive": true, "isEsmAsset": false, "frameSyncStatus": null, "userInfo": { "isEditable": true, "hasLicenseAccess": true } } }, "EmptyApproval": { "type": "object", "description": "Returned within the bulk lookup `approvals` array for asset IDs that have no approval. Contains only `assetId` and `frameSyncStatus`.", "properties": { "assetId": { "type": "string", "description": "The asset ID that was queried." }, "frameSyncStatus": { "type": "string", "nullable": true, "description": "Always `null` when no approval exists." } }, "example": { "assetId": "69b1ea8500006ebab6a5eb8e622d4b09", "frameSyncStatus": null } }, "TemplateDeleteResult": { "type": "object", "description": "Result of a bulk template delete.", "properties": { "deleted": { "type": "array", "items": { "type": "string" }, "description": "Template IDs that were successfully deleted." }, "failed": { "type": "array", "items": { "type": "string" }, "description": "Template IDs that were not deleted (e.g. a permission denial or an AAS delete failure)." }, "errors": { "type": "array", "description": "Per-ID error details for IDs not deleted due to an upstream problem (e.g. an AuthZ failure) — distinct from a permission denial in `failed`.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "reason": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "GroupedApprovalParticipantInput": { "type": "object", "required": [ "id", "role" ], "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$", "description": "Workfront user or team ID." }, "type": { "type": "string", "enum": [ "USER", "TEAMOB" ], "description": "Participant type. Defaults to USER." }, "role": { "type": "string", "description": "Participant role on the stage (e.g. approver, reviewer)." }, "participantMetadata": { "type": "object", "description": "Optional free-form key/value metadata for this participant.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } } }, "GroupedApprovalStageInput": { "type": "object", "required": [ "stageId", "name", "parentIds", "participants" ], "properties": { "stageId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Client-assigned stage identifier, unique across all paths in the approval (not just within its own path)." }, "name": { "type": "string", "maxLength": 255, "description": "Display name of the stage." }, "parentIds": { "type": "array", "items": { "type": "string" }, "description": "stageIds this stage depends on. Empty for a first stage; a stage activates once its parents complete." }, "participants": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/GroupedApprovalParticipantInput" }, "description": "Approvers/reviewers on this stage." }, "deadlineDate": { "type": "string", "format": "date-time", "description": "Absolute deadline for the stage." }, "deadlineBusinessDays": { "type": "number", "description": "Deadline expressed as a number of business days from activation." }, "deadlineTimeOfDay": { "type": "object", "description": "Time-of-day paired with deadlineBusinessDays.", "properties": { "hours": { "type": "number" }, "minutes": { "type": "number" } } }, "stageMetadata": { "type": "object", "description": "Free-form stage-level metadata.", "additionalProperties": true }, "config": { "type": "object", "description": "Stage configuration options.", "additionalProperties": true }, "customMessage": { "type": "string", "description": "Optional message included in stage notifications." } } }, "GroupedApprovalPathInput": { "type": "object", "required": [ "stages" ], "description": "An approval path: an ordered set of stages that the group's assets move through.", "properties": { "pathId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Client-assigned path identifier (used on updates to match an existing path)." }, "name": { "type": "string", "description": "Display name of the path." }, "stages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/GroupedApprovalStageInput" } } } }, "GroupedApprovalCreate": { "type": "object", "required": [ "name", "assets", "paths" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Display name of the grouped approval." }, "parentId": { "type": "string", "description": "Workfront parent object ID to associate with this grouped approval. Requires objCode." }, "objCode": { "type": "string", "description": "Workfront parent object type code (e.g. PROJ, TASK). Required when parentId is set." }, "templateId": { "type": "string", "description": "Optional approval-template ID to seed the workflow from." }, "assets": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Document version (DOCV) IDs to include in the group." }, "paths": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/GroupedApprovalPathInput" }, "description": "One or more approval paths, each a sequence of stages." } } }, "GroupedApprovalUnifiedUpdate": { "type": "object", "additionalProperties": false, "required": [ "paths" ], "description": "Full-state update of a grouped approval. Submit the complete set of paths (and optionally assets); the connector reconciles them against the current state, adding/updating/removing so the group matches what you send.", "properties": { "paths": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/GroupedApprovalPathInput" }, "description": "The complete set of approval paths for the group." }, "assets": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "The complete set of document version (DOCV) IDs the group should contain." }, "idempotencyKey": { "type": "string", "maxLength": 128, "description": "Optional client-supplied key that makes a retried request safe (the same key will not apply the update twice)." } } }, "GroupedApprovalAssetsUpdate": { "type": "object", "description": "Add and/or remove assets on a grouped approval in a single call.", "properties": { "add": { "type": "array", "items": { "type": "string" }, "description": "Document version (DOCV) IDs to add." }, "remove": { "type": "array", "items": { "type": "string" }, "description": "Document version (DOCV) IDs to remove." } } }, "GroupedApprovalStagesUpdate": { "type": "object", "description": "Combined add/update/remove of stages, processed in the order remove, then update, then add.", "properties": { "add": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalStageAdd" } }, "update": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalStageUpdate" } }, "remove": { "type": "array", "items": { "type": "object", "required": [ "stageId" ], "properties": { "stageId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "stageId of the stage to remove." } } } } } }, "GroupedApprovalStageAdd": { "type": "object", "required": [ "stageId", "pathId", "name", "parentIds", "participants" ], "additionalProperties": false, "description": "A new stage to add. Participants are set at add time; per-stage deadlines, config and customMessage are set afterwards via an update operation.", "properties": { "stageId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "Client-assigned stage identifier, unique across all paths in the approval (not just within its own path)." }, "pathId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$", "description": "The path this stage is added to." }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "parentIds": { "type": "array", "items": { "type": "string" }, "description": "stageIds this stage depends on." }, "participants": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/GroupedApprovalParticipantInput" } }, "stageMetadata": { "type": "object", "additionalProperties": true } } }, "GroupedApprovalStageUpdate": { "type": "object", "required": [ "stageId" ], "additionalProperties": false, "description": "Changes to an existing stage, identified by stageId. Note: pathId, parentIds and participants cannot be changed here - use the stage participants endpoint to change participants.", "properties": { "stageId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "deadlineDate": { "type": "string", "format": "date-time" }, "deadlineBusinessDays": { "type": "number" }, "stageMetadata": { "type": "object", "additionalProperties": true }, "config": { "type": "object", "additionalProperties": true }, "customMessage": { "type": "string" } } }, "GroupedApprovalStageParticipantsUpdate": { "type": "object", "description": "Combined add/update/remove of participants on a stage. The three lists use different shapes.", "properties": { "add": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalParticipantAdd" } }, "update": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalParticipantUpdate" } }, "remove": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalParticipantRemove" } } } }, "GroupedApprovalParticipantAdd": { "type": "object", "required": [ "id", "role" ], "additionalProperties": false, "description": "A participant to add to the stage.", "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$", "description": "Workfront user or team ID." }, "type": { "type": "string", "enum": [ "USER", "TEAMOB" ], "description": "Participant type. Defaults to USER." }, "role": { "type": "string", "enum": [ "approver", "reviewer" ], "description": "Participant role (case-insensitive; APPROVER/REVIEWER also accepted)." }, "participantMetadata": { "type": "object", "additionalProperties": true, "description": "Optional free-form metadata for the participant." } } }, "GroupedApprovalParticipantUpdate": { "type": "object", "required": [ "id" ], "additionalProperties": false, "description": "Update an existing participant. Supply at least one of role or participantMetadata. Note that participantMetadata here is an add/update/remove operations object, not a flat map.", "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" }, "type": { "type": "string", "enum": [ "USER", "TEAMOB" ] }, "role": { "type": "string", "enum": [ "approver", "reviewer" ] }, "participantMetadata": { "type": "object", "additionalProperties": false, "description": "Metadata operations.", "properties": { "add": { "type": "object", "additionalProperties": true }, "update": { "type": "object", "additionalProperties": true }, "remove": { "type": "array", "items": { "type": "string" }, "description": "Metadata keys to remove." } } } } }, "GroupedApprovalParticipantRemove": { "type": "object", "required": [ "id" ], "additionalProperties": false, "description": "A participant to remove, identified by id.", "properties": { "id": { "type": "string", "pattern": "^[a-fA-F0-9]{32}$" }, "type": { "type": "string", "enum": [ "USER", "TEAMOB" ] } } }, "GroupedApprovalStageMetadataUpdate": { "type": "object", "description": "Add/update/remove free-form metadata keys on a stage.", "properties": { "add": { "type": "object", "additionalProperties": true }, "update": { "type": "object", "additionalProperties": true }, "remove": { "type": "array", "items": { "type": "string" }, "description": "Metadata keys to remove." } } }, "Reference": { "type": "object", "required": [ "id", "type" ], "description": "An external reference that identifies a Workfront/IMS entity.", "properties": { "id": { "type": "string", "description": "The reference ID.", "example": "884313730004e310f947559b08e68b11" }, "type": { "type": "string", "description": "The type of reference (e.g. `wfUserId`, `imsUserId`, `email`, `DOCV`, `esm`, `genStudioDraft`).", "example": "wfUserId" } } }, "DecisionCounts": { "type": "object", "description": "Progress of asset decisions within a scope (group, path, stage, or participant).", "properties": { "decided": { "type": "integer", "description": "The number of assets that have been decided on.", "example": 1 }, "undecided": { "type": "integer", "description": "The number of assets that do not yet have a decision.", "example": 2 } } }, "GroupedApprovalIdentity": { "type": "object", "description": "A resolved Workfront identity (user or team).", "properties": { "identityGuid": { "type": "string", "description": "The GUID of the identity.", "example": "884313730004e310f947559b08e68b11" }, "type": { "type": "string", "nullable": true, "enum": [ "USER", "TEAMOB" ], "description": "The type of identity. Null when the identity could not be hydrated.", "example": "USER" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" }, "description": "External references associated with the identity.", "example": [ { "id": "884313730004e310f947559b08e68b11", "type": "wfUserId" }, { "id": "15401B8A66C8F9CB0A49423C@13cc192466c8c9a949410f.e", "type": "imsUserId" }, { "id": "creator@example.com", "type": "email" } ] } } }, "GroupedApprovalAsset": { "type": "object", "description": "An asset (document version) in the grouped approval, with its rolled-up decision.", "properties": { "assetGuid": { "type": "string", "description": "The GUID for the asset.", "example": "673fc29b0006af515e33732d1ebdc39a" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" }, "description": "External references associated with the asset.", "example": [ { "id": "698b61d400011579a3dbc96cfb99ca06", "type": "DOCV" }, { "id": "urn:aaid:sc:US:f9228e94-dace-34c9-91da-332a190186d4:0", "type": "esm" }, { "id": "urn:aaid:aem:eb19fb9d-1543-47c1-b219-578f5be98d2c:1", "type": "genStudioDraft" } ] }, "decision": { "type": "string", "nullable": true, "enum": [ "reviewed", "approved", "approved with changes", "needs work" ], "description": "The decision for the asset. Null until a decision is reached.\n\nRolled-up decision (`null` until decided):\n- `reviewed` - A reviewer marked it reviewed (non-binding).\n- `approved` - Approved.\n- `approved with changes` - Approved, with changes requested.\n- `needs work` - Returned for changes / not approved.", "example": "approved" } } }, "GroupedApprovalParticipant": { "type": "object", "description": "A participant (approver or reviewer) on a stage, with their rolled-up decision progress.", "properties": { "identityGuid": { "type": "string", "description": "The GUID of the participant identity.", "example": "698b60820000462ecf66c409d1248fa9" }, "type": { "type": "string", "nullable": true, "enum": [ "USER", "TEAMOB" ], "description": "The type of participant. Null when the identity could not be hydrated.", "example": "USER" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" }, "description": "External references associated with the participant.", "example": [ { "id": "698b60820000462ecf66c409d1248fa9", "type": "wfUserId" }, { "id": "1BF9194166C9284F0A49412F@13cc192466c8c9a949410f.e", "type": "imsUserId" }, { "id": "approver@example.com", "type": "email" } ] }, "role": { "type": "string", "enum": [ "approver", "reviewer" ], "description": "The role of the participant. `approver` has a binding vote; `reviewer` is non-binding.", "example": "approver" }, "status": { "type": "string", "enum": [ "not started", "pending", "opened", "decided", "not required" ], "description": "Lifecycle status of the participant on the stage.\n\nParticipant lifecycle status:\n- `not started` - The participant's stage has not activated yet.\n- `pending` - Activated and awaiting this participant's decision.\n- `opened` - The participant has opened the review but not yet decided.\n- `decided` - The participant has recorded a final decision.\n- `not required` - The participant is not required to decide on this scope.", "example": "opened" }, "decisionCounts": { "$ref": "#/components/schemas/DecisionCounts" }, "decisionDate": { "type": "string", "format": "date-time", "nullable": true, "description": "When the participant reached a final decision.", "example": null }, "participantMetadata": { "type": "object", "additionalProperties": true, "description": "Free-form per-participant metadata (e.g. Proof integration data)." } } }, "GroupedApprovalStage": { "type": "object", "description": "A stage in a path: an ordered checkpoint with its participants, status and rolled-up decision.", "properties": { "stageId": { "type": "string", "description": "The id for the stage (not a GUID; other approvals may reuse the same id).", "example": "legal-review" }, "name": { "type": "string", "nullable": true, "description": "The name of the stage.", "example": "Legal Review" }, "status": { "type": "string", "enum": [ "not started", "pending review", "in review", "decided", "withdrawn" ], "description": "The rolled-up status of the stage across all assets.\n\nRolled-up lifecycle status:\n- `not started` - Not yet activated; no participant has started.\n- `pending review` - Active and awaiting decisions; participants have been notified but none has decided yet.\n- `in review` - Active with some decisions recorded, but not yet enough to conclude.\n- `decided` - All required decisions are in; a final decision has been reached.\n- `withdrawn` - Retracted; no further action is possible.", "example": "in review" }, "decision": { "type": "string", "nullable": true, "enum": [ "reviewed", "approved", "approved with changes", "needs work" ], "description": "The rolled-up decision for the stage. Null until decided.\n\nRolled-up decision (`null` until decided):\n- `reviewed` - A reviewer marked it reviewed (non-binding).\n- `approved` - Approved.\n- `approved with changes` - Approved, with changes requested.\n- `needs work` - Returned for changes / not approved.", "example": null }, "decisionCounts": { "$ref": "#/components/schemas/DecisionCounts" }, "decisionDate": { "type": "string", "format": "date-time", "nullable": true, "description": "When the stage reached a final decision.", "example": null }, "isLocked": { "type": "boolean", "description": "If the stage is locked, no further decisions or participant changes can be made.", "example": false }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalParticipant" }, "description": "The participants on the stage." }, "parentIds": { "type": "array", "items": { "type": "string" }, "description": "Stage ids that must complete before this stage activates.", "example": [] }, "deadlineDate": { "type": "string", "format": "date-time", "nullable": true, "description": "The deadline for the stage.", "example": "2025-01-16T12:00:00.000Z" }, "deadlineBusinessDays": { "type": "number", "nullable": true, "description": "The deadline expressed as a number of business days.", "example": null }, "deadlineTimeOfDay": { "type": "object", "nullable": true, "description": "The time of day the stage deadline falls on.", "properties": { "hours": { "type": "number" }, "minutes": { "type": "number" } } }, "config": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/ApprovalStageConfig" } ], "nullable": true, "description": "Stage configuration. Null when not set." }, "customMessage": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Custom message shown to participants on the stage. Null when not set." }, "stageMetadata": { "type": "object", "additionalProperties": true, "description": "Key/value pairs provided by the connector." }, "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/StageTrigger" }, "description": "Triggers that control when the stage activates." } } }, "GroupedApprovalPath": { "type": "object", "description": "A path in the grouped approval: an ordered set of stages, with rolled-up status and decision progress.", "properties": { "pathId": { "type": "string", "description": "The id for the path.", "example": "primary" }, "name": { "type": "string", "nullable": true, "description": "The name of the path.", "example": "Primary Review Path" }, "status": { "type": "string", "enum": [ "not started", "pending review", "in review", "decided", "withdrawn" ], "description": "The rolled-up status for the path.\n\nRolled-up lifecycle status:\n- `not started` - Not yet activated; no participant has started.\n- `pending review` - Active and awaiting decisions; participants have been notified but none has decided yet.\n- `in review` - Active with some decisions recorded, but not yet enough to conclude.\n- `decided` - All required decisions are in; a final decision has been reached.\n- `withdrawn` - Retracted; no further action is possible.", "example": "in review" }, "decision": { "type": "string", "nullable": true, "enum": [ "reviewed", "approved", "approved with changes", "needs work" ], "description": "The rolled-up decision for the path. Null until decided.\n\nRolled-up decision (`null` until decided):\n- `reviewed` - A reviewer marked it reviewed (non-binding).\n- `approved` - Approved.\n- `approved with changes` - Approved, with changes requested.\n- `needs work` - Returned for changes / not approved.", "example": null }, "decisionCounts": { "$ref": "#/components/schemas/DecisionCounts" }, "isLocked": { "type": "boolean", "description": "If the path is locked, no further decisions or participant changes can be made.", "example": false }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalStage" }, "description": "The stages in the path." } } }, "GroupedApproval": { "type": "object", "description": "A grouped approval: many document versions moving together through shared paths and stages, with rolled-up status and decision progress.", "properties": { "groupedApprovalGuid": { "type": "string", "description": "The Grouped Approval GUID.", "example": "9f8b60820000462ecf66c409d1248fa9" }, "name": { "type": "string", "description": "The name of the Grouped Approval.", "example": "Q1 Campaign Assets" }, "templateId": { "type": "string", "nullable": true, "description": "The template the Grouped Approval was created from, if any.", "example": null }, "status": { "type": "string", "enum": [ "not started", "pending review", "in review", "decided", "withdrawn" ], "description": "The overall (rolled-up) status of the Grouped Approval.\n\nRolled-up lifecycle status:\n- `not started` - Not yet activated; no participant has started.\n- `pending review` - Active and awaiting decisions; participants have been notified but none has decided yet.\n- `in review` - Active with some decisions recorded, but not yet enough to conclude.\n- `decided` - All required decisions are in; a final decision has been reached.\n- `withdrawn` - Retracted; no further action is possible.", "example": "in review" }, "decisionCounts": { "$ref": "#/components/schemas/DecisionCounts" }, "decisionDate": { "type": "string", "format": "date-time", "nullable": true, "description": "When the Grouped Approval reached a final decision.", "example": null }, "creator": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupedApprovalIdentity" } ], "nullable": true, "description": "The identity that created the Grouped Approval. Null when it could not be hydrated." }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalAsset" }, "description": "The assets in the Grouped Approval." }, "assetReferenceTypes": { "type": "array", "items": { "type": "string" }, "description": "Distinct reference types across all assets in the Grouped Approval.", "example": [ "DOCV", "esm", "genStudioDraft" ] }, "paths": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalPath" }, "description": "The paths in the Grouped Approval, each containing its stages." }, "createdByClientId": { "type": "string", "nullable": true, "description": "The client id that created the Grouped Approval.", "example": "workfront-fusion" }, "lastModifiedByClientId": { "type": "string", "nullable": true, "description": "The client id that last modified the Grouped Approval.", "example": "workfront-fusion" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp.", "example": "2025-01-10T09:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp.", "example": "2025-01-14T16:30:00.000Z" } } }, "GroupedApprovalCreatedParticipant": { "type": "object", "properties": { "identityGuid": { "type": "string", "description": "The resolved Identity GUID.", "example": "698b60820000462ecf66c409d1248fa9" }, "type": { "type": "string", "enum": [ "USER", "TEAMOB" ], "description": "The participant type.", "example": "USER" }, "role": { "type": "string", "description": "The role (approver, reviewer). Only on stage participants.", "example": "approver" }, "status": { "type": "string", "description": "The participant lifecycle status.", "example": "not started" }, "decisionCounts": { "$ref": "#/components/schemas/DecisionCounts" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" }, "description": "External references associated with the identity.", "example": [ { "id": "698b60820000462ecf66c409d1248fa9", "type": "wfUserId" }, { "id": "1BF9194166C9284F0A49412F@13cc192466c8c9a949410f.e", "type": "imsUserId" }, { "id": "approver@example.com", "type": "email" } ] }, "participantMetadata": { "type": "object", "additionalProperties": true, "description": "Free-form per-participant metadata (e.g. Proof integration data)." } } }, "GroupedApprovalCreatedStage": { "type": "object", "properties": { "stageId": { "type": "string", "example": "legal-review" }, "name": { "type": "string", "example": "Legal Review" }, "parentIds": { "type": "array", "items": { "type": "string" }, "example": [] }, "triggers": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "status": { "type": "string", "example": "not started" }, "decision": { "type": "string", "nullable": true, "example": null }, "decisionDate": { "type": "string", "format": "date-time", "nullable": true, "example": null }, "decisionCounts": { "$ref": "#/components/schemas/DecisionCounts" }, "isLocked": { "type": "boolean", "example": false }, "config": { "type": "object", "additionalProperties": true }, "customMessage": { "type": "string", "nullable": true, "example": null }, "deadlineDate": { "type": "string", "format": "date-time", "nullable": true, "example": "2025-01-16T12:00:00.000Z" }, "deadlineBusinessDays": { "type": "number", "nullable": true, "example": null }, "deadlineTimeOfDay": { "type": "object", "nullable": true, "properties": { "hours": { "type": "number" }, "minutes": { "type": "number" } } }, "stageMetadata": { "type": "object", "additionalProperties": true }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalCreatedParticipant" } } } }, "GroupedApprovalCreatedPath": { "type": "object", "properties": { "pathId": { "type": "string", "example": "primary" }, "name": { "type": "string", "nullable": true, "example": "Primary Review Path" }, "status": { "type": "string", "example": "not started" }, "decision": { "type": "string", "nullable": true, "example": null }, "decisionCounts": { "$ref": "#/components/schemas/DecisionCounts" }, "decisionDate": { "type": "string", "format": "date-time", "nullable": true, "example": null }, "isLocked": { "type": "boolean", "example": false }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalCreatedStage" } } } }, "GroupedApprovalCreatedResponse": { "type": "object", "description": "The full created grouped approval, echoing the submitted structure with server-assigned ids (pathId, stageId, identityGuid, assetGuid) filled in.", "properties": { "groupedApprovalGuid": { "type": "string", "description": "GUID of the created grouped approval.", "example": "9f8b60820000462ecf66c409d1248fa9" }, "imsOrgId": { "type": "string", "example": "1269195F66C8C84F0A494025@AdobeOrg" }, "customerId": { "type": "string", "example": "697be14f00392452aa729f7eb29059fe" }, "templateId": { "type": "string", "nullable": true, "example": null }, "name": { "type": "string", "example": "Q1 Campaign Assets" }, "status": { "type": "string", "example": "not started" }, "decisionCounts": { "$ref": "#/components/schemas/DecisionCounts" }, "decisionDate": { "type": "string", "format": "date-time", "nullable": true, "example": null }, "creator": { "$ref": "#/components/schemas/GroupedApprovalCreatedParticipant" }, "realCreator": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/GroupedApprovalCreatedParticipant" } ], "nullable": true, "description": "The proxy identity that actually created the group (technical-account / proxy user). Matches creator when no proxying took place." }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalAsset" } }, "assetReferenceTypes": { "type": "array", "items": { "type": "string" }, "example": [ "DOCV", "esm", "genStudioDraft" ] }, "paths": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalCreatedPath" } }, "createdByClientId": { "type": "string", "example": "workfront-fusion" }, "lastModifiedByClientId": { "type": "string", "example": "workfront-fusion" }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-01-10T09:00:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-01-10T09:00:00.000Z" } } }, "GroupedApprovalSummary": { "type": "object", "required": [ "groupedApprovalGuid", "name", "status" ], "properties": { "groupedApprovalGuid": { "type": "string", "description": "GUID of the grouped approval.", "example": "9f8b60820000462ecf66c409d1248fa9" }, "name": { "type": "string", "example": "Q1 Campaign Assets" }, "status": { "type": "string", "description": "Rolled-up status of the grouped approval.", "example": "in review" } } }, "GroupedApprovalListResponse": { "type": "object", "required": [ "data" ], "example": { "data": [ { "groupedApprovalGuid": "9f8b60820000462ecf66c409d1248fa9", "name": "Q1 Campaign Assets", "status": "in review" } ] }, "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalSummary" } }, "message": { "type": "string", "description": "Present only when data is empty; states the parentId the lookup was scoped to.", "example": "No grouped approvals found for parentId 5f9a1c2b0000d4e1a1b2c3d4e5f60718." } } }, "GroupedApprovalApprovalsResponse": { "type": "array", "description": "The individual asset approvals that make up the grouped approval, as a flat array. Each item is a full Approval plus its rolled-up `decision` within the group.", "items": { "allOf": [ { "$ref": "#/components/schemas/Approval" }, { "type": "object", "properties": { "decision": { "type": "string", "nullable": true, "description": "The asset's decision within the grouped approval." }, "documentVersion": { "type": "object", "additionalProperties": true, "description": "The Workfront documentVersion record, attached only when `documentVersionData=true`." } } } ] } }, "GroupedApprovalSearchRequest": { "type": "object", "properties": { "view": { "type": "string", "enum": [ "awaitingApprovals" ], "default": "awaitingApprovals", "description": "Named view that determines the response shape. Currently only awaitingApprovals is supported." }, "teamIds": { "type": "array", "items": { "type": "string" }, "description": "Optional team IDs; the search also matches groups where one of these teams is a participant." }, "cursor": { "type": "string", "nullable": true, "description": "Opaque cursor for the next page (from the prior response). When a non-null cursor is sent, limit is ignored." }, "limit": { "type": "integer", "default": 20, "maximum": 100, "description": "Page size for the first page, when no cursor is supplied. Defaults to 20, max 100." } } }, "GroupedApprovalSearchResponse": { "type": "object", "required": [ "data", "cursor" ], "description": "Cursor-paginated search results. The row shape under `data` is determined by the requested `view` (the `awaitingApprovals` view is shown in the example).", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Result rows in the requested view's shape." }, "cursor": { "type": "string", "nullable": true, "description": "Cursor for the next page of results. Null if there are no more results." } }, "example": { "data": [ { "guid": "f47ac10b58cc4372a5670e02b2c3d479", "imsOrgId": "1269195F66C8C84F0A494025@AdobeOrg", "customerId": "697be14f00392452aa729f7eb29059fe", "name": "Grouped Approval 123", "creator": { "guid": "884313730004e310f947559b08e68b11", "type": "USER", "references": [ { "id": "884313730004e310f947559b08e68b11", "type": "wfUserId" }, { "id": "00000000000000000000000000000000@00000000000000000000.e", "type": "imsUserId" } ] }, "createdAt": "2025-01-10T09:00:00.000Z", "stages": [ { "name": "Legal Review", "stageId": "019dd8a16cb17a58a3b73fc991f16e07", "deadlineDate": "2025-01-16T12:00:00.000Z", "participant": { "guid": "698b60820000462ecf66c409d1248fa9", "type": "USER", "references": [ { "id": "698b60820000462ecf66c409d1248fa9", "type": "wfUserId" } ], "role": "approver", "status": "opened", "decisionCounts": { "decided": 1, "undecided": 2 } }, "metadata": { "reviewLink": "https://frame.io/f47ac10b58cc4372a5670e02b2c3d479/stage/019dd8a16cb17a58a3b73fc991f16e07", "reviewLinkStatus": "success" } } ] } ], "cursor": null } }, "GroupedApprovalUpdateResult": { "type": "object", "additionalProperties": true, "description": "The full resolved state of the grouped approval after the update: the same paths/assets shape as the request, with every pathId/stageId/identityGuid/assetGuid filled in for newly-created entities. Kept permissive so a legitimate upstream response is never truncated.", "properties": { "paths": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "assets": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "example": { "paths": [ { "pathId": "primary", "stages": [ { "stageId": "legal-review", "participants": [ { "identityGuid": "698b60820000462ecf66c409d1248fa9" } ] } ] } ], "assets": [ { "assetGuid": "673fc29b0006af515e33732d1ebdc39a" } ] } }, "GroupedApprovalAssetResult": { "type": "object", "additionalProperties": true, "properties": { "assetGuid": { "type": "string", "example": "673fc29b0006af515e33732d1ebdc39a" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" }, "example": [ { "id": "698b61d400011579a3dbc96cfb99ca06", "type": "DOCV" }, { "id": "urn:aaid:sc:US:f9228e94-dace-34c9-91da-332a190186d4:0", "type": "esm" }, { "id": "urn:aaid:aem:eb19fb9d-1543-47c1-b219-578f5be98d2c:1", "type": "genStudioDraft" } ] } } }, "GroupedApprovalAssetError": { "type": "object", "additionalProperties": true, "description": "A failed asset operation within an assets PATCH.", "properties": { "operation": { "type": "string", "description": "The operation that failed (add, remove).", "example": "add" }, "code": { "type": "string", "description": "The error code for the failed item.", "example": "ASSET_ALREADY_IN_GROUP" }, "message": { "type": "string", "example": "Asset already belongs to another grouped approval." }, "assetGuid": { "type": "string", "example": "673fc29b0006af515e33732d1ebdc39a" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" }, "example": [ { "id": "698b61d400011579a3dbc96cfb99ca06", "type": "DOCV" }, { "id": "urn:aaid:sc:US:f9228e94-dace-34c9-91da-332a190186d4:0", "type": "esm" }, { "id": "urn:aaid:aem:eb19fb9d-1543-47c1-b219-578f5be98d2c:1", "type": "genStudioDraft" } ] } } }, "GroupedApprovalStageParticipantError": { "type": "object", "additionalProperties": true, "description": "A failed participant operation within a stage-participants PATCH.", "properties": { "operation": { "type": "string", "description": "The operation that failed (add, update, remove).", "example": "add" }, "code": { "type": "string", "description": "The error code for the failed item.", "example": "IDENTITY_NOT_FOUND" }, "message": { "type": "string", "example": "Could not resolve the participant identity." }, "guid": { "type": "string", "example": "698b60820000462ecf66c409d1248fa9" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" }, "example": [ { "id": "698b60820000462ecf66c409d1248fa9", "type": "wfUserId" }, { "id": "1BF9194166C9284F0A49412F@13cc192466c8c9a949410f.e", "type": "imsUserId" }, { "id": "approver@example.com", "type": "email" } ] } } }, "GroupedApprovalAssetsSummary": { "type": "object", "additionalProperties": true, "description": "Counts for an assets add/remove PATCH.", "properties": { "added": { "type": "integer", "example": 2 }, "removed": { "type": "integer", "example": 0 }, "failed": { "type": "integer", "example": 1 } } }, "GroupedApprovalOperationSummary": { "type": "object", "additionalProperties": true, "description": "Counts of succeeded/failed operations for a management PATCH.", "properties": { "added": { "type": "integer", "example": 1 }, "updated": { "type": "integer", "example": 1 }, "removed": { "type": "integer", "example": 0 }, "failed": { "type": "integer", "example": 0 } } }, "GroupedApprovalAssetsResult": { "type": "object", "additionalProperties": true, "description": "Result of an assets add/remove PATCH. A 200 can still carry per-item failures in `errors`; check `summary` for counts.", "properties": { "added": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalAssetResult" } }, "removed": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalAssetResult" } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalAssetError" } }, "summary": { "$ref": "#/components/schemas/GroupedApprovalAssetsSummary" } } }, "GroupedApprovalParticipantResult": { "type": "object", "additionalProperties": true, "description": "A participant echoed back from a stage-participants PATCH (fields relayed from upstream; may include more).", "properties": { "guid": { "type": "string", "example": "698b60820000462ecf66c409d1248fa9" }, "type": { "type": "string", "example": "USER" }, "role": { "type": "string", "example": "approver" }, "references": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" }, "example": [ { "id": "698b60820000462ecf66c409d1248fa9", "type": "wfUserId" }, { "id": "1BF9194166C9284F0A49412F@13cc192466c8c9a949410f.e", "type": "imsUserId" }, { "id": "approver@example.com", "type": "email" } ] } } }, "GroupedApprovalStageParticipantsResult": { "type": "object", "additionalProperties": true, "description": "Result of a stage-participants add/update/remove PATCH. A 200 can still carry per-item failures in `errors`; check `summary` for counts.", "properties": { "added": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalParticipantResult" } }, "updated": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalParticipantResult" } }, "removed": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalParticipantResult" } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/GroupedApprovalStageParticipantError" } }, "summary": { "$ref": "#/components/schemas/GroupedApprovalOperationSummary" } } }, "GroupedApprovalStageMetadataResult": { "type": "object", "additionalProperties": true, "description": "Result of a stage-metadata add/update/remove PATCH. Per-key failures (e.g. METADATA_KEY_NOT_FOUND) are returned in `errors`; check `summary` for counts.", "properties": { "added": { "type": "object", "additionalProperties": true }, "updated": { "type": "object", "additionalProperties": true }, "removed": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "summary": { "$ref": "#/components/schemas/GroupedApprovalOperationSummary" } } }, "GroupedApprovalStagesResult": { "type": "object", "additionalProperties": true, "description": "Result of a stages add/update/remove PATCH. NOT idempotent: a retried add may fail as already-applied - reconcile via GET and re-send only items still in `errors`. Check `summary` for counts.", "properties": { "added": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "updated": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "removed": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "summary": { "$ref": "#/components/schemas/GroupedApprovalOperationSummary" } } } }, "responses": { "ApprovalResponse": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "UnauthorizedResponse": { "description": "Unauthorized \u2014 no valid auth credentials provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFoundResponse": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BadRequestResponse": { "description": "Bad Request \u2014 validation failure or invalid state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerErrorResponse": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "LengthRequiredResponse": { "description": "Length Required \u2014 the service requires a `Content-Length` header. Send an empty JSON object (`{}`) as the request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "paths": { "/api/v1/approvals/{assetType}/{assetId}": { "get": { "tags": [ "Approvals" ], "summary": "Get approval", "description": "Get approval details for an asset. Returns the full `Approval` object when an approval exists. When no approval has been created for the asset yet, returns a partial response containing only `isApprovalActive`, `isEsmAsset`, `frameSyncStatus`, and `userInfo`.", "operationId": "getApproval", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Approval" }, { "$ref": "#/components/schemas/PartialApproval" } ], "discriminator": { "propertyName": "approvalGuid" } } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "post": { "tags": [ "Approvals" ], "summary": "Create approval", "description": "Creates an approval with the supplied stage data. The `stages` array in the body defines the approval structure and is used as-is. `templateId` is optional metadata: the caller is expected to have fetched the template separately (`GET /api/v1/templates/{templateId}`) and copied its stages into the request body. When `templateId` is supplied, it is recorded on the new approval and the corresponding template's `usageCount` is incremented and `lastUsedOnDate` is refreshed.", "operationId": "createApproval", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stages": { "type": "array", "minItems": 1, "description": "Stage definitions used to build a single-path approval. The server uses this array as-is \u2014 it does not look up or expand any referenced template. To create an approval from a template, the caller must fetch the template independently (`GET /api/v1/templates/{templateId}`), copy its `stages` into this array, and optionally pass the same `templateId` to record the source on the approval and increment its usage counter. Mutually exclusive with `paths` \u2014 provide one or the other.", "items": { "$ref": "#/components/schemas/StageBody" } }, "paths": { "type": "array", "minItems": 1, "description": "Path definitions used to build a multi-path approval, each with its own `stages`. Mutually exclusive with the top-level `stages` \u2014 provide one or the other.", "items": { "$ref": "#/components/schemas/ApprovalPathCreate" } }, "templateId": { "type": "string", "description": "ID of the template used to create this approval, if any. Recorded on the approval for traceability and used to increment the template's `usageCount` and refresh `lastUsedOnDate`. The server does **not** load stages from the template \u2014 the caller must fetch the template via `GET /api/v1/templates/{templateId}` and copy its stages into the `stages` array." } }, "anyOf": [ { "required": [ "stages" ] }, { "required": [ "paths" ] } ] } } } }, "responses": { "201": { "$ref": "#/components/responses/ApprovalResponse", "description": "Approval created." }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "delete": { "tags": [ "Approvals" ], "summary": "Delete approval", "description": "Deletes the approval for the given asset. The asset must be in an editable state. Check `userInfo.isEditable` on the approval response to determine whether the requesting user can perform write operations.", "operationId": "deleteApproval", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "204": { "description": "Approval deleted successfully \u2014 no content returned" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/approvals/{assetType}/{assetId}/getSuggestedApprovals": { "get": { "tags": [ "Approvals" ], "summary": "Get suggested approvals", "description": "Returns suggested approval payloads derived from prior document versions, shaped for use when creating a new approval on the current asset. Results are ordered newest version first.", "operationId": "getSuggestedApprovals", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "suggestedApprovals" ], "properties": { "suggestedApprovals": { "type": "array", "items": { "type": "object", "properties": { "sourceVersion": { "description": "Document version number this suggestion was derived from", "oneOf": [ { "type": "number" }, { "type": "string" } ] } }, "additionalProperties": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/approvals/{assetType}/{assetId}/stages": { "post": { "tags": [ "Stages" ], "summary": "Create stages (auto-creates approval)", "description": "Adds one or more stages to the approval for the given asset. If no approval exists for the asset yet, one is created automatically \u2014 so this endpoint can be used in place of `POST /api/v1/approvals/{assetType}/{assetId}` to create an approval and its initial stages in a single call. Returns 201 on success.", "operationId": "postStages", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stages": { "type": "array", "minItems": 1, "description": "Stage definitions used to build a single-path approval. Mutually exclusive with `paths` — provide one or the other.", "items": { "$ref": "#/components/schemas/StageBody" } }, "paths": { "type": "array", "minItems": 1, "description": "Path definitions used to build a multi-path approval, each with its own `stages`. Mutually exclusive with the top-level `stages` — provide one or the other.", "items": { "$ref": "#/components/schemas/ApprovalPathCreate" } }, "templateId": { "type": "string", "description": "ID of the template used to create this approval, if any." } }, "anyOf": [ { "required": [ "stages" ] }, { "required": [ "paths" ] } ] } } } }, "responses": { "201": { "$ref": "#/components/responses/ApprovalResponse" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "put": { "tags": [ "Stages" ], "summary": "Update all stages", "description": "Replaces all stages on an existing approval with the given stage data. The asset must be in an editable state. Check `userInfo.isEditable` on the approval response to determine whether the requesting user can perform write operations.", "operationId": "putStages", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stages": { "type": "array", "description": "Replacement stage definitions for a single-path approval. Mutually exclusive with `paths` — provide one or the other.", "items": { "$ref": "#/components/schemas/StageBody" } }, "paths": { "type": "array", "minItems": 1, "description": "Replacement path definitions for a multi-path approval, each with its own `stages`. Mutually exclusive with the top-level `stages` — provide one or the other.", "items": { "$ref": "#/components/schemas/ApprovalPathUpdate" } } }, "anyOf": [ { "required": [ "stages" ] }, { "required": [ "paths" ] } ] } } } }, "responses": { "200": { "$ref": "#/components/responses/ApprovalResponse" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/approvals/{assetType}/{assetId}/stages/{stageId}": { "patch": { "tags": [ "Stages" ], "summary": "Update a stage", "description": "Partially updates any field on the specified stage. The asset must be in an editable state. Check `userInfo.isEditable` on the approval response to determine whether the requesting user can perform write operations.", "operationId": "patchStage", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/StageId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StageBody" } } } }, "responses": { "200": { "$ref": "#/components/responses/ApprovalResponse" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "delete": { "tags": [ "Stages" ], "summary": "Delete a stage", "description": "Deletes the specified stage from the approval. The asset must be in an editable state. Check `userInfo.isEditable` on the approval response to determine whether the requesting user can perform write operations.", "operationId": "deleteStage", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/StageId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "$ref": "#/components/responses/ApprovalResponse" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/approvals/{assetType}/{assetId}/stages/{stageId}/lock": { "put": { "tags": [ "Stages" ], "summary": "Lock a stage", "description": "Locks the specified stage. All decisions on the stage must have been made before locking. The asset must be in an editable state. Check `userInfo.isEditable` on the approval response to determine whether the requesting user can perform write operations.", "operationId": "lockStage", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/StageId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "$ref": "#/components/responses/ApprovalResponse" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" }, "411": { "$ref": "#/components/responses/LengthRequiredResponse" } }, "requestBody": { "required": true, "description": "Send an empty JSON object. The service returns HTTP 411 if no body is provided.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } }, "/api/v1/approvals/{assetType}/{assetId}/stages/{stageId}/unlock": { "put": { "tags": [ "Stages" ], "summary": "Unlock a stage", "description": "Unlocks the specified stage, making it editable again. The asset must be in an editable state. Check `userInfo.isEditable` on the approval response to determine whether the requesting user can perform write operations.", "operationId": "unlockStage", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/StageId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "$ref": "#/components/responses/ApprovalResponse" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" }, "411": { "$ref": "#/components/responses/LengthRequiredResponse" } }, "requestBody": { "required": true, "description": "Send an empty JSON object. The service returns HTTP 411 if no body is provided.", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } }, "/api/v1/approvals/{assetType}/{assetId}/decisions": { "post": { "tags": [ "Decisions" ], "summary": "Make decisions", "description": "Makes a decision on one or more stages. If the decision already exists it will be updated. Overall stage and approval status is recalculated after each decision. Throws an error if the approval is not found or the current user is not a participant.", "operationId": "makeDecisions", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "description": "The decision value (e.g. `approved`, `needs work`, `approved with changes`, `reviewed`)", "enum": [ "approved", "needs work", "approved with changes", "reviewed" ] }, "stageIds": { "type": "array", "items": { "type": "string" }, "description": "Stage IDs to apply the decision to. Defaults to all active stages if omitted." } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApprovalResponse" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "delete": { "tags": [ "Decisions" ], "summary": "Delete decisions", "description": "Removes the current user's decision(s) from all active stages. The approval must be active.", "operationId": "deleteDecisions", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "$ref": "#/components/responses/ApprovalResponse" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/approvals/{assetType}/{assetId}/decisions/stage/{stageId}": { "post": { "tags": [ "Decisions" ], "summary": "Make decision on a stage", "description": "Makes a decision on a specific stage. Equivalent to `POST /decisions` with a single stage ID.", "operationId": "makeDecisionOnStage", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/StageId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "description": "The decision value", "enum": [ "approved", "needs work", "approved with changes", "reviewed" ] } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApprovalResponse" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "delete": { "tags": [ "Decisions" ], "summary": "Delete decision on a stage", "description": "Removes the current user's decision from the specified stage.", "operationId": "deleteDecisionOnStage", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/StageId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "$ref": "#/components/responses/ApprovalResponse" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/approvals/{assetType}/{assetId}/getSuggestedParticipants": { "get": { "tags": [ "Participants" ], "summary": "Get suggested participants", "description": "Returns participant suggestions derived from the previous document version's approval.", "operationId": "getSuggestedParticipants", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "participantSuggestions": { "type": "array", "items": { "type": "object", "properties": { "participantId": { "type": "string" }, "participantType": { "type": "string", "enum": [ "USER", "TEAMOB" ], "description": "Type of participant.\n\n- `USER` \u2014 Individual Workfront user (or AI bot user).\n- `TEAMOB` \u2014 Workfront team." }, "participantRole": { "type": "string", "enum": [ "approver", "reviewer" ], "description": "Role this participant plays on the stage.\n\n- `approver` \u2014 Has a binding vote; their decision directly affects stage and approval status.\n- `reviewer` \u2014 Non-binding; can mark reviewed but does not block approval progression.\n\nThe role, combined with the participant's current decision, also drives the `userInfo.action` value on every approval response \u2014 see [`Approval.userInfo.action`](#section/Schemas/Approval) for the role/decision \u2192 action mapping." } } } }, "prevVersionWithApprovers": { "type": "string", "description": "The prior document version that had approvers" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/approvals/{assetType}/{assetId}/participants": { "post": { "tags": [ "Participants" ], "summary": "Add participants", "description": "Adds one or more participants to an approval. If the approval does not yet exist, one will be created. If a participant already exists they will be merged and updated. The asset must be in an editable state. Check `userInfo.isEditable` on the approval response to determine whether the requesting user can perform write operations.", "operationId": "addParticipants", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ParticipantBody" } } } } }, "responses": { "200": { "$ref": "#/components/responses/ApprovalResponse" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/approvals/{assetType}/{assetId}/participants/{participantType}/{participantId}": { "delete": { "tags": [ "Participants" ], "summary": "Delete participant", "description": "Removes a participant from the approval. If all participants are removed, the stage and approval are also deleted. The asset must be in an editable state. Check `userInfo.isEditable` on the approval response to determine whether the requesting user can perform write operations.", "operationId": "deleteParticipant", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/ParticipantType" }, { "$ref": "#/components/parameters/ParticipantId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "OK. Returns the updated approval when participants remain. When removing this participant empties the approval, the approval is deleted and the response is an `ApprovalDeletedResponse` envelope with `deleted: true` instead of the full approval payload.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Approval" }, { "$ref": "#/components/schemas/ApprovalDeletedResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/approvals/{assetType}/{assetId}/participants/{participantId}/remind": { "post": { "tags": [ "Participants" ], "summary": "Remind participant", "description": "Sends a reminder notification to the specified participant. The approval must exist and be in an editable state. Check `userInfo.isEditable` on the approval response to determine whether the requesting user can perform write operations.", "operationId": "remindParticipant", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/ParticipantId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" }, "411": { "$ref": "#/components/responses/LengthRequiredResponse" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "participantId" ], "properties": { "participantId": { "type": "string", "description": "ID of the participant to remind. Must match the `participantId` in the URL path." }, "participantType": { "type": "string", "enum": [ "USER", "TEAMOB" ], "description": "Optional. Type of the participant being reminded.\n\n- `USER` \u2014 Individual Workfront user (or AI bot user).\n- `TEAMOB` \u2014 Workfront team." }, "participantRole": { "type": "string", "enum": [ "approver", "reviewer" ], "description": "Optional. Role of the participant being reminded.\n\n- `approver` \u2014 Has a binding vote.\n- `reviewer` \u2014 Non-binding." } } } } } } } }, "/api/v1/approvals/{assetType}/{assetId}/participants/remindUndecided": { "post": { "tags": [ "Participants" ], "summary": "Remind all undecided participants", "description": "Sends reminder notifications to all participants across all stages who have not yet made a decision.", "operationId": "remindUndecidedParticipants", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" }, "411": { "$ref": "#/components/responses/LengthRequiredResponse" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } }, "description": "Send an empty JSON object at minimum. The service returns HTTP 411 if no body is provided." } } }, "/api/v1/approvals/{assetType}/{assetId}/stages/{stageId}/participants/{participantId}/remind": { "post": { "tags": [ "Participants" ], "summary": "Remind participant on a stage", "description": "Sends a reminder notification to a specific participant within a specific stage.", "operationId": "remindMultiStageParticipant", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/StageId" }, { "$ref": "#/components/parameters/ParticipantId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" }, "411": { "$ref": "#/components/responses/LengthRequiredResponse" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "participantId": { "type": "string", "description": "ID of the participant to remind. Must match the `participantId` in the URL path." }, "participantType": { "type": "string", "enum": [ "USER", "TEAMOB" ], "description": "Optional. Type of the participant being reminded.\n\n- `USER` \u2014 Individual Workfront user (or AI bot user).\n- `TEAMOB` \u2014 Workfront team." }, "participantRole": { "type": "string", "enum": [ "approver", "reviewer" ], "description": "Optional. Role of the participant being reminded.\n\n- `approver` \u2014 Has a binding vote.\n- `reviewer` \u2014 Non-binding." } } } } } } } }, "/api/v1/approvals/{assetType}/{assetId}/stages/{stageId}/participants/remindUndecided": { "post": { "tags": [ "Participants" ], "summary": "Remind undecided participants on a stage", "description": "Sends reminder notifications to all undecided participants within a specific stage.", "operationId": "remindMultiStageUndecidedParticipants", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/AssetId" }, { "$ref": "#/components/parameters/StageId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" }, "411": { "$ref": "#/components/responses/LengthRequiredResponse" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } }, "description": "Send an empty JSON object at minimum. The service returns HTTP 411 if no body is provided." } } }, "/api/v1/templates": { "get": { "tags": [ "Templates" ], "summary": "List templates", "description": "Returns all approval templates visible to the current user.", "operationId": "getTemplates", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } }, "required": [ "templates" ] } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "post": { "tags": [ "Templates" ], "summary": "Create template", "description": "Creates an approval template. A customer can create a maximum of 1000 templates. Requires template management permissions.", "operationId": "createTemplate", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/templates/{templateId}": { "get": { "tags": [ "Templates" ], "summary": "Get template", "description": "Returns a single approval template by ID.", "operationId": "getTemplate", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TemplateId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "description": "Internal Server Error. Also returned when the template ID does not exist \u2014 the service currently returns 500 instead of 404 for unrecognized IDs." } } }, "put": { "tags": [ "Templates" ], "summary": "Update template", "description": "Partially updates an approval template. Requires template management permissions.", "operationId": "putTemplate", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TemplateId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "patch": { "tags": [ "Templates" ], "summary": "Update template", "description": "Partially updates an approval template. Requires template management permissions.", "operationId": "patchTemplate", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TemplateId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateBody" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "delete": { "tags": [ "Templates" ], "summary": "Delete template", "description": "Deletes a single approval template. Requires template management permissions.", "operationId": "deleteTemplate", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TemplateId" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "Template deleted successfully." }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/templates/bulkDelete/{ids}": { "delete": { "tags": [ "Templates" ], "summary": "Bulk delete templates", "description": "Deletes multiple approval templates in one call. IDs are comma-separated in the path. Requires template management permissions.", "operationId": "bulkDeleteTemplates", "security": [ { "Bearer": [] } ], "parameters": [ { "name": "ids", "in": "path", "required": true, "description": "Comma-separated list of template IDs to delete", "schema": { "type": "string", "example": "templateId1,templateId2,templateId3" } }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "Delete operation acknowledged. Check the `deleted`/`failed`/`errors` arrays to see which of the requested IDs were removed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDeleteResult" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "description": "Returned when one or more supplied IDs are not valid MongoDB ObjectId format strings. An ID that fails the permission check is not an error — it is returned in the 200 response's `failed` array instead. Note: a valid-format ID that passes the permission check but does not match any template is reported in `deleted`, since the upstream delete does not report per-ID outcomes." } } } }, "/api/v1/bots": { "get": { "tags": [ "Bots" ], "summary": "List bot reviewers", "description": "Returns a paginated list of Workfront bot users that are eligible to be added as reviewer participants on an approval. A bot reviewer is invoked automatically when its assigned stage becomes active.", "operationId": "getBots", "security": [ { "Bearer": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "metadata", "results" ], "properties": { "metadata": { "type": "object", "properties": { "totalItems": { "type": "integer" }, "currentPage": { "type": "integer" }, "totalPages": { "type": "integer" }, "pageSize": { "type": "integer" } } }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The unique identifier for the bot" }, "name": { "type": "string", "description": "The name the creator gave to the bot" }, "description": { "type": "string", "description": "The description of what the bot does or is used for" }, "type": { "type": "string", "enum": [ "doc-brand-reviewer" ] }, "isActive": { "type": "boolean", "description": "Whether the bot has been enabled" }, "brandId": { "type": "string", "description": "The ID of the brand the bot is associated with" }, "creatorId": { "type": "string", "description": "The ID of the user who created the bot" }, "customerId": { "type": "string", "description": "The ID of the Workfront customer the bot is associated with" }, "imsOrgId": { "type": "string", "description": "The IMS organization ID associated with the bot" }, "eauthUserID": { "type": "string", "description": "The IMS user ID associated with the bot" }, "wfUserId": { "type": "string", "description": "The Workfront user ID associated with the bot" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/bot-reviews/search": { "post": { "tags": [ "Bot Reviews" ], "summary": "Search AI brand reviews", "description": "Returns AI brand-review results produced for a document version under an approval. Each review is generated when a bot reviewer participant runs against a stage on the approval and captures the bot\u2019s pass/fail findings against the brand\u2019s guidelines. Filter results by bot, document version, parent document, or stage to narrow the response to a specific asset, review run, or stage on its approval.", "operationId": "searchBotReviews", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "botEauthUserId": { "type": "string", "description": "The Workfront eauthUserID of the bot. Maps to associatedTechnicalAccountId on the bot record. Required if `objId` and `parentObjId` are not provided." }, "parentObjType": { "type": "string", "enum": [ "DOCU" ], "description": "Type of the parent object." }, "parentObjId": { "type": "string", "description": "ID of the parent object (the document). Required if `objId` and `botEauthUserId` are not provided." }, "objType": { "type": "string", "enum": [ "DOCV" ], "description": "Type of the object being reviewed." }, "objId": { "type": "string", "description": "ID of the object being reviewed (the document version). Required if `parentObjId` and `botEauthUserId` are not provided." }, "stageId": { "type": "string", "description": "ID of the stage on the approval." }, "page": { "type": "integer", "default": 1 }, "limit": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, "description": "At least one of `objId`, `parentObjId`, or `botEauthUserId` must be provided. Omitting all three will result in a 403 response." } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "reviews" ], "properties": { "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/BotReview" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" }, "403": { "description": "Forbidden \u2014 returned when none of `objId`, `parentObjId`, or `botEauthUserId` are provided in the request body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/approvals/search/{assetType}": { "post": { "tags": [ "Approvals" ], "summary": "Bulk lookup approvals by asset ID", "description": "Simple bulk lookup of approvals for a known list of asset IDs within a specific asset type. Provide the asset type in the path and an array of `assetIds` in the body to retrieve their approvals in a single call. If no body is supplied, the endpoint returns approvals for projects owned by the requesting user that are currently in review. Asset IDs with no approval are included in the response array as a stub containing only `assetId` and `frameSyncStatus: null`.", "operationId": "bulkLookupApprovalsByAssetType", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AssetType" }, { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "assetIds": { "type": "array", "items": { "type": "string" }, "description": "Asset IDs to look up approvals for." }, "assetType": { "type": "string", "description": "Optional. Asset type in the body. The path-level `assetType` is authoritative.", "enum": [ "DOCV" ] } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "approvals": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/Approval" }, { "$ref": "#/components/schemas/EmptyApproval" } ] }, "description": "List of approvals. Asset IDs with no approval are represented as stub objects with only `assetId` and `frameSyncStatus`." } } } } } }, "400": { "description": "Bad Request. Returned for validation errors, or when the request body is an empty object (`{}`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/grouped-approvals": { "get": { "tags": [ "Grouped Approvals" ], "summary": "List grouped approvals by parent", "operationId": "listGroupedApprovalsByParent", "description": "Returns the grouped approvals associated with a Workfront parent object (e.g. a project or task). Supply the parent's `parentId`, and optionally its `objCode`, as query parameters.", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "name": "parentId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Workfront parent object ID (e.g. `5f9a1c2b0000d4e1a1b2c3d4e5f60718`)." }, { "name": "objCode", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Workfront parent object type code (e.g. `PROJ`, `TASK`)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "post": { "tags": [ "Grouped Approvals" ], "summary": "Create grouped approval", "operationId": "createGroupedApproval", "description": "Creates a grouped approval: a set of document versions that move together through one or more approval paths, each an ordered sequence of stages with its own participants. Optionally associate it with a Workfront parent object via `parentId`/`objCode`, or seed it from a `templateId`.", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalCreate" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalCreatedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/grouped-approvals/{groupGuid}": { "get": { "tags": [ "Grouped Approvals" ], "summary": "Get grouped approval", "operationId": "getGroupedApproval", "description": "Returns a grouped approval by its GUID, including its paths, stages, participants, assets and rolled-up status.", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/GroupGuid" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApproval" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "delete": { "tags": [ "Grouped Approvals" ], "summary": "Delete grouped approval", "operationId": "deleteGroupedApproval", "description": "Deletes a grouped approval, cascading to its child asset approvals and paths.", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/GroupGuid" } ], "responses": { "204": { "description": "No Content" }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } }, "patch": { "tags": [ "Grouped Approvals" ], "summary": "Update grouped approval (full state)", "operationId": "updateGroupedApproval", "description": "Applies a full-state update to a grouped approval: the submitted structure (assets, paths, stages, participants) is reconciled against the current one - adding, updating and removing so the group matches what you send.", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/GroupGuid" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalUnifiedUpdate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalUpdateResult" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/grouped-approvals/{groupGuid}/approvals": { "get": { "tags": [ "Grouped Approvals" ], "summary": "Get approvals in a grouped approval", "operationId": "getGroupedApprovalApprovals", "description": "Returns the individual asset approvals that make up a grouped approval. Pass `documentVersionData=true` to also attach each document version's Workfront record to the corresponding approval.", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/GroupGuid" }, { "name": "documentVersionData", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When true, attach the Redrock documentVersion record to each DOCV approval." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalApprovalsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/grouped-approvals/search": { "post": { "tags": [ "Grouped Approvals" ], "summary": "Search grouped approvals", "operationId": "searchGroupedApprovals", "description": "Searches grouped approvals using a named `view`. The default `awaitingApprovals` view returns groups where the requesting user (or one of the supplied `teamIds`) is a participant on the active stage and a decision is still required. Results are cursor-paginated: send `limit` for the first page, then the returned `cursor` for each subsequent page.", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalSearchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/grouped-approvals/{groupGuid}/assets": { "patch": { "tags": [ "Grouped Approvals" ], "summary": "Manage assets on a grouped approval", "operationId": "manageGroupedApprovalAssets", "description": "Adds and/or removes document versions on a grouped approval. Send `add` and/or `remove` arrays of document version IDs.", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/GroupGuid" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalAssetsUpdate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalAssetsResult" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/grouped-approvals/{groupGuid}/stages/{stageId}/participants": { "patch": { "tags": [ "Grouped Approvals" ], "summary": "Manage stage participants", "operationId": "manageGroupedApprovalStageParticipants", "description": "Adds, updates and/or removes participants on a specific stage of a grouped approval. New participants (`add`/`update`) are resolved to Workfront users or teams; `remove` matches on identity.", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/GroupGuid" }, { "$ref": "#/components/parameters/StageId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalStageParticipantsUpdate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalStageParticipantsResult" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/grouped-approvals/{groupGuid}/stages/{stageId}/metadata": { "patch": { "tags": [ "Grouped Approvals" ], "summary": "Manage stage metadata", "operationId": "manageGroupedApprovalStageMetadata", "description": "Adds, updates and/or removes free-form metadata keys on a specific stage of a grouped approval.", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/GroupGuid" }, { "$ref": "#/components/parameters/StageId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalStageMetadataUpdate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalStageMetadataResult" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } }, "/api/v1/grouped-approvals/{groupGuid}/stages": { "patch": { "tags": [ "Grouped Approvals" ], "summary": "Manage stages on a grouped approval", "operationId": "manageGroupedApprovalStages", "description": "Adds, updates and/or removes stages on a grouped approval. Operations are processed in the order remove, then update, then add.", "security": [ { "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/XApiKey" }, { "$ref": "#/components/parameters/XGwSubdomain" }, { "$ref": "#/components/parameters/WfCustomerId" }, { "$ref": "#/components/parameters/WfUserId" }, { "$ref": "#/components/parameters/WfLane" }, { "$ref": "#/components/parameters/XRequestId" }, { "$ref": "#/components/parameters/XCorrelationId" }, { "$ref": "#/components/parameters/GroupGuid" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalStagesUpdate" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupedApprovalStagesResult" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "500": { "$ref": "#/components/responses/InternalServerErrorResponse" } } } } } }