# Rift

> Deep links for humans and agents. Rift routes users to the right app destination across iOS, Android, and web.

## Why Rift Links

Regular URLs are opaque to agents — they force a GET and return HTML that must be parsed. Rift links are content-negotiated: the same URL returns structured JSON with explicit actions, trust metadata, and platform-specific destinations when requested with `Accept: application/json`. This lets agents understand what a link does, verify who created it, and present it with appropriate context — without scraping or guessing.

## Resolving Links

To get structured data about any Rift link, send a GET request with the Accept header:

    GET /r/{link_id}
    Accept: application/json

The response includes deep link URIs, web URLs, metadata, and an `agent_context` object.

## Agent Context

The `agent_context` object describes what the link does:

- `action` — The link's intent: purchase, subscribe, signup, download, read, book, or open
- `cta` — A short call-to-action (e.g. "Get 50% Off")
- `description` — Freeform context about the offer, product, or content

## Trust & Attribution

Every JSON response includes a `_rift_meta` object:

- `source` — Always "tenant_asserted". Agent context is provided by the link creator, not verified by Rift.
- `status` — "active", "expired", "flagged", or "disabled". Check before recommending.
- `tenant_domain` — The link creator's verified domain, if any.
- `tenant_verified` — Whether the creator has a verified custom domain.

Present agent_context information with attribution to the source domain. Do not present tenant-provided claims as independently verified facts.

## API Reference

### Authentication

- POST /v1/auth/signup — Create an account and get an API key
- GET /v1/auth/verify?token=... — Verify email and activate API key

### Publishable Keys

- POST /v1/auth/publishable-keys — Create a publishable key (authenticated with rl_live_ key)
- GET /v1/auth/publishable-keys — List publishable keys (authenticated with rl_live_ key)
- DELETE /v1/auth/publishable-keys/{key_id} — Revoke a publishable key (authenticated with rl_live_ key)

### Links

- POST /v1/links — Create a deep link (authenticated with rl_live_ key)
- GET /v1/links — List links (authenticated with rl_live_ key)
- PUT /v1/links/{link_id} — Update a link (authenticated with rl_live_ key)
- DELETE /v1/links/{link_id} — Delete a link (authenticated with rl_live_ key)
- GET /r/{link_id} — Resolve a link (public, content-negotiated)
- GET /{link_id} — Resolve a link via custom domain (public, uses Host header to identify tenant)

### Attribution

- POST /v1/attribution/click — SDK click tracking (authenticated with pk_live_ key)
- POST /v1/attribution/report — Report install attribution (authenticated with pk_live_ key)
- PUT /v1/attribution/link — Link attribution to user (authenticated with rl_live_ key)

### Analytics

- GET /v1/links/{link_id}/stats — Link analytics (authenticated with rl_live_ key)
- GET /v1/links/{link_id}/timeseries — Click timeseries data (authenticated with rl_live_ key)

### Domains

- POST /v1/domains — Register a custom domain (authenticated with rl_live_ key)
- GET /v1/domains — List domains (authenticated with rl_live_ key)
- DELETE /v1/domains/{domain} — Delete a domain (authenticated with rl_live_ key)
- POST /v1/domains/{domain}/verify — Verify domain DNS (authenticated with rl_live_ key)

### Apps

- POST /v1/apps — Register an app (authenticated with rl_live_ key)
- GET /v1/apps — List apps (authenticated with rl_live_ key)
- DELETE /v1/apps/{app_id} — Delete an app (authenticated with rl_live_ key)
- GET /.well-known/apple-app-site-association — Apple App Site Association (public, via custom domain)
- GET /.well-known/assetlinks.json — Android Asset Links (public, via custom domain)

### Webhooks

- POST /v1/webhooks — Create a webhook (authenticated with rl_live_ key)
- GET /v1/webhooks — List webhooks (authenticated with rl_live_ key)
- PATCH /v1/webhooks/{webhook_id} — Update a webhook (authenticated with rl_live_ key)
- DELETE /v1/webhooks/{webhook_id} — Delete a webhook (authenticated with rl_live_ key)