List services, metadata and form schemas

Discover service IDs before calling submission or analytics APIs. The Builder REST API lists the services in a library and provides service metadata, confirmed deployment status, field summaries, full definitions and deployment history. These endpoints can be called by an ordinary application; an AI or MCP client is not required.

Choose the right API host

For service discovery and definitions, use the Builder host:

https://govforms.uk

If your organisation runs a private Builder, use its Builder base URL. The endpoints below are not hosted on the QA or Production service hosts.

Builder definitions describe the current design, which may include changes that have not been deployed. The directory includes confirmed deployment status recorded by Builder. To check the deployed version directly in an environment, use the deployed service version endpoint on the relevant QA or Production host.

Authentication and permissions

Use an API key belonging to the requested library. Send the Authorization header with each request:

Authorization: GovformsApiKey <key-id>:<key-secret>

Substitute credentials from your secure configuration. The endpoints also accept GovformsApiHmac authentication. Any source-IP restrictions configured on the key still apply.

Permission	Use
`apiOrgRead`	List the library’s services. In API-key settings this is labelled AI/MCP: read library information and forms list.
`apiFormRead`	Read service summaries, full definitions and deployment history. In API-key settings this is labelled AI/MCP: read form JSON, summaries, history and deployment status.
`getDeployedServiceVersion`	Check the currently deployed version on a QA or Production service host.

The AI/MCP labels also cover these REST calls. Listing services does not grant access to submitted data; submission retrieval requires its own permission. See API key settings.

Endpoint reference

In Builder paths, formId means the Service ID. Replace libraryId with the library’s stable ID.

GET path on Builder	Response	Permission	API units
`/builder/libraries/{libraryId}/api/forms`	Service directory, metadata and confirmed deployment status	`apiOrgRead`	5
`/builder/libraries/{libraryId}/api/form/{formId}/summary`	Pages, top-level fields and version summary	`apiFormRead`	1
`/builder/libraries/{libraryId}/api/form/{formId}`	Full current Builder definition	`apiFormRead`	5
`/builder/libraries/{libraryId}/api/deployments/{formId}`	Latest 20 deployment records	`apiFormRead`	5

These GET endpoints do not require a request body or query parameters. The directory has no pagination parameters; deployment history returns at most 20 records. Each successful call uses the units shown above. See API units and limits.

List services and metadata

GET https://govforms.uk/builder/libraries/demo-library/api/forms

Example response; optional metadata varies by service:

{
  "forms": [
    {
      "_id": "demo-library-demo-service-1",
      "org": "demo-library",
      "formName": "Example application",
      "isTemplate": false,
      "lastUpdatedTime": "2026-10-08T09:00:00.000Z",
      "labels": [],
      "publicationStatus": {
        "currentVersionNum": 12,
        "hasAnyDeployment": true,
        "hasUnpublishedChanges": true,
        "environments": [
          {
            "env": "qa",
            "isDeployed": true,
            "deployedVersionNum": 12,
            "deployedSsId": "revision-12",
            "deployedTime": "2026-10-08T09:30:00.000Z",
            "deployedUser": "service-owner@example.org",
            "isRunningLatestVersion": true,
            "hasUnpublishedChanges": false
          },
          {
            "env": "production",
            "isDeployed": true,
            "deployedVersionNum": 10,
            "deployedSsId": "revision-10",
            "deployedTime": "2026-10-01T14:00:00.000Z",
            "deployedUser": "service-owner@example.org",
            "isRunningLatestVersion": false,
            "hasUnpublishedChanges": true
          }
        ]
      }
    }
  ]
}

The response is an object containing a forms array, sorted by service name. Entries contain _id, org, formName, and, where stored, isTemplate, templateDescription, lastUpdatedUser, lastUpdatedTime and labels. Each entry also includes publicationStatus.

The directory includes undeployed services and templates. It excludes managed Collection forms; use the Response Hub API for Collection programme operations. It does not return field definitions or respondent data. Deployment status is reported separately for each environment under publicationStatus.environments.

Read confirmed deployment status

In the example, QA is running Builder version 12, while Production is running version 10 and has unpublished changes. Use the environment-specific flags when deciding which services are deployed to QA or Production.

