{"$schema":"https://json-schema.org/draft/2020-12/schema","title":"797.cx Machine-to-Machine (M2M) API Specification","version":"1.1.0","generated_at":"2026-11-16T12:40:00Z","service":{"name":"797.cx Short-URL Platform","description":"Multi-tenant, multi-domain programmable short URL, QR code, and link intelligence engine.","documentation_url":"https://app.797.cx/api/v1/docs","openapi_url":"https://app.797.cx/api/v1/openapi.json"},"servers":[{"url":"https://app.797.cx/api/v1","description":"Production API v1 (recommended)"},{"url":"https://app.797.cx/api","description":"Production legacy API mount"},{"url":"http://127.0.0.1:8792/api/v1","description":"Local development server"}],"authentication":{"type":"http_bearer","header":"Authorization","format":"Bearer cx_live_<secret>","token_properties":{"prefix":"cx_live_","entropy_bytes":24,"storage":"SHA-256 hash (raw key shown once on generation)","validation_cache_ttl_seconds":60,"scope_binding":"workspace"},"machine_binding":{"description":"API keys can be bound to specific machine IP addresses or CIDR blocks and labeled with a machine name.","enforcement":"Requests from unauthorized IPs are rejected with HTTP 403 machine_ip_unauthorized.","supported_formats":["IPv4 address (e.g. 192.168.1.100)","IPv4 CIDR block (e.g. 10.0.0.0/24)","IPv6 address (e.g. 2001:db8::1)","localhost (127.0.0.1, ::1)"]},"scopes":[{"name":"*","description":"Full access to all operations in the active workspace"},{"name":"links:read","description":"Read link details, lists, and search queries"},{"name":"links:write","description":"Create, update, and delete links and aliases"},{"name":"analytics:read","description":"Query visitor analytics and listen to realtime click streams"},{"name":"domains:read","description":"List custom and platform domains"},{"name":"domains:write","description":"Register, verify, and delete custom BYO domains, manage subdomains, and configure apex/subdomain root index links"},{"name":"folders:read","description":"List folders"},{"name":"folders:write","description":"Create, rename, and delete folders"},{"name":"tags:read","description":"List tags"},{"name":"tags:write","description":"Create, assign, and delete tags"},{"name":"keys:read","description":"List workspace API keys"},{"name":"keys:write","description":"Generate and revoke workspace API keys"},{"name":"webhooks:read","description":"List and inspect webhook configurations and delivery attempts"},{"name":"webhooks:write","description":"Create, update, test, and delete webhook subscriptions"}]},"quotas_and_restrictions":{"plans":{"free":{"api_rpm":60,"links_per_hour":200,"links_per_month":1000,"clicks_per_month":5000,"api_monthly_requests":50000,"webhooks":2,"seats":1,"teams":1},"hobby":{"api_rpm":120,"links_per_hour":500,"links_per_month":5000,"clicks_per_month":25000,"api_monthly_requests":200000,"webhooks":5,"seats":2,"teams":1},"pro":{"api_rpm":600,"links_per_hour":2000,"links_per_month":25000,"clicks_per_month":150000,"api_monthly_requests":1000000,"webhooks":20,"seats":5,"teams":1},"team":{"api_rpm":1200,"links_per_hour":10000,"links_per_month":100000,"clicks_per_month":500000,"api_monthly_requests":5000000,"webhooks":50,"seats":20,"teams":1},"enterprise":{"api_rpm":3000,"links_per_hour":50000,"links_per_month":null,"clicks_per_month":null,"api_monthly_requests":null,"webhooks":100,"seats":null,"teams":null}},"headers":{"rate_limit":"X-RateLimit-Limit","remaining":"X-RateLimit-Remaining","reset":"X-RateLimit-Reset","retry_after":"Retry-After"},"exceeded_responses":{"rate_limit":{"status":429,"code":"rate_limited","description":"Per-minute API request quota exceeded on this plan"},"hourly_link_limit":{"status":429,"code":"link_quota_exceeded","description":"Hourly new link creation ceiling reached"},"monthly_link_quota":{"status":429,"code":"monthly_link_quota_exceeded","description":"Monthly new link creation quota reached"}}},"idempotency":{"header":"Idempotency-Key","description":"Ensures exactly-once execution on network retries for POST and PATCH operations.","retention_seconds":86400,"max_key_length":255,"replayed_header":"Idempotent-Replayed: true","mismatched_payload_error":{"status":422,"code":"idempotency_key_reused"}},"error_contract":{"content_type":"application/json; charset=utf-8","schema":{"type":"object","required":["error","code","request_id"],"properties":{"error":{"type":"string","description":"Human-readable diagnostic description"},"code":{"type":"string","description":"Machine-readable enum value"},"request_id":{"type":"string","description":"Correlated request trace ID"},"details":{"type":"array","description":"Field-level validation error breakdown","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}},"required_scope":{"type":"string","description":"Scope missing from token"},"retry_after":{"type":"integer","description":"Seconds to wait before retrying"}}},"error_codes":["validation_failed","unauthorized","insufficient_scope","forbidden","session_required","not_found","conflict","alias_reserved","plan_required","rate_limited","link_quota_exceeded","monthly_link_quota_exceeded","idempotency_key_reused","idempotency_in_progress","invalid_idempotency_key","internal_error"]},"webhooks":{"supported_events":["link.created","link.updated","link.deleted","link.flagged","link.clicked","ping"],"delivery_headers":{"event":"X-797-Event","delivery_id":"X-797-Delivery","signature":"X-797-Signature"},"signature_format":"t=<timestamp_seconds>,v1=<hmac_sha256_hex>","signature_algorithm":"HMAC-SHA256(secret, `${t}.${raw_body}`)","timeout_ms":10000,"max_attempts":8,"retry_backoff_seconds":[10,30,120,600,1800,3600,10800,21600],"auto_disable_threshold":50},"realtime_stream":{"endpoint":"/api/v1/stream","method":"GET","content_type":"text/event-stream","required_scope":"analytics:read","description":"Continuous SSE stream emitting live link.clicked payloads (including qr_id, qr_token, qr_name when triggered from a dynamic QR code)"},"qr_and_barcode":{"public_hubs":{"qr_generator":"https://qr.797.cx","qr_canonical_redirect":"https://qr-code.797.cx -> 301 https://qr.797.cx","barcode_and_code_api":"https://code.797.cx"},"workspace_endpoints":[{"method":"POST","path":"/api/v1/qr/dynamic","required_scope":"links:write","description":"1-call dynamic QR creation: creates short link + qr_card metadata + styled design + switchable published QR asset"},{"method":"GET","path":"/api/v1/qr-codes","required_scope":"links:read","description":"List published switchable dynamic QR codes across the active workspace"},{"method":"POST","path":"/api/v1/qr/render","required_scope":"links:read","description":"Stateless styled QR renderer supporting PNG, SVG, and PDF output with gradients, shapes, frames, and preset or custom logos"},{"method":"PATCH","path":"/api/v1/links/:id/qr-card","required_scope":"links:write","description":"Update structured dynamic QR card payload (wifi, vcard, event, email, sms, phone, text, crypto, social, location) without reprinting"}],"stateless_edge_endpoints":[{"method":"GET|POST","url":"https://code.797.cx/qr","formats":["png","svg","pdf"],"description":"Stateless QR image generation with shapes, gradients, outer frames, preset/custom logos, and quiet zone"},{"method":"GET|POST","url":"https://code.797.cx/barcode","formats":["png","svg"],"description":"Stateless 1D/2D barcode generation powered by bwip-js (code128, ean13, upca, datamatrix, pdf417, azteccode, etc.)"}],"webhook_click_enrichment":{"event":"link.clicked","fields_on_qr_scan":["qr_id","qr_token","qr_name"]}},"domain_architecture":{"platform_domain":{"host":"797.cx","rules":"Managed approval queue: Users can request single-level or multi-level vanity subdomains at any depth (e.g. sub.797.cx or sub.sub.sub.797.cx up to 200 chars). All requests require platform superadmin (owner) approval via POST /api/admin/subdomain-requests/:id/approve before going live.","multi_level_allowed":true,"requires_approval":true,"check_endpoint":{"url":"/api/v1/subdomains/check","method":"GET","scopes":["domains:read","links:read","links:write"],"description":"Single-endpoint query for M2M devices and clients to check whether a specific subdomain exists, its approval status, and if the client has permission to create links on it."}},"byo_custom_domains":{"rules":"Full workspace self-service: workspace users can add, verify, delete their own domains, instantly create single-level and multi-level subdomains without platform admin approval, and map root index links (/) on both domain apex and subdomains.","multi_level_allowed":true,"requires_approval":false,"apex_root_index_supported":true,"subdomain_root_index_supported":true,"cross_workspace_isolation":true}},"download_endpoints":{"openapi":{"direct_download":"https://app.797.cx/api/v1/download/openapi.json","query_param_download":"https://app.797.cx/api/v1/openapi.json?download=1","format":"OpenAPI 3.1.0 JSON"},"m2m_specification":{"direct_download":"https://app.797.cx/api/v1/download/m2m-specification.json","query_param_download":"https://app.797.cx/api/v1/m2m-specification.json?download=1","format":"JSON Schema / M2M Specification"}}}