xmark API
chat with your x bookmarks
base URL
https://xmark-sigma.vercel.app/api/v1the xmark API uses REST conventions with JSON request and response bodies. all endpoints require authentication via API key.
responses follow a consistent shape: { data: ... } for success and { error: { code, message, requestId } } for errors.
authentication
all API requests must include your API key in the Authorization header. keys are prefixed with nt_live_ and shown exactly once at creation — store them in a secret manager, never commit them.
header format
Authorization: Bearer nt_live_YOUR_API_KEYverify your key
any valid key can call GET /keys/me to introspect itself — useful for confirming a key works and seeing its scopes.
curl "https://xmark-sigma.vercel.app/api/v1/keys/me" \
-H "Authorization: Bearer nt_live_YOUR_API_KEY"scopes
each API key carries a set of scopes. grant the minimum needed — an admin key can create other keys and manage webhooks, so treat it as a root credential.
| 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 |
default scopes (if none specified): read, write.
API reference
projects
create and list projects owned by the authenticated user.
list the caller's projects, newest first
create a new project
API keys
manage API keys programmatically. key-management endpoints require the admin scope.
list the caller's API keys
create a new API key. the raw key is returned exactly once
introspect the key making this request. no scope required
fetch a specific key owned by the caller
rename an api key
revoke an api key immediately
rotate an api key. revokes the old key and returns a new one with the same name + scopes. the usage counter is net-zero so rotation never trips the active-key limit
webhooks
register HTTPS endpoints that receive signed HMAC-SHA256 payloads when events happen. all webhook-management endpoints require the admin scope.
list the caller's webhook endpoints
create a webhook endpoint. returns the signing secret exactly once
fetch a specific webhook
update a webhook's url, events, or active flag
soft-delete a webhook. no new deliveries are attempted
rotate the signing secret. the new secret is returned exactly once
list recent delivery attempts for a webhook. useful for debugging failed deliveries
error handling
errors are returned as JSON with code, message, optional field, and requestId. the X-Request-ID response header carries a per-request trace id — include it when contacting support.
{
"error": {
"code": "SERVER_005",
"message": "name must be under 100 characters",
"field": "name",
"requestId": "req_abc123"
}
}| 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 | 429 | plan usage limit reached |
| BILLING_007 | 402 | subscription required for this operation |
| BILLING_008 | 403 | current plan does not include this feature |
| code | HTTP | description |
|---|---|---|
| RATE_001 | 429 | too many requests - back off and retry |
| 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 |