> ## 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.

# Keeping references current

> Push new fields to every occurrence of a reference, or ask Reintersect to resolve it again.

> Reintersect apps are in developer preview. Names and limits can still change before general
> release.

A reference shows the fields from its last resolve until something changes them. Your app has two
ways to change them:

| Method | What happens | Use it when |
| - | - | - |
| Revalidate | Reintersect calls your `resolve` again and stores the new answer. Needs `references:write`. | You know the object changed but don't have its new fields at hand. |
| Push | You send the new fields directly. Reintersect stores them without calling `resolve`. Needs `references:write`. | You already have the new state, for example from a webhook your service sent you. |

Either way, the update applies to the workspace's shared record for that object, so every chip, link
and card that shows it in that workspace updates at once, in every conversation.

## Revalidate

```ts theme={null}
await reintersect.references.revalidate({ kind: "deployment", externalId: "dpl_9xK2" });
```

Pass the reference kind and the `externalId` your `resolve` returned. Reintersect queues a resolve
of the stored URL for the workspace the client acts for and answers `202` at once; the new fields
appear when your `resolve` answers. To update the same object in several workspaces, call it once
per install.

## Push

```ts theme={null}
const { data, error } = await reintersect.references.push({
  kind: "deployment",
  externalId: "dpl_9xK2",
  fields: {
    status: { state: "success", label: "Ready" },
    summary: "Deployment of web from main. Ready since 14:02.",
    updatedAt: "2026-10-04T14:02:11Z",
  },
  version: 1759586531000,
});
```

`fields` accepts `title`, `summary`, `subtitle`, `icon`, `status`, `updatedAt`, `url`, `visibility`
and `block`. Fields you leave out keep their current values; `null` clears an optional field.
`block` replaces the whole rendered card, as `{ tree, actions }`, or removes it with `null`; to change
a card's props, revalidate instead so the SDK renders it.

`version` is a whole number that increases every time the object changes on your side. A timestamp
in milliseconds or a revision counter both work. Reintersect keeps the highest version it has stored
and ignores a push with a lower version, so pushes that arrive out of order can't overwrite
fresher data. A push with the same version is applied, so sending the same push again is safe. An
ignored push isn't an error: the response is `{ applied: false, version }` with the version
Reintersect already holds.

## Calling from handlers and routes

Inside a handler, use the `reintersect` client from the context; it's already authorized for the
install. Declare `references:write` on the piece that pushes:

```ts theme={null}
export const promote = defineAction(
  "promote",
  { args: z.object({ deploymentId: z.string() }), destructive: true, scopes: ["references:write"] },
  async ({ args, reintersect }) => {
    await promoteDeployment(args.deploymentId);
    await reintersect.references.push({
      kind: "deployment",
      externalId: args.deploymentId,
      fields: { status: { state: "running", label: "Promoting" } },
      version: Date.now(),
    });
  },
);
```

Outside a delivery, for example in a [route](/hosting/routes) that receives your own service's
webhooks, get a client for the install with `reintersect.forInstall(installId)`, or create one with
`createReintersectClient(app, { installId })`. Your app stores install ids, never tokens: the SDK
mints a short-lived install token with your app's client credentials, or, on Reintersect hosting,
lets the gateway add it. See [Client](/reference/client).

The kind is typed from the app: pushing to a kind the app doesn't include is a type error.

## Over HTTP

Both operations are plain API calls if you don't use the SDK:

* [Revalidate a reference](/api-reference/references/revalidate): `POST /v0/references/revalidate`
* [Push reference fields](/api-reference/references/push): `PUT /v0/references`

## Automatic refresh

A [restricted](/references/resolving#visibility) reference is resolved again for a member who views
it once their last answer is more than 30 minutes old. A public reference keeps the fields from its
last successful resolve until you push or revalidate. Links pasted after an update reuse the shared
record and show the current fields immediately.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.