Skip to main content
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 in the Effect guide.

Define a reference kind

This is the reference npm create reintersect scaffolds:
src/taskReference.ts
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.

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: Members choose how a reference displays, and can switch at any time: 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 <app name>” 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, 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.
  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.
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.

Next steps

URL patterns

The pattern grammar, with allowed and rejected examples.

Resolving references

Core fields, access results, visibility and custom cards.

Search

Let members find your objects from the slash menu.

Keeping references current

Push new fields or ask Reintersect to resolve again.