API Reference

Base URL

http://localhost:9100

The server listens on port 9100 by default. All endpoints return JSON.

Authentication

When auth.required = true (the default), every /v1/* endpoint requires a bearer token:

Authorization: Bearer spl_<env>_<sa_id>_<secret>

Tokens are minted against service accounts with a closed scope list. The middleware validates the token, checks the requested endpoint's required scope, and verifies the claimed actor DID (X-Syncropel-Actor) is in the SA's allowed-actors list.

The spl CLI resolves bearer tokens in this precedence: --token <value> flag first, then the SPL_TOKEN environment variable, then ~/.syncro/token. HTTP callers pass the token directly in the Authorization header.

Exempt routes (unauthenticated even when auth is enforced):

• GET /health
• POST /v1/bootstrap/service-account (one-shot per namespace)
• GET /.well-known/syncropel

For the full model — scopes, token format, rotation, federation composition — see the Authentication & Service Accounts guide. Endpoints for managing service accounts and tokens are documented in the Service accounts section below.

Health

Records

Find

Blended text search — file names, file contents, and conversations in one ranked result set. No embedding provider required. See the Find guide for hit shapes and examples.

Ingest a Record

curl -X POST http://localhost:9100/v1/records \
  -H "Content-Type: application/json" \
  -d '{
    "act": "INTEND",
    "actor": "did:sync:user:alice",
    "thread": "th_abc123...",
    "body": {"goal": "Deploy the service"},
    "clock": 0,
    "data_type": "SCALAR"
  }'

Namespace-scoped ingest

Records can target a specific namespace by setting body.namespace. The instance walks the namespace's ancestor chain and rejects the record with 403 NAMESPACE_REJECTED if any ancestor is missing or not Active. Records that omit body.namespace fall through to the implicit default namespace and are always accepted.

curl -X POST http://localhost:9100/v1/records \
  -H "Content-Type: application/json" \
  -d '{
    "act": "INTEND",
    "actor": "did:sync:user:alice",
    "thread": "th_abc123...",
    "body": {
      "namespace": "acme-corp/payments/staging",
      "goal": "Deploy v2.3 to staging"
    },
    "clock": 0,
    "data_type": "SCALAR"
  }'

If the namespace does not exist, the response is:

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "NAMESPACE_REJECTED",
  "message": "namespace 'acme-corp/payments/staging' rejected: ancestor 'acme-corp/payments' is not Active in the registry. Create it first with `spl namespace create acme-corp/payments`."
}

The error always names the failing ancestor and includes the exact recovery command. To declare namespaces use the spl namespace CLI commands, which write to the well-known thread th_namespace_registry that the engine hot-reloads on every change.

Rich query

POST /v1/records/query runs a structured filter over the record log server-side. The body is the filter AST — top-level keys are AND-combined, values are either scalars (sugar for $eq) or operator documents ($in, $gt, $like, $regex, $and, $or, $not, …). Body fields are addressed with dot-paths (body.kind, body.priority, body._refs.track.id). See the query guide for the full grammar, operator semantics, and index-awareness.

curl -s -X POST http://localhost:9100/v1/records/query \
  -H "Authorization: Bearer $SPL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "act": "INTEND",
      "actor": "did:sync:agent:dev",
      "body.kind": { "$in": ["core.task.record", "core.task.record.v1"] }
    },
    "sort": { "clock": -1 },
    "limit": 20
  }'

Request body:

Response:

{
  "object": "list",
  "data": [
    {
      "object": "record",
      "id": "7a2936eccf6b...",
      "parents": [],
      "thread": "th_abc...",
      "actor": "did:sync:agent:dev",
      "act": "INTEND",
      "body": { "kind": "core.task.record.v1", "...": "..." },
      "clock": 42,
      "data_type": "SCALAR"
    }
  ],
  "plan": {
    "sql": "SELECT ... WHERE act = ? AND actor = ? ...",
    "bind_count": 3,
    "indexed_fields": ["act", "actor", "thread"],
    "unindexed_fields": ["body.kind"]
  }
}

The plan block is only present when explain=true. Results are always tenant-filtered — records outside the caller's namespace never appear.

Error codes:

Index-backed fast paths depend on the indexed field registry — declare indexed body.<field> paths via spl config add-body-kind-manifest so predicates on them use CREATE INDEX expressions instead of scanning JSON.

Semantic search

POST /v1/records/search embeds the query through the configured provider, ranks records by cosine similarity, and returns the top K. Envelope filters (thread, actor, kind, after_clock) narrow the result after ranking so near-misses outside the scope don't crowd out the best answer. See the semantic search guide for provider setup, CLI usage, and SDK helpers.

curl -s -X POST http://localhost:9100/v1/records/search \
  -H "Authorization: Bearer $SPL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication failure logs",
    "k": 5,
    "thread": "th_incident_42"
  }'

Request body:

Response:

{
  "object": "list",
  "embedder": "ollama:nomic-embed-text",
  "k": 5,
  "data": [
    {
      "object": "record",
      "id": "3f4a...",
      "score": 0.847,
      "parents": [],
      "thread": "th_incident_42",
      "actor": "did:sync:agent:ops",
      "act": "KNOW",
      "body": { "...": "..." },
      "clock": 118,
      "data_type": "SCALAR"
    }
  ]
}

Results are tenant-filtered after scoring — a record outside the caller's namespace never reaches the response, regardless of score.

Error codes:

Backfill embeddings

POST /v1/records/embed walks records that don't yet have an embedding for the active provider and embeds them synchronously within the request. Use this once after enabling a provider to backfill existing archives; new records are embedded inline by the INGEST loop.

curl -s -X POST http://localhost:9100/v1/records/embed \
  -H "Authorization: Bearer $SPL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100}'

limit defaults to 100, max 500. Response: {embedder, embedded, skipped_empty, failed, remaining, has_more}. Loop until has_more is false — or drive the CLI wrapper spl embed --loop.

Threads

Thread Projections

curl "http://localhost:9100/v1/threads/th_abc123.../project?format=tui"

Projection formats:

Data plane (files & blobs)

The data plane is a per-namespace virtual filesystem. The control surface (/v1/data/*) manages paths and metadata; the byte surface (/v1/blobs/*) moves content. The TypeScript SDK wraps all of this as client.data.*.

Writing a file

A write is three steps: initiate, upload (chunked), commit. Pass precondition.expected_hash for optimistic concurrency — a string for compare-and-swap, null for create-only; omit it for last-writer-wins. A mismatch returns 409 with { expected_hash, current_hash }.

# 1. initiate
curl -X POST http://localhost:9100/v1/data/write/init \
  -H "content-type: application/json" \
  -d '{"path":"/files/notes.md","size_bytes":12,"content_type":"text/markdown"}'
# → { "ok": true, "upload_id": "up_...", "chunk_size": 8388608 }

# 2. upload the bytes
curl -X PUT http://localhost:9100/v1/blobs/upload/up_... \
  -H "content-range: bytes 0-11/12" --data-binary "# hello mom"

# 3. commit
curl -X POST http://localhost:9100/v1/data/write/complete \
  -H "content-type: application/json" -d '{"upload_id":"up_..."}'
# → { "ok": true, "content_hash": "9565f5...", "size_bytes": 12 }

Folds

A fold is a derived view computed from records — the turn timeline, thread state, trust, and more. One endpoint resolves any fold; Syncropel dispatches by name.

curl "http://localhost:9100/v1/folds/turn/th_abc123..."
# → { "fold_name": "turn", "cache_key": "th_abc123...", "watermark": 42, "value": [ ... ] }

Each response carries a watermark (max(records.sequence) the value covers) so a client can cache and refetch only when it moves.

Graph

Graph queries traverse the record graph of people, threads, and the records that connect them. Pass ?root=⊤ to query across everything you reach (see Universal traversal).

curl "http://localhost:9100/v1/graph/query?op=shared_context&a=did:sync:user:alice&b=did:sync:user:bob"

Trust

Actors

Dispatch

Dispatch Work

curl -X POST http://localhost:9100/v1/dispatch \
  -H "Content-Type: application/json" \
  -d '{
    "actor_did": "did:sync:agent:dev",
    "goal": "Fix the authentication bug",
    "thread_id": "th_abc123...",
    "budget": {"max_cost_usd": 1.0, "max_duration_secs": 600}
  }'

Work loops

Start a loop

curl -X POST http://localhost:9100/v1/work/loop \
  -H "Authorization: Bearer $SPL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Summarise this week of dispatches",
    "max_turns": 16
  }'

The response shape:

{
  "object": "work_loop",
  "status": "started",
  "thread": "th_...",
  "tier": "operator",
  "effective_config": {
    "max_turns": 16,
    "token_budget": null,
    "wall_clock_secs": null,
    "forbidden_tools": ["bash", "write_file"]
  },
  "watch": "/v1/threads/.../records"
}

The thread id is the loop id (there is no separate loop_id field). tier is the actor's resolved tier. effective_config carries the resource ceilings the loop will run under — combining the tier's daily limits with any per-loop task_budget you sent. watch is the SSE stream URL for live progress.

Cost preview before starting

curl -X POST http://localhost:9100/v1/work/loop/preview \
  -H "Authorization: Bearer $SPL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal": "..."}'

Returns the actor's effective tier (Trial / Paid / Team / Operator), the tier caps (max_turns, wall_clock_secs, token_budget, daily_cost_cap_usd, daily_loop_cap), usage so far today (loop_count, cost_usd), estimated_cost_usd, the tool_grant shape (default and requestable tool sets), and — if the request would exceed a cap — would_be_denied: true with denial_reason set to WORK_DAILY_CAP_EXCEEDED or WORK_DAILY_COUNT_EXCEEDED.

Watch live progress over SSE

curl -N http://localhost:9100/v1/work/loop/th_abc123.../stream \
  -H "Authorization: Bearer $SPL_TOKEN"

Emits the loop's thread records as they land — core.work.turn.v1, core.work.tool_call.v1, core.work.tool_result.v1, and ultimately core.work.loop_outcome.v1.

Cancel a loop

curl -X POST http://localhost:9100/v1/work/loop/th_abc123.../cancel \
  -H "Authorization: Bearer $SPL_TOKEN"

This emits a core.work.loop_cancel.v1 DO record on the loop's thread; the reconciler propagates the cancel to the in-process loop, which exits with a cancelled outcome.

Decisions

Approve a Decision

curl -X POST http://localhost:9100/v1/aitl/abc123.../decide \
  -H "Content-Type: application/json" \
  -d '{"decision": "approve", "reason": "Looks correct"}'

Engine

Expression cache stats

curl http://localhost:9100/v1/engine/expression_cache/stats

Returns a JSON object with hits, misses, compile_errors, hit_rate_pct, avg_compile_micros, size, capacity. Healthy steady-state: hit rate > 99%, avg compile < 100μs, size much less than capacity (1024 default). spl doctor consumes this endpoint as one of its 7 checks.

Audit

There is no dedicated /v1/audit/* endpoint family. The spl audit export CLI command produces JSONL by querying existing endpoints client-side:

1. GET /v1/threads → enumerate threads
2. GET /v1/threads/:id/records → fetch records per thread
3. Filter client-side by category (system actor, AITL verdict, dispatch outcome, governance) and time window
4. Emit one JSON object per matching record on stdout

This means spl audit export works against any Syncropel instance without server-side changes. The trade-off is that it's O(n) over thread count — for very large stores you should pass --thread <id> to scope the query.

A server-side /v1/audit/export?since=...&categories=... endpoint is planned for a future release. It would push the filtering into SQL and return a single JSONL stream, removing the per-thread round trips. For now, use spl audit export (scoped with --thread <id> for large stores).

For SIEM integration recipes (cron rotation, Splunk/Elastic/Loki pipelines, etc.) see the SIEM Integration guide.

Permission denials are NOT in audit export today

HTTP middleware permission denials are emitted as tracing::warn! events to the instance log (~/.syncro/logs/spl.log), not as records. They appear in the log filtered by grep "PERMISSION DENIED" but do NOT appear in spl audit export output. Promoting denials to first-class audit records is tracked as a follow-up — for now treat the instance log and the audit export as complementary security-event streams.

Proxy

The proxy endpoint accepts a Messages-API-shape request body and translates it into Syncropel records. Use this to route existing AI tool calls through Syncropel for observability and trust tracking.

Capability discovery

Two endpoints expose what the instance supports. Clients should prefer them over hard-coding feature flags — the manifest is the single source of truth.

GET /v1/capabilities

The authenticated surface. Returns the capability manifest scoped to the caller — auth state, advertised MCP tools, supported DID methods, store backend, available transports, API version. Clients use this to enable or disable features based on what the connected instance actually supports; SDKs feature-detect without a trial-and-error HTTP round trip.

curl -s -H "Authorization: Bearer $SPL_TOKEN" \
  http://localhost:9100/v1/capabilities | jq

Response (elided):

{
  "object": "capabilities_manifest",
  "manifest_version": "1",
  "daemon": {
    "version": "0.X.Y",
    "api_version": "v1",
    "spec_version": "0.18"
  },
  "auth": { "required": true },
  "did_methods": ["did:sync", "did:key", "did:web"],
  "record": {
    "algebra_version": "v1",
    "hashed_fields": ["parents", "thread", "actor", "act", "body", "clock", "data_type"]
  },
  "mcp_tools": ["find", "create_thread", "emit_record", "read_thread", "trust_query", "fold_thread", "dispatch", "fan_out"],
  "transports": { "...": "..." },
  "semantic_search": { "...": "..." },
  "store_backends": ["sqlite", "memory"],
  "capabilities": {
    "records": true,
    "threads": true,
    "sync": true,
    "federation_consent": true,
    "directory": false,
    "...": "..."
  },
  "conventions": {
    "aitl_path": "/v1/aitl",
    "identity_path": "/v1/identity",
    "sync_path": "/v1/sync",
    "trust_path": "/v1/trust"
  }
}

The capabilities map is a set of boolean feature flags covering the full surface — sync, directory (gated by config.directory_enabled), federation_consent, identity, dispatch_observability, cusum_alerts, trust_detail, reconcile_queue, and more. Flags are additive across releases; absence of a flag means unsupported.

When auth is off, the endpoint is reachable without a token. When auth is on, an unauthenticated call returns 401 AUTH_REQUIRED — use /.well-known/syncropel below for the public view.

GET /.well-known/syncropel

The unauthenticated surface, served at the Well-Known URI location so any peer on the public internet can discover an instance without prior coordination. The response envelope carries two top-level manifests as sibling keys:

curl -s http://localhost:9100/.well-known/syncropel | jq 'keys'
# [ "capabilities_manifest", "federation_manifest" ]

The federation_manifest key is present only when the instance is federation-enabled and has a signing key available. Peers that only want the client view can read capabilities_manifest and ignore the federation sibling.

Federation manifest shape

The federation_manifest is Ed25519-signed over its canonical JSON (excluding the signature field). Verification proceeds against the DID document resolved from instance.did. Consumers — spl discover, federation directories, peer-discovery CLIs — verify the signature before trusting any advertised field.

{
  "object": "federation_manifest",
  "manifest_version": "1",
  "daemon": {
    "did": "did:web:alice.dev",
    "version": "0.X.Y",
    "federation_protocol_version": "0.13"
  },
  "federation": {
    "enabled": true,
    "pair_endpoint": "https://alice.dev/v1/sync",
    "sync_change_endpoint": "https://alice.dev/v1/sync/changes",
    "sync_record_endpoint": "https://alice.dev/v1/sync/records"
  },
  "advertises": {
    "kinds": ["music.catalog.track", "music.catalog.artist"],
    "refs": [],
    "namespaces": ["alice-music"]
  },
  "consent_policy": {
    "default_posture": "pair-then-ask",
    "accepts_pair_requests": true,
    "requires_did_method": [],
    "rejects_did_method": []
  },
  "capabilities_ref": {
    "url": "https://alice.dev/.well-known/syncropel",
    "key": "capabilities_manifest"
  },
  "responders_ref": {
    "url": "https://alice.dev/.well-known/syncropel",
    "key": "responders_manifest"
  },
  "directory": {
    "registered_at": [],
    "directory_registration_id": null
  },
  "signature": {
    "alg": "Ed25519",
    "key_id": "did:web:alice.dev#key-1",
    "signature": "<base64>",
    "signed_at": "2026-04-22T18:00:00Z",
    "expires_at": "2026-04-29T18:00:00Z"
  }
}

Key fields:

For the discovery workflow and how this composes with did:web, did:sync, and mDNS discovery, see the federation discovery guide.

Identity

Returns the instance's own identity — {actor, display_name, did, method, key_path, key_fingerprint} — populated at instance startup. New installs generate a did:key:... on spl init; upgraded installs without a DID need spl init --force once.

This endpoint requires a valid bearer token. Since v0.53 the response also reports the calling token's own authentication state, so a renderer can decide what to show the viewer:

The anonymous form of this block — is_authenticated: false, scopes: [] — is what an unauthenticated caller sees inside the bootstrap aggregate below.

Instance

Endpoints that resolve an instance's chrome — the core.instance.shell.v1 record that frames every screen of Studio. See Instance chrome for the concept.

GET /v1/instance/shell

Returns the resolved core.instance.shell.v1 record. Requires a valid bearer token (records:read scope).

{
  "object": "instance_shell",
  "version": 4,
  "shell": { "kind": "core.instance.shell.v1", "...": "..." }
}

Returns 404 when no chrome has been published — a renderer falls back to its bundled default.

GET /v1/instance/bootstrap

The aggregate a renderer calls on load. Returns the published chrome, the instance metadata, and the caller's identity together, so the frame draws without a waterfall of requests.

This endpoint is auth-invariant — it needs no token. An anonymous caller gets the public surface; a caller presenting a valid token additionally sees their resolved scopes in the identity block.

{
  "object": "instance_bootstrap",
  "shell": { "...": "core.instance.shell.v1 record, or null" },
  "metadata": { "...": "core.instance.metadata.v1 record, or null" },
  "identity": { "object": "identity", "is_authenticated": false, "scopes": [] },
  "is_owner": false,
  "ts": "2026-05-20T18:30:00Z"
}

shell is null when no chrome has been published. is_owner is true only when the caller's identity matches the chrome's owner.

Federation sync

Federation is pull-first HTTP replication between two instances. Both flat (/v1/sync/*) and domain-grouped (/v1/federation/sync/*) routes are served.

Changes feed

Feed modes:

• normal (default) — single response, returns up to limit (default 1000, max 10000) records
• longpoll — holds the connection up to 30s waiting for new records
• continuous — Server-Sent Events stream (for live subscriptions)

Response: {records: [{id, record}], next_cursor: "opaque", has_more: bool}. Records are consent-filtered per target_namespace (see consent guide).

Record batch fetch

Request body: {ids: [...]} or {records: [...]}. When the x-syncropel-federation: 1 header is set, each record must include a sig field — Ed25519 over canonical JSON. Unsigned federation requests return HTTP 422. Replay of previously-accepted records is deduped via content-addressed hash.

Pair management

Create body: {peer_did, peer_url, thread_id}. Response includes pair_id and, if the instance detects a loopback misconfiguration, a warning field with the recovery command.

The pair direction is semantically "target pulls source" — creating a pair on B with peer_did=A means records flow A→B. For bidirectional sync, create a pair on each side.

Pair state is persistent across instance restart — the registry is rebuilt from lifecycle records on a reserved control thread at startup.

Federation health + per-pair stats

Aggregate response shape (elided):

{
  "object": "sync_health",
  "pairs_total": 5,
  "pairs_by_state": { "running": 3, "failing": 1, "paused": 1 },
  "records_pulled_last_hour": 2147,
  "mean_delivery_latency_ms": 847,
  "p95_delivery_latency_ms": 2410,
  "slowest_pairs": [...],
  "most_errored_pairs": [...],
  "drift_alerts": [...]
}

Metrics are in-memory with a 1-hour rolling window — ephemeral, reset on instance restart. The instance-wide /health endpoint also includes a federation summary for one-glance status.

LAN peer discovery

Returns a roster of peers with DID, endpoint, namespace, handle, capabilities (all from their TXT records), and last_seen timestamps. Used by spl fleet sync peers discover --method mdns.

The instance advertises itself on _syncropel._tcp.local when [sync.discovery] mdns_broadcast = true; it listens for other instances' advertisements by default. Failures during mDNS init are logged but never fail the instance (LAN discovery is a soft feature).

did:sync directory

Gated by config.directory_enabled — off by default. An instance can act as a did:sync directory provider; most installs don't need to.

Service accounts

Bootstrap the first service account

POST /v1/bootstrap/service-account is a one-shot, unauthenticated endpoint used to create the first SA on a fresh instance. Once any SA exists in the target namespace, the endpoint returns 409 BOOTSTRAP_CLOSED and you must use the authenticated POST /v1/service-accounts path instead.

curl -X POST http://localhost:9100/v1/bootstrap/service-account \
  -H "Content-Type: application/json" \
  -d '{
    "service_account_id": "sa_abc123def456ghi7",
    "display_name": "First admin",
    "scopes": ["admin"],
    "namespace": "default",
    "with_token": {
      "token_id": "a3f9e7d1c8b2h6j4k5m7n9p1q3r5t7v9",
      "env_tag": "prod",
      "created_at": "2026-04-20T12:30:00Z"
    }
  }'

Response (201 Created):

{
  "object": "bootstrap_result",
  "service_account_id": "sa_abc123def456ghi7",
  "sa_record_id": "7a2936eccf6b...",
  "namespace": "default",
  "token_id": "a3f9e7d1c8b2...",
  "token_record_id": "151439fe2972..."
}

The client is responsible for generating service_account_id + token_id. The CLI (spl service-account create --bootstrap --with-token) handles this automatically.

List service accounts

curl -H "Authorization: Bearer $SPL_TOKEN" \
  http://localhost:9100/v1/service-accounts

Returns an array. api_key is always null in list responses — plaintext tokens are only disclosed at creation time.

[
  {
    "id": "sa_abc123def456ghi7",
    "name": "CI runner",
    "did": "did:sync:system:sa_abc123def456ghi7",
    "api_key": null,
    "active": true,
    "created_at": null
  }
]

Create a service account + token

curl -X POST http://localhost:9100/v1/service-accounts \
  -H "Authorization: Bearer $SPL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Webhook integration"}'

Response (201 Created) includes the plaintext bearer token once — save it immediately:

{
  "id": "sa_new123...",
  "name": "Webhook integration",
  "did": "did:sync:system:sa_new123...",
  "api_key": "spl_prod_sa_new123_a3f9e7d1c8b2h6j4k5m7n9p1q3r5t7v9",
  "active": true,
  "created_at": null
}

Revoke a service account

DELETE /v1/service-accounts/{id} performs per-SA revocation: every token ever minted for the SA becomes invalid, and future token mints for the SA are blocked.

curl -X DELETE -H "Authorization: Bearer $SPL_TOKEN" \
  http://localhost:9100/v1/service-accounts/sa_abc123def456ghi7

Response (200): {"status": "revoked"}.

Rotate an SA's key

POST /v1/service-accounts/{id}/rotate-key mints a new token first, then revokes previous tokens. Guarantees callers don't get locked out on partial failure.

curl -X POST -H "Authorization: Bearer $SPL_TOKEN" \
  http://localhost:9100/v1/service-accounts/sa_abc123def456ghi7/rotate-key

Response (200):

{
  "id": "sa_abc123def456ghi7",
  "api_key": "spl_prod_sa_abc123_new_secret_here"
}

Error codes

Pair-share-invite

The surface for adding either a new device of yours (guest holder) or a federated colleague (federated holder). Operator-facing guide: Pair, share, invite. SDK surface: client.invites.* in the TypeScript SDK guide.

The (always) annotation on admin routes is load-bearing: even with the instance's auth.required = false master switch enabled (auth-off mode for local dev), the operator routes refuse anonymous callers via a separate always_admin_auth_route gate. The auth-off switch covers data-plane endpoints; the admin gate is independent.

Issue a pair invite

curl -X POST http://localhost:9100/v1/invites \
  -H "Authorization: Bearer $SPL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl_seconds": 86400,
    "max_uses": 1,
    "scopes": ["records:read", "records:write"],
    "accept_holder_types": ["guest"],
    "device_label": "Alice phone",
    "notes": "personal device — for travel"
  }'

Response (201):

{
  "object": "invite",
  "invite_id": "inv_a3f9...",
  "record_id": "7a29...",
  "issuer_did": "did:sync:user:alice",
  "issuer_key_fp": "abc123...",
  "issued_at": "2026-05-23T18:30:00Z",
  "expires_at": "2026-05-24T18:30:00Z",
  "max_uses": 1,
  "uses_remaining": 1,
  "redirect_url": "https://alice.syncropel.app/i/inv_a3f9...?sig=...",
  "qr_payload": "https://alice.syncropel.app/i/inv_a3f9...?sig=..."
}

The optional scope_target body field narrows the invite — {"kind": "thread", "thread_id": "th_..."} or {"kind": "namespace", "namespace": "..."} instead of the default {"kind": "instance"}.

Preview an invite (public)

curl https://alice.syncropel.app/v1/invites/inv_a3f9...

Returns folded state: revoked, expired, uses_remaining, accept_holder_types, scopes, and the issuer's signature for verification. No bearer required — this is what the QR landing page reads.

Redeem — guest holder

curl -X POST https://alice.syncropel.app/v1/invites/inv_a3f9.../redeem \
  -H "Content-Type: application/json" \
  -d '{
    "holder_type": "guest",
    "holder_pubkey": "base64url-encoded-ed25519-pubkey",
    "holder_label": "Alice phone"
  }'

Response includes the new bearer (bearer), the actor DID Syncropel minted for the holder (actor_did), the granted scopes, and the bearer's expires_at.

Redeem — federated holder

curl -X POST https://alice.syncropel.app/v1/invites/inv_a3f9.../redeem \
  -H "Content-Type: application/json" \
  -d '{
    "holder_type": "federated",
    "holder_did": "did:sync:user:bob",
    "holder_proof": "base64url-encoded-ed25519-signature",
    "holder_proof_issued_at_ms": 1729900000000,
    "signer_instance_did": "did:sync:instance:bob.syncropel.app"
  }'

Syncropel resolves Bob's DID document, verifies the Ed25519 signature against the signer_instance_did's key, and rejects (with audit) on bad_proof, key_unknown, or freshness_violation (issued-at-ms outside the ±60s window).

Bulk revoke

curl -X POST http://localhost:9100/v1/invites/bulk-revoke \
  -H "Authorization: Bearer $SPL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filter": "expired", "reason": "scheduled cleanup"}'

Response: {"revoked_count": N, "invite_ids": [...], "filter": "expired"}. Allowed filter values are expired and exhausted.

Rotate a bearer

curl -X POST http://localhost:9100/v1/tokens/$TOKEN_ID/rotate \
  -H "Authorization: Bearer $CURRENT_BEARER"

Self-only — Syncropel computes sha256($CURRENT_BEARER) and rejects with ROTATE_NOT_SELF if it doesn't match $TOKEN_ID. Response includes the new bearer + new expires_at. The previous bearer is invalidated.

Error codes

CORS

All /v1/* + /.well-known/* + /directory/* endpoints include CORS headers (tower-http::CorsLayer with permissive defaults). The instance at localhost:9100 is reachable from web UI origins without proxy configuration.