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.
- Get resource change indexed page
List executions
Create execution
Show execution
Update execution
Upload resource change page
List resource change rows
Get resource change detail
Get resource change detail by address
Commit resource changes
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
Get resource change index...
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
Upload a single sharded resource-change page file for an execution stage.
Resource-change data is split into categories (planned_changes, drift_changes, resources, etc.) and each category is sharded into zero-based pages. The request body is the raw page file (application/octet-stream) and is currently discarded.
The planned_changes and drift_changes categories are uploaded twice: once as pages of the whole category, and once as pages of a single change type, identified by the change parameter. Rows in both categories are expected pre-sorted by change-type priority (deleted, replaced, added, changed, unchanged, removed, imported).
The body is a JSON array whose element shape depends on {category}:
planned_changes | unchanged | drift_changes -> ChangedResource[] resources | data_sources -> Resource[] outputs -> Output[]
Example body (category=planned_changes):
[
{
"provider": "AWS",
"type": "aws_s3_bucket",
"name": "app_bucket",
"module": "root",
"change": "added",
"change_count": 1,
"drift": false,
"changes": {
"bucket": { "change": "added", "old": "", "new": "my-bucket" }
}
}
]Example body (category=resources):
[
{
"provider": "AWS",
"type": "aws_instance",
"name": "app_server",
"module": "root",
"mode": "resource",
"path_id": "namespace",
"resource_id": "i-0abc123",
"attributes": { "instance_type": "t2.micro" },
"drift_status": "unchanged",
"drift_attributes": {},
"sensitive_attributes": []
}
]Security
x-api-key
Path
Resource-change category the page belongs to
Enum"planned_changes""unchanged""drift_changes""resources""data_sources""outputs"
Example: planned_changes
- Harness host URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/{category}/{page}
- Vanity URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/{category}/{page}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://app.harness.io/iacm/api/orgs/n/projects/1b/executions/4y/j/resource-changes/planned_changes/1?change=added&generation_id=Error+harum+harum+molestiae+in+enim.' \
-H 'Content-Length: 4096' \
-H 'Harness-Account: bcs' \
-H 'x-api-key: YOUR_API_KEY_HERE'Request
Get one page of indexed resource-change rows together with badge totals and selection-aware filter counts.
Badge totals, facets, rows, total items, and pagination are read in one repeatable-read transaction over one committed plan/applied generation pair, so a commit that lands during the request cannot mix those values.
Badge totals are fixed for the pair. The resources badge counts managed resources only. Facets and rows keep the category semantics of list-resource-change-rows and get-resource-change-filter-counts, including data sources inside the resources category.
A 404 means the stage has no fresh indexed snapshot. Callers fall through to the sharded page files and then the legacy list.
Security
x-api-key
Query
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
Case-insensitive substring match against the resource address and name.
Example: search=app_bucket
- Harness host URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/{category}/indexed-page
- Vanity URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/{category}/indexed-page
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://app.harness.io/iacm/api/orgs/ei/projects/dh/executions/jz/hbd/resource-changes/planned_changes/indexed-page?change=added%2Cdeleted&provider=registry.opentofu.org%2Fhashicorp%2Faws&type=aws_instance&module=root&search=app_bucket&limit=25&page=1' \
-H 'Harness-Account: k' \
-H 'x-api-key: YOUR_API_KEY_HERE'OK response.
Badge totals for resource-changes tab, computed independently of paging.
Example: {"added":1,"changed":0,"data_sources":0,"deleted":0,"drift_added":0,"drift_changed":1,"drift_changes":1,"drift_deleted":0,"drift_imported":0,"drift_removed":0,"drift_replaced":0,"drift_unchanged":0,"has_applied_state":false,"imported":0,"outputs":1,"planned_changes":1,"removed":0,"replaced":0,"resources":3,"unchanged":2}
Count of changed resources in drift changes.
Example: 1
Count of deleted resources in drift changes.
Example: 0
Count of imported resources in drift changes.
Example: 0
Count of removed resources in drift changes.
Example: 0
Count of replaced resources in drift changes.
Example: 0
Count of unchanged resources in drift changes, which unlike planned unchanged rows are part of the drift_changes total.
Example: 0
Whether this execution stage produced applied state.
Example: false
Selection-aware counts for every filter option, across every dimension, in one request.
These are not the badge totals get-resource-change-counts returns. A badge total describes the whole snapshot and never moves. A filter count answers "how many rows would I get if I also picked this option", which is what makes the number beside a filter option useful, and it changes as the user filters.
Each dimension is counted with the other dimensions' filters applied but not its own. Counting every dimension under one shared predicate would make every unselected option read zero and leave the user unable to widen a selection they had already narrowed.
Example: {"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}}
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}
One page of resource-change rows for an execution stage.
Pages are numbered and randomly addressable, so the table's page picker can jump straight to page 5. totalItems and totalPages are what render the picker and the "(1 - 25) of 131" count.
Rows come back in the order they were stored, which is change-type priority (deleted, added, changed, unchanged, removed, imported) then name. There is no sort parameter: the ordering was settled once at write time, so no request pays to establish it and no two callers disagree about it.
Example: {"page":1,"pageSize":25,"rows":[{"category":"planned_changes","change":"added","change_count":3,"detail_bytes":2048,"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,"type":"aws_s3_bucket","value":"i-0abc123"},{"category":"planned_changes","change":"added","change_count":3,"detail_bytes":2048,"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,"type":"aws_s3_bucket","value":"i-0abc123"},{"category":"planned_changes","change":"added","change_count":3,"detail_bytes":2048,"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,"type":"aws_s3_bucket","value":"i-0abc123"},{"category":"planned_changes","change":"added","change_count":3,"detail_bytes":2048,"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,"type":"aws_s3_bucket","value":"i-0abc123"}],"totalItems":131,"totalPages":6}
Example: [{"category":"planned_changes","change":"added","change_count":3,"detail_bytes":2048,"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,"type":"aws_s3_bucket","value":"i-0abc123"},{"category":"planned_changes","change":"added","change_count":3,"detail_bytes":2048,"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,"type":"aws_s3_bucket","value":"i-0abc123"},{"category":"planned_changes","change":"added","change_count":3,"detail_bytes":2048,"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,"type":"aws_s3_bucket","value":"i-0abc123"}]
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
Uncompressed size in bytes of this row's attribute document, so a client can decide whether to fetch it. Zero for outputs rows, which carry their value inline.
Example: 2048
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
Cloud provider associated with the resource.
Example: "AWS"
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
Total rows matching these filters, ignoring paging.
Example: 131
Response
application/json
{ "badges": { "added": 1, "changed": 0, "data_sources": 0, "deleted": 0, "drift_added": 0, "drift_changed": 1, "drift_changes": 1, "drift_deleted": 0, "drift_imported": 0, "drift_removed": 0, "drift_replaced": 0, "drift_unchanged": 0, "has_applied_state": false, "imported": 0, "outputs": 1, "planned_changes": 1, "removed": 0, "replaced": 0, "resources": 3, "unchanged": 2 }, "facets": { "categories": { … }, "change_types": { … }, "modules": { … }, "providers": { … }, "types": { … } }, "row_page": { "page": 1, "pageSize": 25, "rows": [ … ], "totalItems": 131, "totalPages": 6 } }
Request
List one page of resource-change rows for an execution stage.
Served entirely from the indexed snapshot: every column the response carries is a scalar, so a list request reads no attribute data. Attribute documents are fetched one row at a time from get-resource-change-detail.
Pages are numbered and randomly addressable, because the table's page picker lets a caller jump straight to page 5 rather than walking there. Unfiltered, a page is a bare ordinal range over an index — ordinals are dense within a category — so page 40 costs what page 1 costs. Once a filter or search is applied ordinals stop being contiguous and the page has to be counted into, but by then the result set has narrowed to the point where there is little to count past.
Rows come back in stored order: change-type priority (deleted, added, changed, unchanged, removed, imported) then name. There is no sort parameter, because the columns filter rather than sort — the ordering is fixed at write time and identical for every caller.
Only committed snapshots are visible. A stage whose upload never completed, or that predates indexing, is a 404 and the caller should fall back to list-resource-changes.
Security
x-api-key
Query
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
Case-insensitive substring match against the resource address and name.
Example: search=app_bucket
- Harness host URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/{category}/rows
- Vanity URLhttps://app.harness.io/iacm/api/orgs/{org}/projects/{project}/executions/{pipeline_execution_id}/{pipeline_stage_id}/resource-changes/{category}/rows
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://app.harness.io/iacm/api/orgs/7/projects/k1f/executions/s/h8/resource-changes/planned_changes/rows?change=added%2Cdeleted&provider=registry.opentofu.org%2Fhashicorp%2Faws&type=aws_instance&module=root&search=app_bucket&limit=25&page=1' \
-H 'Harness-Account: b' \
-H 'x-api-key: YOUR_API_KEY_HERE'OK response.
Example: [{"category":"planned_changes","change":"added","change_count":3,"detail_bytes":2048,"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,"type":"aws_s3_bucket","value":"i-0abc123"},{"category":"planned_changes","change":"added","change_count":3,"detail_bytes":2048,"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,"type":"aws_s3_bucket","value":"i-0abc123"},{"category":"planned_changes","change":"added","change_count":3,"detail_bytes":2048,"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,"type":"aws_s3_bucket","value":"i-0abc123"}]
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
Uncompressed size in bytes of this row's attribute document, so a client can decide whether to fetch it. Zero for outputs rows, which carry their value inline.
Example: 2048
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
Response
application/json
{ "page": 1, "pageSize": 25, "rows": [ { … }, { … }, { … }, { … } ], "totalItems": 131, "totalPages": 6 }