The CICD API provides endpoints that enable integration with common DevOps tools for building pipelines. These tools include Jenkins, Azure Pipelines, GitLab, GitHub Actions, Atlassian Bamboo/Pipelines, and more.

It provides integrators with the ability to build CICD pipelines for Now Platform applications driven by pull/merge request workflows typical in source-driven development. It leverages the Source Control, Application Repository, and Automated Test Framework features.

The CI/CD API provides the following product and feature areas:

  • Source control

    Apply remote changes for an application linked to a remote Git repository through the Source Control feature in Studio, on a specific instance.

    Imports an application using the specified repository URL and branch name.

  • Application repository: Available for scoped applications, global application, application customizations for scoped applications on the ServiceNow Store, and through plugins.
    • Publish an application from an instance to the connected application repository.
    • Install an application onto an instance from the connected application repository.
    • Rollback an application that was installed through rollback context.
  • Batch
    • Define a JSON manifest file to batch install multiple applications together.
    • Rollback the entire batch install through rollback context.
    • Returns the results of a batch install based on a specified result identifier.
  • Plugins
    • Activate a plugin.
    • Rollback a plugin through rollback context.
  • Automated Test Framework (ATF)
    • Start an ATF test suite.
    • Obtain the pass/fail result of an ATF test suite.
  • Instance scan
    • Start an instance scan (full, point scan on table, point scan on record, scoped application, update set, combination of these items.)
    • Obtain the pass/fail result of an instance scan run.
  • Progress

    Obtain the percentage completion on an instance for processes initiated by other endpoint calls. You can use this feature to poll until progress completion before proceeding with the next step.

This API uses an asynchronous response model. When you call an endpoint, such as to run a test suite /sn_cicd/testsuite/run, the endpoint kicks off the associated function, such as starting the execution of the test suite. The endpoint then returns a response message that contains the execution status of the requested function, typically Pending, along with a unique identifier and link. Use this information to obtain additional information about the progress, source, results, and/or findings of the request. Depending on the function request, you can use one of the following means to obtain additional information about a request:
  • Call the /sn_cicd/progress/{progress_id} endpoint using the links.progress.id parameter returned by the initiating endpoint.
  • Call the /sn_cicd/testsuite/results/{result_id} endpoint using the links.result.id parameter returned by the initiating endpoint.
  • Call the /sn_cicd/instance_scan/result/{progress_id} endpoint using the links.progress.id parameter returned by the initiating endpoint.
  • Call the /sn_cicd/sc/apply_stash/{stash_id} endpoint using the links.stash.id parameter returned by the/sn_cicd/progress/{progress_id} endpoint.
  • Link out to the links.<progress/result/source/findings>.url parameter returned by the initiating endpoint.
Note: To install an application from a repository, the application must first be published to the repository using the /sn_cicd/app_repo/publish endpoint. Once published, any instance connected to that repository can then install and rollback the application. If the application is not first published, the installation request fails.

The sn_cicd.sys_ci_automation or admin role is required to use this API.

Beginning in Tokyo, the CICD API endpoints that need to obtain the instance wide lock / mutex to perform their requested operation will use a queue, rather than rejecting requests while the instance wide lock / mutex is occupied. Multiple CICD pipelines simultaneously make requests without detecting the rejection and retrying, and instead, can simply monitor the progress as they would for successful requests previously. This behavior is on by default.

The current queue can be inspected by a user with the admin role by navigating to the System Diagnostic ->Application Operation Queue. From here the queue can be paused and resumed by the admin to allow for other manual operations that may require the instance wide lock / mutex.
Note: When paused, any in progress operation will run to completion but no new operation will be started. The API will continue to accept and queue new requests. A pending operation can also be cancelled before it begins running by updating the listed execution tracker to a cancelled state. If for whatever reason, an operation cannot proceed after the time out specified in com.glide.update_operation.job_cancel_timeout_minutes (default: 48 hours), it will be cancelled.
When an upgrade is scheduled, the queue will go into an upgrade paused state two hours prior to the upgrade unless overridden by the property com.glide.update_operation.queue_upgrade_window. This allows for any in progress operation to complete before the upgrade commences.
Note: The queue automatically resumes when the upgrade is completed.
For additional information on CICD, see:

CI/CD - GET /sn_cicd/app/batch/results/{result_id}

Returns the results of a batch install based on a specified result identifier.

Call this method after calling the /sn_cicd/app/batch/install endpoint to obtain the results of the batch install. Use the value returned in the links.results.id parameter of the return results of /sn_cicd/app/batch/install endpoint as the result_id for this endpoint. You can also call the /api/sn_cicd/progress/{progress_id} endpoint to obtain information on the progress of the installation if it has not yet completed.

URL format

Versioned URL: /api/sn_cicd/{api_version}/app/batch/results/{result_id}

Default URL: /api/sn_cicd/app/batch/results/{result_id}

Supported request parameters

Table 1. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
result_id Sys_id of the batch installation for which to return results information. This value is returned in the links.results.id parameter of the /sn_cicd/app/batch/install endpoint.

Data type: String
Table 2. Query parameters
Name Description
None
Table 3. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 4. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 5. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

This example checks the status of a batch installation plan called Release 2.0 IT Operations.

