Synack Missions API

openapi: 3.1.0
info:
  title: Assessment Service Assessment Groups Missions API
  version: 1.0.0
  description: 'APIs for managing Assessment and related operations on the Synack.

    '
  contact:
    name: Synack Engineering
    email: engineering@synack.com
servers:
- url: https://client.synack.com/api/assessment
  description: Commercial
- url: https://client.synack.us/api/assessment
  description: FedRAMP (Medium)
security:
- bearerAuth: []
tags:
- name: Missions
  description: Access mission information.
paths:
  /v2/campaigns/:
    get:
      x-mint:
        metadata:
          title: Get Group of Missions
      tags:
      - Missions
      summary: Search for Group of Missions.
      description: Allows searching for Group of Missions (campaigns) available to the current authenticated user. Group of Missions are filtered based on what current listings and organizations the current user has access to.
      operationId: GetCampaigns
      parameters:
      - name: page
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Page'
      - name: perPage
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PerPage'
      - name: sort
        description: Sorts by field names.
        in: query
        required: false
        schema:
          type: array
          description: If sorting is done on "TASKSFAILED" then it will set includeTaskStats to true.
          items:
            default: PUBLISHED
            enum:
            - PUBLISHED
            - TASKSFAILED
            - CREATED
            - STATUSCREATED
            - COMPLETED
      - name: sortDir
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/SortDir'
      - name: q
        description: Search by campaign's title, description or scope
        in: query
        required: false
        schema:
          type: string
      - name: createdByRole
        description: Filter campaigns by created_role
        in: query
        required: false
        schema:
          type: string
      - name: orgUids
        description: Filter by organization UIDs.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: listingUids
        description: Filter by listing UIDs.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: status
        description: Filter by Campaign Status.
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/CampaignStatus'
      - name: listingType
        description: Filter by listing types. Search is performed on the campaign's tags.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: includeTaskStats
        description: "If this set to true, then additional tasks stats fields will be set for each campaign in the response which include:\n  * tasksTotal\n  * tasksCompleted\n  * tasksPassed\n  * tasksFailed\n"
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: includeCatalogCategory
        description: If set to true, then the CampaignCatalog that each Campaign belongs to will be included in the response.
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: includePublishedWaiting
        description: 'If this is set to true, then additional tasksPublishedWaiting field will be set for each campaign in the response, which contains the count of missions that have been in PUBLISHED state for more than 30 minutes.

          '
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: publishedStartDate
        description: It is possible this value alone to the query. If both published start and end date are provided, it is required for startDate < endDate.
        in: query
        required: false
        schema:
          type: string
          format: date
      - name: publishedEndDate
        description: It is possible this value alone to the query. If both published start and end date are provided, it is required for startDate < endDate.
        in: query
        required: false
        schema:
          type: string
          format: date
      - name: deactivated
        description: Filter by activated/deactivated campaigns.
        in: query
        required: false
        schema:
          type: boolean
      - name: creditsDeducted
        description: Whether to return deducted credits.
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful operation.
          headers:
            X-Request-ID:
              $ref: '#/components/schemas/RequestID'
            Pagination-Limit:
              $ref: '#/components/schemas/HeaderPaginationLimit'
            Pagination-Current-Page:
              $ref: '#/components/schemas/HeaderPaginationCurrentPage'
            Pagination-Total-Pages:
              $ref: '#/components/schemas/HeaderPaginationTotalPages'
            Pagination-Total-Count:
              $ref: '#/components/schemas/HeaderPaginationTotalCount'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetCampaignsResult'
        '400':
          description: Returned when query params are in bad format or when some of the Tasks requested for retesting were not found.
          headers:
            X-Request-ID:
              $ref: '#/components/schemas/RequestID'
          content:
            application/problem+json:
              schema:
                type: object
                description: Response returned with more information about the error that occurred.
                properties:
                  errorCode:
                    $ref: '#/components/schemas/ExtErrorCode400'
                  errorMsg:
                    $ref: '#/components/schemas/ResponseErrMsg'
        '403':
          description: Returned whenever a user does not have the required features enabled, has no orgs/listings assigned.
          headers:
            X-Request-ID:
              $ref: '#/components/schemas/RequestID'
          content:
            application/problem+json:
              schema:
                type: object
  /v2/campaigns/{campaignID}:
    get:
      x-mint:
        metadata:
          title: Get a specific Group of Missions
      tags:
      - Missions
      summary: Search for Group of Missions by ID.
      description: Allows searching for Group of Missions (campaign) by ID if available to the current authenticated user.
      operationId: GetCampaignByID
      parameters:
      - name: campaignID
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: includeTaskStats
        description: "If this set to true, then additional tasks stats fields will be set for the campaign in the response which include:\n  * tasksTotal\n  * tasksCompleted\n  * tasksPassed\n  * tasksFailed\n"
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: includeCatalogCategory
        description: If set to true, then the CampaignCatalog that this Campaign belongs to will be included in the response.
        in: query
        required: false
        schema:
          type: boolean
          default: false
      - name: creditsDeducted
        description: Whether to return deducted credits.
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful operation.
          headers:
            X-Request-ID:
              $ref: '#/components/schemas/RequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCampaignResult'
        '403':
          description: Returned whenever a user does not have the required features enabled, has no orgs/listings assigned.
          headers:
            X-Request-ID:
              $ref: '#/components/schemas/RequestID'
          content:
            application/problem+json:
              schema:
                type: object
        '404':
          description: Campaign not found
          headers:
            X-Request-ID:
              $ref: '#/components/schemas/RequestID'
  /v2/campaigns/stats:
    get:
      x-mint:
        metadata:
          title: Get Group of Missions stats
      tags:
      - Missions
      summary: Get Group of Missions stats by status.
      description: Allows searching for Group of Missions (campaigns) stats by status if available to the current authenticated user.
      operationId: GetCampaignsStats
      parameters:
      - name: orgUids
        description: Filter by organization UIDs.
        in: query
        required: true
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: listingUids
        description: Filter by listing UIDs.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation.
          headers:
            X-Request-ID:
              $ref: '#/components/schemas/RequestID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCampaignsStatsResult'
        '403':
          description: Returned whenever a user does not have an authorized client role.
          headers:
            X-Request-ID:
              $ref: '#/components/schemas/RequestID'
          content:
            application/problem+json:
              schema:
                type: object
  /v2/tasks:
    get:
      x-mint:
        metadata:
          title: Get missions
      tags:
      - Missions
      summary: Search for missions.
      description: Allows searching for missions (tasks) available to the current authenticated user. Missions are filtered based on what current listings and organizations the current user has access to.
      operationId: GetTasks
      parameters:
      - name: page
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Page'
      - name: perPage
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/PerPage'
      - name: sort
        description: 'Sorts by field names.

          '
        in: query
        required: false
        schema:
          type: array
          items:
            default: PUBLISHED
            enum:
            - PUBLISHED
            - TITLE
            - STATUS
            - CAMPAIGNTITLE
            - AMOUNT
            - SUBMITTED
            - RESULT
            - ASSET
            - CLAIMED
            - SYN_CATEGORIES
            - CATEGORIES
      - name: sortDir
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/SortDir'
      - name: approvedStartDate
        description: Filter by approved date (this value can be sent alone to the query). If both approved start and end date are provided, it is required for startDate < endDate.
        in: query
        required: false
        schema:
          type: string
          format: date
      - name: approvedEndDate
        description: Filter by approved date (this value can be sent alone to the query). If both approved start and end date are provided, it is required for startDate < endDate.
        in: query
        required: false
        schema:
          type: string
          format: date
      - name: assetTypes
        description: Filter by asset types.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: attackTypes
        description: Filter by attack types.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: categories
        description: Filter by categories.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: cwe
        description: Filter by CWEs.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: Uids
        description: Filter by tasks UIDs.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: orgUids
        description: Filter by organization UIDs.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: listingUids
        description: Filter by listing UIDs.
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            format: uuid
      - name: status
        description: Filter by task status.
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/TaskStatus'
      - name: sv
        description: Filter by tasks SV.
        in: query
        required: false
        schema:
          type: string
      - name: assignee
        description: Filter by user assignee to the tasks.
        in: query
        required: false
        schema:
          type: string
      - name: campaignUid
        description: Filter by campaign UID.
        in: query
        required: false
        schema:
          type: string
      - name: deactivated
        description: Filter by activated/deactivated tasks and campaigns.
        in: query
        required: false
        schema:
          type: boolean
      - name: deactivatedTasks
        description: Filter by activated/deactivated tasks only - no impact from campaigns.
        in: query
        required: false
        schema:
          type: boolean
      - name: attachments
        in: query
        description: Include attachments for the tasks in the response. By default is false.
        schema:
          type: boolean
      - name: viewed
        description: Include the viewed field in the response. By default is false.
        in: query
        required: false
        schema:
          type: boolean
      - name: q
        description: Query used to perform a full text search on task's title, description or scope.
        in: query
        required: false
        schema:
          type: string
      - name: taskTemplateUid
        description: Filter by task template UID.
        in: query
        required: false
        schema:
          type: string
      - name: definitionId
        description: Filter by definition ID.
        in: query
        required: false
        schema:
          type: string
      - name: batchId
        description: Filter by batch ID.
        in: query
        required: false
        schema:
          type: string
      - name: taskGroup
        description: Filter by task group.
        in: query
        required: false
        schema:
          type: string
      - name: structuredResponse
        description: Filter by task structured response.
        in: query
        required: false
        schema:
          type: string
      - name: taskTypes
        description: 'Filter task types, case insensitively. Currently accepted values are: "MISSION", "SV2M" and "TAAS".'
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
      - name: includeAssignedBySynackUser
        description: Return whether the task was assigned to the researcher by a boss user.
        in: query
        required: false
        schema:
          type: boolean
      - name: includeTaskTemplateCredits
        description: Return the task template credits for the task.
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Successful operation.
          headers:
            X-Request-ID:
              $ref: '#/components/schemas/RequestID'
            Pagination-Limit:
              $ref: '#/components/schemas/HeaderPaginationLimit'
            Pagination-Current-Page:
              $ref: '#/components/schemas/HeaderPaginationCurrentPage'
            Pagination-Total-Pages:
              $ref: '#/components/schemas/HeaderPaginationTotalPages'
            Pagination-Total-Count:
              $ref: '#/components/schemas/HeaderPaginationTotalCount'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetTasksResult'
        '400':
          description: Returned when query params are in bad format.
          headers:
            X-Request-ID:
              $ref: '#/components/schemas/RequestID'
          content:
            application/problem+json:
              schema:
                type: object
                description: Response returned with more information about the error that occurred.
                properties:
                  errorCode:
                    $ref: '#/components/schemas/ExtErrorCode400'
                  errorMsg:
                    $ref: '#/components/schemas/ResponseErrMsg'
        '403':
          description: Returned whenever a user does not have the required features enabled, or has requested for orgs/listings that he doesn't have access to.
          headers:
            X-Request-ID:
              $ref: '#/components/schemas/RequestID'
          content:
            application/problem+json:
              schema:
                type: object
