{ "openapi": "3.1.0", "info": { "title": "xmark API", "version": "0.17.0", "summary": "Semantic search and chat over a user's X (Twitter) bookmarks.", "description": "xmark exposes a REST surface that lets developers query their X bookmark library by semantic search and ask natural-language questions with citations, plus manage bookmarks, conversations, insights, notifications, and account settings. Authentication uses scoped API keys created in /settings/api, or a Supabase user JWT for native clients.", "contact": { "name": "xmark", "url": "https://www.xmark.dev", "email": "josh@jclvsh.art" }, "license": { "name": "Proprietary", "url": "https://www.xmark.dev/terms" }, "x-service-info": { "name": "xmark", "category": "Knowledge", "docs": { "homepage": "https://www.xmark.dev", "apiReference": "https://www.xmark.dev/docs", "llms": "https://api.xmark.dev/llms.txt" } }, "x-guidance": [ "Use scoped API keys with the minimum scope needed.", "All requests must be HTTPS. The canonical host is api.xmark.dev.", "See https://api.xmark.dev/llms-full.txt for full documentation." ] }, "servers": [ { "url": "https://api.xmark.dev", "description": "Production" } ], "security": [ { "apiKeyAuth": [] } ], "tags": [ { "name": "bookmarks", "description": "read, search, and sync the authenticated user's X bookmarks." }, { "name": "chat", "description": "ask natural-language questions about bookmarks; Claude answers with citations grounded in them." }, { "name": "conversations", "description": "list, read, and delete past chat conversations." }, { "name": "usage", "description": "plan and quota usage for the authenticated user." }, { "name": "insights", "description": "bookmark analytics: velocity, top authors/topics, early calls, and follow recommendations." }, { "name": "notifications", "description": "the caller's notification inbox." }, { "name": "connections", "description": "connect and disconnect the caller's X account (native OAuth)." }, { "name": "account", "description": "profile, onboarding, settings, and notification preferences." }, { "name": "billing", "description": "subscription management and Apple receipt verification." }, { "name": "referrals", "description": "the 'share your wrapped on X for 2 months free' referral." }, { "name": "wrapped", "description": "the caller's 'xmark wrapped' aggregate stats." }, { "name": "API keys", "description": "manage API keys programmatically. key-management endpoints require the admin scope." }, { "name": "webhooks", "description": "developer webhook endpoints with signed deliveries. all endpoints require the admin scope." }, { "name": "changelog", "description": "machine-readable release history - public, no API key required." } ], "paths": { "/bookmarks": { "get": { "x-status": "live", "tags": [ "bookmarks" ], "summary": "paginated list of the caller's bookmarks, newest first", "operationId": "listBookmarks", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bookmark" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "pageSize", "total", "totalPages" ] } }, "required": [ "data", "pagination" ] }, "example": { "success": true, "data": [ { "id": "uuid", "tweet_id": "1234567890", "text": "full tweet text, including long-form note tweets", "author": { "id": "string | absent", "username": "jclvsh", "name": "josh", "profile_image_url": "https://... | null" }, "bookmarked_at": "ISO 8601 | null", "url": "https://x.com/jclvsh/status/1234567890", "public_metrics": { "like_count": 42, "retweet_count": 7 }, "media": [ {} ] } ], "pagination": { "page": 1, "pageSize": 50, "total": 1234, "totalPages": 25 } } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] } }, "/bookmarks/{id}": { "get": { "x-status": "live", "tags": [ "bookmarks" ], "summary": "fetch a single bookmark", "operationId": "getBookmark", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Bookmark" } }, "required": [ "data" ] }, "example": { "success": true, "data": { "id": "uuid", "tweet_id": "1234567890", "text": "full tweet text, including long-form note tweets", "author": { "id": "string | absent", "username": "jclvsh", "name": "josh", "profile_image_url": "https://... | null" }, "bookmarked_at": "ISO 8601 | null", "url": "https://x.com/jclvsh/status/1234567890", "public_metrics": { "like_count": 42, "retweet_count": 7 }, "media": [ {} ] } } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] }, "delete": { "x-status": "live", "tags": [ "bookmarks" ], "summary": "remove a bookmark. local-only by default (the next sync re-creates anything still bookmarked on X); pass unbookmark=true to also remove it on X", "operationId": "deleteBookmark", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MutationAck" } }, "required": [ "data" ] }, "example": { "success": true, "data": { "removed": true } } } } }, "400": { "description": "SERVER_002: x account needs to be reconnected (unbookmark=true only)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" }, { "name": "unbookmark", "in": "query", "required": false, "description": "also remove the bookmark on X via the stored OAuth token", "schema": { "type": "boolean", "default": false } } ] } }, "/bookmarks/search": { "post": { "x-status": "live", "tags": [ "bookmarks" ], "summary": "semantic search over the caller's bookmark library (pgvector + OpenAI embeddings)", "operationId": "searchBookmarks", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } } }, "required": [ "data" ] }, "example": { "success": true, "data": [ { "bookmark": { "id": "uuid", "tweet_id": "1234567890", "text": "...", "author": { "username": "jclvsh", "name": "josh" }, "bookmarked_at": "ISO 8601 | null", "url": "https://x.com/..." }, "score": 0.83 } ] } } } }, "400": { "description": "SERVER_005: invalid json body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "natural-language search query" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "description": "max results", "default": 10 } }, "required": [ "query" ] } } } } } }, "/bookmarks/sync": { "post": { "x-status": "live", "tags": [ "bookmarks" ], "summary": "pull the latest bookmarks from the connected X account, embed new ones, and store them. large libraries sync in chunks: call again while done is false. when X rate-limits the crawl (10 req / 15 min) the response carries retryAfterSeconds: wait that long before the next call, and the sync resumes where it stopped", "operationId": "syncBookmarks", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/SyncResult" } }, "required": [ "data" ] }, "example": { "success": true, "data": { "count": 1234, "newCount": 12, "removedCount": 3, "durationMs": 8200, "done": true } } } } }, "400": { "description": "SERVER_002: x account needs to be reconnected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "SERVER_012: a sync is already in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "BILLING_006: free-tier daily sync limit reached (1/day)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write" } }, "/chat": { "post": { "x-status": "live", "tags": [ "chat" ], "summary": "submit a question. xmark retrieves the most relevant bookmarks via semantic search and has Claude generate an answer with inline citations. returns a single JSON response", "operationId": "chat", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ChatResult" } }, "required": [ "data" ] }, "example": { "success": true, "data": { "answer": "string", "citations": [ { "bookmark_id": "uuid", "tweet_url": "https://x.com/...", "author": "jclvsh", "snippet": "..." } ], "conversation_id": "uuid" } } } } }, "400": { "description": "SERVER_005: invalid json body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "BILLING_006: free-tier monthly chat limit reached (20/month)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "BILLING_006: free-tier concurrent-conversation limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "generate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "description": "the question to ask" }, "conversationId": { "type": "string", "format": "uuid", "description": "continue an existing conversation" }, "maxCitations": { "type": "integer", "minimum": 1, "maximum": 20, "description": "cap the returned citations (all citations are returned when omitted)" } }, "required": [ "question" ] } } } }, "description": "native clients use POST /chat/stream instead: its body is { message, conversationId? } (NOT this route's question/maxCitations shape), answered as a text/event-stream of JSON frames (meta, delta, error, done). streaming is outside the OpenAPI codegen contract" } }, "/conversations": { "get": { "x-status": "live", "tags": [ "conversations" ], "summary": "paginated list of the caller's conversations, most recently active first", "operationId": "listConversations", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "pageSize", "total", "totalPages" ] } }, "required": [ "data", "pagination" ] }, "example": { "success": true, "data": [ { "id": "uuid", "title": "string | null", "created_at": "ISO 8601", "updated_at": "ISO 8601" } ], "pagination": { "page": 1, "pageSize": 50, "total": 3, "totalPages": 1 } } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] } }, "/conversations/{id}/messages": { "get": { "x-status": "live", "tags": [ "conversations" ], "summary": "the conversation's message history, oldest first. assistant messages carry the IDs of the bookmarks retrieved for that answer", "operationId": "listConversationMessages", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }, "required": [ "data" ] }, "example": { "success": true, "data": [ { "id": "uuid", "role": "user", "content": "string", "retrieved_bookmark_ids": null, "created_at": "ISO 8601" }, { "id": "uuid", "role": "assistant", "content": "string", "retrieved_bookmark_ids": [ "uuid" ], "created_at": "ISO 8601" } ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/conversations/{id}": { "delete": { "x-status": "live", "tags": [ "conversations" ], "summary": "permanently delete a conversation and its messages", "operationId": "deleteConversation", "security": [ { "apiKeyAuth": [] } ], "responses": { "204": { "description": "no content" }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/usage": { "get": { "x-status": "live", "tags": [ "usage" ], "summary": "the caller's plan, chat-message usage this month, syncs today, bookmark count, and whether an X account is connected. limit and remaining are null on unlimited plans", "operationId": "getUsage", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/UsageData" } }, "required": [ "data" ] }, "example": { "success": true, "data": { "plan": "free", "x_connected": true, "bookmarks": { "total": 1234 }, "chat": { "used": 4, "limit": 20, "remaining": 16 }, "syncs_today": { "used": 1, "limit": 1, "remaining": 0 } } } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" } }, "/insights": { "get": { "x-status": "live", "tags": [ "insights" ], "summary": "headline stats, weekly bookmark velocity, top authors and topics, 'early calls' (bookmarks saved early that gained traction), and follow recommendations. early calls + recommendations are tier-limited (free: 3, paid: 10)", "operationId": "getInsights", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Insights" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" } }, "/notifications": { "get": { "x-status": "live", "tags": [ "notifications" ], "summary": "paginated list of the caller's notifications, newest first", "operationId": "listNotifications", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationItem" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "pageSize", "total", "totalPages" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] } }, "/notifications/{id}": { "patch": { "x-status": "live", "tags": [ "notifications" ], "summary": "mark a notification read", "operationId": "updateNotification", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MutationAck" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] }, "delete": { "x-status": "live", "tags": [ "notifications" ], "summary": "delete a notification", "operationId": "deleteNotification", "security": [ { "apiKeyAuth": [] } ], "responses": { "204": { "description": "no content" }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/notifications/read-all": { "post": { "x-status": "live", "tags": [ "notifications" ], "summary": "mark all of the caller's unread notifications read", "operationId": "markAllNotificationsRead", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ReadAllResult" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write" } }, "/connections/x/connect": { "post": { "x-status": "live", "tags": [ "connections" ], "summary": "start native X OAuth: returns an authorization URL to open in an ASWebAuthenticationSession. the backend callback exchanges the code server-side and redirects to the app scheme", "operationId": "connectX", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ConnectStart" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write" } }, "/connections/x": { "delete": { "x-status": "live", "tags": [ "connections" ], "summary": "disconnect the X account (revoke + clear stored OAuth tokens). reconnect via /connections/x/connect", "operationId": "disconnectX", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MutationAck" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write" } }, "/me": { "get": { "x-status": "live", "tags": [ "account" ], "summary": "the authenticated user's profile + onboarding state (used for post-login routing)", "operationId": "getMe", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MeProfile" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" } }, "/onboarding/complete": { "post": { "x-status": "live", "tags": [ "account" ], "summary": "mark onboarding complete", "operationId": "completeOnboarding", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MutationAck" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write" } }, "/onboarding/heard-from": { "post": { "x-status": "live", "tags": [ "account" ], "summary": "record how the user heard about xmark (the onboarding self-report). write-once: recorded is false when an answer is already on file", "operationId": "recordHeardFrom", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/HeardFromResult" } }, "required": [ "data" ] }, "example": { "data": { "recorded": true } } } } }, "400": { "description": "SERVER_002: source not in the allowlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "tiktok", "instagram", "x", "reddit", "youtube", "google", "chatgpt", "friend", "other" ], "description": "one of the allowlisted sources" } }, "required": [ "source" ] } } } } } }, "/account": { "delete": { "x-status": "live", "tags": [ "account" ], "summary": "delete the account (soft-delete data, cancel any subscription)", "operationId": "deleteAccount", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MutationAck" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin" } }, "/account/duplicate": { "get": { "x-status": "live", "tags": [ "account" ], "summary": "an older xmark account connected to the same X identity as this one, if any (a second sign-in provider on iOS is the usual cause); the duplicate key is absent when there is nothing to merge", "operationId": "getDuplicateIdentity", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/DuplicateIdentityStatus" } }, "required": [ "data" ] }, "example": { "data": { "duplicate": { "source_user_id": "b8a5e6b0-8f67-45f2-b296-e99696775675", "platform": "twitter", "platform_username": "glowspin", "bookmark_count": 4399, "last_synced_at": "2026-07-26T22:42:14Z", "connected_at": "2026-07-26T22:42:10Z" } } } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" } }, "/account/merge": { "post": { "x-status": "live", "tags": [ "account" ], "summary": "fold the older account into this one - its bookmarks, folders, chats, and wrapped move here (tweets you already have are kept as-is) and the older account is retired", "operationId": "mergeDuplicateIdentity", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/MergeResult" } }, "required": [ "data" ] }, "example": { "data": { "source_user_id": "b8a5e6b0-8f67-45f2-b296-e99696775675", "platform_username": "glowspin", "moved_bookmarks": 1196, "duplicate_bookmarks": 3203, "moved_folders": 0, "merged_folders": 0, "moved_conversations": 0, "moved_snapshots": 0 } } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "AUTH_002: that account does not share an x identity with this one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_user_id": { "type": "string", "format": "uuid", "description": "the account reported by GET /account/duplicate" } }, "required": [ "source_user_id" ] } } } }, "description": "the older account must hold the same X identity you are connected with right now - that authorization is the ownership proof\n\nbilling does not merge: an older account with a live paid subscription is refused until it is cancelled or moved" } }, "/notification-settings": { "get": { "x-status": "live", "tags": [ "account" ], "summary": "the caller's email-notification preference", "operationId": "getNotificationSettings", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/NotificationSettings" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" }, "patch": { "x-status": "live", "tags": [ "account" ], "summary": "update the email-notification preference", "operationId": "updateNotificationSettings", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/NotificationSettings" } }, "required": [ "data" ] } } } }, "400": { "description": "SERVER_005: invalid json body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email_enabled": { "type": "boolean", "description": "whether email notifications are on" } }, "required": [ "email_enabled" ] } } } } } }, "/settings": { "get": { "x-status": "live", "tags": [ "account" ], "summary": "the caller's profile settings (auto-cleanup window, public-profile toggle, username)", "operationId": "getSettings", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/SettingsData" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" }, "patch": { "x-status": "live", "tags": [ "account" ], "summary": "update profile settings", "operationId": "updateSettings", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/SettingsData" } }, "required": [ "data" ] } } } }, "400": { "description": "SERVER_005: invalid json body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "auto_delete_bookmarks_after_days": { "type": "integer", "description": "auto-delete window: null (off), 90, 180, or 365" }, "public_bookmarks_enabled": { "type": "boolean", "description": "enable the public /u/ profile (requires a username first)" }, "username": { "type": "string", "description": "3-20 chars [a-z0-9_-], unique" } } } } } } } }, "/billing/portal": { "post": { "x-status": "live", "tags": [ "billing" ], "summary": "a billing-management URL: a pre-authenticated Stripe customer portal for subscribers, or the web billing page", "operationId": "billingPortal", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/UrlResult" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" } }, "/billing/apple/verify": { "post": { "x-status": "live", "tags": [ "billing" ], "summary": "verify a StoreKit 2 signed transaction server-side and grant the plan", "operationId": "verifyApple", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/PlanResult" } }, "required": [ "data" ] } } } }, "400": { "description": "SERVER_005: invalid json body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signed_transaction": { "type": "string", "description": "the StoreKit 2 signed transaction JWS" } }, "required": [ "signed_transaction" ] } } } } } }, "/referrals": { "get": { "x-status": "live", "tags": [ "referrals" ], "summary": "the caller's referral / wrapped-share bonus status", "operationId": "getReferralStatus", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ReferralStatus" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" } }, "/referrals/share": { "post": { "x-status": "live", "tags": [ "referrals" ], "summary": "post the wrapped summary to the connected X account and grant the one-time bonus", "operationId": "shareReferral", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ReferralShareResult" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "send", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "optional custom share text" } } } } } } } }, "/wrapped": { "get": { "x-status": "live", "tags": [ "wrapped" ], "summary": "wrapped stats: totals, top authors, top topics, languages", "operationId": "getWrapped", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/WrappedStats" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "SERVER_001: internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "read" } }, "/keys": { "get": { "x-status": "live", "tags": [ "API keys" ], "summary": "list the caller's API keys, newest first", "operationId": "listKeys", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "uuid", "name": "string", "key_prefix": "xm_live_abc1", "scopes": [ "read", "write" ], "last_used_at": "ISO 8601 | null", "revoked_at": "ISO 8601 | null", "created_at": "ISO 8601" } ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin" }, "post": { "x-status": "live", "tags": [ "API keys" ], "summary": "create a new API key: the raw key is returned once", "operationId": "createKey", "security": [ { "apiKeyAuth": [] } ], "responses": { "201": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/CreateApiKeyResponse" } }, "required": [ "data" ] } } } }, "400": { "description": "SERVER_005: invalid json body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "key name" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "subset of read/write/generate/send/admin (defaults to ['read','write'] when omitted - pass the full list explicitly if the key needs 'generate' or 'send')" } }, "required": [ "name" ] } } } } } }, "/keys/me": { "get": { "x-status": "live", "tags": [ "API keys" ], "summary": "introspect the calling API key (no scope required; JWT principals get 404)", "operationId": "getCurrentApiKey", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/keys/{id}": { "get": { "x-status": "live", "tags": [ "API keys" ], "summary": "fetch a specific key's metadata", "operationId": "getKey", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] }, "patch": { "x-status": "live", "tags": [ "API keys" ], "summary": "rename a key", "operationId": "updateKey", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "data" ] } } } }, "400": { "description": "SERVER_005: invalid json body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "new key name" } }, "required": [ "name" ] } } } } }, "delete": { "x-status": "live", "tags": [ "API keys" ], "summary": "revoke a key (204 No Content)", "operationId": "deleteKey", "security": [ { "apiKeyAuth": [] } ], "responses": { "204": { "description": "no content" }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/keys/{id}/rotate": { "post": { "x-status": "live", "tags": [ "API keys" ], "summary": "rotate a key: revoke it and mint a replacement with the same name and scopes", "operationId": "rotateApiKey", "security": [ { "apiKeyAuth": [] } ], "responses": { "201": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/CreateApiKeyResponse" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/webhooks": { "get": { "x-status": "live", "tags": [ "webhooks" ], "summary": "list the caller's webhook endpoints, newest first", "operationId": "listWebhooks", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": [ "data" ] }, "example": { "data": [ { "id": "uuid", "url": "https://example.com/hooks/xmark", "events": [ "*" ], "active": true, "created_at": "ISO 8601", "updated_at": "ISO 8601" } ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin" }, "post": { "x-status": "live", "tags": [ "webhooks" ], "summary": "create a webhook endpoint: the signing secret is returned once", "operationId": "createWebhook", "security": [ { "apiKeyAuth": [] } ], "responses": { "201": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ] } } } }, "400": { "description": "SERVER_005: invalid json body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "delivery endpoint" }, "events": { "type": "array", "items": { "type": "string" }, "description": "event types to deliver, or [\"*\"] for all" } }, "required": [ "url", "events" ] } } } } } }, "/webhooks/{id}": { "get": { "x-status": "live", "tags": [ "webhooks" ], "summary": "fetch a webhook endpoint", "operationId": "getWebhook", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] }, "patch": { "x-status": "live", "tags": [ "webhooks" ], "summary": "update url, events, or active", "operationId": "updateWebhook", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/Webhook" } }, "required": [ "data" ] } } } }, "400": { "description": "SERVER_005: invalid json body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "new delivery endpoint" }, "events": { "type": "array", "items": { "type": "string" }, "description": "new event list" }, "active": { "type": "boolean", "description": "pause/resume deliveries" } } } } } } }, "delete": { "x-status": "live", "tags": [ "webhooks" ], "summary": "delete a webhook endpoint (204 No Content)", "operationId": "deleteWebhook", "security": [ { "apiKeyAuth": [] } ], "responses": { "204": { "description": "no content" }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/webhooks/{id}/deliveries": { "get": { "x-status": "live", "tags": [ "webhooks" ], "summary": "paginated delivery log, newest first", "operationId": "listWebhookDeliveries", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "pageSize", "total", "totalPages" ] } }, "required": [ "data", "pagination" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" }, { "name": "page", "in": "query", "required": false, "description": "page number", "schema": { "type": "integer", "default": 1 } }, { "name": "pageSize", "in": "query", "required": false, "description": "items per page", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] } }, "/webhooks/{id}/rotate-secret": { "post": { "x-status": "live", "tags": [ "webhooks" ], "summary": "rotate the signing secret: the new secret is returned once", "operationId": "rotateWebhookSecret", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/RotateSecretResponse" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/webhooks/{id}/test": { "post": { "x-status": "live", "tags": [ "webhooks" ], "summary": "fire a signed test event and report the delivery outcome", "operationId": "testWebhook", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/TestWebhookResponse" } }, "required": [ "data" ] } } } }, "401": { "description": "AUTH_001: missing or invalid authorization header; AUTH_004: invalid or revoked API key / expired session token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "SERVER_003: resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-scope": "admin", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "id" } ] } }, "/changelog": { "get": { "x-status": "live", "tags": [ "changelog" ], "summary": "release history newest-first: version, date, type (feature/fix/breaking/docs), summary, and migration notes on breaking entries. public - the one-line X-Notice header on every response is the latest entry's summary; this is the structured history behind it", "operationId": "getChangelog", "security": [ { "apiKeyAuth": [] } ], "responses": { "200": { "description": "success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChangelogEntry" } } }, "required": [ "data" ] }, "example": { "success": true, "data": [ { "version": "1.0.0", "date": "2026-07-21", "type": "feature", "summary": "..." } ] } } } } } } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "http", "scheme": "bearer", "description": "Scoped API key issued via xmark settings (`Authorization: Bearer nt_live_...`), or a Supabase user access token for native clients signed in as the account owner (`Authorization: Bearer `)." } }, "schemas": { "Error": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "SERVER_001" }, "message": { "type": "string", "example": "internal server error" } }, "required": [ "code", "message" ] } } }, "Bookmark": { "type": "object", "properties": { "id": { "type": "string" }, "tweet_id": { "type": "string" }, "text": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "name": { "type": "string" }, "profile_image_url": { "type": [ "string", "null" ] } }, "required": [ "username", "name" ] }, "bookmarked_at": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "public_metrics": { "type": [ "object", "null" ], "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "media": { "type": [ "array", "null" ], "items": {} }, "folder": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "id", "tweet_id", "text", "author" ] }, "ChatCitation": { "type": "object", "properties": { "bookmark_id": { "type": "string" }, "tweet_url": { "type": "string" }, "author": { "type": "string" }, "snippet": { "type": "string" } }, "required": [ "bookmark_id", "tweet_url", "author", "snippet" ] }, "QuotaUsage": { "type": "object", "properties": { "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "used" ] }, "DuplicateIdentity": { "type": "object", "properties": { "source_user_id": { "type": "string" }, "platform": { "type": "string" }, "platform_username": { "type": [ "string", "null" ] }, "bookmark_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "last_synced_at": { "type": [ "string", "null" ] }, "connected_at": { "type": "string" } }, "required": [ "source_user_id", "platform", "platform_username", "bookmark_count", "last_synced_at", "connected_at" ] }, "ChangelogEntry": { "type": "object", "properties": { "version": { "type": "string" }, "date": { "type": "string" }, "type": { "type": "string", "enum": [ "feature", "fix", "breaking", "docs" ] }, "summary": { "type": "string" }, "migration": { "type": "string" } }, "required": [ "version", "date", "type", "summary" ] }, "SearchResult": { "type": "object", "properties": { "bookmark": { "$ref": "#/components/schemas/Bookmark" }, "score": { "type": "number" } }, "required": [ "bookmark", "score" ] }, "SyncResult": { "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "newCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "removedCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "durationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "done": { "type": "boolean" }, "retryAfterSeconds": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "count", "newCount", "removedCount", "durationMs", "done" ] }, "ChatResult": { "type": "object", "properties": { "answer": { "type": "string" }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/ChatCitation" } }, "conversation_id": { "type": "string" } }, "required": [ "answer", "citations", "conversation_id" ] }, "Conversation": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "created_at", "updated_at" ] }, "Message": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "content": { "type": "string" }, "retrieved_bookmark_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "created_at": { "type": "string" } }, "required": [ "id", "role", "content", "created_at" ] }, "UsageData": { "type": "object", "properties": { "plan": { "type": "string" }, "x_connected": { "type": "boolean" }, "bookmarks": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "total" ] }, "chat": { "$ref": "#/components/schemas/QuotaUsage" }, "syncs_today": { "$ref": "#/components/schemas/QuotaUsage" } }, "required": [ "plan", "x_connected", "bookmarks", "chat", "syncs_today" ] }, "Insights": { "type": "object", "properties": { "stats": { "type": "object", "properties": { "total_bookmarks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unique_authors": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "early_calls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "topics_covered": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "total_bookmarks", "unique_authors", "early_calls", "topics_covered" ] }, "velocity": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "label", "count" ] } }, "top_authors": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "username", "count" ] } }, "top_topics": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "count" ] } }, "early_calls": { "type": "array", "items": { "type": "object", "properties": { "tweet_id": { "type": "string" }, "author_username": { "type": [ "string", "null" ] }, "author_name": { "type": [ "string", "null" ] }, "text": { "type": "string" }, "likes_at_save": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991 }, "latest_likes": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991 }, "score": { "type": [ "number", "null" ] } }, "required": [ "tweet_id", "author_username", "author_name", "text", "likes_at_save", "latest_likes", "score" ] } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] }, "overlap": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "username", "name", "avatar_url", "overlap" ] } } }, "required": [ "stats", "velocity", "top_authors", "top_topics", "early_calls", "recommendations" ] }, "NotificationItem": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "message": { "type": "string" }, "priority": { "type": [ "string", "null" ] }, "read": { "type": "boolean" }, "action_url": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "type", "title", "message", "priority", "read", "action_url", "created_at" ] }, "ReadAllResult": { "type": "object", "properties": { "updated_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "updated_count" ] }, "NotificationSettings": { "type": "object", "properties": { "email_enabled": { "type": "boolean" } }, "required": [ "email_enabled" ] }, "SettingsData": { "type": "object", "properties": { "username": { "type": [ "string", "null" ] }, "public_bookmarks_enabled": { "type": "boolean" }, "auto_delete_bookmarks_after_days": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "username", "public_bookmarks_enabled", "auto_delete_bookmarks_after_days" ] }, "ConnectStart": { "type": "object", "properties": { "auth_url": { "type": "string" } }, "required": [ "auth_url" ] }, "UrlResult": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }, "PlanResult": { "type": "object", "properties": { "plan": { "type": "string" } }, "required": [ "plan" ] }, "MeProfile": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "has_completed_onboarding": { "type": "boolean" }, "onboarding_step": { "type": [ "string", "null" ] }, "is_team": { "type": "boolean" } }, "required": [ "id", "email", "full_name", "has_completed_onboarding", "onboarding_step", "is_team" ] }, "HeardFromResult": { "type": "object", "properties": { "recorded": { "type": "boolean" } }, "required": [ "recorded" ] }, "DuplicateIdentityStatus": { "type": "object", "properties": { "duplicate": { "$ref": "#/components/schemas/DuplicateIdentity" } } }, "MergeResult": { "type": "object", "properties": { "source_user_id": { "type": "string" }, "platform_username": { "type": [ "string", "null" ] }, "moved_bookmarks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "duplicate_bookmarks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "moved_folders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "merged_folders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "moved_conversations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "moved_snapshots": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "source_user_id", "platform_username", "moved_bookmarks", "duplicate_bookmarks", "moved_folders", "merged_folders", "moved_conversations", "moved_snapshots" ] }, "ReferralStatus": { "type": "object", "properties": { "claimed": { "type": "boolean" }, "claimed_at": { "type": [ "string", "null" ] }, "tweet_url": { "type": [ "string", "null" ] }, "bonus_until": { "type": [ "string", "null" ] }, "bonus_active": { "type": "boolean" } }, "required": [ "claimed", "claimed_at", "tweet_url", "bonus_until", "bonus_active" ] }, "ReferralShareResult": { "type": "object", "properties": { "granted": { "type": "boolean" }, "already_claimed": { "type": "boolean" }, "bonus_until": { "type": [ "string", "null" ] }, "tweet_url": { "type": "string" } }, "required": [ "granted", "already_claimed", "bonus_until", "tweet_url" ] }, "WrappedStats": { "type": "object", "properties": {}, "additionalProperties": {} }, "MutationAck": { "type": "object", "properties": {}, "additionalProperties": {} }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key_prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "last_used_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "key_prefix", "scopes", "last_used_at", "revoked_at", "created_at" ] }, "CreateApiKeyResponse": { "type": "object", "properties": { "key": { "type": "string" }, "api_key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "key_prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "last_used_at": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "key_prefix", "scopes", "last_used_at", "revoked_at", "created_at" ] } }, "required": [ "key", "api_key" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "consecutive_failures": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "disabled_at": { "type": [ "string", "null" ] }, "disabled_reason": { "type": [ "string", "null" ] } }, "required": [ "id", "url", "events", "active", "created_at", "updated_at", "consecutive_failures", "disabled_at", "disabled_reason" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string" }, "attempt_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "response_status": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991 }, "response_body": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "failed_at": { "type": [ "string", "null" ] }, "next_retry_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "event_type", "status", "attempt_count", "response_status", "response_body", "delivered_at", "failed_at", "next_retry_at", "created_at" ] }, "RotateSecretResponse": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "secret" ] }, "TestWebhookResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "delivery_id": { "type": [ "string", "null" ] }, "response_status": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991 }, "response_body": { "type": [ "string", "null" ] } }, "required": [ "success", "delivery_id", "response_status", "response_body" ] } } } }