Scrybert Developer API

Reference for the Scrybert Developer API.

Overview

The Developer API provides programmatic access to a Scrybert account's conversation data and to-do list. For a description of the underlying product behavior, see Features and How It Works. Access to this API is governed by a developer key, distinct from the account's primary credential and limited to the scope described in this document.

Four components are exposed:

• An MCP server, for AI assistants and MCP-compatible clients.
• REST endpoints for pulling conversations by tag.
• A REST endpoint for creating to-do items.
• An outbound webhook system for four account events.

Authentication

All Developer API requests authenticate with a developer key. One key exists per account.

Getting a key

1. In the app: Settings > Developer.
2. Tap Generate Key.
3. The full key is shown once, at generation time. Copy it immediately — it cannot be viewed again.

Generating a new key immediately invalidates the previous one. The server stores only the key's SHA-256 hash and its last four characters, so if the full value is lost, generate a new one rather than trying to recover it.

Key format:

scry_dev_<43 characters, URL-safe base64>

Requests authenticate with a bearer token:

Authorization: Bearer scry_dev_<key>

Key comparison is performed in constant time against the stored hash.

Retention requirement

Key generation and all authenticated requests, except webhook delivery, require the account's Keeper (data retention) setting to be 30 days or longer. At a Keeper setting of 0 days, these requests return 403:

{"detail": "Turn Keeper on for 30 days or longer to use this."}

Webhooks are exempt from this requirement.

MCP server

Seven tools are exposed. Six are read-only; one performs a write.

A session identifier has the form 20260921-093512, corresponding to the timestamp recording began. Read operations are limited to data retained under the account's Keeper setting. Data outside the scope of this document, including My People, My Things, and Pivotal Moments, is not accessible through this interface.

OAuth authentication, required by claude.ai's and ChatGPT's browser-based connectors, is not implemented. Clients that accept a bearer token directly, including Claude Code, are supported.

Pull conversations by tag

Every conversation carries up to three tags: the standard categories Scrybert assigns (for example Work, Family, Finance) and the account's three custom tags. Where the account holder has changed a conversation's tags in the app, those choices are used. Custom tags are returned under their current names; renaming a custom tag in the app changes it everywhere at once.

List tags

{
  "tags": [ { "tag": string, "conversations": integer }, ... ]
}

Conversations by tag

Example:

curl "https://api.scrybert.com/v1/developer/conversations?tag=Work&full=true" \
  -H "Authorization: Bearer scry_dev_<key>"

Response (status 200), newest first:

{
  "tag": string or null,
  "total": integer,
  "returned": integer,
  "conversations": [
    {
      "session_id": string,
      "when": string,
      "title": string,
      "blurb": string,
      "tags": [string],
      "topics": [string],
      "people": [string],
      "things": [string],
      "action_items": integer, or [string] when full=true,
      "summary": string (Markdown, full=true),
      "list_items": [string] (full=true),
      "transcript": string (transcript=true)
    }
  ]
}

Only conversations retained under the account's Keeper setting are returned. An invalid or missing key returns 401; Keeper off returns 403.

To-do endpoint

Request body:

{
  "text": string, required, max 500 characters,
  "due": string, optional, "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM",
  "source": string, optional, max 40 characters, default "API",
  "id": string, optional, max 128 characters
}

Response, new item (status 201):

{
  "uid": string,
  "text": string,
  "due": string or null,
  "source": string,
  "created_at": integer (unix ms),
  "duplicate": false
}

If id is supplied and matches a previous request, the endpoint returns status 200 with "duplicate": true and the original item, rather than creating a second item.

An invalid due value returns 422. A missing or empty text value returns 422.

Rate limit: 120 creations per account per hour, tracked in memory. Requests exceeding this limit return 429.

Items created through this endpoint appear on the account's device on the next synchronization cycle, which occurs on application open or at intervals not exceeding 15 minutes.

Webhooks

Four account events are available for subscription. Each event has an independent enabled state and target URL, configured in Settings > Developer.

Payload envelope

{
  "id": string (uuid, unique per delivery attempt group),
  "event": string,
  "test": boolean,
  "created_at": string (ISO 8601, UTC),
  "data": object
}

Request headers

Content-Type: application/json
User-Agent: Scrybert-Webhooks/1
Scrybert-Event: <event name>
Scrybert-Delivery: <delivery id>
Scrybert-Signature: t=<unix timestamp>,v1=<hex-encoded HMAC-SHA256>

Signature verification

Each account has one webhook signing secret, prefixed whsec_, available in Settings > Developer. The v1 value is computed as:

HMAC-SHA256(key = secret, message = "{t}." + raw_request_body)

Reference implementation:

import hmac, hashlib

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = parts["t"], parts["v1"]
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

The signature must be computed over the raw request body as received. Re-serializing the payload before verification can alter key order or whitespace and will produce a mismatch.

Delivery behavior

Pivotal Moments data is not included in any webhook payload under any event.

Rate limits and requirements

Status codes

Support

For issues not covered by this document, see Contact.