Create and manage organizations in your account. You use organizations to group together related projects. For example, you can use an organization to group together projects within a business unit or division.
- Commit resource changes
List executions
Create execution
Show execution
Update execution
Upload resource change page
Get resource change indexed page
List resource change rows
Get resource change detail
Get resource change detail by address
Get resource change filter counts
Begin resource change upload
List cost changes
List cost changes for all stages
List cost changes for all stages by modules
Get dependency graph
List resource changes
List resource changes for all stages
Get resource change counts
Get resource change page
Get risk assessment
Commit resource changes
Harness APIs (1.0)
The Harness Software Delivery Platform uses OpenAPI Specification v3.0. Harness constantly improves these APIs. Please be aware that some improvements could cause breaking changes.
The Harness API allows you to integrate and use all the services and modules we provide on the Harness Platform. If you use client-side SDKs, Harness functionality can be integrated with your client-side automation, helping you reduce manual efforts and deploy code faster.
For more information about how Harness works, read our documentation or visit the Harness Developer Hub.
The Harness API is a RESTful API that uses standard HTTP verbs. You can send requests in JSON, YAML, or form-data format. The format of the response matches the format of your request. You must send a single request at a time and ensure that you include your authentication key. For more information about this, go to Authentication.
Before you start integrating, get to know our API better by reading the following topics:
The methods you need to integrate with depend on the functionality you want to use. Work with your Harness Solutions Engineer to determine which methods you need.
To authenticate with the Harness API, you need to:
- Generate an API token on the Harness Platform.
- Send the API token you generate in the
x-api-keyheader in each request.
To generate an API token, complete the following steps:
- Go to the Harness Platform.
- On the left-hand navigation, click My Profile.
- Click +API Key, enter a name for your key and then click Save.
- Within the API Key tile, click +Token.
- Enter a name for your token and click Generate Token. Important: Make sure to save your token securely. Harness does not store the API token for future reference, so make sure to save your token securely before you leave the page.
Send the token you created in the Harness Platform in the x-api-key header. For example: x-api-key: YOUR_API_KEY_HERE
The structure for each request and response is outlined in the API documentation. We have examples in JSON and YAML for every request and response. You can use our online editor to test the examples.
| Field Name | Type | Default | Description |
|---|---|---|---|
| identifier | string | none | URL-friendly version of the name, used to identify a resource within it's scope and so needs to be unique within the scope. |
| name | string | none | Human-friendly name for the resource. |
| org | string | none | Limit to provided org identifiers. |
| project | string | none | Limit to provided project identifiers. |
| description | string | none | More information about the specific resource. |
| tags | map[string]string | none | List of labels applied to the resource. |
| order | string | desc | Order to use when sorting the specified fields. Type: enum(asc,desc). |
| sort | string | none | Fields on which to sort. Note: Specify the fields that you want to use for sorting. When doing so, consider the operational overhead of sorting fields. |
| limit | int | 30 | Pagination: Number of items to return. |
| page | int | 1 | Pagination page number strategy: Specify the page number within the paginated collection related to the number of items in each page. |
| created | int64 | none | Unix timestamp that shows when the resource was created (in milliseconds). |
| updated | int64 | none | Unix timestamp that shows when the resource was last edited (in milliseconds). |
Harness uses conventional HTTP status codes to indicate the status of an API request. Generally, 2xx responses are reserved for success and 4xx status codes are reserved for failures. A 5xx response code indicates an error on the Harness server.
| Error Code | Description |
|---|---|
| 200 | OK |
| 201 | Created |
| 202 | Accepted |
| 204 | No Content |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 412 | Precondition Failed |
| 415 | Unsupported Media Type |
| 500 | Server Error |
To view our error response structures, go here.
The current version of our Beta APIs is yet to be announced. The version number will use the date-header format and will be valid only for our Beta APIs.
All our beta APIs are versioned as a Generation, and this version is included in the path to every API resource. For example, v1 beta APIs begin with app.harness.io/v1/, where v1 is the API Generation.
The version number represents the core API and does not change frequently. The version number changes only if there is a significant departure from the basic underpinnings of the existing API. For example, when Harness performs a system-wide refactoring of core concepts or resources.
We use pagination to place limits on the number of responses associated with list endpoints. Pagination is achieved by the use of limit query parameters. The limit defaults to 30. Its maximum value is 100.
Following are the pagination headers supported in the response bodies of paginated APIs:
- X-Total-Elements : Indicates the total number of entries in a paginated response.
- X-Page-Number : Indicates the page number currently returned for a paginated response.
- X-Page-Size : Indicates the number of entries per page for a paginated response.
For example:
X-Total-Elements : 30
X-Page-Number : 0
X-Page-Size : 10Download OpenAPI description
Overview
Languages
Servers
Harness host URL
https://app.harness.io
Vanity URL
https://{vanity}
Request
Get every attribute document matching a Terraform resource address.
This is the address-keyed counterpart to get-resource-change-detail. Consumers that hold a Terraform address — the dependency graph, risk map, future agents — can fetch the matching attribute documents without first discovering an ordinal via list-resource-change-rows, and without knowing which category the address lives in.
Omit category to search every category. The same address can appear as a planned change and as drift, or as a planned change and as a provisioned resource; every match is returned and the caller chooses. Pass category to restrict to one bucket. Pass change to restrict planned_changes and drift_changes rows to one change type — for example the added half of a replace.
Only the bytes belonging to each matching row's attribute document are read, so the cost of a detail request is independent of how large the plan or the stored snapshot is.
A 404 means no row is retrievable — an unknown address, an uncommitted snapshot, or a snapshot whose attribute data has passed its retention window while the row survives. It is not an error worth retrying.
Security
x-api-key
- Harness host URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/by-address/{resource_address}
- Vanity URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/by-address/{resource_address}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://app.harness.io/iacm/api/orgs/n7m/projects/n/executions/id/mdr/resource-changes/by-address/module.app.aws_s3_bucket.app_bucket?category=planned_changes&change=added' \
-H 'Harness-Account: whf' \
-H 'x-api-key: YOUR_API_KEY_HERE'OK response.
Example: [{"attributes":{"ami":"ami-830c94ec","instance_type":"t2.micro"},"category":"planned_changes","change":"added","change_count":3,"changes":{"Aut rerum delectus voluptas officiis et.":{"change":"added","drift":false,"new":"new value","old":"old value","sensitive":true},"Et quisquam reprehenderit alias itaque ut.":{"change":"added","drift":false,"new":"new value","old":"old value","sensitive":true}},"drift":false,"mode":"resource","module":"root","name":"app_bucket","ordinal":17,"provider":"AWS","resource_address":"module.app.aws_s3_bucket.app_bucket","resource_id":"arn:aws:s3:::my-bucket","sensitive":false,"sensitive_attributes":["password"],"type":"aws_s3_bucket","value":"i-0abc123"},{"attributes":{"ami":"ami-830c94ec","instance_type":"t2.micro"},"category":"planned_changes","change":"added","change_count":3,"changes":{"Aut rerum delectus voluptas officiis et.":{"change":"added","drift":false,"new":"new value","old":"old value","sensitive":true},"Et quisquam reprehenderit alias itaque ut.":{"change":"added","drift":false,"new":"new value","old":"old value","sensitive":true}},"drift":false,"mode":"resource","module":"root","name":"app_bucket","ordinal":17,"provider":"AWS","resource_address":"module.app.aws_s3_bucket.app_bucket","resource_id":"arn:aws:s3:::my-bucket","sensitive":false,"sensitive_attributes":["password"],"type":"aws_s3_bucket","value":"i-0abc123"},{"attributes":{"ami":"ami-830c94ec","instance_type":"t2.micro"},"category":"planned_changes","change":"added","change_count":3,"changes":{"Aut rerum delectus voluptas officiis et.":{"change":"added","drift":false,"new":"new value","old":"old value","sensitive":true},"Et quisquam reprehenderit alias itaque ut.":{"change":"added","drift":false,"new":"new value","old":"old value","sensitive":true}},"drift":false,"mode":"resource","module":"root","name":"app_bucket","ordinal":17,"provider":"AWS","resource_address":"module.app.aws_s3_bucket.app_bucket","resource_id":"arn:aws:s3:::my-bucket","sensitive":false,"sensitive_attributes":["password"],"type":"aws_s3_bucket","value":"i-0abc123"}]
Flat attribute document for a provisioned resource or data source.
Example: {"ami":"ami-830c94ec","instance_type":"t2.micro"}
Category this row belongs to.
Enum"planned_changes""drift_changes""resources""outputs"
Example: "planned_changes"
Change made to this resource. Populated for planned_changes and drift_changes rows.
Enum"added""changed""deleted""replaced""unchanged""imported""removed"
Example: "added"
Count of changed attributes on this resource. Populated for planned_changes and drift_changes rows.
Example: 3
Per-attribute before and after values.
Example: {"Quia ad amet nam cupiditate qui.":{"change":"added","drift":false,"new":"new value","old":"old value","sensitive":true}}
Whether this row came from drift detection rather than a plan. True exactly when category is drift_changes.
Example: false
Whether the row is a managed resource or a data source. Populated for resources rows.
Enum"resource""data"
Example: "resource"
Name associated with the resource, or the output name for outputs rows.
Example: "app_bucket"
Zero-based position of this row within its category. Ordinals are per-category and stable for the life of the snapshot, which is what makes them safe to address the detail endpoint with.
Example: 17
Fully qualified address of the resource, module path included.
Example: "module.app.aws_s3_bucket.app_bucket"
Identifier for the resource from the cloud provider. Populated for resources rows.
Example: "arn:aws:s3:::my-bucket"
Whether this row's value is sensitive. Populated for outputs rows.
Example: false
Attribute keys whose values are sensitive and have been withheld.
Example: ["password"]
Response
application/json
{ "details": [ { … }, { … } ] }
Request
Upload the counts.json commit marker for an execution stage's resource changes.
Sent after all category pages have been uploaded to signal the upload is complete; the body is the counts.json object (application/octet-stream) and is currently discarded. It carries the badge totals the UI needs without scanning the paged files.
Example body:
{
"PlannedTotal": 42,
"PlannedByChangeType": { "added": 10, "changed": 8, "deleted": 2, "unchanged": 22 },
"Drift": 3,
"Resources": 120,
"DataSources": 15,
"Outputs": 6
}Security
x-api-key
- Harness host URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/counts
- Vanity URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/counts
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://app.harness.io/iacm/api/orgs/xu/projects/p/executions/zhy/p6/resource-changes/counts?generation_id=Impedit+debitis+nihil+vel+est.' \
-H 'Content-Length: 256' \
-H 'Harness-Account: k' \
-H 'x-api-key: YOUR_API_KEY_HERE'Request
Get the count beside every filter option, across every dimension, in one request.
Unlike get-resource-change-counts, which returns fixed whole-snapshot badge totals, these counts are selection-aware: each one answers how many rows the list would hold if the caller also picked that option, so they move as the caller filters. Both endpoints stay — badges read the totals, the filter panel reads these.
Every dimension is counted with the other dimensions' filters applied but not its own. That is what lets a caller widen a selection: were they all counted under one shared predicate, selecting a single provider would make every other provider read zero.
The category filter accepts more than one value here even though the list endpoint takes a single category in its path, so a caller can scope the counts to the categories its tab shows.
Only committed snapshots are visible; an unindexed or incomplete stage is a 404.
Security
x-api-key
Query
Restrict to these categories. Repeat the parameter to select more than one; omit it for all.
Items Enum"planned_changes""drift_changes""resources""outputs"
Example: category=planned_changes&category=drift_changes
Restrict to these change types. Repeat the parameter to select more than one; omit it for all. Only meaningful for the planned_changes and drift_changes categories, whose rows are the only ones carrying a change type.
Items Enum"added""changed""deleted""replaced""unchanged""removed""imported"
Example: change=added&change=deleted
Restrict to these providers. Repeat the parameter to select more than one; omit it for all.
Example: provider=registry.opentofu.org/hashicorp/aws
Restrict to these provider resource types. Repeat the parameter to select more than one; omit it for all.
Example: type=aws_instance
Restrict to these modules. Repeat the parameter to select more than one; omit it for all.
Example: module=root
- Harness host URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/filter-counts
- Vanity URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/filter-counts
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://app.harness.io/iacm/api/orgs/1py/projects/gl/executions/i/fzx/resource-changes/filter-counts?category=planned_changes%2Cdrift_changes&change=added%2Cdeleted&provider=registry.opentofu.org%2Fhashicorp%2Faws&type=aws_instance&module=root&search=app_bucket' \
-H 'Harness-Account: q' \
-H 'x-api-key: YOUR_API_KEY_HERE'OK response.
Row count per category, with every other dimension's filters applied but not the category filter.
Example: {"drift_changes":0,"outputs":0,"planned_changes":131,"resources":0}
Row count per change type, with every other dimension's filters applied but not the change-type filter. Empty for categories that have no change type. These are the numbers on the cards above the table.
Example: {"added":130,"changed":0,"deleted":1,"imported":0,"removed":0,"unchanged":0}
Row count per module, with every other dimension's filters applied but not the module filter.
Example: {"root":131}
Row count per provider, with every other dimension's filters applied but not the provider filter.
Example: {"registry.opentofu.org/hashicorp/aws":131}
Response
application/json
{ "categories": { "drift_changes": 0, "outputs": 0, "planned_changes": 131, "resources": 0 }, "change_types": { "added": 130, "changed": 0, "deleted": 1, "imported": 0, "removed": 0, "unchanged": 0 }, "modules": { "root": 131 }, "providers": { "registry.opentofu.org/hashicorp/aws": 131 }, "types": { "aws_default_vpc": 1, "aws_instance": 130 } }