picked 0.0.101-next.2 → 0.0.101

package/docs/reference/management-api/schema/index.md

@@ -0,0 +1,243 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Management API schema
+
+The Management API is one GraphQL endpoint. Every query and mutation below goes to it:
+
+```http
+POST https://api.picked.app/api/graphql
+Authorization: Bearer <access token>
+```
+
+An API key goes in the `X-API-Key` header in place of `Authorization`. See [Authentication](/reference/management-api/authentication). [`@picked/admin-api-client`](/reference/tools/admin-api-client) gives a typed client for every operation.
+
+An operation with `@auth` needs a caller that has authenticated. `@auth(only: USER)` refuses an API key. The schema is also open to GraphQL introspection.
+
+## Operations
+
+| Operation | Type | Description |
+| --- | --- | --- |
+| [`accountCreate`](/reference/management-api/schema/auth#accountcreate) | Mutation | Register an email address and send it a confirmation email. |
+| [`accountResendVerification`](/reference/management-api/schema/auth#accountresendverification) | Mutation | Resend the email verification link. |
+| [`accountVerifyEmail`](/reference/management-api/schema/auth#accountverifyemail) | Mutation | Verify a user's email address with a confirmation token. |
+| [`action`](/reference/management-api/schema/action#action) | Query | Get an action by ID within a workspace. |
+| [`actionCreate`](/reference/management-api/schema/action#actioncreate) | Mutation | Create a new action. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`actionDelete`](/reference/management-api/schema/action#actiondelete) | Mutation | Delete an action. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`actions`](/reference/management-api/schema/action#actions) | Query | List actions in a workspace. Filter by name with `search` (case-insensitive substring) and order with `sortKey` (default `NAME`) plus `reverse`. |
+| [`actionUpdate`](/reference/management-api/schema/action#actionupdate) | Mutation | Update an action. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`apiKeyCreate`](/reference/management-api/schema/api-key#apikeycreate) | Mutation | Create a new API key. Requires scope: `ORGANIZATION_API_KEYS_CREATE`. User authentication only (not API key). |
+| [`apiKeyRevoke`](/reference/management-api/schema/api-key#apikeyrevoke) | Mutation | Revoke an API key. Requires scope: `ORGANIZATION_API_KEYS_DELETE`. |
+| [`apiKeys`](/reference/management-api/schema/api-key#apikeys) | Query | List API keys for an organisation. Requires authentication. |
+| [`asset`](/reference/management-api/schema/cms-models#asset) | Query | Fetch a CMS Asset by id. |
+| [`assetCommit`](/reference/management-api/schema/cms-models#assetcommit) | Mutation | Finalise an Asset upload — captures size, MIME, and intrinsic dimensions for images. |
+| [`assetDelete`](/reference/management-api/schema/cms-models#assetdelete) | Mutation | Soft-delete an Asset. The underlying storage object is removed best-effort. |
+| [`assets`](/reference/management-api/schema/cms-models#assets) | Query | List CMS Assets in a project, with optional text search, MIME-type filtering, and sort. |
+| [`assetUploadInit`](/reference/management-api/schema/cms-models#assetuploadinit) | Mutation | Initiate an Asset upload — returns a pre-signed PUT URL plus the allocated asset id. |
+| [`condition`](/reference/management-api/schema/condition#condition) | Query | Get a condition by ID within a workspace. |
+| [`conditionCreate`](/reference/management-api/schema/condition#conditioncreate) | Mutation | Create a new condition. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`conditionDelete`](/reference/management-api/schema/condition#conditiondelete) | Mutation | Delete a condition. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`conditions`](/reference/management-api/schema/condition#conditions) | Query | List conditions in a workspace. Filter by name with `search` (case-insensitive substring) and order with `sortKey` (default `NAME`) plus `reverse`. |
+| [`conditionUpdate`](/reference/management-api/schema/condition#conditionupdate) | Mutation | Update a condition. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`contentBlock`](/reference/management-api/schema/cms-models#contentblock) | Query | Fetch a CMS Content Block by id. |
+| [`contentBlockCreate`](/reference/management-api/schema/cms-models#contentblockcreate) | Mutation | Create a new CMS Content Block. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`contentBlockDelete`](/reference/management-api/schema/cms-models#contentblockdelete) | Mutation | Soft-delete a CMS Content Block. |
+| [`contentBlocks`](/reference/management-api/schema/cms-models#contentblocks) | Query | List CMS Content Blocks in a workspace, optionally filtered by category. |
+| [`contentBlockUpdate`](/reference/management-api/schema/cms-models#contentblockupdate) | Mutation | Update a CMS Content Block schema. |
+| [`contentEntries`](/reference/management-api/schema/cms-models#contententries) | Query | List CMS Content Entries in a workspace, optionally filtered by parent Content Model. |
+| [`contentEntry`](/reference/management-api/schema/cms-models#contententry) | Query | Fetch a CMS Content Entry by id. |
+| [`contentEntryCreate`](/reference/management-api/schema/cms-models#contententrycreate) | Mutation | Create a new CMS Content Entry against a parent Content Model. |
+| [`contentEntryDelete`](/reference/management-api/schema/cms-models#contententrydelete) | Mutation | Soft-delete a CMS Content Entry. Refuses if a Step references it. |
+| [`contentEntryUpdate`](/reference/management-api/schema/cms-models#contententryupdate) | Mutation | Update a CMS Content Entry's data. |
+| [`contentModel`](/reference/management-api/schema/cms-models#contentmodel) | Query | Fetch a CMS Content Model by id. |
+| [`contentModelCreate`](/reference/management-api/schema/cms-models#contentmodelcreate) | Mutation | Create a new CMS Content Model. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`contentModelDelete`](/reference/management-api/schema/cms-models#contentmodeldelete) | Mutation | Soft-delete a CMS Content Model. Refuses if dependent Content Entry rows still exist. |
+| [`contentModels`](/reference/management-api/schema/cms-models#contentmodels) | Query | List CMS Content Models in a workspace, optionally filtered by category. |
+| [`contentModelUpdate`](/reference/management-api/schema/cms-models#contentmodelupdate) | Mutation | Update a CMS Content Model. Returns migration warnings when the schema change drops or coerces dependent Content Entry fields. |
+| [`createShopifyMetafieldConfig`](/reference/management-api/schema/shopify#createshopifymetafieldconfig) | Mutation |  |
+| [`createShopifyWebhook`](/reference/management-api/schema/shopify#createshopifywebhook) | Mutation |  |
+| [`deleteShopifyMetafieldConfig`](/reference/management-api/schema/shopify#deleteshopifymetafieldconfig) | Mutation |  |
+| [`deleteShopifyWebhook`](/reference/management-api/schema/shopify#deleteshopifywebhook) | Mutation |  |
+| [`designSystem`](/reference/management-api/schema/design-system#designsystem) | Query | Get a design system by ID. |
+| [`designSystemCreate`](/reference/management-api/schema/design-system#designsystemcreate) | Mutation | Create a new design system. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`designSystemDelete`](/reference/management-api/schema/design-system#designsystemdelete) | Mutation | Delete a design system. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`designSystems`](/reference/management-api/schema/design-system#designsystems) | Query | List design systems in a project. Filter by name with `search` (case-insensitive substring) and order with `sortKey` (default `NAME`) plus `reverse`. |
+| [`designSystemUpdate`](/reference/management-api/schema/design-system#designsystemupdate) | Mutation | Update a design system. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`emailLinkVerify`](/reference/management-api/schema/auth#emaillinkverify) | Mutation | Verify the link from a password-reset, invitation, sign-in or confirmation email and create a session. The link is single-use, so call this when the recipient confirms, never on opening the link: an email security scanner that opens links before delivery would otherwise use it up. |
+| [`experience`](/reference/management-api/schema/experience#experience) | Query | Get an experience by ID within a workspace. |
+| [`experienceCreate`](/reference/management-api/schema/experience#experiencecreate) | Mutation | Create a new experience. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`experienceDelete`](/reference/management-api/schema/experience#experiencedelete) | Mutation | Delete an experience. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`experienceFlowUpdate`](/reference/management-api/schema/experience#experienceflowupdate) | Mutation | Atomically save all changes to an experience flow. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`experiences`](/reference/management-api/schema/experience#experiences) | Query | List experiences within a workspace. Filter by name with `search` (case-insensitive substring) and order with `sortKey` (default `NAME`) plus `reverse`. |
+| [`experienceUpdate`](/reference/management-api/schema/experience#experienceupdate) | Mutation | Update an experience. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`externalApi`](/reference/management-api/schema/external-api#externalapi) | Query | Fetch a single external API by ID, or null if it does not exist. Requires authentication and `ORGANIZATION_INTEGRATIONS_READ` on its project. |
+| [`externalApiAuthHeaderClear`](/reference/management-api/schema/external-api#externalapiauthheaderclear) | Mutation | Remove the static auth header from an external API. Idempotent. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected. |
+| [`externalApiAuthHeaderSet`](/reference/management-api/schema/external-api#externalapiauthheaderset) | Mutation | Set or replace the single static auth header on an external API, removing an OAuth2 credential it holds. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected. |
+| [`externalApiCreate`](/reference/management-api/schema/external-api#externalapicreate) | Mutation | Register an external API to a project. Requires a user context and `ORGANIZATION_INTEGRATIONS_CREATE`; API keys are rejected. |
+| [`externalApiDelete`](/reference/management-api/schema/external-api#externalapidelete) | Mutation | Delete an external API registration and its encrypted credentials. Idempotent. Requires a user context and `ORGANIZATION_INTEGRATIONS_DELETE`; API keys are rejected. |
+| [`externalApiOAuth2Clear`](/reference/management-api/schema/external-api#externalapioauth2clear) | Mutation | Remove the OAuth2 credential, its secrets and its cached access token from an external API. Idempotent. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected. |
+| [`externalApiOAuth2Set`](/reference/management-api/schema/external-api#externalapioauth2set) | Mutation | Set or replace the OAuth2 credential on an external API, removing a static auth header it holds. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected. |
+| [`externalApiUpdate`](/reference/management-api/schema/external-api#externalapiupdate) | Mutation | Rename an external API. Requires a user context and `ORGANIZATION_INTEGRATIONS_UPDATE`; API keys are rejected. |
+| [`feature`](/reference/management-api/schema/feature#feature) | Query | Fetch a single feature by ID and workspace ID. Requires authentication. |
+| [`featureCreate`](/reference/management-api/schema/feature#featurecreate) | Mutation | Create a new feature. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`featureDelete`](/reference/management-api/schema/feature#featuredelete) | Mutation | Delete a feature. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`features`](/reference/management-api/schema/feature#features) | Query | List features in a workspace. Filter by name with `search` (case-insensitive substring) and order with `sortKey` (default `NAME`) plus `reverse`. |
+| [`featureUpdate`](/reference/management-api/schema/feature#featureupdate) | Mutation | Update a feature. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`feedbackCreate`](/reference/management-api/schema/feedback#feedbackcreate) | Mutation | Submit user feedback from the dashboard. Requires authentication (USER token only). |
+| [`field`](/reference/management-api/schema/field#field) | Query | Get a field by ID within a workspace. |
+| [`fieldCreate`](/reference/management-api/schema/field#fieldcreate) | Mutation | Create a new field. Requires scope: `ORGANIZATION_PROJECTS_CREATE`. |
+| [`fieldDelete`](/reference/management-api/schema/field#fielddelete) | Mutation | Delete a field. Requires scope: `ORGANIZATION_PROJECTS_DELETE`. |
+| [`fields`](/reference/management-api/schema/field#fields) | Query | Get list of fields within a workspace. |
+| [`fieldUpdate`](/reference/management-api/schema/field#fieldupdate) | Mutation | Update a field. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`integrationConfigurationCreate`](/reference/management-api/schema/integration#integrationconfigurationcreate) | Mutation | Create a configuration for an installed integration. Requires scope: `ORGANIZATION_INTEGRATIONS_CREATE`. |
+| [`integrationConfigurationDelete`](/reference/management-api/schema/integration#integrationconfigurationdelete) | Mutation | Delete an integration's configuration. Requires scope: `ORGANIZATION_INTEGRATIONS_DELETE`. |
+| [`integrationConfigurationUpdate`](/reference/management-api/schema/integration#integrationconfigurationupdate) | Mutation | Update an integration's configuration. Requires scope: `ORGANIZATION_INTEGRATIONS_UPDATE`. |
+| [`integrationInstall`](/reference/management-api/schema/integration#integrationinstall) | Mutation | Install an integration for a project. Requires scope: `ORGANIZATION_INTEGRATIONS_CREATE`. |
+| [`integrationUninstall`](/reference/management-api/schema/integration#integrationuninstall) | Mutation | Uninstall an integration (cascades to delete all configurations). Requires scope: `ORGANIZATION_INTEGRATIONS_DELETE`. |
+| [`labelsDelete`](/reference/management-api/schema/label#labelsdelete) | Mutation | Remove labels from an owner. Requires scope: `ORGANIZATION_LEADS_UPDATE` on the lead's project for a `LEAD` owner, and `ORGANIZATION_PROJECTS_UPDATE` on the project for a `PROJECT` or `WORKFLOW_RUN` owner. |
+| [`labelsSet`](/reference/management-api/schema/label#labelsset) | Mutation | Create or replace labels on an owner. Requires scope: `ORGANIZATION_LEADS_UPDATE` on the lead's project for a `LEAD` owner, and `ORGANIZATION_PROJECTS_UPDATE` on the project for a `PROJECT` or `WORKFLOW_RUN` owner. |
+| [`lead`](/reference/management-api/schema/lead#lead) | Query | Get a lead by ID. Requires scope: `ORGANIZATION_LEADS_READ`. |
+| [`leadDelete`](/reference/management-api/schema/lead#leaddelete) | Mutation | Permanently delete a lead and its labels. Requires scope: `ORGANIZATION_LEADS_DELETE`. |
+| [`magicLinkSend`](/reference/management-api/schema/auth#magiclinksend) | Mutation | Email an existing account a sign-in code and link. Never creates an account, and answers `success: true` for an address with no account. |
+| [`magicLinkVerify`](/reference/management-api/schema/auth#magiclinkverify) | Mutation | Verify the code from a sign-in or confirmation email and create a session. |
+| [`mcpServer`](/reference/management-api/schema/mcp-server#mcpserver) | Query | Fetch a single registered MCP server by ID, or null if it doesn't exist. Requires authentication. |
+| [`mcpServerAuthHeaderClear`](/reference/management-api/schema/mcp-server#mcpserverauthheaderclear) | Mutation | Remove the auth header from an MCP server. Idempotent. Requires a user context; API keys are rejected. |
+| [`mcpServerAuthHeaderSet`](/reference/management-api/schema/mcp-server#mcpserverauthheaderset) | Mutation | Set or replace the single auth header on an MCP server. Requires a user context; API keys are rejected. |
+| [`mcpServerDelete`](/reference/management-api/schema/mcp-server#mcpserverdelete) | Mutation | Delete an MCP server registration and any encrypted credentials. Idempotent. |
+| [`mcpServerRegister`](/reference/management-api/schema/mcp-server#mcpserverregister) | Mutation | Register a new third-party MCP server. Requires a user context; API keys are rejected. |
+| [`mcpServerUpdate`](/reference/management-api/schema/mcp-server#mcpserverupdate) | Mutation | Update an MCP server's display name. URL rotation goes through `mcpServerUrlSet`. Requires a user context; API keys are rejected. |
+| [`mcpServerUrlSet`](/reference/management-api/schema/mcp-server#mcpserverurlset) | Mutation | Rotate the MCP server's URL. The new URL is encrypted; the response surfaces only the display URL. Requires a user context; API keys are rejected. |
+| [`mfaChallengeCreate`](/reference/management-api/schema/auth#mfachallengecreate) | Mutation | Open a challenge against one of the caller's factors. Requires a user session; exempt from the MFA policy. |
+| [`mfaChallengeVerify`](/reference/management-api/schema/auth#mfachallengeverify) | Mutation | Verify a code against a challenge and lift the caller's session to `AAL2`. Requires a user session; exempt from the MFA policy. |
+| [`mfaFactorEnroll`](/reference/management-api/schema/auth#mfafactorenroll) | Mutation | Enrol an authenticator app for the caller. Requires a user session; exempt from the MFA policy. |
+| [`mfaFactorUnenroll`](/reference/management-api/schema/auth#mfafactorunenroll) | Mutation | Remove one of the caller's factors. Requires a user session; exempt from the MFA policy, though removing a verified factor needs `AAL2`. |
+| [`oauthAuthorize`](/reference/management-api/schema/auth#oauthauthorize) | Mutation | Initiate an OAuth authorisation flow. |
+| [`oauthCallback`](/reference/management-api/schema/auth#oauthcallback) | Mutation | Handle the OAuth callback and create a session. |
+| [`oauthConsentApprove`](/reference/management-api/schema/auth#oauthconsentapprove) | Mutation | Approve an OAuth consent request. Requires authentication. |
+| [`oauthConsentDeny`](/reference/management-api/schema/auth#oauthconsentdeny) | Mutation | Deny an OAuth consent request. Requires authentication. |
+| [`oauthConsentDetails`](/reference/management-api/schema/auth#oauthconsentdetails) | Query | Get OAuth consent authorisation details. Requires authentication (USER token only). |
+| [`organization`](/reference/management-api/schema/organization#organization) | Query | Fetch a single organisation by ID or slug. Requires authentication. |
+| [`organizationClientManagerScopesUpdate`](/reference/management-api/schema/organization#organizationclientmanagerscopesupdate) | Mutation | Set the scopes a client manager holds in one organisation. Requires `STAFF_INVITE_CLIENT_MANAGER` at root. The target must be a client manager, and a caller may not edit their own scopes. A client manager may add or remove only scopes their own client-manager grant in that organisation carries; a super admin may set any. |
+| [`organizationCreate`](/reference/management-api/schema/organization#organizationcreate) | Mutation | Create a new organisation. Requires scope: `ORGANIZATION_CREATE`. |
+| [`organizationDelete`](/reference/management-api/schema/organization#organizationdelete) | Mutation | Delete an organisation. Requires scope: `ORGANIZATION_DELETE`. |
+| [`organizationInvitationAccept`](/reference/management-api/schema/organization#organizationinvitationaccept) | Mutation | Accept an organisation invitation. Requires authentication. |
+| [`organizationInvitationDecline`](/reference/management-api/schema/organization#organizationinvitationdecline) | Mutation | Decline an organisation invitation. Requires authentication. |
+| [`organizationInvitationRevoke`](/reference/management-api/schema/organization#organizationinvitationrevoke) | Mutation | Revoke an organisation invitation. Requires scope: `ORGANIZATION_INVITATIONS_DELETE`. |
+| [`organizationMemberInvite`](/reference/management-api/schema/organization#organizationmemberinvite) | Mutation | Invite a member to an organisation. Requires scope: `ORGANIZATION_INVITATIONS_CREATE`. |
+| [`organizationMemberRemove`](/reference/management-api/schema/organization#organizationmemberremove) | Mutation | Remove a member from an organisation. Requires scope: `ORGANIZATION_MEMBERS_DELETE`. |
+| [`organizationMemberScopesUpdate`](/reference/management-api/schema/organization#organizationmemberscopesupdate) | Mutation | Set the scopes a member holds in an organisation. Requires `ORGANIZATION_MEMBERS_MANAGE_SCOPES` reaching that organisation. The target must be a member. A caller may not grant a scope they do not themselves hold, and may not edit their own scopes. |
+| [`organizations`](/reference/management-api/schema/organization#organizations) | Query | List organisations the authenticated user belongs to. Requires authentication. |
+| [`organizationShopifyWebhooks`](/reference/management-api/schema/shopify#organizationshopifywebhooks) | Query |  |
+| [`organizationUpdate`](/reference/management-api/schema/organization#organizationupdate) | Mutation | Update an organisation. Requires scope: `ORGANIZATION_UPDATE`. |
+| [`passwordResetSend`](/reference/management-api/schema/auth#passwordresetsend) | Mutation | Send a password reset email. |
+| [`passwordUpdate`](/reference/management-api/schema/auth#passwordupdate) | Mutation | Update the current user's password. Requires authentication. An `AAL1` session may set a password only while the user holds no verified factor, and is otherwise refused with `MFA_REQUIRED`. |
+| [`pickedqlQuery`](/reference/management-api/schema/analytics#pickedqlquery) | Query | Execute a PickedQL query scoped to the caller's authorised projects. |
+| [`ping`](/reference/management-api/schema/common#ping) | Query | Liveness probe used by infrastructure to confirm the GraphQL endpoint is up. Unauthenticated. |
+| [`project`](/reference/management-api/schema/project#project) | Query | Fetch a single project by ID. Requires authentication. |
+| [`projectCreate`](/reference/management-api/schema/project#projectcreate) | Mutation | Create a new project. Requires scope: `ORGANIZATION_PROJECTS_CREATE`. |
+| [`projectDelete`](/reference/management-api/schema/project#projectdelete) | Mutation | Delete a project. Requires scope: `ORGANIZATION_PROJECTS_DELETE`. |
+| [`projectPreviewEnvironmentCreate`](/reference/management-api/schema/project#projectpreviewenvironmentcreate) | Mutation | Create a project preview environment. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`projectPreviewEnvironmentDelete`](/reference/management-api/schema/project#projectpreviewenvironmentdelete) | Mutation | Delete a project preview environment. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`projectPreviewEnvironmentUpdate`](/reference/management-api/schema/project#projectpreviewenvironmentupdate) | Mutation | Update a project preview environment. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`projects`](/reference/management-api/schema/project#projects) | Query | List projects the authenticated user can reach, across every organisation they belong to. Pass `organizationId` to narrow the list to one organisation, and `search` to match project names case-insensitively. Requires authentication. |
+| [`projectShopifyMetafieldConfigs`](/reference/management-api/schema/shopify#projectshopifymetafieldconfigs) | Query |  |
+| [`projectUpdate`](/reference/management-api/schema/project#projectupdate) | Mutation | Update a project. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`report`](/reference/management-api/schema/report#report) | Query | Fetch a single report by id. Requires authentication. |
+| [`reportCreate`](/reference/management-api/schema/report#reportcreate) | Mutation | Create a new report. Requires scope: `ORGANIZATION_REPORTS_CREATE`. |
+| [`reportDelete`](/reference/management-api/schema/report#reportdelete) | Mutation | Delete a report. Requires scope: `ORGANIZATION_REPORTS_DELETE`. |
+| [`reportUpdate`](/reference/management-api/schema/report#reportupdate) | Mutation | Update a report. Requires scope: `ORGANIZATION_REPORTS_UPDATE`. |
+| [`savedView`](/reference/management-api/schema/saved-view#savedview) | Query | Get a saved view by ID. Requires scope: `ORGANIZATION_PROJECTS_READ`. |
+| [`savedViewCreate`](/reference/management-api/schema/saved-view#savedviewcreate) | Mutation | Save a view of a project's list. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`savedViewDelete`](/reference/management-api/schema/saved-view#savedviewdelete) | Mutation | Delete a saved view. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`savedViewUpdate`](/reference/management-api/schema/saved-view#savedviewupdate) | Mutation | Rename a saved view, change what it restores, or move the default. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`sessionCreate`](/reference/management-api/schema/auth#sessioncreate) | Mutation | Create a new session by signing in with email and password. |
+| [`sessionRefresh`](/reference/management-api/schema/auth#sessionrefresh) | Mutation | Refresh an existing session using a refresh token. |
+| [`sessionStart`](/reference/management-api/schema/auth#sessionstart) | Mutation | Begin signing in with an email address alone. Answers `PASSWORD` when the account has set a password, and otherwise emails a sign-in code and link and answers `EMAIL_CODE`. Never creates an account. Returns `RATE_LIMITED` when the caller makes too many requests, or when the project's email quota is spent. |
+| [`shopifyCollectionContentUpdate`](/reference/management-api/schema/shopify#shopifycollectioncontentupdate) | Mutation | Update Shopify collection content. Requires authentication. |
+| [`shopifyMetafieldConfigCreate`](/reference/management-api/schema/shopify#shopifymetafieldconfigcreate) | Mutation | Create a Shopify metafield config. Requires authentication. |
+| [`shopifyMetafieldConfigDelete`](/reference/management-api/schema/shopify#shopifymetafieldconfigdelete) | Mutation | Delete a Shopify metafield config. Requires authentication. |
+| [`shopifyMetafieldConfigs`](/reference/management-api/schema/shopify#shopifymetafieldconfigs) | Query | List Shopify metafield configs for a project. Requires authentication. |
+| [`shopifyMetafieldConfigUpdate`](/reference/management-api/schema/shopify#shopifymetafieldconfigupdate) | Mutation | Update a Shopify metafield config. Requires authentication. |
+| [`shopifyProduct`](/reference/management-api/schema/shopify#shopifyproduct) | Query |  |
+| [`shopifyProductContentUpdate`](/reference/management-api/schema/shopify#shopifyproductcontentupdate) | Mutation | Update Shopify product content. Requires authentication. |
+| [`shopifyProducts`](/reference/management-api/schema/shopify#shopifyproducts) | Query |  |
+| [`shopifyWebhookCreate`](/reference/management-api/schema/shopify#shopifywebhookcreate) | Mutation | Create a new Shopify webhook. Requires authentication. |
+| [`shopifyWebhookDelete`](/reference/management-api/schema/shopify#shopifywebhookdelete) | Mutation | Delete a Shopify webhook. Requires authentication. |
+| [`shopifyWebhooks`](/reference/management-api/schema/shopify#shopifywebhooks) | Query | List Shopify webhooks for an organisation. Requires authentication. |
+| [`shopifyWebhookUpdate`](/reference/management-api/schema/shopify#shopifywebhookupdate) | Mutation | Update a Shopify webhook. Requires authentication. |
+| [`step`](/reference/management-api/schema/step#step) | Query | Get a step by ID within a workspace. |
+| [`stepCreate`](/reference/management-api/schema/step#stepcreate) | Mutation | Create a new step. Requires scope: `ORGANIZATION_PROJECTS_CREATE`. |
+| [`stepDelete`](/reference/management-api/schema/step#stepdelete) | Mutation | Delete a step. Requires scope: `ORGANIZATION_PROJECTS_DELETE`. |
+| [`steps`](/reference/management-api/schema/step#steps) | Query | Get list of steps within a workspace. |
+| [`stepUpdate`](/reference/management-api/schema/step#stepupdate) | Mutation | Update a step. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`tenant`](/reference/management-api/schema/tenant-branding#tenant) | Query | Resolve a tenant (and its branding) by host or explicit slug. Unauthenticated; cached for 5 minutes. |
+| [`updateShopifyCollectionContent`](/reference/management-api/schema/shopify#updateshopifycollectioncontent) | Mutation |  |
+| [`updateShopifyMetafieldConfig`](/reference/management-api/schema/shopify#updateshopifymetafieldconfig) | Mutation |  |
+| [`updateShopifyProductContent`](/reference/management-api/schema/shopify#updateshopifyproductcontent) | Mutation |  |
+| [`updateShopifyWebhook`](/reference/management-api/schema/shopify#updateshopifywebhook) | Mutation |  |
+| [`user`](/reference/management-api/schema/auth#user) | Query | Fetch the currently authenticated user. Returns null if the request is unauthenticated. Exempt from the MFA policy, so a gated user can read `mfa` and `mfaFactors`. |
+| [`viewerScopes`](/reference/management-api/schema/auth#viewerscopes) | Query | Root-level scopes for the authenticated user (e.g. `ORGANIZATION_CREATE`, `STAFF_READ`). Use `Organization.viewerScopes` for org-scoped scopes. |
+| [`workbenchAssetAdoptOwned`](/reference/management-api/schema/workbench#workbenchassetadoptowned) | Mutation | Adopts an existing project-library Asset as `OWNED` by a Workbench, transferring the Asset's ownership. Used when a Create-Page upload is bound to its Workbench after the Workbench is created. |
+| [`workbenchAssetImport`](/reference/management-api/schema/workbench#workbenchassetimport) | Mutation | Imports an Asset owned elsewhere into a Workbench, creating an `IMPORTED` membership. Removing the import (`workbenchAssetRemove`) drops only the join, never the Asset. |
+| [`workbenchAssetRemove`](/reference/management-api/schema/workbench#workbenchassetremove) | Mutation | Removes an Asset's membership from a Workbench. If the membership was `OWNED`, the Asset is also soft-deleted; if `IMPORTED`, only the join is dropped. |
+| [`workflow`](/reference/management-api/schema/workflow#workflow) | Query | Get a workflow by ID. |
+| [`workflowCreate`](/reference/management-api/schema/workflow#workflowcreate) | Mutation | Create a new workflow. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`workflowDelete`](/reference/management-api/schema/workflow#workflowdelete) | Mutation | Delete a workflow. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`workflowGraphUpdate`](/reference/management-api/schema/workflow#workflowgraphupdate) | Mutation | Apply a batch of changes to a workflow's graph, all or nothing. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`workflowRun`](/reference/management-api/schema/workflow-run#workflowrun) | Query | Get a workflow run by ID. Requires scope: `ORGANIZATION_PROJECTS_READ`. |
+| [`workflows`](/reference/management-api/schema/workflow#workflows) | Query | List workflows in a workspace. Filter by name with `search` (case-insensitive substring) and order with `sortKey` (default `NAME`) plus `reverse`. |
+| [`workflowTestRun`](/reference/management-api/schema/workflow#workflowtestrun) | Mutation | Walk a workflow's draft graph once against a supplied trigger input, holding every write back, and return what each node did. Nothing is stored. Requires scope `ORGANIZATION_WORKSPACE_UPDATE` and every scope in `Workflow.scopes`; a refusal names each one missing. |
+| [`workflowTools`](/reference/management-api/schema/workflow#workflowtools) | Query | Every tool a workflow node may run, with the arguments each accepts. Read by the editor to build its node palette. |
+| [`workflowUpdate`](/reference/management-api/schema/workflow#workflowupdate) | Mutation | Update a workflow. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`workspace`](/reference/management-api/schema/workspace#workspace) | Query | Get a specific workspace. Requires authentication. |
+| [`workspaceArchive`](/reference/management-api/schema/workspace#workspacearchive) | Mutation | Archive a non-live workspace. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`workspaceContentEntryValidation`](/reference/management-api/schema/cms-models#workspacecontententryvalidation) | Query | Run schema validation across every Content Entry in a workspace and report which rows no longer conform. Read-only — does not auto-fix. Useful as a pre-publish sanity gate, especially after a Content Block schema change. Optionally narrow the sweep to a single Content Model with `contentModelId`. |
+| [`workspaceCreate`](/reference/management-api/schema/workspace#workspacecreate) | Mutation | Create a new workspace on a project. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`workspaceDelete`](/reference/management-api/schema/workspace#workspacedelete) | Mutation | Soft-delete a non-live workspace. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`workspaceDiff`](/reference/management-api/schema/workspace-version#workspacediff) | Query | Compute a structural diff between two workspace snapshots. Each side can be either a live workspace (diffed against its current draft snapshot) or a previously-published `WorkspaceVersion`. Requires authentication and `ORGANIZATION_PROJECTS_READ` scope on the project shared by both sides. |
+| [`workspaceDuplicate`](/reference/management-api/schema/workspace#workspaceduplicate) | Mutation | Duplicate an existing workspace with all of its child entities, including its workflows. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`workspaceExport`](/reference/management-api/schema/workspace#workspaceexport) | Query | Export a workspace and every entity in it as a portable JSON bundle, with a manifest of the asset versions its content references. The asset bytes are not included; download each from its `downloadUrl`. Requires scope: `ORGANIZATION_PROJECTS_READ` on the workspace's project. |
+| [`workspaceImport`](/reference/management-api/schema/workspace#workspaceimport) | Mutation | Create a new draft workspace in a project from a bundle returned by `workspaceExport`, committing every entity in one transaction. Requires scope: `ORGANIZATION_PROJECTS_UPDATE` on the target project. |
+| [`workspacePublish`](/reference/management-api/schema/workspace#workspacepublish) | Mutation | Publish a workspace, creating an immutable version snapshot. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`workspaceUnarchive`](/reference/management-api/schema/workspace#workspaceunarchive) | Mutation | Unarchive an archived workspace (restores it to `DRAFT`). Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`workspaceUpdate`](/reference/management-api/schema/workspace#workspaceupdate) | Mutation | Rename an existing workspace. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+| [`workspaceVersionPublish`](/reference/management-api/schema/workspace#workspaceversionpublish) | Mutation | Promote a previously-published `WorkspaceVersion` to be its project's served (live) version by pointing `projects.live_workspace_version_id` at it and stamping the owning workspace's `publishedAt` with that version's original publish timestamp. Works for the latest version (re-publish) or an earlier one (rollback, in product terms). No new `WorkspaceVersion` row is appended. The target workspace becomes the project's live one (an archived workspace is un-archived). The draft state is NOT modified, so if the draft differs from the published snapshot it shows up as "unpublished changes" in the UI. Use `workspaceDiff` with `(baseWorkspaceId, compareWorkspaceVersionId)` to preview the impact before invoking this mutation. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`. |
+
+## Domains
+
+- [Action](/reference/management-api/schema/action)
+- [Analytics session](/reference/management-api/schema/analytics-session)
+- [Analytics](/reference/management-api/schema/analytics)
+- [Api key](/reference/management-api/schema/api-key)
+- [Auth](/reference/management-api/schema/auth)
+- [Cms fields](/reference/management-api/schema/cms-fields)
+- [Cms models](/reference/management-api/schema/cms-models)
+- [Common](/reference/management-api/schema/common)
+- [Condition](/reference/management-api/schema/condition)
+- [Design system](/reference/management-api/schema/design-system)
+- [Experience](/reference/management-api/schema/experience)
+- [External api](/reference/management-api/schema/external-api)
+- [Feature](/reference/management-api/schema/feature)
+- [Feedback](/reference/management-api/schema/feedback)
+- [Field](/reference/management-api/schema/field)
+- [Integration](/reference/management-api/schema/integration)
+- [Label](/reference/management-api/schema/label)
+- [Lead](/reference/management-api/schema/lead)
+- [Mcp server](/reference/management-api/schema/mcp-server)
+- [Metric](/reference/management-api/schema/metric)
+- [Operation](/reference/management-api/schema/operation)
+- [Organization](/reference/management-api/schema/organization)
+- [Project](/reference/management-api/schema/project)
+- [Report](/reference/management-api/schema/report)
+- [Saved view](/reference/management-api/schema/saved-view)
+- [Shopify](/reference/management-api/schema/shopify)
+- [Step](/reference/management-api/schema/step)
+- [Tenant branding](/reference/management-api/schema/tenant-branding)
+- [Workbench](/reference/management-api/schema/workbench)
+- [Workflow run](/reference/management-api/schema/workflow-run)
+- [Workflow](/reference/management-api/schema/workflow)
+- [Workspace version](/reference/management-api/schema/workspace-version)
+- [Workspace](/reference/management-api/schema/workspace)

package/docs/reference/management-api/schema/integration.md

@@ -0,0 +1,272 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Integration schema
+
+The operations and types that `integration.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Mutations
+
+### `integrationInstall`
+
+Install an integration for a project. Requires scope: `ORGANIZATION_INTEGRATIONS_CREATE`.
+
+```graphql
+integrationInstall(input: IntegrationInstallInput!): IntegrationInstallPayload! @auth
+```
+
+### `integrationUninstall`
+
+Uninstall an integration (cascades to delete all configurations). Requires scope: `ORGANIZATION_INTEGRATIONS_DELETE`.
+
+```graphql
+integrationUninstall(id: ID!): IntegrationUninstallPayload! @auth
+```
+
+### `integrationConfigurationCreate`
+
+Create a configuration for an installed integration. Requires scope: `ORGANIZATION_INTEGRATIONS_CREATE`.
+
+```graphql
+integrationConfigurationCreate(input: IntegrationConfigurationCreateInput!): IntegrationConfigurationCreatePayload! @auth
+```
+
+### `integrationConfigurationUpdate`
+
+Update an integration's configuration. Requires scope: `ORGANIZATION_INTEGRATIONS_UPDATE`.
+
+```graphql
+integrationConfigurationUpdate(id: ID!, input: IntegrationConfigurationUpdateInput!): IntegrationConfigurationUpdatePayload! @auth
+```
+
+### `integrationConfigurationDelete`
+
+Delete an integration's configuration. Requires scope: `ORGANIZATION_INTEGRATIONS_DELETE`.
+
+```graphql
+integrationConfigurationDelete(id: ID!, type: IntegrationType!): IntegrationConfigurationDeletePayload! @auth
+```
+
+## Types
+
+### `IntegrationType`
+
+```graphql
+"""Integration types available for project configuration."""
+enum IntegrationType {
+  """
+  Vercel deployment integration — fires deploy hooks on workspace publish.
+  """
+  VERCEL
+}
+```
+
+### `Integration`
+
+```graphql
+"""
+An integration installed for a project. Created via `integrationInstall`;
+removed via `integrationUninstall` (cascades to the configuration).
+
+`configuration` is null until `integrationConfigurationCreate` is
+invoked. The configuration union is resolved by `type`.
+"""
+type Integration {
+  """Unique integration identifier."""
+  id: ID!
+  """ID of the project this integration belongs to."""
+  projectId: ID!
+  """The type of integration."""
+  type: IntegrationType!
+  """When this integration was installed."""
+  installedAt: DateTime!
+  """When this integration was last updated."""
+  updatedAt: DateTime!
+  """The project this integration belongs to."""
+  project: Project!
+  """
+  Integration-specific configuration (resolved by `type`). Null until `integrationConfigurationCreate` is invoked.
+  """
+  configuration: IntegrationConfiguration @auth
+}
+```
+
+### `IntegrationConfiguration`
+
+```graphql
+"""
+Union of all integration-specific configuration types. New types extend this union.
+"""
+union IntegrationConfiguration = VercelConfiguration
+```
+
+### `VercelConfiguration`
+
+```graphql
+"""
+Configuration for a Vercel integration with deploy hooks. Fires the
+configured hooks on workspace publish so the downstream Vercel project
+re-deploys with the latest content.
+"""
+type VercelConfiguration {
+  """Unique configuration identifier."""
+  id: ID!
+  """ID of the parent integration."""
+  integrationId: ID!
+  """List of deploy hooks configured for this integration."""
+  deployHooks: [VercelDeployHook!]!
+  """When this configuration was created."""
+  createdAt: DateTime!
+  """When this configuration was last updated."""
+  updatedAt: DateTime!
+}
+```
+
+### `VercelDeployHook`
+
+```graphql
+"""A Vercel deploy hook with environment name and URL."""
+type VercelDeployHook {
+  """
+  Environment name (e.g. `Production`, `Staging`). Shown in the dashboard.
+  """
+  name: String!
+  """
+  Vercel deploy hook URL. Treat as sensitive — anyone with this URL can trigger the deploy.
+  """
+  hookUrl: String!
+}
+```
+
+### `IntegrationInstallInput`
+
+```graphql
+"""Input for `integrationInstall`."""
+input IntegrationInstallInput {
+  """ID of the project to install the integration for."""
+  projectId: ID!
+  """Type of integration to install."""
+  type: IntegrationType!
+}
+```
+
+### `IntegrationInstallPayload`
+
+```graphql
+"""Payload returned by `integrationInstall`."""
+type IntegrationInstallPayload {
+  """
+  The installed integration. Configuration is null until `integrationConfigurationCreate` is invoked.
+  """
+  integration: Integration
+}
+```
+
+### `IntegrationUninstallPayload`
+
+```graphql
+"""
+Payload returned by `integrationUninstall`. Removing an integration cascades to its configuration.
+"""
+type IntegrationUninstallPayload {
+  """Whether the uninstall was successful."""
+  success: Boolean!
+}
+```
+
+### `VercelDeployHookInput`
+
+```graphql
+"""Input for a Vercel deploy hook."""
+input VercelDeployHookInput {
+  """Environment name (e.g. `Production`, `Staging`)."""
+  name: String!
+  """Vercel deploy hook URL."""
+  hookUrl: String!
+}
+```
+
+### `VercelConfigurationInput`
+
+```graphql
+"""
+Vercel-specific configuration input for `integrationConfigurationCreate`.
+"""
+input VercelConfigurationInput {
+  """Deploy hooks for this configuration."""
+  deployHooks: [VercelDeployHookInput!]!
+}
+```
+
+### `VercelConfigurationUpdateFields`
+
+```graphql
+"""
+Vercel-specific fields for `integrationConfigurationUpdate`. Omit a field to leave it unchanged.
+"""
+input VercelConfigurationUpdateFields {
+  """Updated deploy hooks. Replaces the existing list when set."""
+  deployHooks: [VercelDeployHookInput!]
+}
+```
+
+### `IntegrationConfigurationCreateInput`
+
+```graphql
+"""
+Input for `integrationConfigurationCreate`. Set the sub-input that matches the integration's `type`.
+"""
+input IntegrationConfigurationCreateInput {
+  """ID of the integration to create the configuration for."""
+  integrationId: ID!
+  """
+  Vercel-specific configuration. Provide when the integration type is `VERCEL`.
+  """
+  vercel: VercelConfigurationInput
+}
+```
+
+### `IntegrationConfigurationCreatePayload`
+
+```graphql
+"""Payload returned by `integrationConfigurationCreate`."""
+type IntegrationConfigurationCreatePayload {
+  """The created configuration."""
+  configuration: IntegrationConfiguration
+}
+```
+
+### `IntegrationConfigurationUpdateInput`
+
+```graphql
+"""Input for `integrationConfigurationUpdate`."""
+input IntegrationConfigurationUpdateInput {
+  """
+  Vercel-specific configuration updates. Provide when the integration type is `VERCEL`.
+  """
+  vercel: VercelConfigurationUpdateFields
+}
+```
+
+### `IntegrationConfigurationUpdatePayload`
+
+```graphql
+"""Payload returned by `integrationConfigurationUpdate`."""
+type IntegrationConfigurationUpdatePayload {
+  """The updated configuration."""
+  configuration: IntegrationConfiguration
+}
+```
+
+### `IntegrationConfigurationDeletePayload`
+
+```graphql
+"""Payload returned by `integrationConfigurationDelete`."""
+type IntegrationConfigurationDeletePayload {
+  """Whether the deletion was successful."""
+  success: Boolean!
+}
+```