Admin API reference

INTRODUCTION

Nimble’s Admin API allows you to perform a number of key account functions, including:

Create, list, update, and delete pipelines
View account status and remaining credits
View account-level and pipeline-level usage reports
Manage authenticated IPs

Authentication

Authenticated IPs

Pipelines

Account Status

Global Preferences

Location

PreviousAdmin API basics NextProduct Updates

This API uses JWT/Bearer authentication:

To generate a token, make a request with the following body/payload: { "username": "string", "password": "string" }

Apply the received token in your following API request, by adding the header: authorization: Bearer [token]

auth.Token TTL time is 72 HRs.

post

/v1/account/login

Body

usernamestringrequired

passwordstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.nimbleway.com/api/v1/account/login' \
  --header 'Content-Type: application/json' \
  --data '{"username":"text","password":"text"}'

200

400

401

{
  "token": "text"
}

This API uses basic authentication: To generate a token, make a request without a body while authorized with your old token auth.Token TTL time is 72 HRs.

post

/v1/account/login/refresh

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.nimbleway.com/api/v1/account/login/refresh' \
  --header 'Authorization: YOUR_API_KEY'

200

401

{
  "token": "text"
}

List account rules

Authenticated IPs allow the use of Nimble pipelines without username or password in your proxy settings

get

/v1/account/authenticatedips

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nimbleway.com/api/v1/account/authenticatedips' \
  --header 'Authorization: YOUR_API_KEY'

200

401

{
  "id": "text",
  "authorized_ips": [
    "text"
  ],
  "pipeline_rules": [
    {
      "pipeline_name": "text",
      "port_range_end": 1,
      "port_range_start": 1
    }
  ]
}

Create a rule

An authenticated IP can only be used with a single account. Authenticated IP will identify the target account in your proxy requests, replacing the need for using username or password

put

/v1/account/authenticatedips

Authorizations

Body

ip_addressesstring[]required

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.nimbleway.com/api/v1/account/authenticatedips' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"ip_addresses":[null]}'

200

401

{
  "id": "text",
  "authorized_ips": [
    "text"
  ],
  "pipeline_rules": [
    {
      "pipeline_name": "text",
      "port_range_end": 1,
      "port_range_start": 1
    }
  ]
}

Delete a rule

Delete an authenticated IP rule

delete

/v1/account/authenticatedips

Authorizations

Body

ip_addressstringrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.nimbleway.com/api/v1/account/authenticatedips' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"ip_address":"text"}'

200

401

No body

List all Pipelines

List all account pipelines

get

/v1/account/pipelines

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines' \
  --header 'Authorization: YOUR_API_KEY'

200

401

404

[
  {
    "name": "text",
    "id": "text",
    "system_name": "text",
    "pipeline_type": "text",
    "proxy_pass": "text",
    "used_gb": 1,
    "spent_requests": 1,
    "created_at": "text",
    "updated_at": "text",
    "allow_ipv6": true,
    "connection_string": "text",
    "pipeline_password": "text",
    "pipeline_username": "text",
    "proxy_server_address": "text",
    "proxy_server_port": 1,
    "status": "text",
    "optimization_engine": [
      "text"
    ],
    "target_locations": [
      {
        "country_code": "text",
        "state_code": "text",
        "city_code": "text"
      }
    ],
    "traffic": {
      "limit": {
        "amount": 1,
        "limit_type": "text"
      },
      "usage": {
        "bytes": 1,
        "last_reset_date": "text",
        "requests": 1,
        "usd": 1
      }
    },
    "session_settings": {
      "rotation_time_in_seconds": 1,
      "ip_rotation_type": "rotating",
      "session_ip_fallback": "replace_ip"
    }
  }
]

Create a new Pipeline

Pipeline name - Use A-Z, a-z, 0-9 (can include space '.', '-', '_'). Up to 50 characters.
Target country - Default target country for the pipeline. Will apply to all request that do not specify a target country. Use ISO country code of 2-letter country code i.e. US, DE, BR.
Session settings configuration: When using rotating type, fallback is required in case a session_id is provided in order to set the behavior in case ip is not available When using fixed_interval type, rotation_time_in_seconds is required in order to set the interval of ip rotation and fallback is required as well for the same reason as above. replace_ip fallback will replace the session's ip to a new one and will keep using it as if it was selected in the first place. keep_asn fallback will find a new ip within the same asn and will keep using it as if it was selected in the first place. fail_request fallback will fail the request.

post

/v1/account/pipelines

Authorizations

Body

namestring · min: 2 · max: 50required

in swagger indicate wat's optional

allow_ipv6boolean

Sets the default behavior of the project to allow the use of ipv6 from peers.

pipeline_passwordstring · min: 8 · max: 12

pipeline_typestring · enumrequired

Options: ip, data, browser

optimization_enginestring[]

target_locationsobject[]

Use ALL in countryCode for no country limit

session_settingsall of

Sets the default behavior of the project's session

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"name":"text","pipeline_type":"ip","optimization_engine":[null],"target_locations":[{}],"session_settings":{"ip_rotation_type":"rotating","session_ip_fallback":"replace_ip"}}'

201

400

401

404

{
  "name": "text",
  "id": "text",
  "system_name": "text",
  "pipeline_type": "text",
  "proxy_pass": "text",
  "used_gb": 1,
  "spent_requests": 1,
  "created_at": "text",
  "updated_at": "text",
  "allow_ipv6": true,
  "connection_string": "text",
  "pipeline_password": "text",
  "pipeline_username": "text",
  "proxy_server_address": "text",
  "proxy_server_port": 1,
  "status": "text",
  "optimization_engine": [
    "text"
  ],
  "target_locations": [
    {
      "country_code": "text",
      "state_code": "text",
      "city_code": "text"
    }
  ],
  "traffic": {
    "limit": {
      "amount": 1,
      "limit_type": "text"
    },
    "usage": {
      "bytes": 1,
      "last_reset_date": "text",
      "requests": 1,
      "usd": 1
    }
  },
  "session_settings": {
    "rotation_time_in_seconds": 1,
    "ip_rotation_type": "rotating",
    "session_ip_fallback": "replace_ip"
  }
}

Created

Get a single Pipeline

get

/v1/account/pipelines/{pipelineName}

Authorizations

Path parameters

pipelineNamestringrequired

Pipeline Name

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines/{pipelineName}' \
  --header 'Authorization: YOUR_API_KEY'

200

401

404

{
  "name": "text",
  "id": "text",
  "system_name": "text",
  "pipeline_type": "text",
  "proxy_pass": "text",
  "used_gb": 1,
  "spent_requests": 1,
  "created_at": "text",
  "updated_at": "text",
  "allow_ipv6": true,
  "connection_string": "text",
  "pipeline_password": "text",
  "pipeline_username": "text",
  "proxy_server_address": "text",
  "proxy_server_port": 1,
  "status": "text",
  "optimization_engine": [
    "text"
  ],
  "target_locations": [
    {
      "country_code": "text",
      "state_code": "text",
      "city_code": "text"
    }
  ],
  "traffic": {
    "limit": {
      "amount": 1,
      "limit_type": "text"
    },
    "usage": {
      "bytes": 1,
      "last_reset_date": "text",
      "requests": 1,
      "usd": 1
    }
  },
  "session_settings": {
    "rotation_time_in_seconds": 1,
    "ip_rotation_type": "rotating",
    "session_ip_fallback": "replace_ip"
  }
}

Update a pipeline

Change pipeline's target country, session settings, Ipv6, project quota limit and status

Session settings configuration: When using rotating type, fallback is required in case a session_id is provided in order to set the behavior in case ip is not available When using fixed_interval type, rotation_time_in_seconds is required in order to set the interval of ip rotation and fallback is required as well for the same reason as above. replace_ip fallback will replace the session's ip to a new one and will keep using it as if it was selected in the first place. keep_asn fallback will find a new ip within the same asn and will keep using it as if it was selected in the first place. fail_request fallback will fail the request.

patch

/v1/account/pipelines/{pipelineName}

Authorizations

Path parameters

pipelineNamestringrequired

Pipeline Name

Body

allow_ipv6boolean

Sets the default behavior of the project to allow the use of ipv6 from peers.

pipeline_passwordstring · min: 8 · max: 12

statusstring

optimization_enginestring[]

target_locationsobject[]

Use ALL in countryCode for no country limit

session_settingsall of

Sets the default behavior of the project's session

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines/{pipelineName}' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"optimization_engine":[null],"target_locations":[{}],"session_settings":{"ip_rotation_type":"rotating","session_ip_fallback":"replace_ip"}}'

200

400

401

404

{
  "name": "text",
  "id": "text",
  "system_name": "text",
  "pipeline_type": "text",
  "proxy_pass": "text",
  "used_gb": 1,
  "spent_requests": 1,
  "created_at": "text",
  "updated_at": "text",
  "allow_ipv6": true,
  "connection_string": "text",
  "pipeline_password": "text",
  "pipeline_username": "text",
  "proxy_server_address": "text",
  "proxy_server_port": 1,
  "status": "text",
  "optimization_engine": [
    "text"
  ],
  "target_locations": [
    {
      "country_code": "text",
      "state_code": "text",
      "city_code": "text"
    }
  ],
  "traffic": {
    "limit": {
      "amount": 1,
      "limit_type": "text"
    },
    "usage": {
      "bytes": 1,
      "last_reset_date": "text",
      "requests": 1,
      "usd": 1
    }
  },
  "session_settings": {
    "rotation_time_in_seconds": 1,
    "ip_rotation_type": "rotating",
    "session_ip_fallback": "replace_ip"
  }
}

