Question 1

what is xmark?

Accepted Answer

xmark lets you chat with your X (Twitter) bookmarks. you sign in, connect your X account, sync your bookmarks, and ask questions in plain english. xmark uses semantic search over the full bookmark contents (text, quoted tweets, linked articles, image alt text) to answer.

Question 2

how do I sign up?

Accepted Answer

go to /auth/signup and sign in with Google. once you're in, head to /bookmarks and connect your X account via the 'connect' button. xmark uses two separate OAuth flows: Google for the xmark account itself, X for read access to your bookmarks.

Question 3

do I need an X (Twitter) account?

Accepted Answer

yes. xmark reads your X bookmarks via the X API, so you need an X account with bookmarks already saved. if you've never bookmarked anything on X, there's nothing for xmark to chat with.

Question 4

what plan do I need?

Accepted Answer

xmark is a single $5/month plan. no free tier, no upgrades. one price covers unlimited bookmark sync, unlimited chat messages, and access to all features.

Question 5

how do I sync my bookmarks?

Accepted Answer

open /bookmarks and click 'sync'. xmark pulls your bookmarks from X via the X API and embeds new ones with OpenAI's text-embedding-3-small for semantic search. the first sync may take a minute if you have hundreds of bookmarks; subsequent syncs only process new ones.

Question 6

is sync automatic?

Accepted Answer

no. sync is manual — you click the button when you want fresh bookmarks. this keeps API usage predictable and avoids hitting X's rate limits unnecessarily.

Question 7

what gets synced?

Accepted Answer

the full tweet text (including long-form note tweets), author info, engagement metrics, quoted tweets, image alt text, linked article metadata (title + description), and topic annotations. all of this becomes searchable in chat.

Question 8

X says my account 'needs to be reconnected' — what now?

Accepted Answer

X's OAuth tokens expire and rotate. when xmark can't refresh your token, you'll see a 'reconnect' prompt on /bookmarks or /settings. click reconnect to re-authorize. xmark detects rotated refresh tokens and saves them automatically going forward.

Question 9

can I delete a bookmark?

Accepted Answer

yes. clicking the remove icon on a bookmark unbookmarks it on X AND removes it from xmark in one step. both must succeed — leaving X bookmarked while removing locally would let the next sync re-create it.

Question 10

how does chat work?

Accepted Answer

you ask a question, xmark embeds it with OpenAI, retrieves the most relevant bookmarks via pgvector cosine similarity, then asks Claude (claude-sonnet-4-5) to answer using those bookmarks as context. responses cite each bookmark by number — [1], [2] — so you can click through to the original tweet.

Question 11

how many bookmarks does chat consider?

Accepted Answer

chat retrieves up to 800 of your most relevant bookmarks per query, ranked by semantic similarity to your question. if you have more, the lowest-ranked are excluded for that specific query, not deleted.

Question 12

why is chat citing the same tweet multiple times?

Accepted Answer

Claude is told to cite every bookmark it references with a number. if a single bookmark is the best match for several parts of an answer, you'll see the same number repeated. clicking any instance of [N] opens the original tweet.

Question 13

do you train models on my bookmarks?

Accepted Answer

no. your bookmarks are sent to OpenAI for embeddings (one-shot, not retained per OpenAI's API terms) and to Anthropic for chat answers (one-shot, not retained per Anthropic's API terms). xmark stores embeddings + bookmark text in your private Supabase row, gated by row-level security.

Question 14

where is my data stored?

Accepted Answer

in xmark's Supabase Postgres database, encrypted at rest. row-level security policies ensure only your authenticated session can read your bookmarks and conversations. nobody else — no admin, no other user — can see your data.

Question 15

what happens to my X access token?

Accepted Answer

X tokens are encrypted with AES-256-GCM before being written to the database. only the running app can decrypt them; database backups don't expose plaintext tokens.

Question 16

how do I delete my account?

Accepted Answer

go to /settings and click 'delete account'. xmark soft-deletes your profile + bookmarks + conversations and hard-deletes your active credentials (X OAuth tokens, API keys). signing back in within the retention window restores your account; after that, the soft-deleted rows are purged.

Question 17

what does the $5/month plan include?

Accepted Answer

unlimited bookmark sync, unlimited chat messages, full access to every feature. the plan is the only paid tier — there are no upsells or per-message overages.

Question 18

how do I cancel?

Accepted Answer

go to /settings → billing and click 'manage subscription'. you'll be redirected to Stripe's customer portal where you can cancel at the end of the current period. cancellation stops the next charge; you keep access until the period ends.

Question 19

do you offer refunds?

Accepted Answer

if you cancel within the first 7 days of a new subscription, email josh@jclvsh.art and we'll refund your most recent payment. after that, cancellations stop future charges but the current period isn't refunded.

Question 20

sync is stuck or won't start

Accepted Answer

xmark uses a Redis lock to prevent concurrent syncs for the same account. if a previous sync hung, the lock auto-expires after 30 seconds — wait, then click sync again. if it still won't start, your X token may have expired (see the reconnect prompt).

Question 21

chat says 'subscription required' but I just paid

Accepted Answer

Stripe webhooks usually arrive within seconds of checkout, but rarely take a minute. refresh /chat after 60 seconds; if you still see the message, contact support with your Stripe email and we'll reconcile the subscription manually.

Question 22

I'm getting rate-limited by X

Accepted Answer

xmark uses X's pay-per-use API tier with strict rate limits. if you hammer the sync button or run many parallel sessions, X may briefly 429 you. wait a few minutes and try again. xmark treats 429 as 'X is healthy, just busy' — it's not a permanent error.

scope	description
read	read-only access to owned resources
write	create and update owned resources
delete	delete owned resources
admin	manage API keys and webhook endpoints

code	HTTP	description
AUTH_001	401	missing or invalid authorization header
AUTH_002	403	API key missing required scope
AUTH_004	401	invalid or revoked API key

code	HTTP	description
BILLING_001	402	no active subscription
BILLING_006	402	plan usage limit reached (402 on chat quota, 429 on sync rate)
BILLING_007	402	subscription required for this operation
BILLING_008	403	current plan does not include this feature

code	HTTP	description
SERVER_001	500	internal server error
SERVER_002	400	bad request (malformed body or missing field)
SERVER_003	404	resource not found
SERVER_004	405	method not allowed
SERVER_005	400	validation failed
SERVER_008	500	database error
SERVER_012	409	conflict (e.g. concurrent modification)

code	HTTP	description
HOOK_001	401	invalid webhook signature
HOOK_002	500	webhook processing failed
HOOK_004	408	webhook delivery timed out

xmark API

authentication

header format

verify your key

scopes

API reference

bookmarks

chat

conversations

usage

error handling