Field within publicationStatus	Meaning
`currentVersionNum`	The current Builder version; 0 if no current version is available.
`hasAnyDeployment`	Whether any included environment has a confirmed deployment.
`hasUnpublishedChanges`	Whether any deployed environment differs from the current Builder version.
`environments[].env`	qa or production, plus staging when enabled.
`environments[].isDeployed`	Whether Builder has a confirmed deployment recorded in this environment.
`environments[].deployedVersionNum`	The deployed version number. Present only for a deployed environment.
`environments[].deployedSsId`	The exact saved revision deployed, where recorded.
`environments[].deployedTime`	The deployment confirmation time as an ISO timestamp, where recorded.
`environments[].deployedUser`	The person or API actor who deployed it, where recorded.
`environments[].isRunningLatestVersion`	Whether the deployed version number matches the current Builder version.
`environments[].hasUnpublishedChanges`	Whether a deployed environment differs from the current Builder version.

An undeployed environment has isDeployed: false, isRunningLatestVersion: false and hasUnpublishedChanges: false; deployment version, revision, time and actor are omitted. A service with no deployed baseline is not marked as having unpublished changes.

{
  "env": "production",
  "isDeployed": false,
  "isRunningLatestVersion": false,
  "hasUnpublishedChanges": false
}

This status reflects successful deployments and undeployments confirmed to Builder. It does not report pending requests or check service availability. Use the deployed service version endpoint when you need a direct check of a particular environment. MCP list_forms returns the same publication metadata in full and paged results; search_forms remains a metadata discovery operation.

Use the returned identifier

The directory’s _id is prefixed with the library ID: demo-library-demo-service-1. Remove the exact demo-library- prefix to obtain the Service ID demo-service-1. Do not split at the first hyphen, because both IDs can contain hyphens.

The Builder detail endpoints accept either the Service ID or its library-prefixed form. QA and Production endpoints such as /api/submitted-data/{libraryId}/{serviceId} and /api/service-deployments/{libraryId}/{serviceId} expect the Service ID without the library prefix.

Read fields and types

GET https://govforms.uk/builder/libraries/demo-library/api/form/demo-service-1/summary

The summary returns id, idWithOrg, formName, version information, lastChange, pages, conditions, numPages and numConditions. Each page includes its index, ID, title, type, field count and a field list. Each field entry includes its ID and type, with title or label where present.

For example, a page’s field list might contain:

[
  {
    "id": "fullName",
    "type": "text",
    "label": "Full name"
  }
]

This is a summary of top-level page fields, not a complete or flattened schema. For nested groups, repeating structures, choice items, validation rules and other configuration, retrieve the full definition:

GET https://govforms.uk/builder/libraries/demo-library/api/form/demo-service-1

This returns the current Builder form object directly, without a form wrapper. Read the field configuration under its pages and nested structures. It is Govform’s service definition format, not a standalone JSON Schema document. The full definition and summary are current Builder designs, not a snapshot of the currently deployed version.

Read deployment history

GET https://govforms.uk/builder/libraries/demo-library/api/deployments/demo-service-1

{
  "formId": "demo-service-1",
  "formIdWithOrg": "demo-library-demo-service-1",
  "currentVersionNum": 12,
  "deployments": [
    {
      "env": "qa",
      "deployTime": "2026-10-05T10:00:00.000Z",
      "deployUser": "service-owner@example.org",
      "deployFormVersionNum": 11,
      "isUndeploy": false
    }
  ]
}

The response contains formId, formIdWithOrg, currentVersionNum and deployments. Deployment records include their environment, time, actor, deployed version, snapshot ID where stored, and withdrawal flag. currentVersionNum is the Builder version. The latest 20 records are returned across environments, newest first; isUndeploy: true identifies a withdrawal.

This is recorded deployment history, not a live check of an environment. An empty array or a history window without an environment’s record is not proof that the service is undeployed there.

Build a library inventory

Call /forms once to discover IDs and metadata. Filter out entries with isTemplate: true if you only want services.
Remove the exact library prefix from each selected _id.
Fetch the summary or full definition for services whose field information you need.
Use publicationStatus.environments from the directory to select confirmed deployments: match the required env and retain entries with isDeployed: true. Check hasUnpublishedChanges to identify deployed versions that differ from Builder.
For a direct environment check, call GET /api/service-deployments/{libraryId}/{serviceId} on the relevant QA or Production host.
Fetch Builder deployment history only when you need release records.

The directory combines service metadata and confirmed deployment status. Fetch complete definitions or direct environment checks separately when needed. Those detail calls are per service and consume API units, so retrieve the information your integration needs and respect the published limits.

Errors

Missing or invalid authentication, a key for another library, a missing permission or a disallowed source IP returns 403. Reading a missing service definition or summary returns 404. Managed Collection forms are unavailable through ordinary service-definition endpoints. Capacity limits return 429; respect Retry-After. Builder API errors use a JSON error.message envelope, with capacity errors providing additional limit information.

For service creation, saves and deletion, see service design operations. The endpoint index lists the other customer APIs.

See authentication headers for raw-key and HMAC formats.