Source: docs/integration/contract-retrieval.md

Retrieve and validate the public contract

Use this guide when a coding agent cannot find the OpenAPI or API reference

through the documentation navigation. The contract is public and does not

require an API key.

Canonical resources

Use the published machine-readable manifest first:

https://docs.forgium.dev/agent-manifest.json

The canonical raw OpenAPI file is:

https://docs.forgium.dev/docs/integration/api.openapi.yaml

The same link is published from the agent entrypoint,

the LLM index, and the agent index.

Do not infer an API host from the OpenAPI document. The API host comes from the

environment-specific FORGIUM_AGENT_BASE_URL access bundle.

Direct retrieval

A shell-based agent can retrieve the file without a search engine or URL

enumeration:

CONTRACT_URL="https://docs.forgium.dev/docs/integration/api.openapi.yaml"
curl -fsSL \
  -H 'Accept: application/yaml,text/plain' \
  "$CONTRACT_URL" \
  -o /tmp/forgium-agent.openapi.yaml

Confirm that the response is the raw contract rather than an HTML error page:

test -s /tmp/forgium-agent.openapi.yaml
grep -q '^openapi:' /tmp/forgium-agent.openapi.yaml
head -20 /tmp/forgium-agent.openapi.yaml

When the local toolchain has Redocly available, validate the syntax and

references:

bunx @redocly/cli lint /tmp/forgium-agent.openapi.yaml

The expected contract version is published in agent-manifest.json and in the

OpenAPI info.version field. Do not silently continue with a different

version.

If retrieval fails

Stop and report the concrete failure when any of these conditions occurs:

• the manifest or raw contract returns a non-success HTTP status;
• the response is HTML, empty, or does not contain an openapi: declaration;
• the downloaded contract fails validation; or
• the contract version does not match the published manifest.

Report the URL, HTTP status, content type, and the next action. Do not try

undocumented openapi.json, swagger.json, API, or internal URLs. Do not

substitute a contract found through an unrelated search result.

Example blocker report:

Blocker: https://docs.forgium.dev/docs/integration/api.openapi.yaml returned
HTTP 404 with Content-Type text/html.
Next action: deploy the public documentation artifact containing the canonical
OpenAPI file, then rerun the retrieval and lint commands.

Missing API credentials is a separate blocker from a missing documentation

contract. Report both when both are present.

Contract evidence for an integration

Record these facts in the implementation handoff:

• canonical contract URL;
• HTTP status and content type;
• OpenAPI version and info.version;
• lint result or the reason lint could not run; and
• whether the authenticated API smoke test was run.

A local adapter may be implemented with mocks while credentials are pending,

but it must be labelled locally verified rather than end-to-end verified.