openapi: 3.2.0 info: title: 'Forward Networks: Complete Aliases Network Snapshots API' description: Model and verify networks contact: email: support@forwardnetworks.com license: name: MIT url: https://spdx.org/licenses/MIT version: '26.6' servers: - url: /api tags: - name: Network Snapshots description: List or manage the network Snapshots collected from network devices summary: Network Snapshots paths: /networks/{networkId}/snapshots: get: tags: - Network Snapshots summary: List all Snapshots operationId: listNetworkSnapshots parameters: - name: networkId in: path required: true schema: type: string - name: state in: query description: List only Snapshots in this state. schema: $ref: '#/components/schemas/SnapshotState' - name: minSuccessfulDevices in: query description: List only Snapshots with at least this many successfully modeled devices. schema: type: integer format: int32 - name: minSuccessfulDevicePct in: query description: List only Snapshots with at least this percentage of devices successfully modeled. schema: type: number format: double - name: maxCollectionFailureDevices in: query description: List only Snapshots with no more than this many devices from which collection has failed. schema: type: integer format: int32 - name: maxCollectionFailureDevicePct in: query description: 'List only Snapshots with no more than this percentage of devices from which collection has failed.' schema: type: number format: double - name: maxParsingFailureDevices in: query description: 'List only Snapshots with no more than this many devices for which parsing of collected data has failed.' schema: type: integer format: int32 - name: maxParsingFailureDevicePct in: query description: 'List only Snapshots with no more than this percentage of devices for which parsing of collected data has failed.' schema: type: number format: double - name: limit in: query description: Maximum number of Snapshots desired schema: type: integer format: int32 - name: includeArchived in: query description: Also include archived snapshots. Defaults to false if not provided. schema: type: boolean default: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/NetworkSnapshots' security: - api_token: [] post: tags: - Network Snapshots summary: Import a Snapshot description: 'Imports a network Snapshot that was previously exported as a .zip file. If multiple Snapshot .zip files are uploaded in a single request, they will be merged. They must not have any devices in common.' operationId: createSnapshot parameters: - name: networkId in: path required: true schema: type: string requestBody: content: multipart/form-data: schema: type: object required: - file properties: file: type: array items: type: string format: binary note: type: string required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SnapshotInfo' security: - api_token: [] /networks/{networkId}/snapshots/latestProcessed: get: tags: - Network Snapshots summary: Get the latest processed Snapshot description: 'Returns the latest processed Snapshot (the most recent one that''s currently prepared for [path searches](https://docs.fwd.app/latest/api/path-search/) and [new checks](https://docs.fwd.app/latest/api/checks/)). Triggers processing of the latest Snapshot if it''s not already underway and the network has no processed Snapshots.' operationId: getLatestProcessedSnapshot parameters: - name: networkId in: path required: true schema: type: string responses: '200': description: Processing is complete for the identified Snapshot. content: application/json: schema: $ref: '#/components/schemas/SnapshotInfo' '404': description: The network has no Snapshots. content: {} '409': description: 'None of the Snapshots in the network are processed. Processing of the latest Snapshot has begun.' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' security: - api_token: [] /snapshots/{snapshotId}: get: tags: - Network Snapshots summary: Export a Snapshot description: Exports a network Snapshot as a .zip file. operationId: exportSnapshot parameters: - name: snapshotId in: path required: true schema: type: string - name: only in: query description: Use `?only=CONFIG` to include only device configuration files. schema: type: string const: CONFIG responses: '200': description: OK content: {} security: - api_token: [] post: tags: - Network Snapshots summary: Export a Snapshot subset description: 'Exports a network Snapshot as a .zip file, optionally limiting which devices are included and optionally [obfuscating](https://docs.fwd.app/latest/application/settings/system/obfuscate-snapshot/) sensitive data. To limit which devices are included, specify either `"includeDevices"` or `"excludeDevices"`. To obfuscate, specify an `"obfuscationKey"`.' operationId: exportSnapshotSubset parameters: - name: snapshotId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SnapshotExportParams' required: true responses: '200': description: OK content: {} security: - api_token: [] delete: tags: - Network Snapshots summary: Delete a Snapshot operationId: deleteSnapshot parameters: - name: snapshotId in: path required: true schema: type: string responses: '200': description: OK content: application/json: schema: type: object security: - api_token: [] /snapshots/{snapshotId}?action=computeAdvancedReachability: post: tags: - Network Snapshots summary: Trigger advanced reachability computation description: 'Requests advanced reachability computation for a Snapshot. The computation runs asynchronously; this endpoint returns immediately. The Snapshot must have completed the reachability processing stage.' operationId: computeAdvancedReachability parameters: - name: snapshotId in: path required: true schema: type: string responses: '204': description: Success content: {} '404': description: The Snapshot was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' '409': description: Prerequisite Snapshot processing has not yet completed. content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' security: - api_token: [] /snapshots/{snapshotId}/metrics: get: tags: - Network Snapshots summary: Get Snapshot metrics description: Returns collection and processing health metrics of a Snapshot. operationId: getSnapshotMetrics parameters: - name: snapshotId in: path required: true schema: type: string responses: '200': description: Successfully retrieved metrics for the Snapshot. content: application/json: schema: $ref: '#/components/schemas/SnapshotMetrics' '404': description: 'The Snapshot was not found or its metrics were not found; the health metrics will be recomputed if the Snapshot is reprocessed.' content: {} security: - api_token: [] components: schemas: Network: type: object required: - id - name - orgId properties: id: type: string parentId: type: string description: 'The network from which this Workspace network was created. Absent if this network is not a Workspace.' name: type: string examples: - My Network orgId: type: string creator: type: string description: The username of the user who created the network, or null if the account was deleted examples: - mary creatorId: type: string description: The id of the user who created the network, or null if the account was deleted examples: - '123' createdAt: type: string examples: - '2022-04-06T20:34:45.118Z' created: type: string description: Deprecated for removal in release 26.7. Use `createdAt` instead. examples: - '2022-04-06T20:34:45.118Z' note: type: string description: An optional network description. retentionDays: type: integer format: int32 minimum: 1 maximum: 365 description: 'The number of days without any use of this network after which it will be automatically deleted. Absent for parent networks and permanent Workspace networks.' secondsToExpiry: type: integer format: int64 description: 'Number of seconds without use before the network expires. Present for temporary Workspace networks only.' NetworkSnapshots: allOf: - $ref: '#/components/schemas/Network' - type: object required: - snapshots properties: snapshots: type: array items: $ref: '#/components/schemas/SnapshotInfo' SnapshotMetrics: type: object properties: collectionConcurrency: type: integer format: int32 examples: - 16 collectionDuration: type: integer format: int64 examples: - 1234 createdAt: type: string examples: - '2022-04-06T20:34:45.118Z' deviceCollectionFailures: type: object additionalProperties: type: integer format: int32 description: 'Possible device error types during collection *UNKNOWN*: Unknown error *CONNECTION_TIMEOUT*: Connection to device timed out *CONNECTION_REFUSED*: Connection to device refused *AUTHENTICATION_FAILED*: Authentication failed *KEY_EXCHANGE_FAILED*: Key exchange failed *AUTHORIZATION_FAILED*: Authorization failed *AVI_SHELL_AUTH_FAILED*: Avi authentication failed *AVI_CONTROLLER_WITHOUT_HEALTHY_SERVICE_ENGINES*: No Avi Service Engines found *NETWORK_UNREACHABLE*: Network not reachable *IO_ERROR*: I/O error *SESSION_CLOSED*: Session closed unexpectedly *STATE_COLLECTION_FAILED*: State collection failed *JUMP_SERVER_CONNECTION_TIMEOUT*: Jump server timed out *JUMP_SERVER_PASSWORD_AUTH_FAILED*: Jump server auth failed *JUMP_SERVER_CONNECTION_FAILED*: Jump server connection refused *JUMP_SERVER_KEY_EXCHANGE_FAILED*: Jump server key exchange failed *PROXY_SERVER_PING_FAILED*: Proxy ping failed *PROXY_SERVER_PORT_REACHABILITY_FAILED*: Proxy port not reachable *PROXY_SERVER_CONNECTION_FAILED*: Proxy connection refused *PROXY_SERVER_AUTHENTICATION_FAILED*: Proxy authentication failed *PRIV_PASSWORD_ERROR*: Privileged password failed *UNSUPPORTED_VERSION*: Unsupported version *DEVICE_TYPE_UNDETECTED*: Undetected device type *WARN_TYPE_MISMATCH*: Device type mismatch *DEVICE_IS_CHILD_CONTEXT*: Parent context required *MANAGER_COLLECTOR_NOT_FOUND*: Collector manager error *INCOMPLETE_SETUP*: Incomplete setup *COLLECTION_NOT_FOUND*: Collection not found *INFINITE_LOOP_IN_COMMAND_OUTPUT*: Collection stuck in loop *MISSING_FILE*: File is missing *UNSUPPORTED_VENDOR*: Vendor not supported *COMMAND_DISABLED*: Required command is disabled *APIC_CONFIG_COLLECTION_FAILED*: APIC config collection failed *UNEXPECTED_KEY_EXCHANGE_MESSAGE*: Unexpected Key-Exchange message *UNDISCOVERED_ACI_FABRIC*: ACI fabric node was not discovered by APIC *SLOW_READ_RATE_DETECTED*: Read rate from the remote peer is too low *COLLECTION_TIMED_OUT*: Collection timed out *COLLECTION_CANCELED*: Collection canceled by user *OPERATION_TIMED_OUT*: Operation timed out *CERTIFICATE_CHECK_FAILED*: Certificate cannot be verified' deviceProcessingFailures: type: object additionalProperties: type: integer format: int32 description: 'Possible error types during processing *LICENSE_EXHAUSTED*: License limit exceeded *MISSING_SIGNATURE*: Missing signature *DUPLICATE*: Duplicate device *PARSER_EXCEPTION*: Couldn''t be parsed *UNSUPPORTED_VENDOR*: Vendor not supported' endpointCollectionFailures: type: object additionalProperties: type: integer format: int32 description: 'Possible device error types during collection *UNKNOWN*: Unknown error *CONNECTION_TIMEOUT*: Connection to device timed out *CONNECTION_REFUSED*: Connection to device refused *AUTHENTICATION_FAILED*: Authentication failed *KEY_EXCHANGE_FAILED*: Key exchange failed *AUTHORIZATION_FAILED*: Authorization failed *AVI_SHELL_AUTH_FAILED*: Avi authentication failed *AVI_CONTROLLER_WITHOUT_HEALTHY_SERVICE_ENGINES*: No Avi Service Engines found *NETWORK_UNREACHABLE*: Network not reachable *IO_ERROR*: I/O error *SESSION_CLOSED*: Session closed unexpectedly *STATE_COLLECTION_FAILED*: State collection failed *JUMP_SERVER_CONNECTION_TIMEOUT*: Jump server timed out *JUMP_SERVER_PASSWORD_AUTH_FAILED*: Jump server auth failed *JUMP_SERVER_CONNECTION_FAILED*: Jump server connection refused *JUMP_SERVER_KEY_EXCHANGE_FAILED*: Jump server key exchange failed *PROXY_SERVER_PING_FAILED*: Proxy ping failed *PROXY_SERVER_PORT_REACHABILITY_FAILED*: Proxy port not reachable *PROXY_SERVER_CONNECTION_FAILED*: Proxy connection refused *PROXY_SERVER_AUTHENTICATION_FAILED*: Proxy authentication failed *PRIV_PASSWORD_ERROR*: Privileged password failed *UNSUPPORTED_VERSION*: Unsupported version *DEVICE_TYPE_UNDETECTED*: Undetected device type *WARN_TYPE_MISMATCH*: Device type mismatch *DEVICE_IS_CHILD_CONTEXT*: Parent context required *MANAGER_COLLECTOR_NOT_FOUND*: Collector manager error *INCOMPLETE_SETUP*: Incomplete setup *COLLECTION_NOT_FOUND*: Collection not found *INFINITE_LOOP_IN_COMMAND_OUTPUT*: Collection stuck in loop *MISSING_FILE*: File is missing *UNSUPPORTED_VENDOR*: Vendor not supported *COMMAND_DISABLED*: Required command is disabled *APIC_CONFIG_COLLECTION_FAILED*: APIC config collection failed *UNEXPECTED_KEY_EXCHANGE_MESSAGE*: Unexpected Key-Exchange message *UNDISCOVERED_ACI_FABRIC*: ACI fabric node was not discovered by APIC *SLOW_READ_RATE_DETECTED*: Read rate from the remote peer is too low *COLLECTION_TIMED_OUT*: Collection timed out *COLLECTION_CANCELED*: Collection canceled by user *OPERATION_TIMED_OUT*: Operation timed out *CERTIFICATE_CHECK_FAILED*: Certificate cannot be verified' endpointProcessingFailures: type: object additionalProperties: type: integer format: int32 description: 'Possible error types during processing *LICENSE_EXHAUSTED*: License limit exceeded *MISSING_SIGNATURE*: Missing signature *DUPLICATE*: Duplicate device *PARSER_EXCEPTION*: Couldn''t be parsed *UNSUPPORTED_VENDOR*: Vendor not supported' hostComputationStatus: $ref: '#/components/schemas/ComputationStatus' description: Host computation status examples: - SUCCESS ipLocationIndexingStatus: $ref: '#/components/schemas/ComputationStatus' description: IP location indexing status examples: - SUCCESS jumpServerCollectionConcurrency: type: integer format: int32 l2IndexingStatus: $ref: '#/components/schemas/ComputationStatus' description: L2 elements (vlans, LAN segments etc.) indexing status examples: - SUCCESS numCollectionFailureDevices: type: integer format: int32 numCollectionFailureEndpoints: type: integer format: int32 numProcessingFailureDevices: type: integer format: int32 numProcessingFailureEndpoints: type: integer format: int32 numSuccessfulDevices: type: integer format: int32 examples: - 401 numSuccessfulEndpoints: type: integer format: int32 examples: - 234 pathSearchIndexingStatus: $ref: '#/components/schemas/ComputationStatus' description: End-to-end path indexing status examples: - SUCCESS processingDuration: type: integer format: int64 examples: - 5678 searchIndexingStatus: $ref: '#/components/schemas/ComputationStatus' description: Object search indexing status examples: - SUCCESS snapshotId: type: string snapshotState: $ref: '#/components/schemas/SnapshotState' description: Current state of the Snapshot examples: - PROCESSING SnapshotExportParams: type: object properties: includeDevices: type: array items: type: string description: Must be absent if `"excludeDevices"` is specified. examples: - - device-1 - device-2 - pa* excludeDevices: type: array items: type: string description: Must be absent if `"includeDevices"` is specified. examples: - - device-6 - device-7 - pa* obfuscationKey: type: string description: 'If specified, sensitive data will be [obfuscated](https://docs.fwd.app/latest/application/settings/system/obfuscate-snapshot/).' examples: - a-sEcr3t-kEy-th4t-i$-h4rd-to-guE$$ obfuscateNames: type: boolean description: 'default: `false`. If specified, `"obfuscationKey"` must also be specified.' examples: - false SnapshotState: type: string enum: - UNPACKING - UNPROCESSED - PROCESSING - PROCESSED - FAILED - CANCELED - TIMED_OUT - ARCHIVED - RESTORING - RESTORE_FAILED SnapshotInfo: type: object properties: createdAt: type: string examples: - '2019-09-20T17:40:34.567Z' id: type: string isDraft: type: boolean examples: - false note: type: string parentSnapshotId: type: string processedAt: type: string examples: - '2019-09-20T18:17:36.789Z' processingTrigger: type: string enum: - UNKNOWN - COLLECTION - IMPORT - REPROCESS - FORK restoredAt: type: string examples: - '2019-09-20T17:40:34.567Z' state: $ref: '#/components/schemas/SnapshotState' advancedReachabilityState: type: string description: State of advanced reachability computation for this Snapshot. enum: - UNPROCESSED - PROCESSING - PROCESSED - FAILED - CANCELED - TIMED_OUT favoritedBy: type: string description: 'The username of the user who most recently marked this Snapshot as a favorite if it''s currently a favorite and the user account hasn’t been deleted.' examples: - mary favoritedByUserId: type: string description: 'The id of the user who most recently marked this Snapshot as a favorite if it’s currently a favorite.' examples: - '1234' favoritedAt: type: string description: 'When this Snapshot was most recently marked as a favorite if it’s currently a favorite. A favorite Snapshot will never be automatically deleted, regardless of its network’s Snapshot retention policy.' examples: - '2019-09-30T19:48:59.481Z' ErrorInfo: type: object required: - httpMethod - apiUrl - message properties: httpMethod: type: string examples: - GET enum: - GET - HEAD - POST - PUT - PATCH - DELETE apiUrl: type: string examples: - /api/version message: type: string description: A description of the error reason: type: string ComputationStatus: type: string enum: - UNKNOWN - FAILURE - SUCCESS - CANCELED securitySchemes: api_token: type: http scheme: basic