curl 'instance.servicenow.com/api/sn_cicd/app/batch/results/df24b1e9db2d0110b5e3f6c5ae97c561 \
--request GET \
--header 'Accept: application/json' \
--user 'username':'password' 
{
"result": {
  "batch_plan": {
    "name":“Release 2.0 IT Operations”,
    "id": "df24b1e9db2d0110b5e3f6c5ae97c561",
    "url": "https://instance.service-now.com/sys_batch_install_plan.do?sys_id=df24b1e9db2d0110b5e3f6c5ae97c561",
    "state": "Installed",
    "notes": "User specified notes for batch install plan",
  }
  "batch_items": [
    {
      "name": "com.sn_cicd_spoke",
      "type": "Application",
      "version": "7.0.0",
      "state": "Installed",
      "install_date": "2020-08-31 15:30:01",
      "id": "c159b1e9db1c0010b5e3f6c5ae961903",
      "url":"https://instance.service-now.com/sys_batch_install_item.do?sys_id=c159b1e9db1c0010b5e3f6c5ae961903",
      "notes" : ""
    },
    {
      "name": "Customization for CSM App1",
      "type": "Application",
      "version": "1.0.0",
      "state": "Installed",
      "install_date": "2020-08-31 15:32:01",
      "id": "e824b1e9db2d1001b5e3f6c5ae97d628",
      "url": "https://instance.service-now.com/sys_batch_install_item.do?sys_id=e824b1e9db2d1001b5e3f6c5ae97d628",
      "notes": "Customized headers.",
      "customization_version": "2.1.1”,
      "status_message": ""

    }]
  }
}

CI/CD - GET /sn_cicd/instance_scan/result/{progress_id}

Returns the current progress and status of the CI/CD instance scan function associated with a passed-in progress ID. Call this method after calling one of the other instance scan CI/CD endpoints such as /sn_cicd/instance_scan/full_scan or /sn_cicd/instance_scan/point_scan.

Note: This endpoint is part of the CICD Instance Scan Execution Service API and is used under the sn_cicd namespace.

URL format

Versioned URL: /api/sn_cicd/{api_version}/instance_scan/result/{progress_id}

Default URL: /api/sn_cicd/instance_scan/result/{progress_id}

Supported request parameters

Table 7. Parameters
Parameter Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
progress_id Unique identifier of the function for which to return progress information. This value is returned in the links.progress.id parameter of the endpoint that initiated the action, such as /sn_cicd/instance_scan/full_scan or /sn_cicd/instance_scan/point_scan.

Data type: String

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 8. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 9. Response headers
Header Description
None

Status codes

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 10. Status codes
Status codeDescription
200 Successful. The request was successfully processed.
401 The user credentials are incorrect.
403 Forbidden. The user isn’t an admin or doesn’t have the sn_cicd.sys_ci_automation role.
500 Internal server error. An unexpected error occurred while processing the request.

Request body

The API accepts these JSON or XML elements in the request body.

Table 11. Elements accepted in the request body
Element Description
None

Response body

The API returns these JSON or XML elements in the response body.

Table 12. Elements returned in the response body
ElementDescription
error Error message.

Data type: String
links All links and sys_ids associated with the response.

Data type: Object

"links": {
  "progress": {Object}
}
links.findings Object that contains information about the instance scan findings.
links.findings.label Additional information about the instance scan findings.
links.findings.url URL to use to retrieve a list of records that violated the checks.
links.progress Describes the progress link information.

Data type: Object

"progress": {
  "id": "String",
  "url": "String"
}
links.progress.id Unique identifier of the progress detail.
links.progress.url URL to use to retrieve the progress details.

Data type: String
links.results Results information.

Data type: Object

"results": {
  "id": "String",
  "url": "String"
}
links.results.id Sys_id of the instance scan results record.
links.results.url URL to use to obtain the results of the instance scan.
status Numeric execution state. Used with status_label.
Values:
  • 0 (Pending)
  • 1 (Running)
  • 2 (Successful)
  • 3 (Failed)
  • 4 (Canceled)

Data type: String
status_detail Additional information about the current state.

Data type: String
status_label Execution state description. Used with status.
Values:
  • Canceled
  • Failed
  • Pending
  • Running
  • Successful

Data type: String
status_message Additional information on why the operation failed. Empty if the operation is successful.

Data type: String

Example: Sample cURL request

curl 'instance.service-now.com/api/sn_cicd/instance_scan/result/a74c70a11b7800103d374087bc4bcb28' \
--request GET \
--header 'Accept: application/json' \
--user 'username':'password'
{
    "result": {
        "links": {
            "findings": {
                "url": "https://instance.service-now.com/api/now/table/scan_finding?sysparm_query%3Dresult%3D6f4cf8651b7800103d374087bc4bcb41%5EORDERBYsys_id",
                "label": "First 10,000 findings"
            },
            "progress": {
                "id": "a74c70a11b7800103d374087bc4bcb28",
                "url": "https://instance.service-now.com/api/sn_cicd/progress/a74c70a11b7800103d374087bc4bcb28"
            },
            "results": {
                "id": "a74c70a11b7800103d374087bc4bcb28",
                "url": "https://instance.service-now.com/api/sn_cicd/instance_scan/result/a74c70a11b7800103d374087bc4bcb28"
            }
        },
        "status": "2",
        "status_label": "Successful",
        "status_message": "",
        "status_detail": "",
        "error": ""
    }
}

CI/CD - GET /sn_cicd/progress/{progress_id}

Returns the current progress and status of the Continuous Integration and Continuous Delivery (CICD) function associated with a specified progress ID.

Call this method after calling one of the asynchronous CICD endpoints such as /sn_cicd/app_repo/publish, /sn_cicd/app_repo/install, /sn_cicd/testsuite/run, or /sn_cicd/sc/apply_stash.

URL format

Versioned URL: /api/sn_cicd/{api_version}/progress/{progress_id}

Default URL: /api/sn_cicd/progress/{progress_id}

Supported request parameters

Table 13. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
progress_id Unique identifier of the function for which to return progress information.

This value is returned in the links.progress.id parameter of the endpoint that initiated the action, such as /sn_cicd/app_repo/publish, /sn_cicd/app_repo/install, /sn_cicd/testsuite/run, or /sn_cicd/sc/apply_stash.

Data type: String
Table 14. Query parameters
Name Description
None
Table 15. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 16. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 17. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: Obtain the progress of a test suite run

