---
title: Continue in Basalt — Handoff API
category: Integrations
icon: 🔁
sort_order: 29
slug: continue-in-basalt-handoff
canonical_url: https://basaltnotes.com/guides/continue-in-basalt-handoff
markdown_url: https://basaltnotes.com/guides/continue-in-basalt-handoff.md
---
# Continue in Basalt — Handoff API

Basalt Handoff v1 lets an authorized external server offer **Continue in Basalt**, **Save to Basalt**, or **Open in Basalt** for one bounded work product. The user signs in or creates a Free account, previews the content, chooses a vault, and explicitly accepts it into the normal Draft Capture Inbox.

A Handoff is a one-time ingress event. It is not ongoing sync, a Connection, a trusted-memory channel, an agent instruction, or a domain plug-in entitlement.

## Create and redirect

Create a scoped client credential with the Basalt deployment operator. Keep it server-side.

```http
POST /api/handoffs
Authorization: Bearer bhc_your_server_credential
Content-Type: application/json
```

```json
{
  "schema": "basalt.handoff",
  "version": 1,
  "intent": "knowledge.capture",
  "provider": "your-product",
  "externalId": "artifact-42",
  "idempotencyKey": "your-product:artifact-42:v1",
  "artifact": {
    "type": "markdown",
    "title": "Example artifact",
    "contentType": "text/markdown",
    "content": "# Useful work\n\nSource-backed content."
  },
  "sources": [],
  "attachments": [],
  "relationships": [],
  "provenance": {
    "createdAt": "2026-08-15T00:00:00.000Z",
    "sourceUrl": "https://your-product.example/work/42",
    "generator": "your-product-v1"
  },
  "returnUrl": "https://your-product.example/work/42",
  "attribution": {
    "source": "your-product",
    "campaign": "continue-in-basalt",
    "medium": "handoff"
  }
}
```

The response contains an opaque `continueUrl`. Redirect the user there. Never put the payload, client credential, title, source URL, or attribution in the redirect URL.

## Supported V1 contract

- intents: `knowledge.capture`, `artifact.continue`, and `research.continue`;
- artifact types: `note`, `markdown`, `structured`, `research`, `source-set`, `document`, and `pdf`;
- maximum inline content: 64 KiB; normalized envelope: 96 KiB; structured data: 32 KiB;
- maximum 50 sources, 50 relationships, and 10 attachment references;
- HTTPS references only; localhost HTTP is accepted for development;
- attachment URLs remain references and are never fetched automatically.

The optional `context.verticalPluginId`, `context.artifactBundleId`, and `context.continuationSurface` fields are routing hints only. They cannot activate or bypass a commercial entitlement.

## Idempotency and retention

Use a stable idempotency key for one external artifact version. Identical pending retries return the same continuation token. Materially changed content produces a new SHA-256 knowledge fingerprint. Acceptance is database-locked and creates one deterministic Capture item, so refresh, back navigation, and retries do not duplicate knowledge.

Staging expires after 48 hours. Payload JSON is erased immediately after acceptance, cancellation, or expiry. Opening the URL does not import anything, and unauthenticated visitors see only provider/type/count metadata—not the staged title or content.

## Trust and privacy

External content remains inert Draft data. Basalt preserves provider, client, external ID, supplied source IDs, timestamps, and the knowledge fingerprint in Markdown provenance. Marketing attribution is stored separately in content-free funnel events and is never evidence.

A Handoff cannot confirm Strata decisions, execute Forge actions, promote trusted memory, fetch arbitrary URLs, change system instructions, or make local-first Basalt depend on the Handoff service.

For deployment configuration, revocation, complete MIME support, stable error codes, and a local request example, see the repository's `docs/basalt-handoff-v1.md` reference.