# Govform API endpoint index

Source: https://govform.com/resources/documentation/article/33-10-api-endpoint-reference
Topic: Govform API & MCP

Find the customer REST endpoints for services, definitions, submitted data, files, analytics, Collection programmes, User portal settings and data source discovery, and Darcy tools. Each entry links to its request, response and permission guidance.

## API hosts and authentication

**Builder:** `https://app.govform.com`, or your private Builder host. **QA:** `https://qa.cloud.govforms.uk`. **Production:** `https://cloud.govforms.uk`. Use the configured host for your organisation's other environments.

Library REST calls use a library API key through Authorization: GovformsApiKey <key-id>:<key-secret>, or GovformsApiHmac. Only grant the permissions your integration needs. JSON writes use Content-Type: application/json. API usage follows the [shared units and limits](<https://govform.com/resources/documentation/article/33-govforms-api#api-units-and-limits>).

Use [service discovery](<https://govform.com/resources/documentation/article/33-09-api-list-services-and-form-schemas>) when you know the library ID but need its Service IDs. Builder definitions can differ from deployed versions; use the target environment's status endpoint to verify what is running.

## Builder service, portal and Darcy endpoints

Call these paths on the Builder host. Permission alternatives mean either named permission is sufficient; individual tools may impose additional checks described in their guide.

| Method and path | API-key permission | Guide |
| --- | --- | --- |
| `GET /builder/libraries/{libraryId}/api/caseworker-portal` | apiCaseworkerPortalRead | [Caseworker portal settings](<https://govform.com/resources/documentation/article/33-18-api-caseworker-portal>) |
| `PATCH /builder/libraries/{libraryId}/api/caseworker-portal` | apiCaseworkerPortalWrite | [Caseworker portal settings](<https://govform.com/resources/documentation/article/33-18-api-caseworker-portal>) |
| `GET /builder/libraries/{libraryId}/api/user-portal` | apiPortalRead | [Read, update and deploy User portal settings](<https://govform.com/resources/documentation/article/33-12-api-user-portal>) |
| `PATCH /builder/libraries/{libraryId}/api/user-portal` | apiPortalWrite | [Read, update and deploy User portal settings](<https://govform.com/resources/documentation/article/33-12-api-user-portal>) |
| `POST /builder/libraries/{libraryId}/api/user-portal/deployments` | apiPortalDeploy | [Read, update and deploy User portal settings](<https://govform.com/resources/documentation/article/33-12-api-user-portal>) |
| `GET /builder/libraries/{libraryId}/api/forms` | apiOrgRead | [List services, metadata and form schemas](<https://govform.com/resources/documentation/article/33-09-api-list-services-and-form-schemas>) |
| `POST /builder/libraries/{libraryId}/api/forms/{formId}` | apiFormWrite | [Create, update and delete services through the API](<https://govform.com/resources/documentation/article/33-11-api-service-design-and-deployment>) |
| `DELETE /builder/libraries/{libraryId}/api/forms/{formId}` | apiFormWrite | [Create, update and delete services through the API](<https://govform.com/resources/documentation/article/33-11-api-service-design-and-deployment>) |
| `GET /builder/libraries/{libraryId}/api/form/{formId}` | apiFormRead | [List services, metadata and form schemas](<https://govform.com/resources/documentation/article/33-09-api-list-services-and-form-schemas>) |
| `GET /builder/libraries/{libraryId}/api/form/{formId}/summary` | apiFormRead | [List services, metadata and form schemas](<https://govform.com/resources/documentation/article/33-09-api-list-services-and-form-schemas>) |
| `PUT /builder/libraries/{libraryId}/api/save-form-version/{formId}` | apiFormWrite | [Create, update and delete services through the API](<https://govform.com/resources/documentation/article/33-11-api-service-design-and-deployment>) |
| `POST /builder/libraries/{libraryId}/api/darcy/form-lock/{formId}` | apiFormWrite | [Create, update and delete services through the API](<https://govform.com/resources/documentation/article/33-11-api-service-design-and-deployment>) |
| `PUT /builder/libraries/{libraryId}/api/darcy/form-lock/{formId}` | apiFormWrite | [Create, update and delete services through the API](<https://govform.com/resources/documentation/article/33-11-api-service-design-and-deployment>) |
| `DELETE /builder/libraries/{libraryId}/api/darcy/form-lock/{formId}` | apiFormWrite | [Create, update and delete services through the API](<https://govform.com/resources/documentation/article/33-11-api-service-design-and-deployment>) |
| `GET /builder/libraries/{libraryId}/api/deployments/{formId}` | apiFormRead | [List services, metadata and form schemas](<https://govform.com/resources/documentation/article/33-09-api-list-services-and-form-schemas>) |
| `POST /builder/libraries/{libraryId}/api/deployments` | apiFormDeploy | [Create, update and delete services through the API](<https://govform.com/resources/documentation/article/33-11-api-service-design-and-deployment>) |
| `GET /builder/libraries/{libraryId}/api/darcy/tools/catalog` | apiDarcyToolRead or apiDarcyToolWrite | [Discover and run Darcy REST tools](<https://govform.com/resources/documentation/article/33-15-api-darcy-tools>) |
| `POST /builder/libraries/{libraryId}/api/darcy/tools/{toolName}` | Tool-specific permission | [Discover and run Darcy REST tools](<https://govform.com/resources/documentation/article/33-15-api-darcy-tools>) |
| `POST /builder/libraries/{libraryId}/api/darcy/ask` | apiDarcyAsk | [Discover and run Darcy REST tools](<https://govform.com/resources/documentation/article/33-15-api-darcy-tools>) |
| `POST /builder/libraries/{libraryId}/api/darcy/agent` | apiDarcyAgent | [Discover and run Darcy REST tools](<https://govform.com/resources/documentation/article/33-15-api-darcy-tools>) |
| `PUT /builder/libraries/{libraryId}/api/upsert-service-definition/{formId}` | upsertServiceDefinition | [Create, update and delete services through the API](<https://govform.com/resources/documentation/article/33-11-api-service-design-and-deployment>) |
| `PUT /builder/libraries/{libraryId}/api/start-deployment/{formId}/{version}/{env}` | triggerServiceDeployment | [Create, update and delete services through the API](<https://govform.com/resources/documentation/article/33-11-api-service-design-and-deployment>) |

## QA and Production data and deployment endpoints

Call these paths on the relevant service environment's host. serviceId is the Service ID without its library prefix.

| Method and path | API-key permission | Guide |
| --- | --- | --- |
| `GET /api/submitted-data/{libraryId}/{serviceId}` | fetchCustomerData | [Fetch submitted form data](<https://govform.com/resources/documentation/article/33-01-api-fetch-submitted-form-data>) |
| `POST /api/submitted-data/{libraryId}/{serviceId}/delete` | deleteSubmittedData | [Delete submitted form data](<https://govform.com/resources/documentation/article/33-06-api-delete-submitted-form-data>) |
| `PUT /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/status` | setFormStatus | [Set submitted form status](<https://govform.com/resources/documentation/article/33-08-api-set-submitted-form-status>) |
| `GET /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/files` | fetchCustomerData | [List and download uploaded files and signatures](<https://govform.com/resources/documentation/article/33-07-api-list-download-uploaded-files>) |
| `GET /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/files/{fieldId}` | fetchCustomerData | [List and download uploaded files and signatures](<https://govform.com/resources/documentation/article/33-07-api-list-download-uploaded-files>) |
| `GET /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/bulk/{fieldId}/{artifact}` | fetchCustomerData | [Bulk Data files and submitted revisions](<https://govform.com/resources/documentation/article/33-14-api-bulk-data-files>) |
| `GET /api/analytics-events/{libraryId}/{serviceId}` | fetchAnalyticsEvents | [Fetch analytics events](<https://govform.com/resources/documentation/article/33-02-api-fetch-analytics-events>) |
| `GET /api/analytics-journeys/{libraryId}/{serviceId}` | fetchAnalyticsJourneys | [Fetch journey analytics records](<https://govform.com/resources/documentation/article/33-03-api-fetch-journey-analytics>) |
| `GET /api/billing-transactions/{libraryId}/{serviceId}` | apiGetBillingTransactions | [Legacy billing transaction totals (1-unit class)](<https://govform.com/resources/documentation/article/33-govforms-api>) |
| `GET /api/service-deployments/{libraryId}/{serviceId}` | getDeployedServiceVersion | [Get deployed service version](<https://govform.com/resources/documentation/article/33-05-api-get-deployed-service-version>) |
| `PUT /api/service-deployments/{libraryId}/{serviceId}/{version}` | triggerServiceDeployment | [Trigger service deployment](<https://govform.com/resources/documentation/article/33-04-api-trigger-service-deployment>) |

## Collection programme endpoints

Call these paths on the Builder host. environment selects the Collection's environment. Creating a Collection additionally requires apiFormWrite; applying its form additionally requires apiFormDeploy. Response Hub must be enabled for the library.

| Method and path | API-key permission | Guide |
| --- | --- | --- |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `PATCH /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `PATCH /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/review-settings` | (apiCollectionProgrammeRead or apiCollectionProgrammeWrite) and (apiFormRead or apiFormWrite) | [Collection review settings](<https://govform.com/resources/documentation/article/33-13-api-response-hub#collection-review-settings>) |
| `PATCH /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/review-settings` | apiCollectionProgrammeWrite and apiFormWrite | [Collection review settings](<https://govform.com/resources/documentation/article/33-13-api-response-hub#collection-review-settings>) |
| `POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/transition/{action}` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/apply-form` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/cohorts` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/cohorts` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `PATCH /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/cohorts/{cohortId}` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/assignments` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/assignments` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/assignments/{assignmentId}/cancel` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}/versions` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}/versions/{versionNumber}/files/{fieldId}/{fileIndex}` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}/versions/{versionNumber}/bulk/{fieldId}/{artifact}` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews/{workItemId}/issues` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews/{workItemId}` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews/{workItemId}/{action}` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/communications` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/audit` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/form-revisions` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId}` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `DELETE /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId}` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId}/manifest` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId}/parts/{partId}` | apiCollectionProgrammeRead or apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/roster` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |
| `POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/roster/{rosterJobId}/apply` | apiCollectionProgrammeWrite | [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) |

## MCP connections and OAuth endpoints

These are Builder endpoints. OAuth discovery and registration prepare the connection; the consent page uses an authenticated browser session. OAuth MCP and its evidence-download links require the connection's bearer token and selected library permissions. Library API-key MCP uses the same library key as REST. Follow the [MCP connection guide](<https://govform.com/resources/documentation/article/33-14-mcp-capabilities>) rather than manually posting to the consent page.

| Method and path | Purpose |
| --- | --- |
| `GET /builder/.well-known/oauth-protected-resource` | MCP resource metadata |
| `GET /builder/.well-known/oauth-authorization-server` | OAuth server metadata |
| `GET /builder/.well-known/openid-configuration` | Discovery metadata alias |
| `POST /builder/oauth/register` | Register an OAuth client |
| `GET /builder/oauth/authorize` | Interactive consent page |
| `POST /builder/oauth/authorize` | Submit consent from the authenticated browser |
| `POST /builder/oauth/token` | Exchange or refresh OAuth tokens |
| `POST /builder/oauth/revoke` | Revoke an OAuth token |
| `GET /builder/mcp` | OAuth MCP transport; requires bearer authentication |
| `POST /builder/mcp` | OAuth MCP protocol requests; requires bearer authentication |
| `POST /builder/libraries/{libraryId}/mcp` | Library API-key MCP protocol requests |
| `GET /builder/libraries/{libraryId}/mcp/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId}/parts/{partId}` | OAuth-authorised export-part download |
| `GET /builder/libraries/{libraryId}/mcp/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}/versions/{versionNumber}/files/{fieldId}/{fileIndex}` | OAuth-authorised submitted file download |
| `GET /builder/libraries/{libraryId}/mcp/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}/versions/{versionNumber}/bulk/{fieldId}/{artifact}` | OAuth-authorised submitted Bulk Data download |

Use the connection URL supplied for the release you intend to use; browser release cookies do not select an MCP release. Evidence links returned by a connection already identify the appropriate download host and path. Never substitute a library API key for the OAuth bearer token on those MCP download links.

## Choose a guide

-   [List services, metadata and form schemas](<https://govform.com/resources/documentation/article/33-09-api-list-services-and-form-schemas>)
-   [Create, update and delete services](<https://govform.com/resources/documentation/article/33-11-api-service-design-and-deployment>)
-   [User portal settings and deployment](<https://govform.com/resources/documentation/article/33-12-api-user-portal>)
-   [Collection programme data, reviews, evidence and exports](<https://govform.com/resources/documentation/article/33-13-api-response-hub>)
-   [Darcy REST tool discovery and execution](<https://govform.com/resources/documentation/article/33-15-api-darcy-tools>)
-   [API-key settings](<https://govform.com/resources/documentation/article/30-govforms-api-key-settings>)

See [authentication headers](<https://govform.com/resources/documentation/article/33-govforms-api#authentication-headers>) for raw-key and HMAC formats.

## Disposable journey testing

`POST /builder/mcp` and `POST /builder/libraries/{libraryId}/mcp` expose `testJourney` when advertised by the connection. The REST equivalent is `POST /builder/libraries/{libraryId}/api/darcy/tools/testJourney`. See [test journeys through MCP and the API](<https://govform.com/resources/documentation/article/33-16-api-journey-tests>) for access, request examples and result interpretation.

## Answer change checkpoints

Collection response Change log reads and retained-file downloads are documented in the [Collection programme API](<https://govform.com/resources/documentation/article/33-13-api-response-hub>). They share its read permissions, environment scope and retention. Live acceptance uses the expected answer state returned by the review read.

## Temporary demos without an account

The separate `POST /builder/try/mcp` connection creates browser demos that expire after 14 days, using a private management token for later changes. It grants no access to existing libraries or deployment. See [Create a temporary demo with an AI client](<https://govform.com/resources/documentation/article/ai-anonymous-demo-services>) for the tools, settings and limits.

## Approved admin submission investigations

Govform staff and configured platform administrators can investigate a specific library’s submissions through the interactive OAuth connection. Customer library administrators and library API keys cannot use these operations. Every search page and retrieval needs its own one-use Builder approval confirming permission from that customer’s GDPR data controller for the exact records and purpose.

| MCP tool | OAuth POST endpoint | Result |
| --- | --- | --- |
| `search_submission_user_data` | `/builder/api/admin-submission-data/search` | Current submission metadata; default 20, maximum 50 records. |
| `get_submission_user_data` | `/builder/api/admin-submission-data/get` | Current journey answers, action results, state and caseworker source linkage. |
| `get_submission_version` | `/builder/api/admin-submission-data/version` | One retained ordinary response version, submitted answers and captured caseworker source linkage. |

All calls select `org`, `formId` and `environment` (`qa`, `staging` or `production`). Retrieval also requires `submissionId`. Version retrieval accepts optional positive `versionNumber`; omit it for the latest retained version. Missing evidence returns not found: it is never reconstructed or replaced by current answers. Collection response versions use the Collection programme operations. Files are metadata only; configured Secrets remain masked.

Supply `approvalDescription` naming the library/customer and purpose. On `CONSENT_REQUIRED`, present the returned `approvalUrl`, wait for the admin to approve in Builder and confirm, then retry the identical request with `approvalToken`. Early access OAuth uses `/builder/early-access/api/admin-submission-data/{search,get,version}`. These reads do not authorise actions, edits or deployment.

Darcy provides matching approved admin sidebar tools. Its Builder release check reports Main or Early access separately from the response data environment. A selected Staging environment does not establish that Early access Builder is switched on.

## SharePoint upsert mapping checks

Saves of an existing service through REST, MCP and Darcy check linked SharePoint lookup and update column mappings. Each update value is written to the lookup list column with the same name, so an update may list only the columns it changes; unlisted columns are left unchanged. Saving an edited update adds new list columns to its lookup without removing any. Conflicting, ambiguous or unknown mappings and removal of non-empty mapped columns return HTTP 400 with `SHAREPOINT_LIST_MAPPINGS_INCONSISTENT` and a review message. Refresh and review the linked list settings in Builder before retrying. Authoring tools do not contact SharePoint to refresh columns or run Automap. Unrelated edits to older services remain possible; deployment checks the exact version selected. Saving and deploying remain separate operations, with existing permissions and approval requirements.

## Data Rooms endpoints

Call room commands and file streams on the Builder host with dedicated room permissions. See [Read and manage Data Rooms through the API](<https://govform.com/resources/documentation/article/33-17-api-data-rooms>) for the three endpoint paths, command examples, revisions, limits and save behaviour.

## Ordinary response comment conversations

Ordinary Form responses with **Allow changes during review** support field comment history and staff/respondent replies in the browser. Standard reviews and Collection programmes have no replies. Public REST, MCP and Darcy have no ordinary-response reply/history operation, and Collection review endpoints cannot operate ordinary responses. See [field comment history and replies](<https://govform.com/resources/documentation/article/21-11-service-response-review#field-comment-history-and-replies>) for the workflow, statuses and permissions. Review and answer-history settings still use their existing authoring APIs and separate save/deploy or save/apply steps.

## Retrieve and recreate public demos

Use `retrieve_demo_service` with the `demoId` (the d-… segment of the shared prototype URL). No management token is needed to retrieve a public design. This operation is available on the separate anonymous MCP connection, authenticated Builder MCP and Darcy. The result includes the latest `form`, `settings`, `state` (active or archived), `expiresAt` and `retainUntil`; it contains no answers, version history or private management metadata.

Working demos expire after 14 days. Their latest definition and branding, including inline images, remain retrievable for twelve calendar months after expiry. Archived designs do not count towards the 5,000 active-demo cap. Retrieval stops at the retention deadline even if physical deletion is delayed. A token-authorised deletion permanently removes active or archived data without retaining a recovery copy.

For another public demo, use the anonymous `create_demo_service` tool with the retrieved definition and settings. It receives a new ID, management token and fourteen-day lifetime under the existing creation limits. For an ordinary service, authenticated MCP `create_form` accepts `demoId` instead of `form`, together with the destination `org` and new `formId`. REST clients send the same optional source to `POST /builder/libraries/{org}/api/forms/{formId}` with the existing apiFormWrite permission. Do not supply both demoId and form. Existing library permissions, write approvals and capacity checks apply. Darcy uses `createService` with `creationMethod: "blank"`, demoId and the desired name/ID. Creation saves a new service without deploying it.

```json
{"demoId":"d-example123","formName":"Recovered service"}
```

Use destination-library branding by default. The AI should ask whether the user wants the demo branding applied to the library and explicitly explain: **This changes the branding for every service/form in this library.** Only apply agreed branding through the existing library-settings permissions, approvals and save/apply steps. Do not implicitly copy regional settings or deploy anything. See [Create a temporary demo with an AI client](<https://govform.com/resources/documentation/article/ai-anonymous-demo-services>) for setup and recovery guidance.
