Govform API endpoint index
Find the customer REST endpoints for services, definitions, submitted data, files, analytics, Collection programmes, User portal settings and Darcy tools. Each entry links to its request, response and permission guidance.
API hosts and authentication
Builder: https://govforms.uk, 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.
Use service discovery 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/user-portal |
apiPortalRead | Read, update and deploy User portal settings |
PATCH /builder/libraries/{libraryId}/api/user-portal |
apiPortalWrite | Read, update and deploy User portal settings |
POST /builder/libraries/{libraryId}/api/user-portal/deployments |
apiPortalDeploy | Read, update and deploy User portal settings |
GET /builder/libraries/{libraryId}/api/forms |
apiOrgRead | List services, metadata and form schemas |
POST /builder/libraries/{libraryId}/api/forms/{formId} |
apiFormWrite | Create, update and delete services through the API |
DELETE /builder/libraries/{libraryId}/api/forms/{formId} |
apiFormWrite | Create, update and delete services through the API |
GET /builder/libraries/{libraryId}/api/form/{formId} |
apiFormRead | List services, metadata and form schemas |
GET /builder/libraries/{libraryId}/api/form/{formId}/summary |
apiFormRead | List services, metadata and form schemas |
PUT /builder/libraries/{libraryId}/api/save-form-version/{formId} |
apiFormWrite | Create, update and delete services through the API |
POST /builder/libraries/{libraryId}/api/darcy/form-lock/{formId} |
apiFormWrite | Create, update and delete services through the API |
PUT /builder/libraries/{libraryId}/api/darcy/form-lock/{formId} |
apiFormWrite | Create, update and delete services through the API |
DELETE /builder/libraries/{libraryId}/api/darcy/form-lock/{formId} |
apiFormWrite | Create, update and delete services through the API |
GET /builder/libraries/{libraryId}/api/deployments/{formId} |
apiFormRead | List services, metadata and form schemas |
POST /builder/libraries/{libraryId}/api/deployments |
apiFormDeploy | Create, update and delete services through the API |
GET /builder/libraries/{libraryId}/api/darcy/tools/catalog |
apiDarcyToolRead or apiDarcyToolWrite | Discover and run Darcy REST tools |
POST /builder/libraries/{libraryId}/api/darcy/tools/{toolName} |
Tool-specific permission | Discover and run Darcy REST tools |
POST /builder/libraries/{libraryId}/api/darcy/ask |
apiDarcyAsk | Discover and run Darcy REST tools |
POST /builder/libraries/{libraryId}/api/darcy/agent |
apiDarcyAgent | Discover and run Darcy REST tools |
PUT /builder/libraries/{libraryId}/api/upsert-service-definition/{formId} |
upsertServiceDefinition | Create, update and delete services through the API |
PUT /builder/libraries/{libraryId}/api/start-deployment/{formId}/{version}/{env} |
triggerServiceDeployment | Create, update and delete services through the API |
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 |
POST /api/submitted-data/{libraryId}/{serviceId}/delete |
deleteSubmittedData | Delete submitted form data |
PUT /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/status |
setFormStatus | Set submitted form status |
GET /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/files |
fetchCustomerData | List and download uploaded files and signatures |
GET /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/files/{fieldId} |
fetchCustomerData | List and download uploaded files and signatures |
GET /api/submitted-data/{libraryId}/{serviceId}/{submissionId}/bulk/{fieldId}/{artifact} |
fetchCustomerData | Bulk Data files and submitted revisions |
GET /api/analytics-events/{libraryId}/{serviceId} |
fetchAnalyticsEvents | Fetch analytics events |
GET /api/analytics-journeys/{libraryId}/{serviceId} |
fetchAnalyticsJourneys | Fetch journey analytics records |
GET /api/service-deployments/{libraryId}/{serviceId} |
getDeployedServiceVersion | Get deployed service version |
PUT /api/service-deployments/{libraryId}/{serviceId}/{version} |
triggerServiceDeployment | 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 |
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes |
apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId} |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
PATCH /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId} |
apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment} |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections |
apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId} |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
PATCH /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId} |
apiCollectionProgrammeWrite | Collection programme API |
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/transition/{action} |
apiCollectionProgrammeWrite | Collection programme API |
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/apply-form |
apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/cohorts |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/cohorts |
apiCollectionProgrammeWrite | Collection programme API |
PATCH /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/cohorts/{cohortId} |
apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/assignments |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/assignments |
apiCollectionProgrammeWrite | Collection programme API |
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/assignments/{assignmentId}/cancel |
apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId}/versions |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
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 |
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 |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/responses/{responseId} |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews/{workItemId}/issues |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews/{workItemId} |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/reviews/{workItemId}/{action} |
apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/communications |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/audit |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/form-revisions |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId} |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
DELETE /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId} |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId}/manifest |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
GET /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/exports/{exportId}/parts/{partId} |
apiCollectionProgrammeRead or apiCollectionProgrammeWrite | Collection programme API |
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/roster |
apiCollectionProgrammeWrite | Collection programme API |
POST /builder/libraries/{libraryId}/api/response-hub/collection-programmes/{collectionProgrammeId}/collections/{environment}/{collectionId}/roster/{rosterJobId}/apply |
apiCollectionProgrammeWrite | Collection programme API |
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 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
- Create, update and delete services
- User portal settings and deployment
- Collection programme data, reviews, evidence and exports
- Darcy REST tool discovery and execution
- API-key settings
See authentication headers for raw-key and HMAC formats.