{ "openapi": "3.0.3", "info": { "title": "ScrapingBuddy SMS API", "version": "1.0.0", "description": "Customer API. Integer USD cents. Keys are created in /dashboard/api. 60 requests/minute/customer. Quotes expire in 2 minutes. Poll orders every 10 seconds." }, "servers": [ { "url": "https://www.scrapingbuddy.com/api/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "ScrapingBuddy customer API key (sb_live_...)" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "Balance": { "type": "object", "properties": { "balanceCents": { "type": "integer", "description": "Available USD balance rounded down to whole cents." }, "balanceUsd": { "type": "string", "description": "Exact available USD decimal amount, including fractional cents; excludes task reservations.", "example": "12.498200000" }, "currency": { "type": "string", "enum": [ "USD" ] } }, "required": [ "balanceCents", "balanceUsd", "currency" ] }, "Country": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "iso": { "type": "string", "nullable": true } } }, "Service": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "available": { "type": "integer" }, "priceCents": { "type": "integer", "nullable": true } } }, "Quote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "country": { "type": "string" }, "product": { "type": "string" }, "amountCents": { "type": "integer" }, "currency": { "type": "string", "enum": [ "USD" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "operator": { "type": "string", "description": "Requested operator selection; any means automatic assignment." } }, "required": [ "id", "country", "product", "amountCents", "currency", "expiresAt", "operator" ] }, "SMS": { "type": "object", "properties": { "id": { "type": "integer" }, "sender": { "type": "string" }, "text": { "type": "string" }, "code": { "type": "string" }, "date": { "type": "string" } }, "required": [ "sender", "text", "code", "date" ] }, "Order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "country": { "type": "string" }, "product": { "type": "string" }, "operator": { "type": "string", "nullable": true }, "amount_cents": { "type": "integer" }, "status": { "type": "string", "enum": [ "purchasing", "purchase_unknown", "PENDING", "RECEIVED", "FINISHED", "CANCELED", "TIMEOUT", "BANNED", "failed" ] }, "phone": { "type": "string", "nullable": true }, "sms": { "type": "array", "items": { "$ref": "#/components/schemas/SMS" } }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "refunded_at": { "type": "string", "format": "date-time", "nullable": true }, "error_code": { "type": "string", "nullable": true } } }, "OrderResponse": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/Order" } }, "required": [ "order" ] }, "Operator": { "type": "object", "properties": { "id": { "type": "string" }, "available": { "type": "integer" }, "priceCents": { "type": "integer", "description": "Indicative customer price in USD cents." } }, "required": [ "id", "available", "priceCents" ] } } }, "paths": { "/balance": { "get": { "summary": "Get balance", "operationId": "get_balance", "responses": { "200": { "description": "Success. Inspect order status for purchase outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "400": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; account limits can last longer." } } }, "503": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/countries": { "get": { "summary": "List countries", "operationId": "list_countries", "responses": { "200": { "description": "Success. Inspect order status for purchase outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "countries": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } } } } } } }, "400": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; account limits can last longer." } } }, "503": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/services": { "get": { "summary": "List services", "operationId": "list_services", "responses": { "200": { "description": "Success. Inspect order status for purchase outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "currency": { "type": "string" } } } } } }, "400": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; account limits can last longer." } } }, "503": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "query", "name": "country", "required": true, "schema": { "type": "string" } } ] } }, "/quotes": { "post": { "summary": "Create quote", "operationId": "create_quote", "responses": { "201": { "description": "Success. Inspect order status for purchase outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; account limits can last longer." } } }, "503": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string" }, "product": { "type": "string" }, "operator": { "type": "string", "default": "any", "description": "Operator ID from GET /operators, or any for automatic assignment." } }, "required": [ "country", "product" ] } } } } } }, "/orders": { "post": { "summary": "Purchase number", "operationId": "purchase_number", "responses": { "200": { "description": "Existing purchase recovered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "201": { "description": "Success. Inspect order status for purchase outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; account limits can last longer." } } }, "503": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID v4. Persist and reuse with the same quoteId on retries." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string", "format": "uuid" } }, "required": [ "quoteId" ] } } } } }, "get": { "summary": "List orders", "operationId": "list_orders", "responses": { "200": { "description": "Success. Inspect order status for purchase outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "hasMore": { "type": "boolean" } } } } } }, "400": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; account limits can last longer." } } }, "503": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "default": 0 } } ] } }, "/orders/{id}": { "get": { "summary": "Get order", "operationId": "get_order", "responses": { "200": { "description": "Success. Inspect order status for purchase outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; account limits can last longer." } } }, "503": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/orders/{id}/refresh": { "post": { "summary": "Refresh order", "operationId": "refresh_order", "responses": { "200": { "description": "Success. Inspect order status for purchase outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; account limits can last longer." } } }, "503": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/orders/{id}/cancel": { "post": { "summary": "Cancel order", "operationId": "cancel_order", "responses": { "200": { "description": "Success. Inspect order status for purchase outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; account limits can last longer." } } }, "503": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/orders/{id}/finish": { "post": { "summary": "Finish order", "operationId": "finish_order", "responses": { "200": { "description": "Success. Inspect order status for purchase outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; account limits can last longer." } } }, "503": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/operators": { "get": { "summary": "List operators", "operationId": "list_operators", "responses": { "200": { "description": "Success. Inspect order status for purchase outcomes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operators": { "type": "array", "items": { "$ref": "#/components/schemas/Operator" } }, "currency": { "type": "string", "enum": [ "USD" ] } } } } } }, "400": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait; account limits can last longer." } } }, "503": { "description": "Request failed; see error message and documentation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "country", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Country ID from GET /countries." }, { "name": "product", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Service ID from GET /services." } ] } } } }