curl 'instance.servicenow.com/api/sn_cicd/progress/a4fae8911bdc00103d374087bc4bcbbd' \
--request GET \
--header 'Accept: application/json' \
--user 'username':'password'

Progress of the apply changes call.

{
    "result": {
        "links": {
            "progress": {
                "id": "a4fae8911bdc00103d374087bc4bcbbd",
                "url": "https://instance.servicenow.com/api/sn_cicd/progress/a4fae8911bdc00103d374087bc4bcbbd"
            },
            "source": {
                "id": "59c4c4d11b5c00103d374087bc4bcb26",
                "url": "https://instance.servicenow.com/api/now/table/sys_app/59c4c4d11b5c00103d374087bc4bcb26"
            }
        },
        "status": "2",
        "status_label": "Successful",
        "status_message": "This operation succeeded",
        "status_detail": "Successfully applied commit 1f14e11a7dedcbfa194beb5875fcdaa15ed8accb from source control",
        "error": "",
        "percent_complete": 100
    }
}

Example: Obtain the progress of an apply changes call. In this case, there were unsaved/uncommitted changes on the instance in Studio, so a stash was created to hold the unsaved changes

curl 'instance.servicenow.com/api/sn_cicd/progress/a4fae8911bdc00103d374087bc4bcbbd' \
--request GET \
--header 'Accept: application/json' \
--user 'username':'password'

Progress providing information on the created stash.

{
"result": {
   "links": {
      "progress": {
         "id": "5b12eca4e0429110f8771827f8fd36a4",
         "url": "https://instance.servicenow.com/api/sn_cicd/progress/5b12eca4e0429110f8771827f8fd36a4"
       },
       "stash": {
         "id": "fc2224e4e0429110f8771827f8fd3634",
         "url": "https://instance.servicenow.com/api/sn_cicd/sc/apply_stash/fc2224e4e0429110f8771827f8fd3634"
}
    },
    "status": "2",
    "status_label": "Successful",
    "status_message": "This operation succeeded",
    "status_detail": "Successfully applied commit fa5626f6f1f7fef677c16b4a0dd8b22ba8a6e311 from source control",
    "error": "",
    "percent_complete": 100
  }
}

Example: cURL request

curl 'instance.servicenow.com/api/sn_cicd/progress/5b12eca4e0429110f8771827f8fd36a4' \
--request GET \
--header 'Accept: application/json' \
--user 'username':'password'

Progress of a test suite run (/sn_cicd/testsuite/run).

{
"result": {
   "links": {
      "progress": {
         "id": "e891389d1b1040103d374087bc4bcb75",
         "url": "https://instance.servicenow.com/api/sn_cicd/progress/e891389d1b1040103d374087bc4bcb75"
       },
       "results": {
         "id": "2891389d1b1040103d374087bc4bcb09",
         "url": "https://instance.servicenow.com/api/sn_cicd/testsuite/results/2891389d1b1040103d374087bc4bcb09"
       }
    },
    "status": "2",
    "status_label": "Successful",
    "status_message": "Suite passed",
    "status_detail": "Suite passed",
    "error": "",
    "percent_complete": 100
  }
}

CI/CD - GET /sn_cicd/testsuite/results/{result_id}

Returns the results of a test suite run based on a specified results identifier.

Call this endpoint after calling /sn_cicd/progress/{progress_id} to obtain the result of the executed test suite.

URL format

Versioned URL: /api/sn_cicd/{api_version}/testsuite/results/{result_id}

Default URL: /api/sn_cicd/testsuite/results/{result_id}

Supported request parameters

Table 19. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
result_id Unique identifier of the test suite results to retrieve. The corresponding /sn_cicd/progress/{progress_id} endpoint call returns this information.

Data type: String
Table 20. Query parameters
Name Description
None
Table 21. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 22. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 23. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

curl 'instance.servicenow.com/api/sn_cicd/testsuite/results/2891389d1b1040103d374087bc4bcb09' \
--request GET \
--header 'Accept: application/json' \
--user 'username':'password'
{
"result": {
   "links": {
       "results": {
           "id": "2891389d1b1040103d374087bc4bcb09",
           "url": "https://instance.servicenow.com/sys_atf_test_suite_result.do?sys_id=2891389d1b1040103d374087bc4bcb09"
       }
   },
   "status": "2",
   "status_label": "Successful",
   "status_message": "",
   "status_detail": "",
   "error": "",
   "test_suite_status": "success",
   "test_suite_duration": "1 Second",
   "rolledup_test_success_count": 1,
   "rolledup_test_failure_count": 0,
   "rolledup_test_error_count": 0,
   "rolledup_test_skip_count": 0,
   "test_suite_name": "Quick Test",
   "child_suite_results": []
 }
}

CI/CD - POST /sn_cicd/app/batch/install

Installs two or more packages in a single specified batch.

A batch can contain any combination of the following types:
  • Application:
    • Scoped applications in the ServiceNow Store that are not owned by your company
    • Scoped or global applications in the application repository that are owned by your company
    • Your application customizations for Store applications in the application repository
  • ServiceNow plugin:

    Application customizations for scoped applications that were packaged in a plugin and were published to the application repository.

Note: This endpoint uses an asynchronous response model. When you call an endpoint, it kicks off the associated function, such as starting the execution of the batch install plan. The endpoint then returns a response message that contains the execution status of the requested function, typically Pending, along with a unique identifier and link. Use this information to obtain additional information about the progress or results of the request.

URL format

Versioned URL: /api/sn_cicd/{api_version}/app/batch/install

Default URL: /api/sn_cicd/app/batch/install

Supported request parameters

Table 25. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 26. Query parameters
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 28. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 29. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

This example initiates a batch installation called Release 2.2 Deployment that contains three packages (one of each type) to install.

curl 'instance.servicenow.com/api/sn_cicd/app/batch/install \
--request POST \
--header 'Accept: application/json' \
--user 'username':'password' \
--data { "name": "Release 2.2 Deployment",
 "packages": [
   {
     "id": "syd_id_abcefghi",
     "type": "application",
     "load_demo_data": false,
     "requested_version": "1.0.2",
     "notes": "User specific text to describe this application install"
   },
   { 
     "id": "syd_id_defabcde",
     "type": "application",
     "requested_version": "1.0.0",
     "requested_customization_version": "2.0.7",
     "notes": "Customization for CSM App1"
   },
   {
     "id": "com.glide.some.plugin",
     "type": "plugin",
     "load_demo_data": true,
     "notes": "Plugin related notes"
   }]
 }
{
"result": {
   "links": {
     "progress": {
       "id": "c159b1e9db1c0010b5e3f6c5ae961903",
       "url": "https://instance.servicenow.com/api/sn_cicd/progress/c159b1e9db1c0010b5e3f6c5ae961903"
     },
     "results": {
       "id": "df24b1e9db2d0110b5e3f6c5ae97c561",
       "url": "https://instance.servicenow.com/api/sn_cicd/app/batch/results/df24b1e9db2d0110b5e3f6c5ae97c561"
     },
     "rollback":{
       "id": "a329f82e871da64c724ba21c82a764f2"
     },
   },
   "status": "0",
   "status_label": "Pending",
   "status_message": "",
   "status_detail": "",
   "error": "",
   "percent_complete": 0
  }
}

CI/CD - POST /sn_cicd/app/batch/rollback/{rollback_id}

Rolls back all of the packages associated with a specific batch installation to their previous versions.

This endpoint works in conjunction with the /sn_cicd/app/batch/install endpoint. The rollback_id is provided in the return results of this endpoint. When this endpoint is called, it rolls back all packages specified in the associated install; you cannot rollback individual packages. If there is no previous version, the endpoint uninstalls the associated package.

Note: This endpoint uses an asynchronous response model. When you call an endpoint, it kicks off the associated function, such as starting the execution of the batch install plan. The endpoint then returns a response message that contains the execution status of the requested function, typically Pending, along with a unique identifier and link. Use this information to obtain additional information about the progress or results of the request.

URL format

Versioned URL: /api/sn_cicd/{api_version}/app/batch/rollback/{rollback_id}

Default URL: /api/sn_cicd/app/batch/rollback/{rollback_id}

Supported request parameters

Table 31. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
rollback_id Sys_id of the batch installation plan for which to rollback the installed packages to their previous versions. This value is returned in the links.rollback.id parameter of the /sn_cicd/app/batch/install endpoint.

Data type: String
Table 32. Query parameters
Name Description
None
Table 33. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 34. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 35. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

This example rolls back all the packages within the specified installation batch plan to their previous version.

curl 'instance.servicenow.com/api/sn_cicd/app/batch/rollback/a329f82e871da64c724ba21c82a764f2 \
--request POST \
--header 'Accept: application/json' \
--user 'username':'password'
{
"result": {
   "links": {
     "progress": {
       "id": "c159b1e9db1c0010b5e3f6c5ae961903",
       "url": "https://instance.servicenow.com/api/sn_cicd/progress/c159b1e9db1c0010b5e3f6c5ae961903"
     },
   "status": "0",
   "status_label": "Pending",
   "status_message": "",
   "status_detail": "",
   "error": "",
   "percent_complete": 0
  }
}

CI/CD - POST /sn_cicd/app_repo/install

Installs the specified application from the application repository onto the instance making the endpoint call.

Using this endpoint you are able to install both unaltered and customized ServiceNow base system and ServiceNow Store applications, customized ServiceNow plugins, and your own ServiceNow applications.

The following outlines the parameters that you need to pass to implement specific use cases. All parameters that are not specified are not passed in and use the associated defaults.

  • To only install the base application and not the corresponding application customizations.
    • sys_id: Sys_id of the base application that has been customized.
    • base_app_version: Version of the base application to install.
  • To install a specified version of application customizations and automatically install the recommended base application version. The recommended base application version is the version of the base application that was installed on the instance at the time that the customizations were last published. Every version of application customizations has a corresponding recommended base application version.
    • sys_id: Sys_id of the application that has been customized.
    • auto_upgrade_base_app: true
    • version: Version of the application customizations to install.
  • To install the latest version of the application customizations and its corresponding recommended base application version.
    • sys_id: Sys_id of the application that has been customized.
    • auto_upgrade_base_app: true
  • To install the latest version of the application customizations, but not upgrade the base application to the application customizations recommended base application version.
    • sys_id: Sys_id of the application that has been customized.
    • auto_upgrade_base_app: false
  • To install application customizations along with the scoped ServiceNow plugin of the current release.
    • scope: Scope of the plugin that has been customized OR
    • sys_id: Sys_id of the application that has been customized. This is not the ID of the plugin.
    • version: Version of the application customizations to install.
  • To install application customizations for an already installed and activated scoped plugin.
    • sys_id: Sys_id of the application that has been customized. This is not the ID of the plugin.
    • auto_upgrade_base_app: false
    • version: Version of the application customizations to install.

Since base plugins can have only one version per family release, the auto_upgrade_base_app and base_app_version parameters do not apply to application customization installs for plugins. To activate a plugin for the first time on an instance, use the /sn_cicd/plugin/{plugin_id}/activate endpoint instead.

Note: This endpoint uses an asynchronous response model. When you call an endpoint, it kicks off the associated function, such as starting the execution of the batch install plan. The endpoint then returns a response message that contains the execution status of the requested function, typically Pending, along with a unique identifier and link. Use this information to obtain additional information about the progress or results of the request.

URL format

Versioned URL: /api/sn_cicd/{api_version}/app_repo/install

Default URL: /api/sn_cicd/app_repo/install

Supported request parameters

Table 37. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 39. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 40. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 41. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

curl 'instance.servicenow.com/api/sn_cicd/app_repo/install?sys_id=2d146921dbd80010caf55268dc9619d8' \
--request POST \
--header 'Accept: application/json' \
--user 'username':'password'
{
"result": {
   "links": {
     "progress": {
        "id": "c159b1e9db1c0010b5e3f6c5ae961903",
        "url": "https://instance.servicenow.com/api/sn_cicd/progress/c159b1e9db1c0010b5e3f6c5ae961903"
      }
   },
   "status": "0",
   "status_label": "Pending",
   "status_message": "",
   "status_detail": "",
   "error": "",
   "percent_complete": 0,
   "rollback_version": "1.1.0"
  }
}

CI/CD - POST /sn_cicd/app_repo/publish

Publishes the specified application and all of its artifacts to the application repository.

Note: If there are uncommitted changes to tracked files when you call this endpoint, it returns a 400 Bad Request status code. You can either commit the changes manually in Studio or call the CI/CD - POST /sn_cicd/sc/apply_changes endpoint to stash the changes. Changes that aren’t tracked in the Customer Updates [sys_update_xml] table are committed automatically after publishing to the application repository. For information about the layout of the changes in the Customer Updates table and a description of the changes that aren’t represented in this table, see Customer Updates table.

URL format

Versioned URL: /api/sn_cicd/{api_version}/app_repo/publish

Default URL: /api/sn_cicd/app_repo/publish

Supported request parameters

Table 43. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 45. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 46. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 47. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example

The following example shows how to publish the application with the specified sys_id and all of its artifacts to the application repository.

curl 'instance.servicenow.com/api/sn_cicd/app_repo/publish?sys_id=4dd9686d1b9800103d374087bc4bcb3d' \
--request POST \
--header 'Accept: application/json' \
--user 'username':'password'
{
"result": {
   "links": {
       "progress": {
           "id": "d174f8e11bd800103d374087bc4bcbd9",
           "url": "https://instance.service-now.com/api/sn_cicd/progress/d174f8e11bd800103d374087bc4bcbd9"
        }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": "",
    "percent_complete": 0
  }
}

CI/CD - POST /sn_cicd/app_repo/rollback

Initiates a rollback of a specified application to a specified version.

Note: The rollback functionality is only available after the installation is complete.

URL format

Versioned URL: /api/sn_cicd/{api_version}/app_repo/rollback

Default URL: /api/sn_cicd/app_repo/rollback

Supported request parameters

Table 49. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 50. Query parameters
Name Description
scope Required if sys_id is not specified. The scope name of the application to rollback.

Data type: String
sys_id Required if scope is not specified. The sys_id of the application to rollback.

Data type: String
version Required. Version of the application that is expected after the rollback operation. If the request is to rollback an App Customization install, then set this field to the version of the base application that the system is expected to have after the rollback operation.

Data type: String
Table 51. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 52. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 53. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

curl 'instance.servicenow.com/api/sn_cicd/app_repo/rollback?sys_id=2d146921dbd80010caf55268dc9619d8&version=1.1.0' \
--request POST \
--header 'Accept: application/json' \
--user 'username':'password'
{
"result": {
   "links": {
      "progress": {
          "id": "f7ddb1eddb1c0010b5e3f6c5ae9619c1",
          "url": "https://instance.service-now.com/api/sn_cicd/progress/f7ddb1eddb1c0010b5e3f6c5ae9619c1"
       }
   },
   "status": "0",
   "status_label": "Pending",
   "status_message": "",
   "status_detail": "",
   "error": "",
   "percent_complete": 0
  }
}

CI/CD - POST /sn_cicd/instance_scan/full_scan

Runs all active checks present in your instance.

You can run checks that are provided with Instance Scan or you can create your own checks. For more information, see Instance Scan.

Note: This endpoint is part of the CICD Instance Scan Execution Service API and is used under the sn_cicd namespace.

URL format

Versioned URL: /api/sn_cicd/{api_version}/instance_scan/full_scan

Default URL: /api/sn_cicd/instance_scan/full_scan

Supported request parameters

Table 55. Parameters
Parameter Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 56. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 57. Response headers
Header Description
None

Status codes

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 58. Status codes
Status codeDescription
200 Successful. The request was successfully processed.
401 The user credentials are incorrect.
403 Forbidden. The user isn’t an admin or doesn’t have the sn_cicd.sys_ci_automation role.
500 Internal server error. An unexpected error occurred while processing the request.

Request body

The API accepts these JSON or XML elements in the request body.

Table 59. Elements accepted in the request body
Element Description
None

Response body

The API returns these JSON or XML elements in the response body.

Table 60. Elements returned in the response body
ElementDescription
error Error message.

Data type: String
links All links and sys_ids associated with the response.

Data type: Object

"links": {
  "progress": {Object}
}
links.progress Describes the progress link information.

Data type: Object

"progress": {
  "id": "String",
  "url": "String"
}
links.progress.id Unique identifier of the progress detail. Use this value when calling the endpoint /sn_cicd/instance_scan/result/{progress_id}.
links.progress.url URL to use to retrieve the progress details.

Data type: String
status Numeric execution state. Used with status_label.
Values:
  • 0 (Pending)
  • 1 (Running)
  • 2 (Successful)
  • 3 (Failed)
  • 4 (Canceled)

Data type: String
status_detail Additional information about the current state.

Data type: String
status_label Execution state description. Used with status.
Values:
  • Canceled
  • Failed
  • Pending
  • Running
  • Successful

Data type: String
status_message Additional information on why the operation failed. Empty if the operation is successful.

Data type: String

Example: Sample cURL request

curl 'instance.service-now.com/api/sn_cicd/instance_scan/full_scan' \
--request POST \
--header 'Accept: application/json' \
--user 'username':'password'
{
"result": {
   "links": {
       "progress": {
           "id": "a4fae8911bdc00103d374087bc4bcbbd",
           "url": "https://instance.service-now/api/sn_cicd/progress/a4fae8911bdc00103d374087bc4bcbbd"
        }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": ""
  }
}

CI/CD - POST /sn_cicd/instance_scan/point_scan

Executes all applicable checks against a specified record.

For example, if you execute a point scan against a Catalog Item, only the checks applicable to the Catalog Item table run, and only the specified record is scanned.

You can run checks that are provided with Instance Scan or you can create your own checks. For more information, see Instance Scan.

Note: This endpoint is part of the CICD Instance Scan Execution Service API and is used under the sn_cicd namespace.

URL format

Versioned URL: /api/sn_cicd/{api_version}/instance_scan/point_scan

Default URL: /api/sn_cicd/instance_scan/point_scan

Supported request parameters

Table 61. Parameters
Parameter Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
target_table Required. Name of the table in which the record to scan resides, such as "Incident."

Data type: String
target_sys_id Required. The sys_id of the record within the specified table to scan.

Data type: String

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 62. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 63. Response headers
Header Description
None

Status codes

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 64. Status codes
Status codeDescription
200 Successful. The request was successfully processed.
400 Bad Request. Invalid or empty query parameters.
401 The user credentials are incorrect.
403 Forbidden. The user isn’t an admin or doesn’t have the sn_cicd.sys_ci_automation role.
500 Internal server error. An unexpected error occurred while processing the request.

Request body

The API accepts these JSON or XML elements in the request body.

Table 65. Elements accepted in the request body
Element Description
None

Response body

The API returns these JSON or XML elements in the response body.

Table 66. Elements returned in the response body
ElementDescription
error Error message.

Data type: String
links All links and sys_ids associated with the response.

Data type: Object

"links": {
  "progress": {Object}
}
links.progress Describes the progress link information.

Data type: Object

"progress": {
  "id": "String",
  "url": "String"
}
links.progress.id Unique identifier of the progress detail. Use this value when calling the endpoint /sn_cicd/instance_scan/result/{progress_id}.
links.progress.url URL to use to retrieve the progress details.

Data type: String
status Numeric execution state. Used with status_label.
Values:
  • 0 (Pending)
  • 1 (Running)
  • 2 (Successful)
  • 3 (Failed)
  • 4 (Canceled)

Data type: String
status_detail Additional information about the current state.

Data type: String
status_label Execution state description. Used with status.
Values:
  • Canceled
  • Failed
  • Pending
  • Running
  • Successful

Data type: String
status_message Additional information on why the operation failed. Empty if the operation is successful.

Data type: String

Example: Sample cURL request

curl 'instance.service-now.com/api/sn_cicd/instance_scan/point_scan?target_table=incident&target_sys_id=2d146921dbd80010caf55268dc9619d8' \
--request POST \
--header 'Accept: application/json' \
--user 'username':'password'
{
"result": {
   "links": {
       "progress": {
           "id": "a4fae8911bdc00103d374087bc4bcbbd",
           "url": "https://instance.service-now/api/sn_cicd/progress/a4fae8911bdc00103d374087bc4bcbbd"
        }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": ""
  }
}

CI/CD - POST /sn_cicd/instance_scan/suite_scan/combo/{combo_sys_id}

Runs a scan using a suite and target (scoped apps or update sets) that have already run previously.

Before calling this endpoint, you must call the /sn_cicd/instance_scan/suite_scan/{suite_sys_id}/scoped_apps or /sn_cicd/instance_scan/suite_scan/{suite_sys_id}/update_sets endpoints, or execute a suite scan in the UI.

Note: This endpoint is part of the CICD Instance Scan Execution Service API and is used under the sn_cicd namespace.

URL format

Versioned URL: /api/sn_cicd/{api_version}/instance_scan/suite_scan/combo/{combo_sys_id}

Default URL: /api/sn_cicd/instance_scan/suite_scan/combo/{combo_sys_id}

Supported request parameters

Table 67. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
combo_sys_id The sys_id of the scan to run. The scan must be an existing scan that you want to re-run. Located in the Combo [scan_combo] table.

Data type: String
Table 68. Query parameters
Name Description
None
Table 69. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 70. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 71. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 72. Status codes
Status codeDescription
200 Successful. The request was successfully processed.
401 The user credentials are incorrect.
403 Forbidden. The user isn’t an admin or doesn’t have the sn_cicd.sys_ci_automation role.
500 Internal server error. An unexpected error occurred while processing the request.

Response body parameters (JSON or XML)

Example: cURL request

curl "https://instance.servicenow.com/api/sn_cicd/instance_scan/suite_scan/combo/245d29cc1bd32010178aed72604bcb4b" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'

Response body - success.

{
  "result": {
    "links": {
      "progress": {
        "id": "c08be5c71b1b2010178aed72604bcb6e",
        "url": "https://instance.servicenow.com/api/sn_cicd/progress/c08be5c71b1b2010178aed72604bcb6e"
      }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": ""
  }
}

CI/CD - POST /sn_cicd/instance_scan/suite_scan/{suite_sys_id}/scoped_apps

Runs all active checks inside a suite against a list of scoped apps.

Note: This endpoint is part of the CICD Instance Scan Execution Service API and is used under the sn_cicd namespace.

URL format

Versioned URL: /api/sn_cicd/{api_version}/instance_scan/suite_scan/{suite_sys_id}/scoped_apps

Default URL: /api/sn_cicd/instance_scan/suite_scan/{suite_sys_id}/scoped_apps

Supported request parameters

Table 73. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
suite_sys_id The sys_id of the suite to run. Located in the Suite [scan_check_suite] table.

Data type: String
Table 74. Query parameters
Name Description
None
Table 75. Request body parameters (XML or JSON)
Name Description
app_scope_sys_ids Required. A list of sys_ids of the scoped applications to scan. Located in the Application [sys_scope] table. The array can't be an empty array.
Data type: Array
app_scope_sys_ids: ["String", "String", "String"]

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 76. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Only supports application/json.
Table 77. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 78. Status codes
Status codeDescription
200 Successful. The request was successfully processed.
401 The user credentials are incorrect.
403 Forbidden. The user isn’t an admin or doesn’t have the sn_cicd.sys_ci_automation role.
500 Internal server error. An unexpected error occurred while processing the request.

Response body parameters (JSON or XML)

Example: cURL request

This example runs all active checks inside a suite against one scoped application.

curl "https://instance.servicenow.com/api/sn_cicd/instance_scan/suite_scan/833655cc1b94101046e87733cd4bcb4e/scoped_apps" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{app_scope_sys_ids: [\"078e8020950f12a215a92e8ad9b346e0\"]}" \
--user 'username':'password'

Response body - success.

{
  "result": {
    "links": {
      "progress": {
        "id": "147fc14b1b572010178aed72604bcbca",
        "url": "https://instance.servicenow.com/api/sn_cicd/progress/147fc14b1b572010178aed72604bcbca"
      }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": ""
  }
}

CI/CD - POST /sn_cicd/instance_scan/suite_scan/{suite_sys_id}/update_sets

Runs all active checks inside a suite against a list of update sets.

Note: This endpoint is part of the CICD Instance Scan Execution Service API and is used under the sn_cicd namespace.

URL format

Versioned URL: /api/sn_cicd/{api_version}/instance_scan/suite_scan/{suite_sys_id}/update_sets

Default URL: /api/sn_cicd/instance_scan/suite_scan/{suite_sys_id}/update_sets

Supported request parameters

Table 79. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
suite_sys_id The sys_id of the suite to run. Located in the Suite [scan_check_suite] table.

Data type: String
Table 80. Query parameters
Name Description
None
Table 81. Request body parameters (XML or JSON)
Name Description
update_set_sys_ids Required. A list of sys_ids of the update sets to scan. Located in the Update Set [sys_update_set] table. The array can't be an empty array.
Data type: Array
update_set_sys_ids: ["String", "String", "String"]

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 82. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Only supports application/json.
Table 83. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Table 84. Status codes
Status codeDescription
200 Successful. The request was successfully processed.
401 The user credentials are incorrect.
403 Forbidden. The user isn’t an admin or doesn’t have the sn_cicd.sys_ci_automation role.
500 Internal server error. An unexpected error occurred while processing the request.

Response body parameters (JSON or XML)

Example: cURL request

This example runs all active checks inside a suite against one update set.

curl "https://instance.servicenow.com/api/sn_cicd/instance_scan/suite_scan/833655cc1b94101046e87733cd4bcb4e/update_sets" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{update_set_sys_ids: [\"7abef63c1b572010178aed72604bcbfd\"]}" \
--user 'username':'password'

Response body - success.

{
  "result": {
    "links": {
      "progress": {
        "id": "d27511031b972010178aed72604bcb72",
        "url": "https://instance.servicenow.com/api/sn_cicd/progress/d27511031b972010178aed72604bcb72"
      }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": ""
  }
}

CI/CD - POST /sn_cicd/plugin/{plugin_id}/activate

Activates the specified plugin.

URL format

Versioned URL: /api/sn_cicd/{api_version}/plugin/{plugin_id}/activate

Default URL: /api/sn_cicd/plugin/{plugin_id}/activate

Supported request parameters

Table 85. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
plugin_id Unique identifier of the plugin. You can locate this identifier on the Plugins page within the card of the desired plugin; identified with the name "ID".

Data type: String
Table 86. Query parameters
Name Description
None
Table 87. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 88. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 89. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

curl 'instance.servicenow.com/api/sn_cicd/plugin/com.glide.web_service_aggregate/activate' \
--request POST \
--header 'Accept: application/json' \
--user 'username':'password'
{
"result": {
   "links": {
      "progress": {
          "id": "5b3f052ddb580010caf55268dc961963",
          "url": "https://instance.service-now.com/api/sn_cicd/progress/5b3f052ddb580010caf55268dc961963"
       }
   },
   "status": "0",
   "status_label": "Pending",
   "status_message": "",
   "status_detail": "",
   "error": "",
   "percent_complete": 0
  }
}

CI/CD - POST /sn_cicd/plugin/{plugin_id}/rollback

Rolls back the specified plugin to the previous installed version. If no prior version has been installed, returns an error.

URL format

Versioned URL: /api/sn_cicd/{api_version}plugin/{plugin_id}/rollback

Default URL: /api/sn_cicd/plugin/{plugin_id}/rollback

Supported request parameters

Table 91. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
plugin_id Unique identifier of the plugin. You can locate this identifier on the Plugins page within the card of the desired plugin; identified with the name "ID".

Data type: String
Table 92. Query parameters
Name Description
None
Table 93. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 94. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 95. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

curl 'instance.servicenow.com/api/sn_cicd/plugin/com.glide.web_service_aggregate/rollback' \
--request POST \
--header 'Accept: application/json' \
--user 'username':'password'
{
"result": {
   "links": {
      "progress": {
         "id": "6185dd61db980010caf55268dc961916",
          "url": "https://instance.service-now.com/api/sn_cicd/progress/6185dd61db980010caf55268dc961916"
        }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": "",
    "percent_complete": 0
  }
}

CI/CD - POST /sn_cicd/sc/apply_changes

Starts applying changes from a remote source control to a specified local application or application-customization.

URL format

Versioned URL: /api/sn_cicd/{api_version}/sc/apply_changes

Default URL: /api/sn_cicd/sc/apply_changes

Supported request parameters

Table 97. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 99. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 100. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 101. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

curl 'https://instance.servicenow.com/api/sn_cicd/sc/apply_changes?app_sys_id=043db024db737300a9a754e4dc961915' \
--request POST \
--header 'Accept: application/json' \
--user 'username':'password'
{
"result": {
   "links": {
       "progress": {
           "id": "a4fae8911bdc00103d374087bc4bcbbd",
           "url": "https://instance.service-now/api/sn_cicd/progress/a4fae8911bdc00103d374087bc4bcbbd"
        }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": "",
    "percent_complete": 0
  }
}

CI/CD - POST /sn_cicd/sc/apply_stash/{stash_id}

Starts applying a previously generated "stash" of changes from a remote source control to a specified local application or application-customization.

This endpoint works in conjunction with the POST/api/sn_cicd/sc/apply_changes and CI/CD - GET /sn_cicd/progress/{progress_id} endpoints. When the POST /api/sn_cicd/sc/apply_changes endpoint is called, any unsaved or uncommitted changes in App Engine Studio on the associated instance are saved into the database as a stash.

The way to determine whether a stash was created when the changes were initially applied is to call the GET /sn_cicd/progress/{progress_id} endpoint. If a stash was created, the sys_id (stash_id) and URL of the stash are returned. To apply the stashed changes to the associated application, call this apply_stash endpoint using the stash_id returned by the progress endpoint.

URL format

Versioned URL: /api/sn_cicd/{api_version}/sc/apply_stash/{stash_id}

Default URL: /api/sn_cicd/sc/apply_stash/{stash_id}

Supported request parameters

Table 103. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
stash_id Unique identifier of the stash to apply. This value is returned in the links.stash.id parameter in the corresponding CI/CD - GET /sn_cicd/progress/{progress_id} endpoint call.

Data type: String
Table 104. Query parameters
Name Description
None
Table 105. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 106. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Content-Type Data format of the request body. Supported types: application/json or application/xml.

Default: application/json
Table 107. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

The following code example shows how to call the apply_stash endpoint for stash_id fc2224e4e0429110f8771827f8fd3634.

curl "https://instance.servicenow.com/api/sn_cicd/sc/apply_stash/fc2224e4e0429110f8771827f8fd3634"\
--request POST \
--header "Accept:application/json" \
--header "Content_Type:application/json" \
--user 'username':'password'

The stash is pending, so not yet applied.

{
  "result": {
    "links": {
      "progress": {
        "id": "6b04ec28e0429110f8771827f8fd36a4",
        "url": "https://instance.servicenow.com/api/sn_cicd/progress/6b04ec28e0429110f8771827f8fd36a4"
      }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": "",
    "percent_complete": 0
  }
}

CI/CD - POST /sn_cicd/sc/import

Imports an application using the specified repository URL and branch name.

Use this endpoint to import an application from source control in the calling instance so you can then use Continuous Integration and Continuous Delivery (CICD) endpoints, such as /sn_cicd/sc/apply_changes, to deploy the application to upper environments.

Note: Before using this endpoint, a Git repository that has been setup by another instance using Link to source control must be available.

URL format

Versioned URL: /api/sn_cicd/{api_version}/sc/import

Default URL: /api/sn_cicd/sc/import

Supported request parameters

Table 109. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 111. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 112. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 113. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

The following example shows how to import the application located at https://code.devsnc.com/some-user/ncRegrApp1.git in the main_branch.

curl "https://instance.servicenow.com/api/sn_cicd/sc/import?repo_url=https%3A%2F%2Fcode.devsnc.com%2Fsome-user%2FncRegrApp1.git&branch_name=main_branch&credential_sys_id=af9b6d6180feb010f8779c30d4dd6b6b" \
--request POST \
--header "Accept:application/json" \
--user 'admin':'admin'

Returns the progress of the import.

{
  "result": {
    "links": {
      "progress": {
        "id": "a18c06ea64f23010f87769cd983d4574",
        "url": "https://instance.servicenow.com/api/sn_cicd/progress/a18c06ea64f23010f87769cd983d4574"
      }
    },
    "status": "0",
    "status_label": "Pending",
    "status_message": "",
    "status_detail": "",
    "error": "",
    "percent_complete": 0
  }
}

CI/CD - POST /sn_cicd/testsuite/run

Starts a specified automated test suite. The test suite runs on the instance from which the endpoint was called.

Note: If the suite you are running contains UI tests, you must have either a scheduled Client Test Runner open, or be able to configure headless Test Runner execution. To learn more see Headless browser for Automated Test Framework.

URL format

Versioned URL: /api/sn_cicd/{api_version}/testsuite/run

Default URL: /api/sn_cicd/testsuite/run

Supported request parameters

Table 115. Path parameters
Name Description
api_version Optional. Version of the endpoint to access. For example, v1 or v2. Only specify this value to use an endpoint version other than the latest.

Data type: String
Table 117. Request body parameters (XML or JSON)
Name Description
None

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Table 118. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 119. Response headers
Header Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Response body parameters (JSON or XML)

Example: cURL request

curl 'https://instance.servicenow.com/api/sn_cicd/testsuite/run?test_suite_sys_id=632e43900b20220050192f15d6673a7e' \
--request POST \
--header 'Accept: application/json' \
--user 'username':'password'
{
"result": {
   "links": {
       "progress": {
           "id": "0578a8d91bdc00103d374087bc4bcbcc",
           "url": "https://instance.service-now.com/api/sn_cicd/progress/0578a8d91bdc00103d374087bc4bcbcc"
        }
   },
   "status": "0",
   "status_label": "Pending",
   "status_message": "",
   "status_detail": "",
   "error": "",
   "percent_complete": 0
  }
}

Failure response:

{
"result": {
    "status": "3",
    "status_label": "Failed",
    "status_message": "",
    "status_detail": "",
    "error": "Scheduled test/suite execution is disabled. Change the value of property 'sn_atf.schedule.enabled' to true to enable it"
  }
}