{"openapi":"3.1.0","info":{"title":"SMS Monkey API","version":"1.0.0","description":"Provision verification numbers, stream one-time codes, manage credits and API keys. All monetary values are strings in USD; all timestamps are ISO 8601 (UTC)."},"servers":[{"url":"https://smsmonkey.org","description":"Base URL"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Account"},{"name":"Catalog"},{"name":"Orders"},{"name":"API keys"},{"name":"Top-ups"}],"paths":{"/api/v1/me":{"get":{"operationId":"getMe","summary":"Get the authenticated account","description":"Returns the identity behind the API key or session used for the request.","tags":["Account"],"responses":{"200":{"description":"The authenticated account.","content":{"application/json":{"example":{"id":"3f1c2b90-6d2a-4a7e-9b8c-2b1d0e4f5a6b","discordId":"1461464020530892933","username":"rx7nerd","isAdmin":false}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"example":{"error":"Unauthorized"}}}}}}},"/api/v1/balance":{"get":{"operationId":"getBalance","summary":"Get credit balance","description":"Returns the account's spendable credit balance, derived from the immutable ledger.","tags":["Account"],"responses":{"200":{"description":"Current balance.","content":{"application/json":{"example":{"balance":"12.40","currency":"USD"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"example":{"error":"Unauthorized"}}}}}}},"/api/v1/prices":{"get":{"operationId":"getPrices","summary":"List services and prices","description":"Returns the available services and their per-number price. This endpoint is public and needs no authentication.","tags":["Catalog"],"security":[],"responses":{"200":{"description":"Available services.","content":{"application/json":{"example":{"services":[{"service":"wonder","name":"Wonder","price":"0.30","currency":"USD"},{"service":"gmx","name":"GMX","price":"0.10","currency":"USD"},{"service":"ticketmaster","name":"Ticketmaster","price":"0.15","currency":"USD"}]}}}}}}},"/api/v1/orders":{"get":{"operationId":"listOrders","summary":"List orders","description":"Returns your most recent orders, newest first (up to 50).","tags":["Orders"],"responses":{"200":{"description":"A list of orders.","content":{"application/json":{"example":{"orders":[{"id":"ord_a1b2c3d4","service":"wonder","number":"+15551234567","status":"received","price":"0.30","code":"481902","fullMessage":"Your verification code is 481902","expiresAt":"2026-08-16T20:20:00.000Z","createdAt":"2026-08-16T20:00:00.000Z"},{"id":"ord_a1b2c3d4","service":"wonder","number":"+15551234567","status":"waiting","price":"0.30","code":null,"fullMessage":null,"expiresAt":"2026-08-16T20:20:00.000Z","createdAt":"2026-08-16T20:00:00.000Z"}]}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"example":{"error":"Unauthorized"}}}}}},"post":{"operationId":"createOrder","summary":"Order a verification number","description":"Provisions a fresh number and debits your balance by the service price. Poll the order (or `GET /orders`) until `status` becomes `received` to read the code.","tags":["Orders"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","description":"Service to order. One of `wonder`, `gmx`, `ticketmaster`. Defaults to `wonder`. See GET /prices for names and prices.","example":"wonder"}}},"example":{"service":"wonder"}}}},"responses":{"201":{"description":"Order created; a number was assigned.","content":{"application/json":{"example":{"id":"ord_a1b2c3d4","service":"wonder","number":"+15551234567","status":"waiting","price":"0.30","code":null,"fullMessage":null,"expiresAt":"2026-08-16T20:20:00.000Z","createdAt":"2026-08-16T20:00:00.000Z"}}}},"400":{"description":"Unsupported service.","content":{"application/json":{"example":{"error":"Unsupported service"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"example":{"error":"Unauthorized"}}}},"402":{"description":"Insufficient credit balance.","content":{"application/json":{"example":{"error":"Insufficient balance"}}}},"503":{"description":"No numbers are available right now.","content":{"application/json":{"example":{"error":"No numbers are available for this service right now"}}}}}}},"/api/v1/orders/{id}":{"get":{"operationId":"getOrder","summary":"Retrieve an order","description":"Fetches a single order by its public id. Use this to poll for the incoming code.","tags":["Orders"],"parameters":[{"name":"id","in":"path","required":true,"description":"The public order id.","schema":{"type":"string"},"example":"ord_a1b2c3d4"}],"responses":{"200":{"description":"The order.","content":{"application/json":{"example":{"id":"ord_a1b2c3d4","service":"wonder","number":"+15551234567","status":"received","price":"0.30","code":"481902","fullMessage":"Your verification code is 481902","expiresAt":"2026-08-16T20:20:00.000Z","createdAt":"2026-08-16T20:00:00.000Z"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"example":{"error":"Unauthorized"}}}},"404":{"description":"No such order for this account.","content":{"application/json":{"example":{"error":"Order not found"}}}}}}},"/api/v1/orders/{id}/cancel":{"post":{"operationId":"cancelOrder","summary":"Cancel an order","description":"Cancels an order that has not yet received a code and refunds the charge.","tags":["Orders"],"parameters":[{"name":"id","in":"path","required":true,"description":"The public order id.","schema":{"type":"string"},"example":"ord_a1b2c3d4"}],"responses":{"200":{"description":"The cancelled, refunded order.","content":{"application/json":{"example":{"id":"ord_a1b2c3d4","service":"wonder","number":"+15551234567","status":"cancelled","price":"0.30","code":null,"fullMessage":null,"expiresAt":null,"createdAt":"2026-08-16T20:00:00.000Z"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"example":{"error":"Unauthorized"}}}},"404":{"description":"No such order for this account.","content":{"application/json":{"example":{"error":"Order not found"}}}},"409":{"description":"A code already arrived; the order can't be refunded.","content":{"application/json":{"example":{"error":"This order already received a code and cannot be refunded"}}}}}}},"/api/v1/api-keys":{"get":{"operationId":"listKeys","summary":"List API keys","description":"Lists your active API keys. Only a non-sensitive prefix is returned — never the full key.","tags":["API keys"],"responses":{"200":{"description":"Active API keys.","content":{"application/json":{"example":{"apiKeys":[{"id":"b7f0…","name":"Production","prefix":"wnd_EdcOHmGD","lastUsedAt":"2026-08-16T19:55:00.000Z","createdAt":"2026-08-01T10:00:00.000Z"}]}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"example":{"error":"Unauthorized"}}}}}},"post":{"operationId":"createKey","summary":"Create an API key","description":"Creates a new API key. The full secret is returned once, in this response only.","tags":["API keys"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"A label for the key (1–80 chars). Defaults to `API key`.","example":"Production"}}},"example":{"name":"Production"}}}},"responses":{"201":{"description":"The created key. Store `key` now — it is never shown again.","content":{"application/json":{"example":{"id":"b7f0…","name":"Production","key":"wnd_9f3a1c…full-secret","prefix":"wnd_9f3a1c"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"example":{"error":"Unauthorized"}}}}}}},"/api/v1/api-keys/{id}":{"delete":{"operationId":"deleteKey","summary":"Revoke an API key","description":"Permanently revokes an API key. Requests using it will start returning 401.","tags":["API keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"The API key id (not the secret).","schema":{"type":"string"},"example":"b7f0e2a1-…"}],"responses":{"200":{"description":"The key was revoked.","content":{"application/json":{"example":{"revoked":true}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"example":{"error":"Unauthorized"}}}},"404":{"description":"No such key for this account.","content":{"application/json":{"example":{"error":"API key not found"}}}}}}},"/api/v1/top-ups":{"get":{"operationId":"listTopups","summary":"List top-ups","description":"Lists your recent crypto top-up payments, newest first (up to 25).","tags":["Top-ups"],"responses":{"200":{"description":"Recent payments.","content":{"application/json":{"example":{"payments":[{"id":"pay_ZpcN53Vc","amount":"25.00","status":"finished","checkoutUrl":"https://nowpayments.io/payment/…","createdAt":"2026-08-16T18:00:00.000Z"}]}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"example":{"error":"Unauthorized"}}}}}},"post":{"operationId":"createTopup","summary":"Create a top-up invoice","description":"Creates a crypto payment invoice via NOWPayments. Send the user to `checkoutUrl`; credits are added automatically once the payment is confirmed on-chain.","tags":["Top-ups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"USD amount to add. Minimum 5, maximum 1000.","example":25},"promoCode":{"type":"string","description":"Optional first-deposit promo code.","example":"PROMO_CODE"}},"required":["amount"]},"example":{"amount":25,"promoCode":"PROMO_CODE"}}}},"responses":{"201":{"description":"Invoice created.","content":{"application/json":{"example":{"id":"pay_ZpcN53Vc","amount":"25.00","checkoutUrl":"https://nowpayments.io/payment/…"}}}},"400":{"description":"Amount out of range or invalid promo code.","content":{"application/json":{"example":{"error":"Minimum top-up is $5.00"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"example":{"error":"Unauthorized"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Send your API key as `Authorization: Bearer wnd_...`."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Order":{"type":"object","properties":{"id":{"type":"string","example":"ord_a1b2c3d4"},"service":{"type":"string","enum":["wonder","gmx","ticketmaster"]},"number":{"type":"string","nullable":true,"example":"+15551234567"},"status":{"type":"string","enum":["pending","waiting","received","cancelled","expired","failed"]},"price":{"type":"string","example":"0.30"},"code":{"type":"string","nullable":true,"example":"481902"},"fullMessage":{"type":"string","nullable":true},"expiresAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","service","status","price","createdAt"]}}}}