API Draft
Honest status first: SyncPocket App has no public network API yet. This page documents what you can integrate with today, and lays out the draft proposal for the API we plan to expose — published early so future partners and developers can give feedback before anything is frozen.
What you can build against today
SyncPocket App is local-first, and its current integration surface is the documented on-disk format:
- Read the archive:
~/Library/Application Support/MemoryApp/items.jsonis a versionedHistoryEnvelopecontaining items and Board definitions; binary payloads live next to it inblobs/. - Reuse the model:
MemoryKitcontains the exact item, Board, retention, persistence and sync-interface implementation — Foundation/CryptoKit only, so it can be embedded in another Swift tool.
Rule of thumb: treat items.json as read-only from outside the app. If you write to it while the app runs, your changes can be overwritten. A safe write API is exactly what the proposal below is for.
Not an API: iCloud sync
Signed, entitled builds use CloudKitSyncEngine and the user's private CloudKit database; isolated UI tests use NoopSyncEngine. This is an implementation detail, not a public API — there are no SyncPocket App data servers to call, and third parties cannot access users' archives through it. Public release remains gated on production signing and two-device verification.
Current item routing for reminders
Local reminder notifications store the stable item UUID in notification metadata and route it directly to the item's detail view. The iOS router also recognizes the internal shape memoryapp://item/<UUID>. This is an app-owned navigation contract today, not yet a registered public automation API.
Draft proposal: local automation API
The first public API is planned as a local one (the app runs on the user's machine and owns local data), likely exposed as a URL scheme and/or command-line interface. Sketch:
| Operation | Sketch | Purpose |
|---|---|---|
| Query history | memoryapp://search?q=…&type=link | Launcher/automation integrations (Raycast, Alfred, Shortcuts). |
| Open exact item | memoryapp://item/<UUID> | Use the same stable destination as reminder notifications. |
| Add an item | memoryapp://add?text=… | Let other tools push into the memory safely. |
| Pin / unpin | memoryapp://pin?id=… | Automation around frequently used snippets. |
| Add to Board | memoryapp://board/add?item=…&board=… | Organize an item without editing the archive directly. |
| Set reminder | memoryapp://remind?id=…&at=… | Schedule the local exact-item notification. |
Draft proposal: remote API
If/when a hosted component exists (for example for shared team Boards or partner integrations), the API is expected to look like this. Everything below is a proposal and can change without notice.
Conventions
- Base URL:
https://api.syncpocket.app/v1(reserved, not live). - JSON in/out; UTF-8; ISO 8601 timestamps.
- Auth:
Authorization: Bearer <token>(per-user tokens, scoped). - Versioning in the path (
/v1); breaking changes only with a version bump.
Resource: Item
The wire format mirrors the on-disk ClipItem, with dates as ISO 8601 and payloads as URLs:
{
"id": "5b1e9c2a-8f1d-4a5e-9c77-2a1b3c4d5e6f",
"type": "color", // text | link | color | image | file
"date": "2026-07-07T17:24:00Z",
"createdAt": "2026-07-07T17:24:00Z",
"plainText": "#FF6B6B",
"sourceAppName": "Figma",
"pinned": false,
"boardIDs": ["f0000000-0000-4000-8000-000000000001"],
"reminderDate": "2026-07-15T14:00:00Z",
"contentHash": "sha256:a1b2c3…"
}Endpoints (sketch)
| Method & path | Description |
|---|---|
GET /v1/items | List items. Filters: type, pinned, board, q and since; cursor pagination. |
POST /v1/items | Add an item. Server computes contentHash and deduplicates — posting existing content bumps it to the top and returns the existing item. |
GET /v1/items/{id} | Fetch one item (payload links included). |
PATCH /v1/items/{id} | Update mutable fields such as pinned, boardIDs and reminderDate. |
DELETE /v1/items/{id} | Delete an item. |
GET /v1/boards | List Pinned, Loved, Saved and custom Boards. |
POST /v1/boards | Create a named custom Board. |
PATCH /v1/boards/{id} | Rename a custom Board. |
DELETE /v1/boards/{id} | Delete a custom Board without deleting its items. |
Deduplication contract
The same content-hash semantics as the local format: identity is sha256 of the content. Clients may compute the hash themselves to check for existence before uploading payloads.
Feedback
Building a launcher plugin, an automation, or interested in a partnership? Tell us what you need from this API before it ships — early feedback is the whole reason this draft is public. Write to hello@syncpocket.app or use the contact page.