Get started with Harness API
Any resource you can create in Harness, you can also create with the Harness REST API.
For detailed documentation of endpoints and other Harness API reference information, go to the Harness API reference documentation.
Requirements
To use Harness API to manage a resource, you must have the necessary permissions to view, create/edit, or delete that resource. You need one of the following default roles or an equivalent custom role: Account Administrator, Organization Admin, Project Admin.
You need an understanding of Harness, RBAC in Harness, sending API requests, and mechanisms for sending requests, such as curl.
Create a Harness API key and token
You need to use API keys to authenticate requests. Create an API key in your Harness user profile, add tokens to the key, and then use the token in your API requests. For more information, go to Manage API keys.
- Service accounts: You can use service account tokens instead of personal API keys and tokens. For more information, go to Manage service accounts.
- CORS: Harness API supports cross-origin resource sharing (CORS). This allows interactions between resources from different origins, and it is normally prohibited to prevent malicious behavior. Each API request must provide authentication credentials, either a personal access token or a service account token.
Go to your user profile in Harness.
Under My API Keys, select API Key.
Enter a Name for the API key. Description and Tags are optional.
Select Save to create your API key.
Select Token under your new API key.
Enter a Name for the token. Description and Tags are optional.
Select Set Expiration Date and enter an expiration date in
mm/dd/yyyyformat.Select Generate Token and copy the token.
cautionThe token is only displayed once. Store the token somewhere secure that you can access when you make API requests.
Your API keys carry many privileges. Don't store them in publicly-accessible areas.
After rotating tokens make sure you always use the new token.
Get your account ID
To send API requests, you need your Harness account ID.
You can find your account ID in any Harness URL, for example:
https://app.harness.io/ng/#/account/ACCOUNT_ID/home/get-started
Use the API
Once you have a token and your account ID, you can start sending requests.
The following examples demonstrate how to create a project, connector, and pipeline using curl and the Harness APIs. Although these examples use curl, the Harness APIs support many languages, such as Go, Java, and Node.js. You can find examples for other supported languages in the Harness API reference documentation.
Harness uses rate limiting to control traffic and ensure the stability of the platform. For platform rate limit information, go to Rate limits.
Example: Create a project through API
A Harness project is a group of Harness modules and their pipelines and other resources.
The following curl command creates a Harness project called APISample in the default Harness organization. To use this command replace ACCOUNT_ID with your Harness account ID, and replace API_KEY_TOKEN with your token. If you want to create a project under a different organization, replace default in the command with the desired organization ID.
curl -i -X POST \
'https://app.harness.io/ng/api/projects?accountIdentifier=ACCOUNT_ID&orgIdentifier=default' \
-H 'Content-Type: application/json' \
-H 'x-api-key: API_KEY_TOKEN' \
-d '{
"project": {
"orgIdentifier": "default",
"identifier": "apisample",
"name": "APISample",
"color": "#0063F7",
"modules": [],
"description": "",
"tags": {}
}
}'
A successful response includes the project data from the request, as well as creation timestamps, metadata (which may be null), and a correlation ID. For example:
{
"status": "SUCCESS",
"data": {
"project": {},
"createdAt": 0,
"lastModifiedAt": 0,
"isFavorite": true
},
"metaData": { },
"correlationId": "string"
}
If the response is successful, go to your Projects in Harness to find your APISample project.
Example: Create a connector through API
Harness connectors contain information necessary to integrate and communicate with third-party tools, such as Docker registries, cloud providers, a source control repositories.
The following curl command creates a Docker registry connector called dockerhub that connects to Docker Hub anonymously. The connector is created in the default Harness organization under the APISample project.
To use this command replace ACCOUNT_ID with your Harness account ID, and replace API_KEY_TOKEN with your token.
If you want to create your connector under a different organization, replace default in the command with the desired organization ID. If you want to create your connector under a different project, replace apisample with the desired project ID.
curl -i -X POST \
'https://app.harness.io/ng/api/connectors?accountIdentifier=ACCOUNT_ID' \
-H 'Content-Type: application/json' \
-H 'x-api-key: API_KEY_TOKEN' \
-d '{
"connector": {
"name": "dockerhub",
"identifier": "dockerhub",
"description": "",
"accountIdentifier": "ACCOUNT_ID",
"orgIdentifier": "default",
"projectIdentifier": "apisample",
"tags": {},
"type": "DockerRegistry",
"spec": {
"connectorType": "DockerConnector",
"dockerRegistryUrl": "https://index.docker.io/v2/",
"providerType": "DockerHub",
"auth":
"type": "Anonymous"
}
}
}'
You can create all types of connectors with this endpoint. For this endpoint's specifications, go to the Harness API reference documentation.
A successful response includes the connector data from the request, as well as creation timestamps, various metadata and settings, and a correlation ID. For example:
{
"status": "SUCCESS",
"data": {
"connector": {},
"createdAt": 0,
"lastModifiedAt": 0,
"status": {},
"activityDetails": {},
"harnessManaged": true,
"gitDetails": {},
"entityValidityDetails": {},
"governanceMetadata": {},
"isFavorite": true
},
"metaData": { },
"correlationId": "string"
}
If the response is successful, you can find your new connector in Harness in your APISample project's Connectors.
Example: Create a pipeline through API
A pipelines are end-to-end workflows. There are several types of pipelines across the Harness modules.
The following curl command creates a simple CD pipeline that contains a hello world shell script. The pipeline uses Runtime Inputs (<+input>) for most settings. The pipeline is created in the default Harness organization under the APISample project.
To use this command replace ACCOUNT_ID with your Harness account ID, and replace API_KEY_TOKEN with your token.
If you want to create the pipeline under a different organization, replace default in the command with the desired organization ID. If you want to create the pipeline under a different project, replace apisample with the desired project ID.
curl -i -X POST \
'https://app.harness.io/pipeline/api/pipelines/v2?accountIdentifier=ACCOUNT_IT&orgIdentifier=default&projectIdentifier=apisample' \
-H 'Content-Type: application/yaml' \
-H 'x-api-key: API_KEY_TOKEN' \
-d 'pipeline:
name: api example
identifier: api_example
allowStageExecutions: false
projectIdentifier: apisample
orgIdentifier: default
tags: {}
stages:
- stage:
name: Sample Deploy Stage
identifier: Sample_Deploy_Stage
description: ""
type: Deployment
spec:
serviceConfig:
serviceRef: <+input>
serviceDefinition:
spec:
variables: []
type: Kubernetes
infrastructure:
environmentRef: <+input>
infrastructureDefinition:
type: KubernetesDirect
spec:
connectorRef: <+input>
namespace: <+input>
releaseName: release-<+INFRA_KEY>
allowSimultaneousDeployments: false
execution:
steps:
- step:
name: shell
identifier: shell
type: ShellScript
spec:
shell: Bash
onDelegate: true
source:
type: Inline
spec:
script: echo "hello world!"
environmentVariables: []
outputVariables: []
executionTarget: {}
timeout: 10m
rollbackSteps: []
tags: {}
failureStrategies:
- onFailure:
errors:
- AllErrors
action:
type: StageRollback
'
For more information about this endpoint, go to the Harness API reference documentation.
A successful response includes the pipeline data from the request, as well as the pipeline ID, various metadata, and a correlation ID. For example:
{
"status": "SUCCESS",
"data": {
"identifier": "string",
"governanceMetadata": {}
},
"metaData": { },
"correlationId": "string"
}
If the response is successful, you can find your new pipeline in Harness in your APISample project's Pipelines.
Reference documentation
For detailed documentation of endpoints and other Harness API reference information, go to the Harness API reference documentation.
Error responses
Harness uses conventional HTTP response codes to indicate the success or failure of an API request.
| HTTPS Status Code | Summary |
|---|---|
| 200 - OK | The request has been processed successfully on the server. |
| 400 - Bad Request | The request was not processed successfully due to incorrect syntax or missing parameters. |
| 401 - Unauthorized | The request was unauthorized due to an invalid API Key. |
| 402 - Request Failed | The request cannot be processed. |
| 403 - Forbidden | The API Key does not have permission to perform the request. |
| 404 - Not Found | The requested resource does not exist. |
| 429 - Server Errors | The rate limit is exceeded. |
| 500, 502, 503, 504 - Server Errors | The Harness server encountered an unexpected error. |