Links
links stores one primary link and optional alternative links, each a URL with an optional
human-readable label. Use it for websites, documentation, support addresses or phone links that
belong to a record. Ordinary text attributes are unchanged: a text value that happens to look
like a URL is never converted.
Valueโ
{
"primary": { "url": "https://example.com/docs", "label": "Documentation" },
"alternatives": [
{ "url": "mailto:support@example.com", "label": "Support" },
{ "url": "https://status.example.com" }
]
}
| Member | Rules |
|---|---|
primary | Required whenever the value is present. One link object. |
alternatives | Optional on write, always an array on read. Ordered; at most 10 entries. |
url | Required per link. Trimmed, 1 to 2048 characters, an absolute URL using http, https, mailto or tel. Web URLs need a host. |
label | Optional per link. Trimmed, at most 200 characters; blank labels are dropped. |
The same URL may appear only once across the primary and the alternatives. Saving or displaying a link never contacts its destination: no previews, no crawling, no metadata.
A supplied value replaces the stored value entirely. To promote an alternative, send the
structure with that entry as primary and the former primary in alternatives; the API stores
the structure it receives.
Empty valuesโ
A value without a primary link and without alternatives, such as {} or
{"alternatives": []}, is empty. It clears the attribute exactly like null: an optional
attribute is removed and a required one returns 422 required-field. Alternatives without a
primary return 422 links-primary-required.
Validation errorsโ
| Error type | Cause |
|---|---|
type-mismatch | The value, a link or alternatives has the wrong shape; the pointer names the member, for example #/data/website/alternatives/1. |
unknown-field | A member other than primary, alternatives, url or label. |
required-field | A link without url. |
links-unsafe-link | A URL on a scheme other than http, https, mailto or tel. |
invalid-format | A URL that cannot be parsed, has no host, or contains whitespace or control characters. |
string-too-long | A url or label exceeds its length limit. |
duplicate-items | The same URL appears twice; the pointer names the repeated alternative. |
too-many-items | More than 10 alternatives. |
links-primary-required | Alternatives were supplied without a primary link. |
Displayโ
Display templates and compact list cells show the primary link's label, or its URL when it has
no label. The Tourfold web app renders every link as its label with the URL as a tooltip; web
links open in a new tab with rel="noopener noreferrer", mail and phone links are handed to the
device, and a URL on any other scheme is shown as plain text. Consumers rendering stored links
should apply the same scheme policy.
Definitionโ
{
"slug": "website",
"type": "links",
"name": {"en": "Website", "de": "Webseite"},
"config": {"is_required": false}
}
| Configuration | Behavior |
|---|---|
is_required | A primary link must be present. |
default | Not available. |
is_unique | Not supported; returns 422 unique-unsupported-type. |
Query capabilitiesโ
| Surface | Capability |
|---|---|
REST filter_operators | contains and is_null (is_null only for optional attributes) |
REST is_sortable | false |
| GraphQL output | RecordLinks { primary: RecordLink!, alternatives: [RecordLink!]! } with RecordLink { url: String!, label: String } |
| GraphQL filter | LinksOperators with _contains and _is_null |
GraphQL order_by | Not available |
| Search | Labels and URLs of every link are indexed; member names are not |
contains matches the labels and URLs of all links case-insensitively. Equality, prefix and
suffix operators return 422 filter-operator-not-applicable; a sort returns
422 unsupported-sort-field.
Integration surfacesโ
Webhook payloads, MCP record tools, workflow record operations and Vehicle definitions carry the
same object inside data, exactly as REST returns it, with alternatives always present.