Discover and run Darcy REST tools
Use the Builder REST API to discover the Darcy tools available to a library API key and invoke a tool using its advertised schema. Tool availability depends on the configured release and the key's permissions.
Host and authentication
Use https://govforms.uk (or your private Builder host), with /builder/libraries/{libraryId}/api as the prefix. Send Authorization: GovformsApiKey <key-id>:<key-secret> or GovformsApiHmac. POST requests use JSON.
Endpoints and permissions
Paths below follow the Builder prefix.
| Method and path | Permission | Behaviour |
|---|---|---|
GET /darcy/tools/catalog |
apiDarcyToolRead or apiDarcyToolWrite | Discover tools permitted for this key. |
POST /darcy/tools/{toolName} |
apiDarcyToolRead or apiDarcyToolWrite, depending on the tool | Run a discovered tool. Mutating tools require apiDarcyToolWrite. |
POST /darcy/ask |
apiDarcyAsk | Ask a non-mutating question where supported. |
POST /darcy/agent |
apiDarcyAgent | Request a Darcy agent operation where supported. |
These routes use 1 API unit per successful call. Form-write or tool-write permission is additionally required for the agent to be allowed to mutate forms. A question request is always non-mutating.
Discover tools before invoking them
GET /darcy/tools/catalog accepts mode=all (default), readonly or mutating. The returned tools array includes each tool's name, title, description, inputSchema and annotations where available. The catalogue is filtered by the key: use only names and inputs advertised by the connection.
Some tools require a service. Include formId in the input for those tools, using its Service ID or library-prefixed ID. Read the current service and relevant guidance before authoring a change.
POST /darcy/tools/{toolName} accepts either the tool input object directly or {"input": {...}}. For example, the wrapper for a tool requiring a form is:
{"input": {"formId": "example-application"}}
Add every other property required by that tool's inputSchema. Optional X-On-Behalf-Of records an actor for changes. A successful mutating tool result can save a new Builder version; it does not automatically deploy it. The response is the tool's result object, so inspect success and its returned data rather than assuming one uniform payload for all tools.
Optional question and agent operations
POST /darcy/ask and POST /darcy/agent forward their JSON payload to the configured Darcy capability. The wrapper sets the library, API-key identity and permitted mutation context; callers cannot grant themselves write access. Support and the detailed request/result contract depend on the configured capability. These endpoints can return 501 when that operation is unsupported or 503 when Darcy is unavailable. Discover direct guidance and authoring tools through the catalogue instead when question or agent operations are unavailable.
Errors and limits
Unknown or unauthorised tool names return 404. Missing required service input and a tool result with success: false return 400. Invalid credentials, source-IP restrictions or insufficient permission return 403. Rate and quota limits return 429. Follow error.message and Retry-After when provided.
For an MCP client, see Govform MCP capabilities. An ordinary REST integration does not need an MCP client.
See authentication headers for raw-key and HMAC formats.