Config-As-Code Using REST APIs
Harness includes many REST APIs that allow you to have full control over its Config-as-Code functionality.
The REST APIs allow you to perform CRUD operations on Harness YAML entities.
In this topic:
- Before You Begin
- Harness Permissions Required
- REST API Summary
- Create and Update Multiple YAML Entities
- Delete YAML Entities
- Create and Update a Single YAML Entity
- Fetch Config-as-Code Directory Structure
- Fetch YAML Content for a Single Entity
- Notes
Before You Begin
Harness Permissions Required
The Harness User account that executes the API must belong to a User Group with the following Account Permission:
- Account Permission:
Administer Other Account Functions
. - Application Permission:
Action: Update
on any Permission Types that are needed (or all types).
REST API Summary
Harness provides CRUD APIs that allow you to have full control over your account’s Config-as-Code YAML without having to use the Harness Manager or sync with a Git repo.
Authorization for the APIs is performed using Harness API keys. Ensure you have Harness API keys before using the commands below.
For each API, you use a CURL command that contains the URL and ID of the Harness account and the type of change to make:
https://app.harness.io/gateway/api/setup-as-code/yaml/{change_type}?accountId={account_ID}
You also include headers for Content-Type and authentication:
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: [API_key]'
That’s it. You can simply run CRUD operations via REST API to manage your Harness Config-as-Code YAML.
Create and Update Multiple YAML Entities
You can use a ZIP file to create or replace multiple YAML entities in your Harness account.
The upsert-entities
parameter identifies that this is a Create or Update operation.
URL: /api/setup-as-code/yaml/upsert-entities?accountId={accountId}
HTTP Method: POST
Query Param: accountId
is your account identifier (ID).
Request body: a ZIP (.zip
) file consisting of the YAML files for a Harness Application(s) and Application entities (Services, Workflows, Pipelines, Environments, Triggers, Infrastructure Provisioners).
Sample ZIP file:
harness-docs/Setup.zip at main · wings-software/harness-docs
Click Download to view the contents of the ZIP file.
Sample cURL:
curl --location --request POST 'https://app.harness.io/gateway/api/setup-as-code/yaml/upsert-entities?accountId=12345678910' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: Bearer {bearer_token}' \
--form '[email protected]/Users/johndoe/Documents/SampleApp.zip'
API key example:
curl --location --request POST 'https://app.harness.io/gateway/api/setup-as-code/yaml/upsert-entities?accountId=12345678910' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {api_key}' \
--form '[email protected]"/Users/johndoe/Downloads/Setup.zip"'
Delete YAML Entities
The delete-entities
parameter identifies that this is a Delete operation.
A comma-separated list of file paths identifies the entities to delete.
URL: /api/setup-as-code/yaml/delete-entities?accountId={accountId}&filePaths={comma-separated-list-of-filePaths}
The filePaths
should be a full path to the YAML file(s) you want to delete. For example, the following path is to a Kubernetes manifest:
1filePaths=Setup/Applications/test%20app/Services/test3/Manifests/Files/templates/deployment.yaml
HTTP Method: DELETE
Query Params:
accountId
is your account identifier (ID).filePaths
is a comma-separated list of filePath(s).
Response: status code 200 OK
if successful, error message if failed.
Sample cURL:
curl --location --request DELETE 'https://app.harness.io/gateway/api/setup-as-code/yaml/delete-entities?accountId=12345678910&filePaths=Setup/Applications/test%20app/Services/test3/Manifests/Files/templates/deployment.yaml' \
--header 'accept: application/json, text/plain, */*' \
--header 'authorization: Bearer {bearer_token}'
API key example:
curl --location --request DELETE 'https://app.harness.io/gateway/api/setup-as-code/yaml/delete-entities?accountId=12345678910&filePaths=Setup/Applications/test%20app/Services/test3/Manifests/Files/templates/deployment.yaml' \
--header 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {api_key}'
Create and Update a Single YAML Entity
Instead of posting a ZIP file to create or update all of the entities in an Application, you can post a single YAML change.
You simply provide the full path to the YAML file and the YAML content (yamlContent
) to create/update.
The content must identify the YAML key and value with careful attention paid to any quotes.
For example, here's a line in YAML that you want to change:
harnessApiVersion: '1.0'
The yamlContent
must escape the quotes:
'yamlContent={key_name}: '\''1.0'\''
URL: /api/setup-as-code/yaml/upsert-entity?accountId={accountId}&yamlFilePath={yamlFilePath}
HTTP Method: POST
Query Params:
accountId
is your account identifier (ID).filePaths
is a comma-separated list of filePath(s).yamlContent
is the form-data parameter holding the YAML content to be created/updated.
Sample curl:
curl -X POST \
'https://app.harness.io/gateway/api/setup-as-code/yaml/upsert-entity?accountId=12345678910&yamlFilePath=Setup/Applications/test%20app/Index.yaml' \
-H 'accept: application/json, text/plain, */*' \
-H 'authorization: Bearer {bearer_token}' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F 'yamlContent=harnessApiVersion: '\''1.0'\''
type: APPLICATION'
API key example:
curl -X POST \
'https://app.harness.io/gateway/api/setup-as-code/yaml/upsert-entity?accountId=12345678910&yamlFilePath=Setup/Applications/test%20app/Index.yaml' \
-H 'accept: application/json, text/plain, */*' \
--header 'x-api-key: {api_key}' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F 'yamlContent=harnessApiVersion: '\''1.0'\''
type: APPLICATION'
Fetch Config-as-Code Directory Structure
You can fetch the directory structure for a Harness Application using the directory
parameter.
URL: /api/setup-as-code/yaml/directory?accountId={accountId}&appId={applicationId}
Query Params:
accountId
is your account identifier (ID).appId
is the Application identifier (ID).
HTTP Method: GET
Sample cURL:
curl --location --request GET 'https://app.harness.io/gateway/api/setup-as-code/yaml/directory?accountId=12345678910&appId=fCLnFhwsTryU-HEdKDVZ1g' \
--header 'accept: application/json' \
--header 'content-type: application/json; charset=utf-8' \
--header 'x-api-key: {api_key}'
API key example:
curl --location --request GET 'https://app.harness.io/gateway/api/setup-as-code/yaml/directory?accountId=12345678910&appId=fCLnFhwsTryU-HEdKDVZ1g' \
--header 'accept: application/json' \
--header 'content-type: application/json; charset=utf-8' \
--header 'x-api-key: {api_key}'
Fetch YAML Content for a Single Entity
Using the response from the Fetch Config-as-Code Directory Structure API (/api/setup-as-code/yaml/directory
), you can fetch the YAML content of an individual Application or account-level entity based on its restName
and uuid
.
For example, here’s the response from a /api/setup-as-code/yaml/directory
API call:

For all Application-level entities like Service, Workflow, Pipeline etc., you can use the API to fetch YAML content.
URL: /api/setup-as-code/yaml/{node.restName}/{node.uuid}?accountId={accountId}&appId={appId}
Every node in the tree directory structure returned using the directory
parameter has an associated restName
property and a uuid
. These can be used in the API.
Query Params:
node.restName
the name of the Harness entity type:workflows, services, pipelines, environments
, etc.node.uuid
is the universally unique identifier (UUID) of the node.accountId
is your account identifier (ID).appId
is the Application identifier (ID).
Sample cURL:
curl --location --request GET 'https://qa.harness.io/gateway/api/setup-as-code/yaml/services/pT65F_wHTzSALR2qYknX9Q?accountId=12345678910&appId=fCLnFhwsTryU-HEdKDVZ1g' \
--header 'authorization: Bearer {bearer_token}'
Here node
is a node in the YAML tree.
Similarly, for all account-level entities like Cloud providers and Connector, the API call would look like this:
/api/setup-as-code/yaml/{node.restName}/{node.uuid}?accountId={accountId}
Notes
- To find the bearer token for your session, open Dev Tools in your browser and search for bearer:
