# Youform agent instructions

Guidance reviewed October 17, 2026.

## When to use this

Use Youform for client intake, lead capture, feedback surveys, event registration,
and quizzes when a user needs a shareable or embedded form. Use the public
catalog to choose an existing template. Use the authorized product MCP connection
to work with a user's forms and responses.

## Discovery

Start at the [Youform developer hub](https://youform.com/developers/).
The homepage and API return RFC 8288 Link headers for the API catalog,
OpenAPI service description, developer documentation, and llms.txt.
[The API catalog](https://youform.com/.well-known/api-catalog) uses RFC 9727
and RFC 9264 application/linkset+json. It links to the real catalog and MCP
services; it does not imply anonymous access to protected account tools.

## Public template catalog

The marketing API is public, read-only, and requires no credentials.
It returns committed template metadata, not live account data or respondent data.

1. GET https://youform.com/openapi.json for the OpenAPI 3.1 contract.
2. GET https://youform.com/api for discovery links.
3. GET https://youform.com/api/v1/templates?type=form&q=intake&limit=5 to search.
4. Open an item's returned `url` to read its guide and preview. Preserve slug casing.
5. For more results, repeat the same filters with `offset` set to `nextOffset`.
   Stop when `nextOffset` is null. No matches is a successful empty list.

`q` matches a substring of the name, description, or categories, ignoring case;
it accepts at most 200 characters. `type` is `form`, `survey`, or `quiz`.
`limit` defaults to 20 and accepts integers from 1 to 100. `offset` defaults to 0
and accepts integers from 0 to 9007199254740991. Parameters may appear only once.
Unknown parameters return 400. GET, HEAD, and OPTIONS are supported. The catalog
is a build-time snapshot and is refreshed with site releases.

Errors use RFC 9457 `application/problem+json`: `type`, `title`, `status`, `detail`,
and `instance`, plus the extension fields `code` and `hint`. Read `hint` to recover:

- 400 / `invalid_parameter`: correct the query and retry.
- 404 / `endpoint_not_found`: consult the OpenAPI paths; do not invent endpoints.
- 405 / `method_not_allowed`: use GET or HEAD; check the Allow header.
- 500 / `internal_error`: retry later or browse https://youform.com/templates/.

No API operation creates a form, publishes a draft, or submits a response.

## Versioning and usage

Use /api/v1 for integrations. Read the
[versioning and deprecation policy](https://youform.com/developers/api-policy/).
No retirement is scheduled. Planned breaking changes use a new major URL;
affected endpoints will advertise Deprecation and, when scheduled, Sunset.
Follow Cache-Control. No fixed per-client quota or remaining-request counter
is currently advertised; avoid bursts and honor Retry-After if infrastructure
returns 429 with that header.

## Account workflows

Connect a compatible remote MCP client to https://app.youform.com/mcp using OAuth.
The current published scope is `mcp:use`; this is broad MCP access, not separate
read-only or editing scopes. Discover current values from the application's
[protected resource metadata](https://app.youform.com/.well-known/oauth-protected-resource)
and [authorization server metadata](https://app.youform.com/.well-known/oauth-authorization-server).
Do not apply these scopes to the unauthenticated public template catalog.
Follow the [connection guide](https://help.youform.com/connect-an-ai-assistant-to-youform-1tjid)
and discover current tool schemas through the client. Request access only to the
intended account; do not ask the user to paste passwords or tokens into chat.

For form creation or editing, establish the audience, purpose, and questions,
create or edit a draft, then review it with the user before publishing. Obtain
authorization for writes. For response analysis, establish the form, date range,
and whether incomplete responses are relevant; report sample size and limits.
Check the [tool reference](https://help.youform.com/youform-mcp-tools-and-permissions-e9hl0)
and [pricing](https://youform.com/pricing/) for current permissions and plan boundaries.

The [developer API](https://help.youform.com/does-youform-have-a-developer-api-mgfiw)
uses account tokens separately from MCP OAuth. This site's OpenAPI document covers
only its public marketing catalog; do not apply it to the product's API or MCP.

## Recovery and boundaries

Missing web paths return HTTP 404. Use `Accept: text/markdown` for a short recovery
body; browsers requesting HTML keep the normal designed 404. Default and wildcard
requests receive Markdown. HEAD returns the same status and headers without a body.
Use [llms.txt](https://youform.com/llms.txt), the
[sitemap](https://youform.com/sitemap.xml), and the
[help center](https://help.youform.com/) to find a real destination.

Public embeds and AI generation are real product actions. Do not submit demo
responses or generate forms merely to test connectivity. Do not infer legal
compliance, a completed payment, or a confirmed booking from a form field.