components:
  schemas:
    ResponseErrMsg:
      type: string
      description: When included, this error message provides the developer a more descriptive error message in the default lang (english). This error message should not be used to show to the client.
    CatalogCategoryResult:
      type: object
      description: The CatalogCategory which this Campaign belongs to (via CampaignTemplate).
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
    Page:
      type: integer
      description: Page to start showing results from.
      minimum: 1
      default: 1
    GetTasksAttachmentsForReportResult:
      type: object
      description: Attachments related to that task
      properties:
        uid:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        originalFilename:
          type: string
        sizeInBytes:
          type: number
        groupUID:
          type: string
          format: uuid
        createdOn:
          type: string
          format: date
        modifiedOn:
          type: string
          format: date
        createdBy:
          type: string
        modifiedBy:
          type: string
        version:
          type: integer
          format: uint
        data:
          type: string
          description: URL to download attachment from GCS. Can be incomplete if there is an error obtaining URL. API will return 206 partial content.
        thumbnailData:
          type: string
          description: URL to download attachment thumbnail from GCS. Can be incomplete if there is an error obtaining URL. API will return 206 partial content.
        position:
          type: integer
          format: int
        mimeType:
          type: string
    GetCampaignsResult:
      type: object
      description: Response model used by the GET /campaigns/ endpoint. All nullable fields will be omitted from the response body if their value is null.
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        listingUid:
          type: string
          format: uuid
        listingCodename:
          type: string
        listingName:
          type: string
        organizationUid:
          type: string
          format: uuid
        organizationName:
          type: string
        organizationCodename:
          type: string
        status:
          $ref: '#/components/schemas/CampaignStatus'
        published:
          type: string
          format: date
          nullable: true
        completed:
          type: string
          format: date
          nullable: true
        tasksCompleted:
          type: integer
        tasksTotal:
          type: integer
        tasksPassed:
          type: integer
        tasksFailed:
          type: integer
        tasksPublishedWaiting:
          type: integer
          description: Count of missions that have been in PUBLISHED state for more than 30 minutes.
        isRetestable:
          type: boolean
          description: "This flag will be set to true if these conditions are met:\n  * The campaign is completed.\n  * The campaign is not a retest (parentUid is NULL).\n  * The campaign's listing has the boss active flag set to true.\n  * The campaign's listing has active tests.\n  * The campaign's listing is not paused by the client.\n"
        parentUid:
          type: string
          format: uuid
          nullable: true
        deactivated:
          type: string
          format: date
          nullable: true
        createdOn:
          type: string
          format: date
          nullable: true
        createdByRole:
          type: string
          nullable: true
        creditsDeducted:
          type: integer
          nullable: true
        catalogCategory:
          $ref: '#/components/schemas/CatalogCategoryResult'
    HeaderPaginationTotalPages:
      type: string
      description: The total number of pages available for the specified query.
    RequestID:
      type: string
      format: uuid
      description: A unique UUID generated for every request. In the case of an error, this error should be included in the error report by the user so that we can easily filter the logs and find the error quicker.
    GetTasksResult:
      type: object
      description: Response model used by the GET /tasks endpoint. All nullable fields will be omitted from the response body if their value is null.
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        taskTemplateUid:
          type: string
          format: uuid
        taskTemplateCredits:
          type: integer
        campaignUid:
          type: string
          format: uuid
        campaignName:
          type: string
        listingUid:
          type: string
          format: uuid
        listingCodename:
          type: string
        organizationUid:
          type: string
          format: uuid
        organizationCodename:
          type: string
        status:
          $ref: '#/components/schemas/TaskStatus'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/GetTasksAttachmentsResult'
        hasBeenViewed:
          type: boolean
        payout:
          $ref: '#/components/schemas/PayoutResult'
        credits:
          type: integer
        assetTypes:
          type: array
          items:
            type: string
        attackTypes:
          type: array
          items:
            type: string
        sv:
          type: array
          items:
            type: string
        cwe:
          type: array
          items:
            type: string
        categories:
          type: array
          items:
            type: string
        taskType:
          type: string
        attempts:
          type: integer
        batchId:
          type: string
        controlFamily:
          type: string
        definitionId:
          type: string
        definitionName:
          type: string
        fismaLow:
          type: string
        fismaModerate:
          type: string
        fismaHigh:
          type: string
        taskGroup:
          type: string
        response:
          type: string
          description: "It will only be seen by:\n  * Users with Client role (only if the task is in APPROVED status).\n"
        structuredResponse:
          type: string
          description: "It will only be seen by:\n  * Users with Client role (only if the task is in APPROVED status).\n"
        position:
          type: integer
        createdOn:
          type: string
          format: date
        modifiedOn:
          type: string
          format: date
        maxCompletionTimeInSecs:
          type: integer
        pausedDurationInSecs:
          type: integer
        version:
          type: integer
        validResponses:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
              value:
                type: string
        publishedOn:
          type: string
          format: date
        claimedOn:
          type: string
          format: date
        completedOn:
          type: string
          format: date
        validatedOn:
          type: string
          format: date
        reviewedOn:
          type: string
          format: date
        pausedOn:
          type: string
          format: date
        deactivatedOn:
          type: string
          format: date
        invalidatedOn:
          type: string
          format: date
        returnedForEditOn:
          type: string
          format: date
        canEditResponse:
          type: boolean
        isAssigneeCurrentUser:
          type: boolean
        assignedBySynackUser:
          type: boolean
          description: Whether this task was assigned to a researcher by a boss user or not. Only available to researcher users when specifying 'includeAssignedBySynackUser=true' in the query string.
    CampaignStatus:
      type: string
      description: Campaign status enum.
      enum:
      - CREATED
      - COMPLETED
      - PUBLISHED
    TaskStatus:
      type: string
      description: Task status enum.
      enum:
      - APPROVED
      - CLAIMED
      - CREATED
      - COMPLETED
      - FOR_REVIEW
      - PUBLISHED
    HeaderPaginationLimit:
      type: string
      description: The number of per page entries.
    SortDir:
      type: string
      description: Sort direction.
      default: desc
      enum:
      - asc
      - desc
    HeaderPaginationTotalCount:
      type: string
      description: The total number of entries available for the specified query.
    GetCampaignsStatsResult:
      type: object
      description: Response model used by the GET /campaigns/stats endpoint.
      properties:
        all:
          type: integer
          nullable: false
        active:
          type: integer
          nullable: false
        inReview:
          type: integer
          nullable: false
        completed:
          type: integer
          nullable: false
    GetCampaignResult:
      type: object
      description: Response model used by the GET /campaigns/:campaignID endpoint.
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        assetType:
          type: array
          items:
            type: string
        isRetestable:
          type: boolean
          description: "This flag will be set to true if these conditions are met:\n  * The campaign is completed.\n  * The campaign is not a retest (parentUid is NULL).\n  * The campaign's listing has the boss active flag set to true.\n  * The campaign's listing has active tests.\n  * The campaign's listing is not paused by the client.\n"
        parentUid:
          type: string
          format: uuid
          nullable: true
        status:
          $ref: '#/components/schemas/CampaignStatus'
        createdOn:
          type: string
          format: date
          nullable: false
        modifiedOn:
          type: string
          format: date
          nullable: true
        publishedOn:
          type: string
          format: date
          nullable: true
        completedOn:
          type: string
          format: date
          nullable: true
        scheduledOn:
          type: string
          format: date
          nullable: true
        listing:
          type: object
        scope:
          type: string
        tasksCompleted:
          type: integer
        tasksTotal:
          type: integer
        tasksPassed:
          type: integer
        tasksFailed:
          type: integer
        campaignTemplateUid:
          type: string
          format: uuid
        campaignTemplateVersion:
          type: integer
        deactivated:
          type: string
          format: date
          nullable: true
        organizationUid:
          type: string
          format: uuid
        creditsDeducted:
          type: integer
          nullable: true
        catalogCategory:
          $ref: '#/components/schemas/CatalogCategoryResult'
    ExtErrorCode400:
      type: integer
      format: int64
      enum:
      - 1
      - 2
      - 3
      - 4
      - 5
      - 7
      - 8
      - 9
      - 10
      - 11
      description: "400 Bad Request extended error codes:\n  * 1 - Invalid Parameters found in the request.\n  * 2 - Campaign is not retestable.\n  * 3 - Some Task IDs were not found. When this code is set, the payload will contain a string array with all of the Task IDs that were not found.\n  * 4 - Task ID was not specified when trying to spend credits.\n  * 5 - Task is deactivated.\n  * 7 - Campaign template was not found.\n  * 8 - Task already has v1 evidence information.\n  * 9 - Some requested Task Templates for instantiation were not found.\n  * 10 - No active sprint was found for listing.\n  * 11 - Invalid task response value.\n  * 12 - Some requested Campaign for missionize was not found.\n  * 13 - Some SVs already have tasks associated.\n  * 14 - Some requested Task Templates for missionize were not found.\n  * 15 - Type not supported during missionize.\n  * 16 - The requested task types echoed in the payload are not allowed for the current user.\n  * 17 - The requested does not have enough balance to created.\n"
    PerPage:
      type: integer
      description: Number of items to show per page.
      minimum: 1
      default: 1
    GetTasksAttachmentsResult:
      type: object
      description: "Response model used in the GET /tasks endpoint. It will only be seen by:\n  * Users with Client role (only if the task is in APPROVED status).\n"
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        description:
          type: string
        originalFilename:
          type: string
        data:
          type: string
        thumbnailData:
          type: string
        sizeInBytes:
          type: integer
        groupId:
          type: string
        position:
          type: integer
        createdOn:
          type: string
          format: date
        createdBy:
          type: string
        modifiedOn:
          type: string
          format: date
        modifiedBy:
          type: string
        deletedOn:
          type: string
          format: date
        version:
          type: integer
        mimeType:
          type: string
        tasks:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Task id
              title:
                type: string
                description: Task title
              description:
                type: string
                description: Task description
              definitionUID:
                type: string
                description: Task definition ID
              definitionName:
                type: string
   

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/synack/refs/heads/main/openapi/synack-missions-api-openapi.yml