{
  "openapi": "3.0.3",
  "info": {
    "title": "Arcvenza Proxy API",
    "version": "1.0.0",
    "description": "Account API key endpoints for residential and mobile proxy generation, location lookup, and traffic. Create an ak_ account API key in dashboard Settings. Server selects the signed-in user's residential BasicMainKey for MealType=basic; never send that product key as a query parameter."
  },
  "servers": [{ "url": "https://arcvenza.com" }],
  "security": [{ "AccountApiKey": [] }],
  "tags": [
    { "name": "Locations", "description": "Discover exit country, state, city, and ASN values." },
    { "name": "Proxy generation", "description": "Generate ready-to-use proxy credentials. Treat the response as a secret." },
    { "name": "Traffic", "description": "Read traffic for the authenticated account." }
  ],
  "paths": {
    "/api/Location/Search": {
      "post": {
        "tags": ["Locations"],
        "operationId": "searchLocations",
        "summary": "List countries, states, or cities",
        "description": "Send mealType=basic alone for countries, add countryCode for states, or add stateCode for cities. Copy body[].value unchanged into the next request or proxy generation. Lookup does not consume traffic.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/LocationSearchRequest" },
              "examples": {
                "countries": { "value": { "mealType": "basic" } },
                "states": { "value": { "mealType": "basic", "countryCode": "US" } },
                "cities": { "value": { "mealType": "basic", "countryCode": "US", "stateCode": "CA" } }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Location values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationResponse" }, "example": { "code": 200, "message": "Success", "body": [{ "label": "United States", "value": "US", "weight": 0 }] } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/Location/GetAsnsByCountryCode": {
      "get": {
        "tags": ["Locations"],
        "operationId": "getAsnsByCountryCode",
        "summary": "List ASNs for a country",
        "description": "Returns numeric ASNs without the AS prefix. Use the same country for Generate.Country; ASN targeting requires a country.",
        "parameters": [{ "name": "countryCode", "in": "query", "required": true, "description": "Exactly two English letters; normalized to uppercase.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "example": "US" }],
        "responses": {
          "200": { "description": "Available ASNs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsnResponse" }, "example": { "code": 200, "message": "Success", "body": [{ "asn": 7922, "asnInfo": null }] } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/ProxyLogic/Generate": {
      "get": {
        "tags": ["Proxy generation"],
        "operationId": "generateDynamicProxies",
        "summary": "Generate residential or mobile proxies",
        "description": "For residential send MealType=basic. Server derives the user's BasicMainKey and returns one credential per line. Country is required when State, City, or Asn is supplied. Server selects the connection gateway, independently of the exit country. LifeTime=0 rotates; 1–120 adds a sticky session ID. Num must be 1–1000. Format 0 is host:port:username:password, 1 is username:password@host:port, 2 is username:password:host:port.",
        "parameters": [
          { "$ref": "#/components/parameters/MealType" },
          { "$ref": "#/components/parameters/Num" },
          { "$ref": "#/components/parameters/Country" },
          { "$ref": "#/components/parameters/State" },
          { "$ref": "#/components/parameters/City" },
          { "$ref": "#/components/parameters/Asn" },
          { "$ref": "#/components/parameters/LifeTime" },
          { "$ref": "#/components/parameters/Server" },
          { "$ref": "#/components/parameters/Format" }
        ],
        "responses": {
          "200": { "description": "One ready-to-use proxy per line. Keep credentials private.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "proxy.arcvenza.com:10000:<GENERATED_USERNAME>:<GENERATED_PASSWORD>" } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/ProxyLogic/UnlimitedGenerate": {
      "get": {
        "tags": ["Proxy generation"],
        "operationId": "generateUnlimitedProxies",
        "summary": "Generate unlimited residential proxies",
        "description": "Requires a valid unexpired unlimited key owned by the authenticated account. Connection host is unlimited.arcvenza.com:10000. Country is required with State, City or Asn. SessionTime is used when nonempty and not 0; otherwise LifeTime greater than zero adds a sticky session.",
        "parameters": [
          { "name": "KeyName", "in": "query", "required": true, "description": "Active unlimitedKey from the plan. This value is sensitive.", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/Num" },
          { "$ref": "#/components/parameters/Country" },
          { "$ref": "#/components/parameters/State" },
          { "$ref": "#/components/parameters/City" },
          { "$ref": "#/components/parameters/Asn" },
          { "name": "SessionTime", "in": "query", "description": "Nonzero value appended as sticky-session lifetime.", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/LifeTime" },
          { "$ref": "#/components/parameters/Format" }
        ],
        "responses": {
          "200": { "description": "One ready-to-use proxy per line. Keep credentials private.", "content": { "text/plain": { "schema": { "type": "string" }, "example": "unlimited.arcvenza.com:10000:<GENERATED_USERNAME>:<GENERATED_PASSWORD>" } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/ProxyLogic/GetProxyConfig": {
      "get": {
        "tags": ["Proxy generation"],
        "operationId": "getProxyConfig",
        "summary": "Get gateway and credential configuration",
        "description": "Returns the authenticated user's generated proxy username, password, and configured gateway hosts. For residential use mealType=basic. State, city or asn selects regional credentials but keeps the residential BasicMainKey.",
        "parameters": [
          { "name": "mealType", "in": "query", "required": true, "schema": { "type": "string", "enum": ["basic", "mobile"] }, "example": "basic" },
          { "name": "pool", "in": "query", "description": "Defaults to 1.", "schema": { "type": "integer", "default": 1 } },
          { "$ref": "#/components/parameters/State" },
          { "$ref": "#/components/parameters/City" },
          { "$ref": "#/components/parameters/Asn" }
        ],
        "responses": {
          "200": { "description": "Current proxy configuration. Username and password are sensitive.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyConfigResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/ProxyLogic/BandwidthAnalysis": {
      "get": {
        "tags": ["Traffic"],
        "operationId": "getBandwidthAnalysis",
        "summary": "Get dynamic traffic totals and usage",
        "description": "Returns the authenticated user's residential and mobile traffic. Current backend response also retains legacy basic, premium and beta fields.",
        "responses": {
          "200": { "description": "Traffic amounts in GB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BandwidthResponse" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": { "AccountApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Account API key (ak_)" } },
    "parameters": {
      "MealType": { "name": "MealType", "in": "query", "required": true, "description": "basic uses the unified residential product key; mobile uses the mobile product key.", "schema": { "type": "string", "enum": ["basic", "mobile"] }, "example": "basic" },
      "Num": { "name": "Num", "in": "query", "required": true, "description": "Number of proxy lines, 1–1000.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "example": 1 },
      "Country": { "name": "Country", "in": "query", "description": "Exit country value from Location/Search. Required for State, City or Asn.", "schema": { "type": "string" }, "example": "US" },
      "State": { "name": "State", "in": "query", "description": "State value from Location/Search for the selected country.", "schema": { "type": "string" }, "example": "CA" },
      "City": { "name": "City", "in": "query", "description": "City value from Location/Search for the selected state. Preserve the returned value.", "schema": { "type": "string" } },
      "Asn": { "name": "Asn", "in": "query", "description": "Numeric ASN from GetAsnsByCountryCode without AS; requires Country.", "schema": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 4294967295 }, "example": 7922 },
      "LifeTime": { "name": "LifeTime", "in": "query", "description": "0 rotates; 1–120 minutes adds a sticky session.", "schema": { "type": "integer", "minimum": 0, "maximum": 120, "default": 0 }, "example": 5 },
      "Server": { "name": "Server", "in": "query", "description": "Connection gateway, separate from exit country: us=proxy.arcvenza.com:10000, eu=proxy-eu.arcvenza.com:10000, as=proxy-as.arcvenza.com:10000. Mobile uses the corresponding mobile host.", "schema": { "type": "string", "enum": ["us", "eu", "as"], "default": "us" }, "example": "us" },
      "Format": { "name": "Format", "in": "query", "description": "0 host:port:user:pass; 1 user:pass@host:port; 2 user:pass:host:port.", "schema": { "type": "integer", "enum": [0, 1, 2], "default": 0 }, "example": 0 }
    },
    "schemas": {
      "LocationSearchRequest": { "type": "object", "required": ["mealType"], "properties": { "mealType": { "type": "string", "enum": ["basic", "mobile"], "example": "basic" }, "countryCode": { "type": "string", "description": "Omit for countries; supply a returned country value for states or cities.", "example": "US" }, "stateCode": { "type": "string", "description": "Omit for countries or states; supply a returned state value for cities.", "example": "CA" } } },
      "LocationItem": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "weight": { "type": "integer" } } },
      "CountryAsn": { "type": "object", "properties": { "asn": { "type": "integer", "format": "int64" }, "asnInfo": { "type": "string", "nullable": true } } },
      "LocationResponse": { "allOf": [{ "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "body": { "type": "array", "items": { "$ref": "#/components/schemas/LocationItem" } } } }] },
      "AsnResponse": { "allOf": [{ "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "body": { "type": "array", "items": { "$ref": "#/components/schemas/CountryAsn" } } } }] },
      "ApiEnvelope": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } },
      "ProxyConfig": { "type": "object", "properties": { "userName": { "type": "string" }, "proxyPwd": { "type": "string" }, "proxyFmt": { "type": "string" }, "mobileProxyUrl": { "type": "array", "items": { "type": "string" } }, "proxyPort": { "type": "array", "items": { "type": "integer" } }, "usProxyUrl": { "type": "array", "items": { "type": "string" } }, "euProxyUrl": { "type": "array", "items": { "type": "string" } }, "asProxyUrl": { "type": "array", "items": { "type": "string" } }, "directProxyUrl": { "type": "array", "items": { "type": "string" } } } },
      "ProxyConfigResponse": { "allOf": [{ "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "body": { "$ref": "#/components/schemas/ProxyConfig" } } }] },
      "BandwidthAnalysis": { "type": "object", "properties": { "basicTotalBandWidth": { "type": "number" }, "basicUsedBandwidth": { "type": "number" }, "premiumTotalBandWidth": { "type": "number" }, "premiumUsedBandwidth": { "type": "number" }, "betaTotalBandWidth": { "type": "number" }, "betaUsedBandwidth": { "type": "number" }, "mobileTotalBandWidth": { "type": "number" }, "mobileUsedBandwidth": { "type": "number" }, "totalBandWidth": { "type": "number" }, "usedBandwidth": { "type": "number" } } },
      "BandwidthResponse": { "allOf": [{ "$ref": "#/components/schemas/ApiEnvelope" }, { "type": "object", "properties": { "body": { "$ref": "#/components/schemas/BandwidthAnalysis" } } }] }
    },
    "responses": {
      "Unauthorized": { "description": "Missing or invalid account API key." },
      "Forbidden": { "description": "Account API key has no access to this resource." }
    }
  }
}