> ## Documentation Index > Fetch the complete documentation index at: https://developers.reintersect.com/llms.txt > Use this file to discover all available pages before exploring further. # References > Teach Reintersect your links. When a member pastes a URL your app recognizes, Reintersect shows it as a live chip, link or card. > Reintersect apps are in developer preview. Names and limits can still change before general > release. A reference is a link Reintersect understands. Reintersect already knows GitHub pull requests, Linear issues, calls, decisions and ordinary web pages. A reference kind in your app teaches it your links: when a member pastes a URL that matches one of your patterns, Reintersect asks your app what the URL points to and shows the answer as a chip, a link title or a card. Using Effect? See [References](/effect/blocks-and-references#references) in the Effect guide. ## Define a reference kind This is the reference `npm create reintersect` scaffolds: ```ts src/taskReference.ts theme={null} import { defineReference } from "@reintersect/sdk/app"; import { env, InstallConfig } from "./schemas"; import { TaskBlock } from "./taskBlock"; import { findTask, searchTasks, taskUrl } from "./tasks"; export const TaskLink = defineReference("task", { title: "Task", patterns: { task: "https://tasks.example.com/tasks/:id" }, block: TaskBlock, env, config: InstallConfig, resolve: ({ params, config }) => { const task = findTask(params.id); if (task === undefined) return { access: "notFound" }; return { externalId: task.id, title: task.title, subtitle: `${config.project} ${task.id}`, block: { props: { id: task.id, title: task.title, assignee: task.assignee }, state: { status: task.status }, }, }; }, search: ({ query, limit, env: searchEnv }) => searchTasks(query, limit).map((task) => ({ url: taskUrl(searchEnv.TASKS_URL, task.id), title: task.title, subtitle: task.id, })), }); ``` Add it to the app with `.addReference(TaskLink)`. The kind (`"task"`) uses `a-z`, `0-9` and `-`, is at most 48 characters, and is unique within the app. `title` labels the kind in search tabs and on the consent screen; it defaults to the kind. | Option | Description | | - | - | | `patterns` | Named URL patterns, such as `{ task: "https://…/:id" }`. Required. See [URL patterns](/references/patterns). | | `resolve` | Turns a matched URL into core fields or an access result. Required. See [Resolving](/references/resolving). | | `search` | Lets members find your objects from the slash menu. See [Search](/references/search). | | `block` | A block definition whose view replaces the default card. The app must also `.addBlock()` it. | | `title` | The kind's label. | | `scopes`, `env`, `config` | What the handlers use. See [Composing an app](/concepts/composition). | ## What Reintersect builds from your answer `resolve` returns core fields: a title, a status, a summary and a few more. Reintersect derives every presentation from those fields, so you write one function and get consistent results across the product: | Surface | Built from | | - | - | | Chip in text | `icon`, `title`, `status` | | Link title | `title` | | Hover card | `title`, `subtitle`, `status`, `updatedAt`, `summary` | | Card (block display) | All core fields, or your custom `block` | | Agent text | `title`, `status`, `summary` and the URL | | Search results in the slash menu | Your `search` results | ### Chip, link or card Members choose how a reference displays, and can switch at any time: | Display | What members see | | - | - | | Chip | An inline pill with the icon, title and status. | | Link | Ordinary link text, titled by Reintersect. | | Card | A block-level card, built from the core fields unless you supply a custom one. | A custom `block` replaces only the card body. Chips, link titles, hover cards and agent text still come from the core fields, and the card keeps Reintersect's frame and the "via \" line. ## One shared object per workspace Reintersect keeps one record per reference in each workspace, keyed by your kind and the `externalId` you return. Every place the URL appears in that workspace, in any conversation, reply or decision, shows the same record. When you [push new fields or ask for a refresh](/references/updates), every occurrence updates at once. Return the same `externalId` for every URL that points at the same object, so a short URL and a long URL show one record. ## When a member pastes a link 1. Reintersect matches the URL against the patterns of every app installed in the workspace, and the member's own development installs. Matching happens on Reintersect's servers only; your app never sees URLs that don't match its patterns. 2. On a match, Reintersect calls your `resolve` with the parameters extracted from the URL, for the member who pasted it. 3. The answer is stored and the link turns into a reference chip. The editor offers the card display when the kind has a custom block. 4. If your app subscribes to them and holds `conversations:read`, it receives `reference.created` when a member adds a link to one of your objects in a circle it can reach, and `reference.removed` when that link is deleted. See the [event catalog](/events/catalog). The chip stored in the document keeps only the link's host and path. Your app's titles and summaries live in the shared record, never in the document itself, so they follow access rules and updates. Copying a reference and pasting it elsewhere creates another occurrence of the same shared object. Members can also insert a reference from the slash menu by typing `/` and your app's slug, when the kind has `search`. ## Who sees what By default a reference is restricted: Reintersect resolves it for each member who views it, and a member whose resolve was withheld sees only a plain link chip, without your title, summary or card. Return `visibility: "public"` for objects anyone in the workspace may see, and every member gets the shared fields. See [Visibility](/references/resolving#visibility). ## Next steps The pattern grammar, with allowed and rejected examples. Core fields, access results, visibility and custom cards. Let members find your objects from the slash menu. Push new fields or ask Reintersect to resolve again. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.