@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api IX-API
@base /api/v2
@version 2.7.1
@auth Bearer bearer | OAuth2
@endpoints 115
@hint download_for_search
@toc auth(2), facilities(2), devices(2), pops(2), metro-area-networks(2), metro-areas(2), product-offerings(2), availability-zones(2), ports(4), port-reservations(9), connections(11), network-service-configs(11), network-feature-configs(6), account(1), accounts(6), roles(2), contacts(6), role-assignments(4), health(1), implementation(1), extensions(1), ips(5), macs(4), network-services(13), network-features(2), member-joining-rules(6), routing-functions(6)

@group auth
@endpoint POST /auth/token
@desc Create Auth Token
@required {api_key: str, api_secret: str}
@returns(201) {access_token: str, refresh_token: str} # **AuthToken**
@errors {400: ValidationError, 401: Authentication}

@endpoint POST /auth/refresh
@desc Refresh Auth Token
@required {refresh_token: str}
@returns(201) {access_token: str, refresh_token: str} # **AuthToken**
@errors {400: ValidationError, 401: Authentication}

@endgroup

@group facilities
@endpoint GET /facilities
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), capability_speed: int # Filter by capability_speed, capability_speed_lt: int # Filter by capability_speed_lt, capability_speed_lte: int # Filter by capability_speed_lte, capability_speed_gt: int # Filter by capability_speed_gt, capability_speed_gte: int # Filter by capability_speed_gte, capability_media_type: str # Filter by capability_media_type, organisation_name: str # Filter by organisation_name, metro_area: str # Filter by metro_area, metro_area_network: str # Filter by metro_area_network, address_country: str # Filter by address_country, address_locality: str # Filter by address_locality, postal_code: str # Filter by postal_code}
@returns(200) List of: **Facility**
@returns(206) Paginated List of: **Facility**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /facilities/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {id: str, name: str, metro_area: str, address_country: str, address_locality: str, address_region: str, postal_code: str, street_address: str, peeringdb_facility_id: int(int32)?, organisation_name: str, pops: [str], latitude: num, longitude: num} # **Facility**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group devices
@endpoint GET /devices
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), capability_speed: int # Filter by capability_speed, capability_speed_lt: int # Filter by capability_speed_lt, capability_speed_lte: int # Filter by capability_speed_lte, capability_speed_gt: int # Filter by capability_speed_gt, capability_speed_gte: int # Filter by capability_speed_gte, name: str # Filter by name, capability_media_type: str # Filter by capability_media_type, facility: str # Filter by facility, pop: str # Filter by pop, metro_area_network: str # Filter by metro_area_network}
@returns(200) List of: **Device**
@returns(206) Paginated List of: **Device**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /devices/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {id: str, name: str, pop: str, capabilities: [map], facility: str} # **Device**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group pops
@endpoint GET /pops
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), facility: str # Filter by facility, metro_area_network: str # Filter by metro_area_network, capability_media_type: str # Filter by capability_media_type, capability_speed: int # Filter by capability_speed, capability_speed_lt: int # Filter by capability_speed_lt, capability_speed_lte: int # Filter by capability_speed_lte, capability_speed_gt: int # Filter by capability_speed_gt, capability_speed_gte: int # Filter by capability_speed_gte}
@returns(200) List of: **Point Of Presence**
@returns(206) Paginated List of: **Point Of Presence**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /pops/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {name: str, facility: str, metro_area_network: str, devices: [str], id: str, availability_zone: str?} # **Point Of Presence**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group metro-area-networks
@endpoint GET /metro-area-networks
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), name: str # Filter by name, metro_area: str # Filter by metro_area, service_provider: str # Filter by service_provider}
@returns(200) List of: **MetroAreaNetwork**
@returns(206) Paginated List of: **MetroAreaNetwork**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /metro-area-networks/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {id: str, name: str, metro_area: str, service_provider: str, pops: [str]} # **MetroAreaNetwork**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group metro-areas
@endpoint GET /metro-areas
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination)}
@returns(200) List of: **MetroArea**
@returns(206) Paginated List of: **MetroArea**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /metro-areas/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {id: str, un_locode: str, iata_code: str, display_name: str, facilities: [str], metro_area_networks: [str]} # **MetroArea**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group product-offerings
@endpoint GET /product-offerings
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), type: str(connection/exchange_lan/p2p_vc/mp2mp_vc/p2mp_vc/cloud_vc/routing_function) # Filter by type, resource_type: str(connection/port_reservation/network_service/network_service_config/routing_function) # Filter by resource_type, name: str # Filter by name, handover_metro_area: str # Filter by handover_metro_area, handover_metro_area_network: str # Filter by handover_metro_area_network, handover_pop: str # Filter by handover_pop, service_metro_area: str # Filter by service_metro_area, service_metro_area_network: str # Filter by service_metro_area_network, service_provider: str # Filter by service_provider, downgrade_allowed: str(true/false) # Filter by downgrade_allowed, upgrade_allowed: str(true/false) # Filter by upgrade_allowed, bandwidth: int # Find product offerings where bandwidth is within the range of `bandwidth_min` and `bandwidth_max`., physical_port_speed: int # Filter by physical_port_speed, service_provider_region: str # Filter by service_provider_region, service_provider_pop: str # Filter by service_provider_pop, delivery_method: str(dedicated/shared) # Filter by delivery_method, cloud_key: str # For product offerings of type `cloud_vc`, if the `service_provider_workflow` is `provider_first` the `cloud_key` will be used for filtering the relevant offerings., contract_initial_period: str # Filter by contract_initial_period, contract_initial_notice_period: str # Filter by contract_initial_notice_period, contract_renewal_period: str # Filter by contract_renewal_period, contract_renewal_notice_period: str # Filter by contract_renewal_notice_period, fields: str # Returned objects only have properties which are present in the list of fields. The required `type` property is *implicitly* included. The results are *deduplicated*.}
@returns(200) List of: **Polymorphic Product Offering**
@returns(206) Paginated List of: **Polymorphic Product Offering**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /product-offerings/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {type: str} # **Polymorphic Product Offering**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group availability-zones
@endpoint GET /availability-zones
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), name: str # Filter by name}
@returns(200) List of: **AvailabilityZone**
@returns(206) Paginated List of: **AvailabilityZone**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /availability-zones/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {id: str, name: str} # **AvailabilityZone**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group ports
@endpoint GET /ports
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), state: str # Filter by state, state__is_not: str # Filter by state__is_not, managing_account: str # Filter by the ID of the managing [account](#tag/accounts)., consuming_account: str # Filter by the ID of the consuming [account](#tag/accounts)., external_ref: str # Filter by external_ref, media_type: str # Filter by media_type, pop: str # Filter by pop, name: str # Filter by name, device: str # Filter by device, speed: str # Filter by speed, connection: str # Filter by connection}
@returns(200) List of: **Port**
@returns(206) Paginated List of: **Port**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /ports/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {state: str, status: [map], managing_account: str, consuming_account: str, external_ref: str?, purchase_order: str, contract_ref: str?, billing_account: str, role_assignments: [str], id: str, connection: str?, speed: int?, name: str, media_type: str, operational_state: str, device: str, pop: str} # **Port**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /ports/{id}/statistics
@desc Read Statistics
@required {id: str # Get by id}
@optional {start: str(date-time) # Beginning of the traffic aggregation., end: str(date-time) # End of the traffic aggregation. Default is `now`.}
@returns(200) {aggregates: map, light_levels_tx: [num], light_levels_rx: [num]} # **Port Statistics**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /ports/{id}/statistics/{aggregate}/timeseries
@desc Read Statistics Timeseries
@required {id: str # Get by id, aggregate: str # Get by aggregate}
@optional {start: str(date-time) # Start of the timeseries., end: str(date-time) # End of the timeseries.  Default: `now`, fields: str # Select fields from the aggregates to export as a timeseries.  Default: `average_pps_in,average_pps_out,average_ops_in,average_ops_out`}
@returns(200) {title: str, precision: int, created_at: str(date-time), next_update_at: str(date-time), origin_timezone: str, fields: [str], samples: [[any]]} # **Aggregated Statistics Timeseries**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group port-reservations
@endpoint GET /port-reservations
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), state: str # Filter by state, state__is_not: str # Filter by state__is_not, connection: str # Filter by connection, port: str # Filter by port, external_ref: str # Filter by external_ref}
@returns(200) List of: **A PortReservation**
@returns(206) Paginated List of: **A PortReservation**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /port-reservations
@desc Create
@required {id: str # The *primary identifier* of the `A PortReservation`., connection: str # A connection is required for port allocation.}
@optional {purchase_order: str= # Purchase Order ID which will be displayed on the invoice. *(Sensitive Property)*, contract_ref: str # A reference to a contract. If no specific contract is used, a default MAY be chosen by the implementer. *(Sensitive Property)*, external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, subscriber_side_demarc: str # In an exchange initiated scenario, this field will indicated one of the provided `subscriber_side_demarcs` from the connection., connecting_party: str # Name of the service provider who establishes connectivity on your behalf.  This is only relevant, if the cross connect initiator is the `subscriber`.  Please refer to the usage guide of the internet exchange., cross_connect_id: str # An optional identifier of a cross connect.}
@returns(201) {state: str, status: [map], decommission_at: str(date), charged_until: str(date), current_billing_start_date: str(date), purchase_order: str, contract_ref: str?, external_ref: str?, id: str, subscriber_side_demarc: str, connecting_party: str?, cross_connect_id: str, connection: str, exchange_side_demarc: str?, port: str?} # **A PortReservation**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /port-reservations/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {state: str, status: [map], decommission_at: str(date), charged_until: str(date), current_billing_start_date: str(date), purchase_order: str, contract_ref: str?, external_ref: str?, id: str, subscriber_side_demarc: str, connecting_party: str?, cross_connect_id: str, connection: str, exchange_side_demarc: str?, port: str?} # **A PortReservation**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PUT /port-reservations/{id}
@desc Update (Deprecated)
@required {id: str # Get by id, id: str # The *primary identifier* of the `PortReservation Update`.}
@optional {purchase_order: str= # Purchase Order ID which will be displayed on the invoice. *(Sensitive Property)*, contract_ref: str # A reference to a contract. If no specific contract is used, a default MAY be chosen by the implementer. *(Sensitive Property)*, external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, subscriber_side_demarc: str # In an exchange initiated scenario, this field will indicated one of the provided `subscriber_side_demarcs` from the connection., connecting_party: str # Name of the service provider who establishes connectivity on your behalf.  This is only relevant, if the cross connect initiator is the `subscriber`.  Please refer to the usage guide of the internet exchange., cross_connect_id: str # An optional identifier of a cross connect.}
@returns(202) {state: str, status: [map], decommission_at: str(date), charged_until: str(date), current_billing_start_date: str(date), purchase_order: str, contract_ref: str?, external_ref: str?, id: str, subscriber_side_demarc: str, connecting_party: str?, cross_connect_id: str, connection: str, exchange_side_demarc: str?, port: str?} # **A PortReservation**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PATCH /port-reservations/{id}
@desc Update
@required {id: str # Get by id}
@returns(202) {state: str, status: [map], decommission_at: str(date), charged_until: str(date), current_billing_start_date: str(date), purchase_order: str, contract_ref: str?, external_ref: str?, id: str, subscriber_side_demarc: str, connecting_party: str?, cross_connect_id: str, connection: str, exchange_side_demarc: str?, port: str?} # **A PortReservation**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint DELETE /port-reservations/{id}
@desc Request Decommission
@required {id: str # Get by id}
@optional {decommission_at: str(date) # An optional date for scheduling the cancellation and service decommissioning.}
@returns(202) {state: str, status: [map], decommission_at: str(date), charged_until: str(date), current_billing_start_date: str(date), purchase_order: str, contract_ref: str?, external_ref: str?, id: str, subscriber_side_demarc: str, connecting_party: str?, cross_connect_id: str, connection: str, exchange_side_demarc: str?, port: str?} # **A PortReservation**
@errors {400: CancellationPolicyError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /port-reservations/{id}/cancellation-policy
@desc Read Cancellation Policy
@required {id: str # Get by id}
@optional {decommission_at: str # By providing a date in the format `YYYY-MM-DD` you can query the policy what would happen if you request a decommissioning on this date.}
@returns(200) {decommission_at: str(date), charged_until: str(date)} # **Cancellation Policy**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /port-reservations/{id}/loa
@desc Download LOA
@required {id: str # Get by id}
@returns(200) A Letter Of Authorization
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint POST /port-reservations/{id}/loa
@desc Upload LOA
@required {id: str # Get by id}
@returns(200) The upload was successful
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group connections
@endpoint GET /connections
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), state: str # Filter by state, state__is_not: str # Filter by state__is_not, managing_account: str # Filter by the ID of the managing [account](#tag/accounts)., consuming_account: str # Filter by the ID of the consuming [account](#tag/accounts)., external_ref: str # Filter by external_ref, mode: str # Filter by mode, mode__is_not: str # Filter by mode__is_not, name: str # Filter by name, metro_area: str # Filter connections by ID of the metro_area, metro_area_network: str # Filter connections by ID of the metro_area_network, pop: str # Filter by pop, facility: str # Filter by facility, role_assignments: [str] # Filter by role_assignments, contacts: [str] # Filter by contacts, supported_network_service: str # Filter connections that can be used in a network service config for the service identified by ID}
@returns(200) List of: **Connection**
@returns(206) Paginated List of: **Connection**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /connections
@desc Create
@required {managing_account: str # The `id` of the account responsible for managing the service via the API. A manager can read and update the state of entities. *(Sensitive Property)*, consuming_account: str # The `id` of the account consuming a service.  Used to be `owning_customer`. *(Sensitive Property)*, billing_account: str # An account requires billing_information to be used as a `billing_account`. *(Sensitive Property)*, role_assignments: [str] # A set of `RoleAssignment`s. See the documentation on the specific `required_contact_roles`, `nfc_required_contact_roles` or `nsc_required_contact_roles` on what `RoleAssignment`s to provide.  Please note, that any contact role can additionally be provided. The presence of at least one of each required contact roles is necessary.  *(Sensitive Property)*, id: str # The *primary identifier* of the `Request a new connection`., mode: str(lag_lacp/lag_static/flex_ethernet/standalone) # Sets the mode of the connection. The mode can be:  - `lag_lacp`: connection is build as a LAG with LACP enabled - `lag_static`: connection is build as LAG with static configuration - `flex_ethernet`: connect is build as a FlexEthernet channel - `standalone`: only one port is allowed in this connection without any bundling., product_offering: str # The product offering must match the type `connection`., port_quantity: int # The number of `PortReservation`s that will be created for this connection.}
@optional {external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, purchase_order: str= # Purchase Order ID which will be displayed on the invoice. *(Sensitive Property)*, contract_ref: str # A reference to a contract. If no specific contract is used, a default MAY be chosen by the implementer. *(Sensitive Property)*, lacp_timeout: str(slow/fast) # This sets the LACP Timeout mode. Both ends of the connections need to be configured the same., subscriber_side_demarcs: [str] # The workflow for allocating ports is dependent on the `cross_connect_initiator` property of the `product_offering`:  **Cross-Connect initiator: exchange**  The subscriber needs to provide a list of demarc information.  At least one needs to be provided, but not more than `port_quantity`.  The content is interpreted by the exchange and may contain a reference to a pre-existing cross connect order or information required for patching in a structured format (e.g. `...`).  Please refer to the usage guide of the internet exchange.  ---  **Cross-Connect initiator: subscriber**  This field can be omitted, when the cross connect initiator is the `subscriber`., connecting_party: str # Name of the service provider who establishes connectivity on your behalf.  This is only relevant, if the cross connect initiator is the `subscriber` and might be `null`.  Please refer to the usage guide of the internet exchange.}
@returns(201) {state: str, status: [map], decommission_at: str(date), charged_until: str(date), current_billing_start_date: str(date), managing_account: str, consuming_account: str, external_ref: str?, purchase_order: str, contract_ref: str?, billing_account: str, role_assignments: [str], id: str, mode: str, lacp_timeout: str?, product_offering: str, name: str, ports: [str], port_reservations: [str], pop: str, speed: int?, capacity_allocated: int, capacity_allocation_limit: int?, vlan_types: [str], outer_vlan_ethertypes: [str], port_quantity: int, subscriber_side_demarcs: [str], metro_area: str, metro_area_network: str} # **Connection**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /connections/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {state: str, status: [map], decommission_at: str(date), charged_until: str(date), current_billing_start_date: str(date), managing_account: str, consuming_account: str, external_ref: str?, purchase_order: str, contract_ref: str?, billing_account: str, role_assignments: [str], id: str, mode: str, lacp_timeout: str?, product_offering: str, name: str, ports: [str], port_reservations: [str], pop: str, speed: int?, capacity_allocated: int, capacity_allocation_limit: int?, vlan_types: [str], outer_vlan_ethertypes: [str], port_quantity: int, subscriber_side_demarcs: [str], metro_area: str, metro_area_network: str} # **Connection**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PUT /connections/{id}
@desc Update (Deprecated)
@required {id: str # Get by id, managing_account: str # The `id` of the account responsible for managing the service via the API. A manager can read and update the state of entities. *(Sensitive Property)*, consuming_account: str # The `id` of the account consuming a service.  Used to be `owning_customer`. *(Sensitive Property)*, billing_account: str # An account requires billing_information to be used as a `billing_account`. *(Sensitive Property)*, role_assignments: [str] # A set of `RoleAssignment`s. See the documentation on the specific `required_contact_roles`, `nfc_required_contact_roles` or `nsc_required_contact_roles` on what `RoleAssignment`s to provide.  Please note, that any contact role can additionally be provided. The presence of at least one of each required contact roles is necessary.  *(Sensitive Property)*, id: str # The *primary identifier* of the `Connection Update`., mode: str(lag_lacp/lag_static/flex_ethernet/standalone) # Sets the mode of the connection. The mode can be:  - `lag_lacp`: connection is build as a LAG with LACP enabled - `lag_static`: connection is build as LAG with static configuration - `flex_ethernet`: connect is build as a FlexEthernet channel - `standalone`: only one port is allowed in this connection without any bundling., product_offering: str # The product offering must match the type `connection`.}
@optional {external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, purchase_order: str= # Purchase Order ID which will be displayed on the invoice. *(Sensitive Property)*, contract_ref: str # A reference to a contract. If no specific contract is used, a default MAY be chosen by the implementer. *(Sensitive Property)*, lacp_timeout: str(slow/fast) # This sets the LACP Timeout mode. Both ends of the connections need to be configured the same.}
@returns(202) {state: str, status: [map], decommission_at: str(date), charged_until: str(date), current_billing_start_date: str(date), managing_account: str, consuming_account: str, external_ref: str?, purchase_order: str, contract_ref: str?, billing_account: str, role_assignments: [str], id: str, mode: str, lacp_timeout: str?, product_offering: str, name: str, ports: [str], port_reservations: [str], pop: str, speed: int?, capacity_allocated: int, capacity_allocation_limit: int?, vlan_types: [str], outer_vlan_ethertypes: [str], port_quantity: int, subscriber_side_demarcs: [str], metro_area: str, metro_area_network: str} # **Connection**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PATCH /connections/{id}
@desc Update
@required {id: str # Get by id}
@returns(202) {state: str, status: [map], decommission_at: str(date), charged_until: str(date), current_billing_start_date: str(date), managing_account: str, consuming_account: str, external_ref: str?, purchase_order: str, contract_ref: str?, billing_account: str, role_assignments: [str], id: str, mode: str, lacp_timeout: str?, product_offering: str, name: str, ports: [str], port_reservations: [str], pop: str, speed: int?, capacity_allocated: int, capacity_allocation_limit: int?, vlan_types: [str], outer_vlan_ethertypes: [str], port_quantity: int, subscriber_side_demarcs: [str], metro_area: str, metro_area_network: str} # **Connection**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint DELETE /connections/{id}
@desc Request Decommission
@required {id: str # Get by id}
@optional {decommission_at: str(date) # An optional date for scheduling the cancellation and service decommissioning.}
@returns(202) {state: str, status: [map], decommission_at: str(date), charged_until: str(date), current_billing_start_date: str(date), managing_account: str, consuming_account: str, external_ref: str?, purchase_order: str, contract_ref: str?, billing_account: str, role_assignments: [str], id: str, mode: str, lacp_timeout: str?, product_offering: str, name: str, ports: [str], port_reservations: [str], pop: str, speed: int?, capacity_allocated: int, capacity_allocation_limit: int?, vlan_types: [str], outer_vlan_ethertypes: [str], port_quantity: int, subscriber_side_demarcs: [str], metro_area: str, metro_area_network: str} # **Connection**
@errors {400: CancellationPolicyError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /connections/{id}/statistics
@desc Read Statistics
@required {id: str # Get by id}
@optional {start: str(date-time) # Beginning of the traffic aggregation., end: str(date-time) # End of the traffic aggregation. Default is `now`.}
@returns(200) {aggregates: map} # **Mapping of Aggregated Statistics**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /connections/{id}/statistics/{aggregate}/timeseries
@desc Read Statistics Timeseries
@required {id: str # Get by id, aggregate: str # Get by aggregate}
@optional {start: str(date-time) # Start of the timeseries., end: str(date-time) # End of the timeseries.  Default: `now`, fields: str # Select fields from the aggregates to export as a timeseries.  Default: `average_pps_in,average_pps_out,average_ops_in,average_ops_out`}
@returns(200) {title: str, precision: int, created_at: str(date-time), next_update_at: str(date-time), origin_timezone: str, fields: [str], samples: [[any]]} # **Aggregated Statistics Timeseries**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /connections/{id}/loa
@desc Download LOA
@required {id: str # Get by id}
@returns(200) A Letter Of Authorization
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint POST /connections/{id}/loa
@desc Upload LOA
@required {id: str # Get by id}
@returns(200) The upload was successful
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /connections/{id}/cancellation-policy
@desc Read Cancellation Policy
@required {id: str # Get by id}
@optional {decommission_at: str # By providing a date in the format `YYYY-MM-DD` you can query the policy what would happen if you request a decommissioning on this date.}
@returns(200) {decommission_at: str(date), charged_until: str(date)} # **Cancellation Policy**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group network-service-configs
@endpoint GET /network-service-configs
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), state: str # Filter by state, state__is_not: str # Filter by state__is_not, managing_account: str # Filter by the ID of the managing [account](#tag/accounts)., consuming_account: str # Filter by the ID of the consuming [account](#tag/accounts)., external_ref: str # Filter by external_ref, type: str(exchange_lan/p2p_vc/p2mp_vc/mp2mp_vc/cloud_vc) # Filter by type, inner_vlan: int # Filter by inner_vlan, outer_vlan: int # Filter by outer_vlan, capacity: int # Filter by capacity, network_service: str # Filter by network_service, connection: str # Filter by connection, product_offering: str # Filter by product_offering, role_assignments: [str] # Filter by role_assignments, contacts: [str] # Filter by contacts}
@returns(200) List of: **Polymorphic Network Service Config**
@returns(206) Paginated List of: **Polymorphic Network Service Config**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /network-service-configs
@desc Create
@required {type: str}
@returns(201) {type: str} # **Polymorphic Network Service Config**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /network-service-configs/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {type: str} # **Polymorphic Network Service Config**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PUT /network-service-configs/{id}
@desc Update (Deprecated)
@required {id: str # Get by id, type: str}
@returns(202) {type: str} # **Polymorphic Network Service Config**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PATCH /network-service-configs/{id}
@desc Update
@required {id: str # Get by id}
@returns(202) {type: str} # **Polymorphic Network Service Config**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint DELETE /network-service-configs/{id}
@desc Request Decommission
@required {id: str # Get by id}
@optional {decommission_at: str(date) # An optional date for scheduling the cancellation and service decommissioning.}
@returns(202) {type: str} # **Polymorphic Network Service Config**
@errors {400: CancellationPolicyError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /network-service-configs/{id}/statistics
@desc Read Statistics
@required {id: str # Get by id}
@optional {start: str(date-time) # Beginning of the traffic aggregation., end: str(date-time) # End of the traffic aggregation. Default is `now`.}
@returns(200) {aggregates: map} # **Statistics for NetworkServiceConfig**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /network-service-configs/{id}/statistics/{aggregate}/timeseries
@desc Read Statistics Timeseries
@required {id: str # Get by id, aggregate: str # Get by aggregate}
@optional {start: str(date-time) # Start of the timeseries., end: str(date-time) # End of the timeseries.  Default: `now`, fields: str # Select fields from the aggregates to export as a timeseries.  Default: `average_pps_in,average_pps_out,average_ops_in,average_ops_out`}
@returns(200) {title: str, precision: int, created_at: str(date-time), next_update_at: str(date-time), origin_timezone: str, fields: [str], samples: [[any]]} # **Aggregated Statistics Timeseries**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /network-service-configs/{id}/peer-statistics
@desc Read Peer Statistics
@required {id: str # Get by id}
@optional {start: str(date-time) # Beginning of the traffic aggregation., end: str(date-time) # End of the traffic aggregation. Default is `now`., asn: int # Filter by asn, mac_address: str # Filter by mac_address, ip_address: str # Filter by ip_address, ip_version: int # Filter by ip_version}
@returns(200) List of: **PeerStatistics**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /network-service-configs/{id}/peer-statistics/{aggregate}/timeseries
@desc Read Peer Statistics Timeseries
@required {id: str # Get by id, aggregate: str # Get by aggregate}
@optional {start: str(date-time) # Start of the timeseries., end: str(date-time) # End of the timeseries.  Default: `now`, fields: str # Select fields from the aggregates to export as a timeseries.  Default: `average_pps_in,average_pps_out,average_ops_in,average_ops_out`, asn: int # Filter by asn, mac_address: str # Filter by mac_address, ip_address: str # Filter by ip_address, ip_version: int # Filter by ip_version}
@returns(200) List of: **PeerStatistics Timeseries**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /network-service-configs/{id}/cancellation-policy
@desc Read Cancellation Policy
@required {id: str # Get by id}
@optional {decommission_at: str # By providing a date in the format `YYYY-MM-DD` you can query the policy what would happen if you request a decommissioning on this date.}
@returns(200) {decommission_at: str(date), charged_until: str(date)} # **Cancellation Policy**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group network-feature-configs
@endpoint GET /network-feature-configs
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), state: str # Filter by state, state__is_not: str # Filter by state__is_not, managing_account: str # Filter by the ID of the managing [account](#tag/accounts)., consuming_account: str # Filter by the ID of the consuming [account](#tag/accounts)., external_ref: str # Filter by external_ref, type: str # Filter by type, service_config: str # Filter by the id of the NetworkServiceConfig the feature configuration is related to.  **DEPRECATION NOTICE**: Use `network_service_config` instead., network_service_config: str # Filter by the id of the NetworkServiceConfig the feature configuration is related to., network_feature: str # Filter by network_feature, role_assignments: [str] # Filter by role_assignments, contacts: [str] # Filter by contacts}
@returns(200) List of: **Polymorphic Network Feature Config**
@returns(206) Paginated List of: **Polymorphic Network Feature Config**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /network-feature-configs
@desc Create
@required {type: str}
@returns(201) {type: str} # **Polymorphic Network Feature Config**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /network-feature-configs/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {type: str} # **Polymorphic Network Feature Config**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PUT /network-feature-configs/{id}
@desc Update (Deprecated)
@required {id: str # Get by id, type: str}
@returns(202) {type: str} # **Polymorphic Network Feature Config**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PATCH /network-feature-configs/{id}
@desc Update
@required {id: str # Get by id}
@returns(202) {type: str} # **Polymorphic Network Feature Config**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint DELETE /network-feature-configs/{id}
@desc Request Decommission
@required {id: str # Get by id}
@returns(202) {type: str} # **Polymorphic Network Feature Config**
@errors {400: UnableToFulfill, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group account
@endpoint GET /account
@desc Read
@returns(200) {state: str, status: [map], id: str, managing_account: str?, name: str, legal_name: str?, billing_information: map{name: str, address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, vat_number: str?}, external_ref: str?, discoverable: bool, metro_area_network_presence: [str], address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, asns: [int]} # **Account**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group accounts
@endpoint GET /accounts
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), state: str # Filter by state, state__is_not: str # Filter by state__is_not, managing_account: str # Filter by managing_account, billable: int # Filter by billable, external_ref: str # Filter by external_ref, name: str # Filter by name, asn: int # Filter by asn}
@returns(200) List of: **Account**
@returns(206) Paginated List of: **Account**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /accounts
@desc Create
@required {id: str # The *primary identifier* of the `Account Request`., name: str # Name of the account, how it gets represented in e.g. a "customers list"., address: map{country!: str, locality!: str, region: str, postal_code!: str, street_address!: str, post_office_box_number: str} # A postal address. *(Sensitive Property)*}
@optional {managing_account: str # The `id` of a managing account. Can be used for creating a customer hierachy. *(Sensitive Property)*, legal_name: str # Legal name of the organisation. Only required when it's different from the account name. *(Sensitive Property)*, billing_information: map{name!: str, address!: map, vat_number: str} # Optional information required for issuing invoices. Only accounts with `billing_information` present can be used as a `billing_account`. *(Sensitive Property)*, external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, discoverable: bool=false # The account will be included for all members of the ix in the list of accounts.  Only `id`, `name` and `present_in_metro_area_networks` are provided to other members., metro_area_network_presence: [str]= # Informal list of `MetroAreaNetwork` ids, indicating the presence to other accounts. The list is maintained by the account and can be empty.}
@returns(201) {state: str, status: [map], id: str, managing_account: str?, name: str, legal_name: str?, billing_information: map{name: str, address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, vat_number: str?}, external_ref: str?, discoverable: bool, metro_area_network_presence: [str], address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, asns: [int]} # **Account**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /accounts/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {state: str, status: [map], id: str, managing_account: str?, name: str, legal_name: str?, billing_information: map{name: str, address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, vat_number: str?}, external_ref: str?, discoverable: bool, metro_area_network_presence: [str], address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, asns: [int]} # **Account**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PUT /accounts/{id}
@desc Update (Deprecated)
@required {id: str # Get by id, id: str # The *primary identifier* of the `Account Update`., name: str # Name of the account, how it gets represented in e.g. a "customers list"., metro_area_network_presence: [str] # Informal list of `MetroAreaNetwork` ids, indicating the presence to other accounts. The list is maintained by the account and can be empty., address: map{country!: str, locality!: str, region: str, postal_code!: str, street_address!: str, post_office_box_number: str} # A postal address. *(Sensitive Property)*}
@optional {managing_account: str # The `id` of a managing account. Can be used for creating a customer hierachy. *(Sensitive Property)*, legal_name: str # Legal name of the organisation. Only required when it's different from the account name. *(Sensitive Property)*, billing_information: map{name!: str, address!: map, vat_number: str} # Optional information required for issuing invoices. Only accounts with `billing_information` present can be used as a `billing_account`. *(Sensitive Property)*, external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, discoverable: bool=false # The account will be included for all members of the ix in the list of accounts.  Only `id`, `name` and `present_in_metro_area_networks` are provided to other members.}
@returns(202) {state: str, status: [map], id: str, managing_account: str?, name: str, legal_name: str?, billing_information: map{name: str, address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, vat_number: str?}, external_ref: str?, discoverable: bool, metro_area_network_presence: [str], address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, asns: [int]} # **Account**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PATCH /accounts/{id}
@desc Update
@required {id: str # Get by id}
@returns(202) {state: str, status: [map], id: str, managing_account: str?, name: str, legal_name: str?, billing_information: map{name: str, address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, vat_number: str?}, external_ref: str?, discoverable: bool, metro_area_network_presence: [str], address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, asns: [int]} # **Account**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint DELETE /accounts/{id}
@desc Destroy
@required {id: str # Get by id}
@returns(200) {state: str, status: [map], id: str, managing_account: str?, name: str, legal_name: str?, billing_information: map{name: str, address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, vat_number: str?}, external_ref: str?, discoverable: bool, metro_area_network_presence: [str], address: map{country: str, locality: str, region: str?, postal_code: str, street_address: str, post_office_box_number: str?}, asns: [int]} # **Account**
@errors {400: UnableToFulfill, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group roles
@endpoint GET /roles
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), name: str # Filter by name, contact: str # Filter by contact}
@returns(200) List of: **Role for a Contact**
@returns(206) Paginated List of: **Role for a Contact**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /roles/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {name: str, required_fields: [str], id: str} # **Role for a Contact**
@errors {401: Authentication}

@endgroup

@group contacts
@endpoint GET /contacts
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), managing_account: str # Filter by the ID of the managing [account](#tag/accounts)., consuming_account: str # Filter by the ID of the consuming [account](#tag/accounts)., external_ref: str # Filter by external_ref}
@returns(200) List of: **Contact**
@returns(206) Paginated List of: **Contact**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /contacts
@desc Create
@required {managing_account: str # The `id` of the account responsible for managing the service via the API. A manager can read and update the state of entities. *(Sensitive Property)*, consuming_account: str # The `id` of the account consuming a service.  Used to be `owning_customer`. *(Sensitive Property)*, id: str # The *primary identifier* of the `Contact Create Request`.}
@optional {external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, name: str # A name of a person or an organisation, telephone: str # The telephone number in E.164 Phone Number Formatting, email: str # The email of the legal company entity.}
@returns(201) {managing_account: str, consuming_account: str, external_ref: str?, id: str, name: str?, telephone: str?, email: str?} # **Contact**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /contacts/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {managing_account: str, consuming_account: str, external_ref: str?, id: str, name: str?, telephone: str?, email: str?} # **Contact**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PUT /contacts/{id}
@desc Update (Deprecated)
@required {id: str # Get by id, managing_account: str # The `id` of the account responsible for managing the service via the API. A manager can read and update the state of entities. *(Sensitive Property)*, consuming_account: str # The `id` of the account consuming a service.  Used to be `owning_customer`. *(Sensitive Property)*, id: str # The *primary identifier* of the `Contact Update`.}
@optional {external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, name: str # A name of a person or an organisation, telephone: str # The telephone number in E.164 Phone Number Formatting, email: str # The email of the legal company entity.}
@returns(200) {managing_account: str, consuming_account: str, external_ref: str?, id: str, name: str?, telephone: str?, email: str?} # **Contact**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PATCH /contacts/{id}
@desc Update
@required {id: str # Get by id}
@returns(200) {managing_account: str, consuming_account: str, external_ref: str?, id: str, name: str?, telephone: str?, email: str?} # **Contact**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint DELETE /contacts/{id}
@desc Destroy
@required {id: str # Get by id}
@returns(200) {managing_account: str, consuming_account: str, external_ref: str?, id: str, name: str?, telephone: str?, email: str?} # **Contact**
@errors {400: UnableToFulfill, 401: Authentication, 403: PermissionDenied, 404: NotFound, 409: ConstraintViolation}

@endgroup

@group role-assignments
@endpoint GET /role-assignments
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), contact: str # Filter by contact, role: str # Filter by role}
@returns(200) List of: **A role assignment for a contact**
@returns(206) Paginated List of: **A role assignment for a contact**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /role-assignments
@desc Create
@required {role: str # The `id` of a role the contact is assigned to., contact: str # The `id` of a contact the role is assigned to.}
@returns(201) {role: str, contact: str, id: str} # **A role assignment for a contact**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /role-assignments/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {role: str, contact: str, id: str} # **A role assignment for a contact**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint DELETE /role-assignments/{id}
@desc Destroy
@required {id: str # Get by id}
@returns(200) {role: str, contact: str, id: str} # **A role assignment for a contact**
@errors {400: UnableToFulfill, 401: Authentication, 403: PermissionDenied, 404: NotFound, 409: ConstraintViolation}

@endgroup

@group health
@endpoint GET /health
@desc Read
@returns(200) {status: str, version: str, releaseId: str, notes: [str], output: str, serviceId: str, description: str, checks: map, links: map} # **Health Status Response**

@endgroup

@group implementation
@endpoint GET /implementation
@desc Read
@returns(200) {schema_version: str, service_version: str, supported_network_service_types: [str], supported_network_service_config_types: [str], supported_network_feature_types: [str], supported_network_feature_config_types: [str], supported_operations: [str], supported_features: map{pagination: bool}} # **API Implementation**

@endgroup

@group extensions
@endpoint GET /extensions
@desc List (Query)
@optional {page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination)}
@returns(200) List of: **Implementation specific API extensions**
@returns(206) Paginated List of: **Implementation specific API extensions**
@errors {400: ValidationError}

@endgroup

@group ips
@endpoint GET /ips
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), managing_account: str # Filter by the ID of the managing [account](#tag/accounts)., consuming_account: str # Filter by the ID of the consuming [account](#tag/accounts)., external_ref: str # Filter by external_ref, network_service: str # Filter by network_service, network_service_config: str # Filter by network_service_config, network_feature: str # Filter by network_feature, network_feature_config: str # Filter by network_feature_config, version: int # Filter by version, fqdn: str # Filter by fqdn, prefix_length: int # Filter by prefix_length, valid_not_before: str # Filter by valid_not_before, valid_not_after: str # Filter by valid_not_after}
@returns(200) List of: **IP-Address**
@returns(206) Paginated List of: **IP-Address**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /ips
@desc Create
@required {managing_account: str # The `id` of the account responsible for managing the service via the API. A manager can read and update the state of entities. *(Sensitive Property)*, consuming_account: str # The `id` of the account consuming a service.  Used to be `owning_customer`. *(Sensitive Property)*, id: str # The *primary identifier* of the `IP-Address / Prefix allocation Request`., version: int(4/6) # The version of the internet protocol., address: str # IPv4 or IPv6 Address in the following format: - IPv4: [dot-decimal notation](https://en.wikipedia.org/wiki/Dot-decimal_notation) - IPv6: hexadecimal colon separated notation, prefix_length: int(int32) # The CIDR ip prefix length}
@optional {external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, fqdn: str, valid_not_before: str(date-time), valid_not_after: str(date-time)}
@returns(201) {managing_account: str, consuming_account: str, external_ref: str?, id: str, version: int, address: str, prefix_length: int(int32), fqdn: str?, valid_not_before: str(date-time)?, valid_not_after: str(date-time)?} # **IP-Address**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /ips/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {managing_account: str, consuming_account: str, external_ref: str?, id: str, version: int, address: str, prefix_length: int(int32), fqdn: str?, valid_not_before: str(date-time)?, valid_not_after: str(date-time)?} # **IP-Address**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PUT /ips/{id}
@desc Update
@required {id: str # Get by id, managing_account: str # The `id` of the account responsible for managing the service via the API. A manager can read and update the state of entities. *(Sensitive Property)*, consuming_account: str # The `id` of the account consuming a service.  Used to be `owning_customer`. *(Sensitive Property)*, id: str # The *primary identifier* of the `IP-Address Update`., version: int(4/6) # The version of the internet protocol., address: str # IPv4 or IPv6 Address in the following format: - IPv4: [dot-decimal notation](https://en.wikipedia.org/wiki/Dot-decimal_notation) - IPv6: hexadecimal colon separated notation, prefix_length: int(int32) # The CIDR ip prefix length}
@optional {external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, fqdn: str, valid_not_before: str(date-time), valid_not_after: str(date-time)}
@returns(200) {managing_account: str, consuming_account: str, external_ref: str?, id: str, version: int, address: str, prefix_length: int(int32), fqdn: str?, valid_not_before: str(date-time)?, valid_not_after: str(date-time)?} # **IP-Address**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PATCH /ips/{id}
@desc Update
@required {id: str # Get by id}
@returns(200) {managing_account: str, consuming_account: str, external_ref: str?, id: str, version: int, address: str, prefix_length: int(int32), fqdn: str?, valid_not_before: str(date-time)?, valid_not_after: str(date-time)?} # **IP-Address**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group macs
@endpoint GET /macs
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), managing_account: str # Filter by the ID of the managing [account](#tag/accounts)., consuming_account: str # Filter by the ID of the consuming [account](#tag/accounts)., external_ref: str # Filter by external_ref, network_service_config: str # Filter by network_service_config, address: str # Filter by address, valid_not_before: str # Filter by valid_not_before, valid_not_after: str # Filter by valid_not_after}
@returns(200) List of: **MAC-Address**
@returns(206) Paginated List of: **MAC-Address**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /macs
@desc Create
@required {managing_account: str # The `id` of the account responsible for managing the service via the API. A manager can read and update the state of entities. *(Sensitive Property)*, consuming_account: str # The `id` of the account consuming a service.  Used to be `owning_customer`. *(Sensitive Property)*, id: str # The *primary identifier* of the `MAC-Address Request`., address: str # Unicast MAC address, formatted hexadecimal values with colons.}
@optional {external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, valid_not_before: str(date-time) # When a mac address is assigned to a NSC, and the current datetime is before this value, then the MAC address *cannot* be used on the peering platform.  Afterwards, it is supposed to be available. If the value is `null` or the property does not exist, the mac address is valid from the creation date., valid_not_after: str(date-time) # When a mac address is assigned to an NSC, and the current datetime is before this value, the MAC address *can* be used on the peering platform.  Afterwards, it is supposed to be unassigned from the NSC and cannot any longer be used on the peering platform.  If the value is null or the property does not exist, the MAC address is valid indefinitely. The value may not be in the past.}
@returns(201) {managing_account: str, consuming_account: str, external_ref: str?, id: str, address: str, valid_not_before: str(date-time)?, valid_not_after: str(date-time)?} # **MAC-Address**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /macs/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {managing_account: str, consuming_account: str, external_ref: str?, id: str, address: str, valid_not_before: str(date-time)?, valid_not_after: str(date-time)?} # **MAC-Address**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint DELETE /macs/{id}
@desc Destroy
@required {id: str # Get by id}
@returns(200) {managing_account: str, consuming_account: str, external_ref: str?, id: str, address: str, valid_not_before: str(date-time)?, valid_not_after: str(date-time)?} # **MAC-Address**
@errors {400: UnableToFulfill, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group network-services
@endpoint GET /network-services
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), state: str # Filter by state, state__is_not: str # Filter by state__is_not, managing_account: str # Filter by the ID of the managing [account](#tag/accounts)., consuming_account: str # Filter by the ID of the consuming [account](#tag/accounts)., external_ref: str # Filter by external_ref, type: str(exchange_lan/p2p_vc/p2mp_vc/mp2mp_vc/cloud_vc) # Filter by type, pop: str # Filter by pop, product_offering: str # Filter by product_offering}
@returns(200) List of: **Polymorphic Network Services**
@returns(206) Paginated List of: **Polymorphic Network Services**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /network-services
@desc Create
@required {type: str}
@returns(201) {type: str} # **Polymorphic Network Services**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /network-services/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {type: str} # **Polymorphic Network Services**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PUT /network-services/{id}
@desc Update (Deprecated)
@required {id: str # Get by id, type: str}
@returns(202) {type: str} # **Polymorphic Network Services**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PATCH /network-services/{id}
@desc Update
@required {id: str # Get by id}
@returns(202) {type: str} # **Polymorphic Network Services**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint DELETE /network-services/{id}
@desc Request Decommission
@required {id: str # Get by id}
@optional {decommission_at: str(date) # An optional date for scheduling the cancellation and service decommissioning.}
@returns(202) {type: str} # **Polymorphic Network Services**
@errors {400: CancellationPolicyError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /network-services/{id}/statistics
@desc Read Statistics
@required {id: str # Get by id}
@optional {start: str(date-time) # Beginning of the traffic aggregation., end: str(date-time) # End of the traffic aggregation. Default is `now`.}
@returns(200) {aggregates: map} # **Mapping of Aggregated Statistics**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /network-services/{id}/statistics/{aggregate}/timeseries
@desc Read Statistics Timeseries
@required {id: str # Get by id, aggregate: str # Get by aggregate}
@optional {start: str(date-time) # Start of the timeseries., end: str(date-time) # End of the timeseries.  Default: `now`, fields: str # Select fields from the aggregates to export as a timeseries.  Default: `average_pps_in,average_pps_out,average_ops_in,average_ops_out`}
@returns(200) {title: str, precision: int, created_at: str(date-time), next_update_at: str(date-time), origin_timezone: str, fields: [str], samples: [[any]]} # **Aggregated Statistics Timeseries**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /network-services/{id}/rtt-statistics
@desc Read RTT Statistics
@required {id: str # Get by id}
@optional {asn: str # Show only results from this `ASN`., ip: str # Show only results from this `IP`., after: int # Show only results with a `serial` greater than `after`.}
@returns(200) List of: **Peer RTT Statistics**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /network-services/{id}/change-request
@desc Read Change Request
@required {id: str # Get by id}
@returns(202) {product_offering: str, capacity: int?} # **NetworkServiceChangeRequest**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint POST /network-services/{id}/change-request
@desc Create Change Request
@required {id: str # Get by id, product_offering: str # Migrate to a diffrent product offering. Please note, that the offering only may differ in bandwidth.}
@optional {capacity: int # The desired capacity of the service in Mbps.  Must be within the range of `bandwidth_min` and `bandwidth_max` of the `ProductOffering`.  When `null` the maximum capacity wil be used.}
@returns(202) {product_offering: str, capacity: int?} # **NetworkServiceChangeRequest**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint DELETE /network-services/{id}/change-request
@desc Delete Change Request
@required {id: str # Get by id}
@returns(202) {product_offering: str, capacity: int?} # **NetworkServiceChangeRequest**
@errors {400: UnableToFulfill, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /network-services/{id}/cancellation-policy
@desc Read Cancellation Policy
@required {id: str # Get by id}
@optional {decommission_at: str # By providing a date in the format `YYYY-MM-DD` you can query the policy what would happen if you request a decommissioning on this date.}
@returns(200) {decommission_at: str(date), charged_until: str(date)} # **Cancellation Policy**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group network-features
@endpoint GET /network-features
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), type: str # Filter by type, required: str # Filter by required, network_service: str # Filter by network_service, name: str # Filter by name}
@returns(200) List of: **Polymorphic Network Feature**
@returns(206) Paginated List of: **Polymorphic Network Feature**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /network-features/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {type: str} # **Polymorphic Network Feature**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group member-joining-rules
@endpoint GET /member-joining-rules
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), managing_account: str # Filter by the ID of the managing [account](#tag/accounts)., consuming_account: str # Filter by the ID of the consuming [account](#tag/accounts)., external_ref: str # Filter by external_ref, network_service: str # Filter by network_service}
@returns(200) List of: **Polymorphic Member Joining Rule**
@returns(206) Paginated List of: **Polymorphic Member Joining Rule**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /member-joining-rules
@desc Create
@required {type: str}
@returns(201) {type: str} # **Polymorphic Member Joining Rule**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /member-joining-rules/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {type: str} # **Polymorphic Member Joining Rule**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PUT /member-joining-rules/{id}
@desc Update (Deprecated)
@required {id: str # Get by id, type: str}
@returns(200) {type: str} # **Polymorphic Member Joining Rule**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PATCH /member-joining-rules/{id}
@desc Update
@required {id: str # Get by id}
@returns(200) {type: str} # **Polymorphic Member Joining Rule**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint DELETE /member-joining-rules/{id}
@desc Destroy
@required {id: str # Get by id}
@returns(200) {type: str} # **Polymorphic Member Joining Rule**
@errors {400: UnableToFulfill, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@group routing-functions
@endpoint GET /routing-functions
@desc List (Query)
@optional {id: [str] # Filter by id, page_limit: int # The maximum number of items in the response. [*(Pagination)*](#section/Pagination), page_offset: int # The offset of the first item in the response. [*(Pagination)*](#section/Pagination), page_token: str # The pagination token from the initial response. [*(Pagination)*](#section/Pagination), state: str # Filter by state, state__is_not: str # Filter by state__is_not, managing_account: str # Filter by the ID of the managing [account](#tag/accounts)., consuming_account: str # Filter by the ID of the consuming [account](#tag/accounts)., external_ref: str # Filter by external_ref, asn: str # Filter by asn}
@returns(200) List of: **Routing Function**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint POST /routing-functions
@desc Create
@required {managing_account: str # The `id` of the account responsible for managing the service via the API. A manager can read and update the state of entities. *(Sensitive Property)*, consuming_account: str # The `id` of the account consuming a service.  Used to be `owning_customer`. *(Sensitive Property)*, billing_account: str # An account requires billing_information to be used as a `billing_account`. *(Sensitive Property)*, id: str # The *primary identifier* of the `Routing Function Request`., product_offering: str # The product offering to be used for the routing function., asn: int # Any routing function instance needs to be assigned a 2-byte or 4-byte ASN of the customer's choice. There is no restriction on private or public ASNs.}
@optional {external_ref: str # Reference field, free to use for the API user. *(Sensitive Property)*, purchase_order: str= # Purchase Order ID which will be displayed on the invoice. *(Sensitive Property)*, contract_ref: str # A reference to a contract. If no specific contract is used, a default MAY be chosen by the implementer. *(Sensitive Property)*, capacity: int # The desired upper bound of the capacity for the routing function.}
@returns(201) {state: str, status: [map], managing_account: str, consuming_account: str, external_ref: str?, purchase_order: str, contract_ref: str?, billing_account: str, id: str, product_offering: str, asn: int, capacity: int?} # **Routing Function**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied}

@endpoint GET /routing-functions/{id}
@desc Read
@required {id: str # Get by id}
@returns(200) {state: str, status: [map], managing_account: str, consuming_account: str, external_ref: str?, purchase_order: str, contract_ref: str?, billing_account: str, id: str, product_offering: str, asn: int, capacity: int?} # **Routing Function**
@errors {401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint PATCH /routing-functions/{id}
@desc Update
@required {id: str # Get by id}
@returns(200) {state: str, status: [map], managing_account: str, consuming_account: str, external_ref: str?, purchase_order: str, contract_ref: str?, billing_account: str, id: str, product_offering: str, asn: int, capacity: int?} # **Routing Function**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint DELETE /routing-functions/{id}
@desc Request Decommission
@required {id: str # Get by id}
@optional {decommission_at: str(date) # An optional date for scheduling the cancellation and service decommissioning.}
@returns(202) {state: str, status: [map], managing_account: str, consuming_account: str, external_ref: str?, purchase_order: str, contract_ref: str?, billing_account: str, id: str, product_offering: str, asn: int, capacity: int?} # **Routing Function**
@errors {400: CancellationPolicyError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endpoint GET /routing-functions/{id}/cancellation-policy
@desc Read Cancellation Policy
@required {id: str # Get by id}
@optional {decommission_at: str # By providing a date in the format `YYYY-MM-DD` you can query the policy what would happen if you request a decommissioning on this date.}
@returns(200) {decommission_at: str(date), charged_until: str(date)} # **Cancellation Policy**
@errors {400: ValidationError, 401: Authentication, 403: PermissionDenied, 404: NotFound}

@endgroup

@end