List pipeline rules

Authenticated IPs allow the use of Nimble pipelines without username or password in your proxy settings

get

/v1/account/pipelines/{pipelineName}/authenticatedips/portrange

Authorizations

Path parameters

pipelineNamestringrequired

Pipeline name

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines/{pipelineName}/authenticatedips/portrange' \
  --header 'Authorization: YOUR_API_KEY'

200

401

{
  "pipeline_name": "text",
  "port_range_end": 1,
  "port_range_start": 1
}

Create a pipeline rule

An authenticated port range can only be used with a single pipeline. Authenticated port will identify the target pipeline in your proxy requests, replacing the need for using username or password

put

/v1/account/pipelines/{pipelineName}/authenticatedips/portrange

Authorizations

Path parameters

pipelineNamestringrequired

Pipeline name

Body

port_range_endintegerrequired

port_range_startintegerrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines/{pipelineName}/authenticatedips/portrange' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"port_range_end":1,"port_range_start":1}'

200

401

{
  "id": "text",
  "authorized_ips": [
    "text"
  ],
  "pipeline_rules": [
    {
      "pipeline_name": "text",
      "port_range_end": 1,
      "port_range_start": 1
    }
  ]
}

Delete a rule

Delete a pipeline port range rule

delete

/v1/account/pipelines/{pipelineName}/authenticatedips/portrange

Authorizations

Path parameters

pipelineNamestringrequired

Pipeline name

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines/{pipelineName}/authenticatedips/portrange' \
  --header 'Authorization: YOUR_API_KEY'

200

401

No body

Change pipeline password

New password will be automatically generated for the Pipeline

put

/v1/account/pipelines/{pipelineName}/password

Authorizations

Path parameters

pipelineNamestringrequired

Pipeline Name

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines/{pipelineName}/password' \
  --header 'Authorization: YOUR_API_KEY'

200

400

401

404

{
  "name": "text",
  "id": "text",
  "system_name": "text",
  "pipeline_type": "text",
  "proxy_pass": "text",
  "used_gb": 1,
  "spent_requests": 1,
  "created_at": "text",
  "updated_at": "text",
  "allow_ipv6": true,
  "connection_string": "text",
  "pipeline_password": "text",
  "pipeline_username": "text",
  "proxy_server_address": "text",
  "proxy_server_port": 1,
  "status": "text",
  "optimization_engine": [
    "text"
  ],
  "target_locations": [
    {
      "country_code": "text",
      "state_code": "text",
      "city_code": "text"
    }
  ],
  "traffic": {
    "limit": {
      "amount": 1,
      "limit_type": "text"
    },
    "usage": {
      "bytes": 1,
      "last_reset_date": "text",
      "requests": 1,
      "usd": 1
    }
  },
  "session_settings": {
    "rotation_time_in_seconds": 1,
    "ip_rotation_type": "rotating",
    "session_ip_fallback": "replace_ip"
  }
}

Summary of daily Pipeline usage

Returns a daily summary of requests and response size (GB)

get

/v1/account/pipelines/{pipelineName}/reports/daily-usage

Authorizations

Path parameters

pipelineNamestringrequired

Pipeline Name

Query parameters

fromDatestring

From Date (DD/MM/YYYY)

toDatestring

To Date (DD/MM/YYYY)

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines/{pipelineName}/reports/daily-usage' \
  --header 'Authorization: YOUR_API_KEY'

200

401

404

[
  {
    "last_updated_at": "text",
    "total_request_gb": 1,
    "total_response_gb": 1,
    "daily_usages": [
      {
        "date": "text",
        "request_gb": 1,
        "response_gb": 1
      }
    ]
  }
]

Last 100 proxy requests made for specific pipeline

get

/v1/account/pipelines/{pipelineName}/reports/detailed-requests

Authorizations

Path parameters

pipelineNamestringrequired

Pipeline Name

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines/{pipelineName}/reports/detailed-requests' \
  --header 'Authorization: YOUR_API_KEY'

200

401

404

[
  {
    "account_name": "text",
    "client_ip": "text",
    "country_code": "text",
    "datetime": "text",
    "pipeline": "text",
    "request_host": "text",
    "request_port": 1,
    "request_size": 1,
    "response_size": 1,
    "total_size": 1,
    "type": "text"
  }
]

Sets daily quota limit for a pipeline

Sets a daily limit to prevent pipeline from over spending. Two limit types are available:

"gb" for limiting the transferred data by GBs
"credit" for limiting the amount of used credits

post

/v1/account/pipelines/{pipelineName}/spendlimit

Authorizations

Path parameters

pipelineNamestringrequired

Pipeline Name

Body

amountnumber

typestringrequired

Responses

