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
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.
OK
Bad Request
Unauthorized
POST /api/v1/account/login HTTP/1.1
Host: api.nimbleway.com
Content-Type: application/json
Accept: */*
Content-Length: 37
{
"username": "text",
"password": "text"
}
{
"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.
OK
Unauthorized
POST /api/v1/account/login/refresh HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
{
"token": "text"
}
This API uses JWT/Bearer authentication: To generate an API-KEY, make a request with the following body/payload: { "key_name": "string"}
my_key
API key successfully created
Invalid or missing request payload
Unauthorized
Forbidden – no permission to create API key
Internal server error
POST /api/v1/account/api-key HTTP/1.1
Host: api.nimbleway.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 21
{
"key_name": "my_key"
}
{
"guid": "abc123",
"key_name": "my_key",
"key": "abc123",
"createdAt": "2024-06-01T12:00:00Z",
"created_by": "[email protected]",
"account_name": "my_account"
}
Authenticated IPs
Authenticated IPs allow the use of Nimble pipelines without username or password in your proxy settings
OK
Unauthorized
GET /api/v1/account/authenticatedips HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
{
"authorized_ips": [
"text"
],
"id": "text",
"pipeline_rules": [
{
"pipeline_name": "text",
"port_range_end": 1,
"port_range_start": 1
}
]
}
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
OK
Unauthorized
PUT /api/v1/account/authenticatedips HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 25
{
"ip_addresses": [
"text"
]
}
{
"authorized_ips": [
"text"
],
"id": "text",
"pipeline_rules": [
{
"pipeline_name": "text",
"port_range_end": 1,
"port_range_start": 1
}
]
}
Delete an authenticated IP rule
OK
Unauthorized
DELETE /api/v1/account/authenticatedips HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 21
{
"ip_address": "text"
}
No content
Pipelines
List all account pipelines
OK
Unauthorized
Not Found
GET /api/v1/account/pipelines HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
[
{
"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",
"traffic": {
"limit": {
"amount": 1,
"limit_type": "text"
},
"usage": {
"bytes": 1,
"last_reset_date": "text",
"requests": 1,
"usd": 1
}
},
"allow_ipv6": true,
"connection_string": "text",
"optimization_engine": [
"text"
],
"pipeline_password": "text",
"pipeline_username": "text",
"proxy_server_address": "text",
"proxy_server_port": 1,
"session_settings": {
"ip_rotation_type": "rotating",
"rotation_time_in_seconds": 1,
"session_ip_fallback": "replace_ip"
},
"status": "text",
"target_locations": [
{
"country_code": "text",
"state_code": "text",
"city_code": "text"
}
]
}
]
- 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.
in swagger indicate wat's optional
Sets the default behavior of the project to allow the use of ipv6 from peers.
Sets the default behavior of the project's session
Created
Bad Request
Unauthorized
Not Found
POST /api/v1/account/pipelines HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 311
{
"name": "text",
"allow_ipv6": true,
"optimization_engine": [
"text"
],
"pipeline_password": "text",
"pipeline_type": "ip",
"session_settings": {
"ip_rotation_type": "rotating",
"rotation_time_in_seconds": 1,
"session_ip_fallback": "replace_ip"
},
"target_locations": [
{
"country_code": "text",
"state_code": "text",
"city_code": "text"
}
]
}
{
"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",
"traffic": {
"limit": {
"amount": 1,
"limit_type": "text"
},
"usage": {
"bytes": 1,
"last_reset_date": "text",
"requests": 1,
"usd": 1
}
},
"allow_ipv6": true,
"connection_string": "text",
"optimization_engine": [
"text"
],
"pipeline_password": "text",
"pipeline_username": "text",
"proxy_server_address": "text",
"proxy_server_port": 1,
"session_settings": {
"ip_rotation_type": "rotating",
"rotation_time_in_seconds": 1,
"session_ip_fallback": "replace_ip"
},
"status": "text",
"target_locations": [
{
"country_code": "text",
"state_code": "text",
"city_code": "text"
}
]
}
Pipeline Name
OK
Unauthorized
Not Found
GET /api/v1/account/pipelines/{pipelineName} HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
{
"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",
"traffic": {
"limit": {
"amount": 1,
"limit_type": "text"
},
"usage": {
"bytes": 1,
"last_reset_date": "text",
"requests": 1,
"usd": 1
}
},
"allow_ipv6": true,
"connection_string": "text",
"optimization_engine": [
"text"
],
"pipeline_password": "text",
"pipeline_username": "text",
"proxy_server_address": "text",
"proxy_server_port": 1,
"session_settings": {
"ip_rotation_type": "rotating",
"rotation_time_in_seconds": 1,
"session_ip_fallback": "replace_ip"
},
"status": "text",
"target_locations": [
{
"country_code": "text",
"state_code": "text",
"city_code": "text"
}
]
}
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.
Pipeline Name
Sets the default behavior of the project to allow the use of ipv6 from peers.
Sets the default behavior of the project's session
OK
Bad Request
Unauthorized
Not Found
PATCH /api/v1/account/pipelines/{pipelineName} HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 292
{
"allow_ipv6": true,
"optimization_engine": [
"text"
],
"pipeline_password": "text",
"session_settings": {
"ip_rotation_type": "rotating",
"rotation_time_in_seconds": 1,
"session_ip_fallback": "replace_ip"
},
"status": "text",
"target_locations": [
{
"country_code": "text",
"state_code": "text",
"city_code": "text"
}
]
}
{
"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",
"traffic": {
"limit": {
"amount": 1,
"limit_type": "text"
},
"usage": {
"bytes": 1,
"last_reset_date": "text",
"requests": 1,
"usd": 1
}
},
"allow_ipv6": true,
"connection_string": "text",
"optimization_engine": [
"text"
],
"pipeline_password": "text",
"pipeline_username": "text",
"proxy_server_address": "text",
"proxy_server_port": 1,
"session_settings": {
"ip_rotation_type": "rotating",
"rotation_time_in_seconds": 1,
"session_ip_fallback": "replace_ip"
},
"status": "text",
"target_locations": [
{
"country_code": "text",
"state_code": "text",
"city_code": "text"
}
]
}
Authenticated IPs allow the use of Nimble pipelines without username or password in your proxy settings
Pipeline name
OK
Unauthorized
GET /api/v1/account/pipelines/{pipelineName}/authenticatedips/portrange HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
{
"pipeline_name": "text",
"port_range_end": 1,
"port_range_start": 1
}
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
Pipeline name
OK
Unauthorized
PUT /api/v1/account/pipelines/{pipelineName}/authenticatedips/portrange HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 41
{
"port_range_end": 1,
"port_range_start": 1
}
{
"authorized_ips": [
"text"
],
"id": "text",
"pipeline_rules": [
{
"pipeline_name": "text",
"port_range_end": 1,
"port_range_start": 1
}
]
}
Delete a pipeline port range rule
Pipeline name
OK
Unauthorized
DELETE /api/v1/account/pipelines/{pipelineName}/authenticatedips/portrange HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
No content
New password will be automatically generated for the Pipeline
Pipeline Name
OK
Bad Request
Unauthorized
Not Found
PUT /api/v1/account/pipelines/{pipelineName}/password HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
{
"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",
"traffic": {
"limit": {
"amount": 1,
"limit_type": "text"
},
"usage": {
"bytes": 1,
"last_reset_date": "text",
"requests": 1,
"usd": 1
}
},
"allow_ipv6": true,
"connection_string": "text",
"optimization_engine": [
"text"
],
"pipeline_password": "text",
"pipeline_username": "text",
"proxy_server_address": "text",
"proxy_server_port": 1,
"session_settings": {
"ip_rotation_type": "rotating",
"rotation_time_in_seconds": 1,
"session_ip_fallback": "replace_ip"
},
"status": "text",
"target_locations": [
{
"country_code": "text",
"state_code": "text",
"city_code": "text"
}
]
}
Returns a daily summary of requests and response size (GB)
Pipeline Name
From Date (DD/MM/YYYY)
To Date (DD/MM/YYYY)
OK
Unauthorized
Not Found
GET /api/v1/account/pipelines/{pipelineName}/reports/daily-usage HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
[
{
"daily_usages": [
{
"date": "text",
"request_gb": 1,
"response_gb": 1
}
],
"last_updated_at": "text",
"total_request_gb": 1,
"total_response_gb": 1
}
]
Pipeline Name
OK
Unauthorized
Not Found
GET /api/v1/account/pipelines/{pipelineName}/reports/detailed-requests HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
[
{
"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 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
Pipeline Name
OK
Unauthorized
Not Found
POST /api/v1/account/pipelines/{pipelineName}/spendlimit HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 26
{
"amount": 1,
"type": "text"
}
No content
Pipeline Name
OK
Unauthorized
Not Found
DELETE /api/v1/account/pipelines/{pipelineName}/spendlimit HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
No content
Account Status
OK
Unauthorized
Not Found
GET /api/v1/account/remaining-credits HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
{
"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,
"name": "ip",
"quota_type": "gigabytes",
"status": "text",
"trial_end": "text",
"trial_start": "text"
}
]
}
}
Returns a daily summary of requests and response size (GB)
From Date (DD/MM/YYYY)
To Date (DD/MM/YYYY)
OK
Unauthorized
Not Found
GET /api/v1/account/reports/daily-usage HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
[
{
"daily_usages": [
{
"date": "text",
"request_gb": 1,
"response_gb": 1
}
],
"last_updated_at": "text",
"total_request_gb": 1,
"total_response_gb": 1
}
]
OK
Unauthorized
GET /api/v1/account/reports/detailed-requests HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
[
{
"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"
}
]
Global Preferences
- 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
OK
Bad Request
POST /api/v1/account/timeout HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 30
{
"port": 1,
"timeout_in_secs": 1
}
No content
Removes custom timeout to an allowed port
OK
Bad Request
DELETE /api/v1/account/timeout HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 10
{
"port": 1
}
No content
Gets a custom timeout for a specific port
Port to query its timeout
OK
Bad Request
GET /api/v1/account/timeout/{port} HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
No content
Location
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.
table
addCountriesAndUsStates
OK
Bad Request
Internal Server Error
GET /api/v1/location/cities HTTP/1.1
Host: api.nimbleway.com
Authorization: YOUR_API_KEY
Accept: */*
[
"text"
]
Last updated