Client API: Shield
Client-facing DDoS scrubber status and attack events for your IPs.
Client-facing DDoS scrubber status and attack events for your IPs.
Base URL: https://api.coritan.com/api/v1. Paths below are complete.
To try these requests in the browser, open the interactive Client API reference.
Operations
Section titled Operations| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/client/shield/events |
Recent attack events on this account's IP services, live ones first |
| GET | /api/v1/client/shield/status |
Protection view for every assigned floating IP on this account |
| GET | /api/v1/client/shield/subjects/{ip_service_id}/blocked-sources |
The sources refused on this IP, newest first |
| POST | /api/v1/client/shield/subjects/{ip_service_id}/blocked-sources |
Refuse traffic from an address or a CIDR range to this IP only |
| DELETE | /api/v1/client/shield/subjects/{ip_service_id}/blocked-sources/{block_id} |
Remove a block from this IP |
| GET | /api/v1/client/shield/subjects/{ip_service_id}/profile |
The profile scrubbing this IP: the platform default, or its custom one |
| PATCH | /api/v1/client/shield/subjects/{ip_service_id}/profile |
Ensure custom profile |
| POST | /api/v1/client/shield/subjects/{ip_service_id}/rules |
Create subject rule |
| DELETE | /api/v1/client/shield/subjects/{ip_service_id}/rules/{rule_id} |
Delete subject rule |
Recent attack events on this account's IP services, live ones first
Section titled Recent attack events on this account's IP services, live ones firstGET /api/v1/client/shield/events
Recent attack events on this account's IP services, live ones first.
ip_service_id narrows the list to one IP, which must be this
account's (404 otherwise).
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit |
query | integer | no | Default: 50. |
ip_service_id |
query | integer or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Protection view for every assigned floating IP on this account
Section titled Protection view for every assigned floating IP on this accountGET /api/v1/client/shield/status
Protection view for every assigned floating IP on this account.
Unattached IPs remain scrubbed (platform default).
Authentication: an access token, sent as Authorization: Bearer <token>.
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
The sources refused on this IP, newest first
Section titled The sources refused on this IP, newest firstGET /api/v1/client/shield/subjects/{ip_service_id}/blocked-sources
The sources refused on this IP, newest first. Expired blocks are left out.
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
ip_service_id |
path | integer | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Refuse traffic from an address or a CIDR range to this IP only
Section titled Refuse traffic from an address or a CIDR range to this IP onlyPOST /api/v1/client/shield/subjects/{ip_service_id}/blocked-sources
Refuse traffic from an address or a CIDR range to this IP only.
A bare IPv6 address blocks its /64. expires_minutes makes the block
remove itself; without it the block stays until it is removed.
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
ip_service_id |
path | integer | yes |
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required |
|---|---|---|
address |
string | yes |
reason |
string or null | no |
expires_minutes |
integer or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
201 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Remove a block from this IP
Section titled Remove a block from this IPDELETE /api/v1/client/shield/subjects/{ip_service_id}/blocked-sources/{block_id}
Remove a block from this IP. A block our team added stays (403).
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
ip_service_id |
path | integer | yes |
block_id |
path | integer | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
The profile scrubbing this IP: the platform default, or its custom one
Section titled The profile scrubbing this IP: the platform default, or its custom oneGET /api/v1/client/shield/subjects/{ip_service_id}/profile
The profile scrubbing this IP: the platform default, or its custom one.
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
ip_service_id |
path | integer | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Ensure custom profile
Section titled Ensure custom profilePATCH /api/v1/client/shield/subjects/{ip_service_id}/profile
Promote the subject to a customer-editable custom profile (idempotent), then apply any tuning in the body.
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
ip_service_id |
path | integer | yes |
Request body
Section titled Request bodyapplication/json
| Field | Type | Required |
|---|---|---|
protection_mode |
string or null | no |
default_action |
string or null | no |
established_passthrough |
boolean or null | no |
rate_limits |
RateLimitsPatch or null | no |
rate_limits.per_source_pps |
integer or null | no |
rate_limits.aggregate_pps |
integer or null | no |
rate_limits.syn_pps_per_source |
integer or null | no |
rate_limits.icmp_pps_per_source |
integer or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Create subject rule
Section titled Create subject rulePOST /api/v1/client/shield/subjects/{ip_service_id}/rules
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
ip_service_id |
path | integer | yes |
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required |
|---|---|---|
name |
string | no |
enabled |
boolean | no |
action |
string | no |
protocol |
integer or null | no |
src_prefix |
string or null | no |
dst_prefix |
string or null | no |
src_port_min |
integer or null | no |
src_port_max |
integer or null | no |
dst_port_min |
integer or null | no |
dst_port_max |
integer or null | no |
tcp_flags_mask |
integer or null | no |
tcp_flags_value |
integer or null | no |
packet_len_min |
integer or null | no |
packet_len_max |
integer or null | no |
ttl_min |
integer or null | no |
ttl_max |
integer or null | no |
icmp_type |
integer or null | no |
icmp_code |
integer or null | no |
rate_limit_pps |
integer or null | no |
notes |
string or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Delete subject rule
Section titled Delete subject ruleDELETE /api/v1/client/shield/subjects/{ip_service_id}/rules/{rule_id}
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
ip_service_id |
path | integer | yes |
rule_id |
path | integer | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |