> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/api-reference/readme.md).

# API Reference

Use the Harness APIs to automate your account. Find out how to authenticate, which parameters every request needs, and how to try endpoints in the browser.

The Harness APIs give you programmatic access to everything you can do in the Harness UI. Use them to create resources, automate pipelines and policies, and connect Harness to your own tools.

This reference has one section for each product area. Each section lists the endpoints, parameters, and responses for that area, and you can try requests from the page.

## Authenticate your requests

Every request needs a Harness API key token. Send it in the `x-api-key` header.

To get a token:

1. Create an API key in your user profile, or in a service account if the integration is not tied to a person.
2. Add a token to the key and copy it. Harness shows the token only once, so store it somewhere secure.

A token has the same permissions as the user or service account that owns the key. If a request returns a permissions error, check the roles on that user or service account first.

Go to [Manage API keys](https://developer.harness.io/harness-platform/use-harness-platform/automation/api/add-and-manage-api-keys) to create a key and token. Go to [Get started with Harness API](https://developer.harness.io/harness-platform/use-harness-platform/automation/api/api-quickstart) for a walkthrough that ends in a working request.

## Make your first request

Check your token and account ID by listing the projects in your account:

```bash
curl "https://app.harness.io/gateway/ng/api/projects?accountIdentifier=ACCOUNT_ID" \
  -H "x-api-key: $HARNESS_API_KEY"
```

Replace `ACCOUNT_ID` with your account ID, and set `HARNESS_API_KEY` to your API key token. A JSON list of projects means both are working. A `401` means the token is missing or wrong.

## Common parameters

Most endpoints need the same four values. Different APIs name them differently, so the table lists each value with the parameter names you might see for it.

| Value                   | Parameter names you might see                                                           | Where                                  | What it is                                                                                                                    |
| ----------------------- | --------------------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| API key token           | `x-api-key` (also written `X-Api-Key`)                                                  | Header                                 | Your API key token. Send it on every request.                                                                                 |
| Harness account ID      | `accountIdentifier`, `accountId`, `account_identifier`, `account_id`, `Harness-Account` | Query, or header for `Harness-Account` | Your Harness account ID. You can find it in the URL when you are signed in to Harness, after `/account/`.                     |
| Harness organization ID | `orgIdentifier`, `orgId`, `org_identifier`, `organization_identifier`, `org`            | Query, or path for `org`               | The identifier of the organization the resource belongs to, such as `default`. Needed for organization and project resources. |
| Harness project ID      | `projectIdentifier`, `projectId`, `project_identifier`                                  | Query                                  | The identifier of the project the resource belongs to. Needed for project resources.                                          |

Use the identifier, not the display name. The identifiers you need depend on the scope of the resource. An account-level resource needs only the account ID. A project-level resource needs all three.

Most APIs use `accountIdentifier`, `orgIdentifier`, and `projectIdentifier`. Check the parameter list on the endpoint page for the exact names that endpoint expects.

Each API has its own base URL under `https://app.harness.io`, given under **Request basics** on its page. If your account is on another Harness cluster, or you run self-managed Harness, use the host you sign in to and keep the rest of the path.

### Where the pattern differs

Beyond the names, some APIs ask for different things or add extras:

| API                               | How it differs                                                                                                                                                                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Database DevOps                   | Takes the account ID in a `Harness-Account` header. The header is only required when you authenticate with something other than an `x-api-key` token.                                                                                 |
| Infrastructure as Code Management | Takes the account ID in a `Harness-Account` header on most endpoints, and the organization as an `org` path parameter.                                                                                                                |
| Commitment Orchestrator           | Also takes a `routingId` query parameter on many endpoints, and some paths include the account ID.                                                                                                                                    |
| Feature Flags Classic             | Requires the organization and project IDs on most endpoints, and `environmentIdentifier` on many.                                                                                                                                     |
| Feature Flags                     | Takes `account_id`, `organization_identifier`, and `project_identifier` as query parameters on every endpoint, and `environment_id` on environment-level endpoints. Uses the `/fme/api` base path.                                    |
| FME Admin API (Legacy Split)      | Takes an Admin API key, personal access token, or service account token in an `Authorization: Bearer` header instead of `x-api-key`. Identifies a project by `workspace-id` or `wsId`, and has no account or organization parameters. |
| Templates                         | Some endpoints accept optional headers such as `If-Match` and `Load-From-Cache`.                                                                                                                                                      |

Some references also accept a JSON Web Token (JWT) in an `Authorization: Bearer` header. Use `x-api-key` unless the API's own page says otherwise.

## Conventions

Each API follows these conventions, with small differences that the endpoint pages show.

### Paging

Most list endpoints return results a page at a time. The parameter names vary between APIs, for example `pageIndex` and `pageSize`, `page` and `size`, or `page` and `limit`, so check the endpoint's parameters. Keep requesting the next page until you get fewer items than the page size.

### Errors

The APIs use standard HTTP status codes:

| Status | Meaning                                                                                              |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `400`  | The request is malformed, or a required parameter is missing.                                        |
| `401`  | The API key token is missing, wrong, or expired.                                                     |
| `403`  | The token works, but its owner lacks the permission for this action.                                 |
| `404`  | The resource does not exist at the scope you sent. Check the account, organization, and project IDs. |
| `429`  | You sent too many requests. See [Rate limits](#rate-limits).                                         |
| `5xx`  | Something went wrong on the Harness side. Retry later.                                               |

Most error responses include a JSON body with a `message` that explains the problem. Many also include a `correlationId`. Include it when you contact Harness Support, because it lets them find your request.

### Rate limits

Harness limits how many requests an API key and an IP address can send in a period. Over the limit, requests get a `429` response. Wait and retry with an increasing delay. Go to [Platform rate limits](https://developer.harness.io/harness-platform/use-harness-platform/rate-limits) for the current limits.

### Versioning

Each API is versioned on its own. Some include the version in the path, such as `/v1/` or `/api/v2/`, and some do not. Where an endpoint has a newer version, such as `/v2/secrets`, use the newer one for new work. Write clients that ignore response fields they do not recognise, so that new fields do not break them.

### Permissions

An API call needs the same permission as the matching action in the UI. Go to [API permissions reference](https://developer.harness.io/harness-platform/use-harness-platform/automation/api/api-permissions-reference) to see which permission each action needs.

## Try an endpoint in the browser

Each endpoint page has a **Test it** panel. Use it to send a real request without leaving the reference:

1. Open an endpoint from the list of references on the left.
2. Select **Test it**.
3. Enter your API key token in the `x-api-key` field, and fill in the parameters.
4. Send the request and review the response.

Requests from **Test it** run against your real account. Use a token from a service account with limited permissions when you only want to read data, and take care with endpoints that create, change, or delete resources.

## Find the API you need

The references are grouped by product area in the navigation:

* **Platform APIs**: [Core Platform](https://developer.harness.io/api-reference/platform-apis/core-platform.md), [Access Control](https://developer.harness.io/api-reference/platform-apis/access-control.md), [Audit Trails](https://developer.harness.io/api-reference/platform-apis/audit-trails.md), [Templates](https://developer.harness.io/api-reference/platform-apis/templates.md), [Governance](https://developer.harness.io/api-reference/platform-apis/governance.md), and [Dashboards](https://developer.harness.io/api-reference/platform-apis/dashboards.md).
* **Software Delivery Agent APIs**: [Pipelines](https://developer.harness.io/api-reference/software-delivery-agent-apis/pipelines.md), [Test Intelligence](https://developer.harness.io/api-reference/software-delivery-agent-apis/test-intelligence.md), [GitOps](https://developer.harness.io/api-reference/software-delivery-agent-apis/gitops.md), [Code Repository](https://developer.harness.io/api-reference/software-delivery-agent-apis/code-repository.md), [Artifact Registry](https://developer.harness.io/api-reference/software-delivery-agent-apis/artifact-registry.md), [Infrastructure as Code Management](https://developer.harness.io/api-reference/software-delivery-agent-apis/infrastructure-as-code-management.md), and [Database DevOps](https://developer.harness.io/api-reference/software-delivery-agent-apis/database-devops.md).
* **Security Testing Agent APIs**: [Security Testing Orchestration](https://developer.harness.io/api-reference/security-testing-agent-apis/security-testing-orchestration.md).
* **Cost Management Agent APIs**: [Cloud Cost Management](https://developer.harness.io/api-reference/cost-management-agent-apis/cloud-cost-management.md) and [Commitment Orchestrator](https://developer.harness.io/api-reference/cost-management-agent-apis/commitment-orchestrator.md).
* **More Products APIs**: [Feature Flags](https://developer.harness.io/api-reference/more-products-apis/feature-management-and-experimentation.md), [Feature Flags Classic](https://developer.harness.io/api-reference/more-products-apis/feature-flags-classic.md), [FME Admin API (Legacy Split)](https://developer.harness.io/api-reference/more-products-apis/fme-admin-api.md), [Service Reliability Management](https://developer.harness.io/api-reference/more-products-apis/service-reliability-management.md), [AI SRE](https://developer.harness.io/api-reference/more-products-apis/ai-sre.md), and [Chaos Engineering](https://developer.harness.io/api-reference/more-products-apis/chaos-engineering.md).
