{
  "openapi": "3.2.0",
  "info": {
    "title": "Forward: Collector Tasks API",
    "summary": "Submit and track collector tasks",
    "description": "Use these resources to submit collector tasks and to track or stop their progress.",
    "contact": {
      "email": "support@forwardnetworks.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://spdx.org/licenses/MIT"
    },
    "version": "26.8"
  },
  "servers": [
    {
      "url": "/api"
    }
  ],
  "security": [
    {
      "api_token": []
    }
  ],
  "tags": [
    {
      "name": "Network Collection",
      "description": "Configure and run the collection of configuration and state from a network"
    },
    {
      "name": "Collector Tasks",
      "description": "Submit and track collector tasks",
      "parent": "Network Collection"
    }
  ],
  "paths": {
    "/collector-tasks": {
      "get": {
        "tags": [
          "Collector Tasks"
        ],
        "summary": "Get collector tasks",
        "description": "Retrieves information about recent Collector tasks, optionally filtered by task status. Tasks are ordered by\ncreation time, newest first.",
        "operationId": "getCollectorTasks",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "Use a comma (as in `?status=QUEUED,RUNNING`) or repeat this parameter to request multiple statuses at once.\nOmit this parameter to request all statuses.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "QUEUED",
                  "RUNNING",
                  "SUCCEEDED",
                  "FAILED",
                  "TIMED_OUT",
                  "CANCELED"
                ]
              }
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of tasks desired",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "tasks"
                  ],
                  "properties": {
                    "tasks": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CollectorTask"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Collector Tasks"
        ],
        "summary": "Add a collector task",
        "description": "Signals the system to begin collecting a new network Snapshot as soon as a Collector is available. Use [Get a\ncollector task](https://docs.fwd.app/latest/api/collector-tasks/get-collector-task/) to check a task’s\nstatus.\n\nA network can have only one network collection task running at a time.",
        "operationId": "addCollectorTask",
        "parameters": [
          {
            "name": "networkId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "const": "NETWORK_COLLECTION"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StartCollectionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/collector-tasks/{taskId}": {
      "get": {
        "tags": [
          "Collector Tasks"
        ],
        "summary": "Get a collector task",
        "description": "Get information about a recent collector task. Use\n[Add a collector task](https://docs.fwd.app/latest/api/collector-tasks/add-collector-task/) to create a task.",
        "operationId": "getCollectorTask",
        "parameters": [
          {
            "name": "taskId",
            "in": "path",
            "description": "The identifier of the collector task to retrieve",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectorTask"
                }
              }
            }
          }
        }
      }
    },
    "/collector-tasks/{taskId}?action": {
      "post": {
        "tags": [
          "Collector Tasks"
        ],
        "summary": "Stop a collector task",
        "description": "Cancels a queued or in-progress collector task.",
        "operationId": "stopCollectorTask",
        "parameters": [
          {
            "name": "taskId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "action",
            "in": "query",
            "description": "How to stop the task. `CANCEL` is used most often. To stop a _network collection_ task early and create a\nnetwork Snapshot from any devices already collected, use `SKIP`.",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "CANCEL",
                "SKIP"
              ]
            }
          },
          {
            "name": "note",
            "in": "query",
            "description": "A brief note indicating why the task was stopped",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No Content",
            "content": {}
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CollectorTask": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "System-assigned identifier of this task.",
            "examples": [
              "P1234"
            ]
          },
          "type": {
            "type": "string",
            "description": "The type of the task",
            "examples": [
              "NETWORK_COLLECTION"
            ]
          },
          "status": {
            "type": "string",
            "description": "The current status of the task.",
            "examples": [
              "SUCCEEDED"
            ],
            "enum": [
              "QUEUED",
              "RUNNING",
              "SUCCEEDED",
              "FAILED",
              "TIMED_OUT",
              "CANCELED"
            ]
          },
          "networkId": {
            "type": "string",
            "description": "The ID of the network this task is associated with",
            "examples": [
              "123"
            ]
          },
          "networkName": {
            "type": "string",
            "description": "The name of the network this task is associated with",
            "examples": [
              "My Network"
            ]
          },
          "note": {
            "type": "string",
            "description": "An optional user-provided note about the task."
          },
          "createdById": {
            "type": "string",
            "description": "The ID of the user who created this entity, if known. *Note*: The referenced user account might no longer\nexist since an administrator can delete accounts.",
            "examples": [
              "456"
            ]
          },
          "createdBy": {
            "type": "string",
            "description": "The ID of the user who created this entity, if known. *Note*: The referenced user account might no longer\nexist since an administrator can delete accounts.",
            "examples": [
              "456"
            ]
          },
          "createdAt": {
            "type": "string",
            "description": "When this entity was created, if known.",
            "examples": [
              "2024-10-27T16:30:45.111Z"
            ]
          },
          "startedAt": {
            "type": "string",
            "description": "When this task started. Absent if the task hasn’t started yet.",
            "examples": [
              "2024-10-27T21:44:51.345Z"
            ]
          },
          "finishedAt": {
            "type": "string",
            "description": "When this task finished. Absent if the task hasn’t finished yet.",
            "examples": [
              "2024-10-28T00:41:31.123Z"
            ]
          },
          "canceledById": {
            "type": "string",
            "description": "The ID of the user who canceled this task, if the `status` is CANCELED.",
            "examples": [
              "456"
            ]
          },
          "canceledBy": {
            "type": "string",
            "description": "The username of the user who canceled this task, if the `status` is CANCELED. Absent if the user account has\nbeen deleted.",
            "examples": [
              "me@example.com"
            ]
          }
        }
      },
      "StartCollectionResponse": {
        "type": "object",
        "properties": {
          "taskId": {
            "type": "string",
            "description": "The system-assigned identifier of the new network collection task.",
            "examples": [
              "P1234"
            ]
          }
        }
      }
    },
    "securitySchemes": {
      "api_token": {
        "type": "http",
        "scheme": "basic"
      }
    }
  }
}