# List services, metadata and form schemas

Source: https://govform.com/resources/documentation/article/33-09-api-list-services-and-form-schemas
Topic: Govform API & MCP

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://app.govform.com
```

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](<https://govform.com/resources/documentation/article/33-05-api-get-deployed-service-version>) 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](<https://govform.com/resources/documentation/article/30-govforms-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](<https://govform.com/resources/documentation/article/33-govforms-api#api-units-and-limits>).

## List services and metadata

```
GET https://app.govform.com/builder/libraries/demo-library/api/forms
```

Example response; optional metadata varies by service:

```json
{
  "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](<https://govform.com/resources/documentation/article/33-13-api-response-hub>) 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.

```json
{
  "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://app.govform.com/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:

```json
[
  {
    "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://app.govform.com/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.

## Request a compact current definition

The Builder `GET /form/{formId}` route accepts `?removeSuperfluousFields=true`. The default remains the full current definition. The optional representation removes superfluous authoring properties and is a REST read option, not a new MCP save mode or a partial-update contract.

The two representations have distinct ETags: the compact one adds `-superfluous-fields` to the revision inside the quoted ETag. Keep caches separate and return the exact ETag for that representation in `If-None-Match`. A matching response can return `304`.

`createdWithVersion`, where present, is server-owned creation provenance. Do not assign it to upgrade an existing service's behaviour or treat an optional compact read as permission to remove other settings when saving a complete definition.

## Read deployment history

```
GET https://app.govform.com/builder/libraries/demo-library/api/deployments/demo-service-1
```

```json
{
  "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

1.  Call `/forms` once to discover IDs and metadata. Filter out entries with `isTemplate: true` if you only want services.
2.  Remove the exact library prefix from each selected `_id`.
3.  Fetch the summary or full definition for services whose field information you need.
4.  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.
5.  For a direct environment check, call `GET /api/service-deployments/{libraryId}/{serviceId}` on the relevant QA or Production host.
6.  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.

## Related API guides

-   [API overview, authentication and limits](<https://govform.com/resources/documentation/article/33-govforms-api>)
-   [Check the current deployed service version](<https://govform.com/resources/documentation/article/33-05-api-get-deployed-service-version>)
-   [Fetch submitted form data using the discovered Service ID](<https://govform.com/resources/documentation/article/33-01-api-fetch-submitted-form-data>)
-   [Govform MCP capabilities for connected AI clients](<https://govform.com/resources/documentation/article/33-14-mcp-capabilities>)

For service creation, saves and deletion, see [service design operations](<https://govform.com/resources/documentation/article/33-11-api-service-design-and-deployment>). The [endpoint index](<https://govform.com/resources/documentation/article/33-10-api-endpoint-reference>) lists the other customer APIs.

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