{
  "openapi": "3.0.0",
  "info": {
    "title": "Bulkoid API",
    "description": "Programmatic API for ordering social media engagement services",
    "version": "2.0.0",
    "contact": {
      "name": "Bulkoid Support",
      "url": "https://bulkoid.com/contact-us"
    }
  },
  "servers": [
    {
      "url": "https://app.cumparadestept.com/api/v2",
      "description": "Production server"
    }
  ],
  "security": [
    {"ApiKey": []}
  ],
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key",
        "description": "API key from your Bulkoid dashboard Settings page"
      }
    },
    "schemas": {
      "Service": {
        "type": "object",
        "properties": {
          "id": {"type": "integer", "example": 123},
          "name": {"type": "string", "example": "TikTok Followers"},
          "platform": {"type": "string", "example": "TikTok"},
          "rate": {"type": "integer", "description": "Price per 1000 units in cents", "example": 50},
          "min": {"type": "integer", "description": "Minimum order quantity", "example": 100},
          "max": {"type": "integer", "description": "Maximum order quantity", "example": 100000},
          "step": {"type": "integer", "description": "Quantity increment step", "example": 100}
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": {"type": "integer", "example": 456},
          "total": {"type": "integer", "description": "Total in cents", "example": 500},
          "total_formatted": {"type": "string", "example": "$5.00"},
          "status": {"type": "string", "enum": ["Paid", "Ongoing", "Finished", "Error"], "example": "Finished"},
          "platform": {"type": "string", "example": "TikTok"},
          "timestamp": {"type": "integer", "description": "Unix timestamp", "example": 1706000000}
        }
      },
      "OrderDetail": {
        "allOf": [
          {"$ref": "#/components/schemas/Order"},
          {
            "type": "object",
            "properties": {
              "services": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {"type": "integer"},
                    "service_id": {"type": "integer"},
                    "quantity": {"type": "integer"},
                    "link": {"type": "string"},
                    "status": {"type": "string"}
                  }
                }
              }
            }
          }
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {"type": "string"},
          "message": {"type": "string"}
        }
      }
    }
  },
  "paths": {
    "/balance": {
      "get": {
        "summary": "Get account balance",
        "description": "Returns current account balance",
        "operationId": "getBalance",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "balance": {"type": "integer", "description": "Balance in cents", "example": 5000},
                    "currency": {"type": "string", "example": "USD"},
                    "balance_formatted": {"type": "string", "example": "$50.00"}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Error"}
              }
            }
          }
        }
      }
    },
    "/services": {
      "get": {
        "summary": "List available services",
        "description": "Returns all available services for ordering",
        "operationId": "getServices",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "services": {
                      "type": "array",
                      "items": {"$ref": "#/components/schemas/Service"}
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key"
          }
        }
      }
    },
    "/orders": {
      "get": {
        "summary": "List orders",
        "description": "Returns user's orders with pagination",
        "operationId": "getOrders",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {"type": "integer", "default": 100, "maximum": 500},
            "description": "Maximum orders to return"
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {"type": "integer", "default": 0},
            "description": "Number of orders to skip"
          },
          {
            "name": "status",
            "in": "query",
            "schema": {"type": "string", "enum": ["Paid", "Ongoing", "Finished", "Error"]},
            "description": "Filter by status"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "orders": {
                      "type": "array",
                      "items": {"$ref": "#/components/schemas/Order"}
                    },
                    "total": {"type": "integer"},
                    "limit": {"type": "integer"},
                    "offset": {"type": "integer"}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key"
          }
        }
      },
      "post": {
        "summary": "Create order",
        "description": "Create a new order using account balance",
        "operationId": "createOrder",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["service_id", "link", "quantity"],
                "properties": {
                  "service_id": {"type": "integer", "description": "Service ID from /services", "example": 123},
                  "link": {"type": "string", "description": "Target URL", "example": "https://tiktok.com/@username"},
                  "quantity": {"type": "integer", "description": "Amount to order", "example": 1000}
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order_id": {"type": "integer", "example": 456},
                    "charge": {"type": "integer", "description": "Amount charged in cents", "example": 50},
                    "charge_formatted": {"type": "string", "example": "$0.50"},
                    "new_balance": {"type": "integer", "example": 4950},
                    "new_balance_formatted": {"type": "string", "example": "$49.50"},
                    "status": {"type": "string", "example": "Paid"}
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request - missing fields, quantity out of range, or insufficient balance"
          },
          "401": {
            "description": "Invalid or missing API key"
          },
          "403": {
            "description": "Link is banned"
          },
          "404": {
            "description": "Service not found"
          }
        }
      }
    },
    "/orders/{order_id}": {
      "get": {
        "summary": "Get order details",
        "description": "Returns detailed information about a specific order",
        "operationId": "getOrder",
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "required": true,
            "schema": {"type": "integer"},
            "description": "Order ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order": {"$ref": "#/components/schemas/OrderDetail"}
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key"
          },
          "404": {
            "description": "Order not found"
          }
        }
      }
    }
  }
}