*/*

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines/{pipelineName}/spendlimit' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"type":"text"}'

200

401

404

No body

Deletes the pipelines quota daily limit

delete

/v1/account/pipelines/{pipelineName}/spendlimit

Authorizations

Path parameters

pipelineNamestringrequired

Pipeline Name

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.nimbleway.com/api/v1/account/pipelines/{pipelineName}/spendlimit' \
  --header 'Authorization: YOUR_API_KEY'

200

401

404

No body

Get account status

get

/v1/account/remaining-credits

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nimbleway.com/api/v1/account/remaining-credits' \
  --header 'Authorization: YOUR_API_KEY'

200

401

404

{
  "billing": {
    "auto_renewal": true,
    "billing_period_end": "text",
    "billing_period_start": "text",
    "next_payment_date": "text",
    "payment_method": "text",
    "remaining_credits": 1,
    "roll_over": true,
    "spent_credits": 1,
    "subscription_services": [
      {
        "name": "ip",
        "spent_data_in_gb": 1,
        "spent_requests": 1
      }
    ]
  },
  "id": "text",
  "name": "text",
  "proxy_gateway_name": "text",
  "subscription_status": "text",
  "trials": {
    "activeTrials": [
      {
        "free_quota": 1,
        "free_used": 1,
        "quota_type": "gigabytes",
        "status": "text",
        "trial_end": "text",
        "trial_start": "text",
        "name": "ip"
      }
    ]
  }
}

Summary of daily account usage

Returns a daily summary of requests and response size (GB)

get

/v1/account/reports/daily-usage

Authorizations

Query parameters

fromDatestring

From Date (DD/MM/YYYY)

toDatestring

To Date (DD/MM/YYYY)

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nimbleway.com/api/v1/account/reports/daily-usage' \
  --header 'Authorization: YOUR_API_KEY'

200

401

404

[
  {
    "last_updated_at": "text",
    "total_request_gb": 1,
    "total_response_gb": 1,
    "daily_usages": [
      {
        "date": "text",
        "request_gb": 1,
        "response_gb": 1
      }
    ]
  }
]

Last 100 proxy requests made (entire Account)

get

/v1/account/reports/detailed-requests

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nimbleway.com/api/v1/account/reports/detailed-requests' \
  --header 'Authorization: YOUR_API_KEY'

200

401

[
  {
    "account_name": "text",
    "client_ip": "text",
    "country_code": "text",
    "datetime": "text",
    "pipeline": "text",
    "request_host": "text",
    "request_port": 1,
    "request_size": 1,
    "response_size": 1,
    "total_size": 1,
    "type": "text"
  }
]

Sets custom timeout to an allowed port

Sets custom timeout to an allowed port, to allow ports contact Nimble admin (the value can range between 10 and 30 seconds)
Port must be allowed in order to set a custom timeout

post

/v1/account/timeout

Authorizations

Body

portintegerrequired

timeout_in_secsinteger · min: 10 · max: 30required

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.nimbleway.com/api/v1/account/timeout' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"port":1,"timeout_in_secs":1}'

200

400

No body

Removes custom timeout to an allowed port

delete

/v1/account/timeout

Authorizations

Body

portintegerrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.nimbleway.com/api/v1/account/timeout' \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"port":1}'

200

400

No body

Gets a custom timeout for a specific port

get

/v1/account/timeout/{port}

Authorizations

Path parameters

portstringrequired

Port to query its timeout

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nimbleway.com/api/v1/account/timeout/{port}' \
  --header 'Authorization: YOUR_API_KEY'

200

400

No body

List of supported cities

Gets the list of supported cities in either JSON or HTML table. When using HTML table, addCountriesAndUsStates boolean can be used to add the rest of the supported countries and US states.

get

/v1/location/cities

Authorizations

Query parameters

tableboolean

table

addCountriesAndUsStatesboolean

addCountriesAndUsStates

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.nimbleway.com/api/v1/location/cities' \
  --header 'Authorization: YOUR_API_KEY'

200

400

500

[
  "text"
]

INTRODUCTION

Authentication

Authenticated IPs

Pipelines

Account Status

Global Preferences

Location

INTRODUCTION

Authentication

Authenticated IPs

Pipelines

Account Status

Global Preferences

Location

Get authentication token

Get new authentication token

List account rules

Create a rule

Delete a rule

List all Pipelines

Create a new Pipeline

Get a single Pipeline

Update a pipeline

List pipeline rules

Create a pipeline rule

Delete a rule

Change pipeline password

Summary of daily Pipeline usage

Last 100 proxy requests made for specific pipeline

Sets daily quota limit for a pipeline

Deletes the pipelines quota daily limit

Get account status

Summary of daily account usage

Last 100 proxy requests made (entire Account)

Sets custom timeout to an allowed port

Removes custom timeout to an allowed port

Gets a custom timeout for a specific port

List of supported cities