# Argo CD API Endpoints Reference: Complete REST API and gRPC Gateway Guide

> Explore the complete Argo CD API endpoints reference. Discover REST API and gRPC Gateway details for managing Applications, Clusters, and Repositories with ease.

- Repository: [Argo Project/argo-cd](https://github.com/argoproj/argo-cd)
- Tags: api-reference
- Published: 2026-07-14

---

**Argo CD exposes a gRPC-Gateway-backed REST API under the base path `/api/v1/`, where protobuf services map to HTTP verbs via `google.api.http` annotations, enabling CRUD operations for Applications, Clusters, Repositories, and other resources through standardized endpoints.**

Argo CD provides a comprehensive REST API for automating GitOps workflows and managing Kubernetes deployments. This **Argo CD API endpoints reference** documents the complete interface exposed by the `argoproj/argo-cd` repository, detailing how the gRPC-Gateway translates protobuf definitions into HTTP routes. Understanding these endpoints enables you to build custom integrations, CI/CD pipelines, and administrative tools that interact programmatically with your Argo CD instance.

## API Architecture and Routing

The Argo CD server implements a **gRPC-Gateway** pattern that automatically exposes RESTful endpoints for all protobuf service methods. The core routing setup occurs in [`server/server.go`](https://github.com/argoproj/argo-cd/blob/main/server/server.go) (lines 1261-1270 and 1236-1245), where the HTTP multiplexer attaches to the `/api/` prefix and registers gateway handlers via `mustRegisterGWHandler` calls.

Each protobuf RPC method includes `google.api.http` annotations specifying the HTTP verb and URL pattern. For example, in `server/application/application.proto`, the Create RPC carries:

```proto
rpc Create(ApplicationCreateRequest) returns (ApplicationResponse) {
  option (google.api.http) = {
    post: "/api/v1/applications"
    body: "*"
  };
}

```

The gateway code generation (triggered via `make codegen`) produces Go handlers under `pkg/apiclient/*` that marshal JSON requests to protobuf messages and vice versa.

## Core Argo CD API Endpoints by Resource

### Applications

The **Applications** endpoints manage individual Argo CD applications and their lifecycle operations. Defined in `server/application/application.proto` under the `application.ApplicationService`, these endpoints support standard CRUD operations plus specialized sync and rollback capabilities.

- **List**: `GET /api/v1/applications`
- **Get**: `GET /api/v1/applications/{name}`
- **Create**: `POST /api/v1/applications`
- **Update**: `PUT /api/v1/applications/{name}`
- **Delete**: `DELETE /api/v1/applications/{name}`
- **Sync**: `POST /api/v1/applications/{name}/sync`

### ApplicationSets

**ApplicationSets** enable templated bulk application management via `applicationset.ApplicationSetService` in `server/applicationset/applicationset.proto`. These endpoints follow the same CRUD pattern as Applications with additional bulk synchronization support.

- **Base path**: `/api/v1/applicationsets`
- **Sync**: `POST /api/v1/applicationsets/{name}/sync`

### Clusters

Manage Kubernetes cluster credentials and connections through the **Clusters** API defined in `server/cluster/cluster.proto`. The `cluster.ClusterService` provides full CRUD operations for cluster registrations.

- **List**: `GET /api/v1/clusters`
- **Get**: `GET /api/v1/clusters/{name}`
- **Create**: `POST /api/v1/clusters`
- **Update**: `PUT /api/v1/clusters/{name}`
- **Delete**: `DELETE /api/v1/clusters/{name}`

### Repositories

The **Repositories** API in `server/repository/repository.proto` manages Git repository configurations via `repository.RepositoryService`. Beyond standard CRUD, it includes endpoints to inspect repository contents.

- **Base path**: `/api/v1/repositories`
- **List Apps**: `GET /api/v1/repositories/{repoURL}/apps`

### Repository Credentials

Store and manage external repository credentials securely using endpoints defined in `server/repocreds/repocreds.proto` under `repocreds.RepoCredsService`.

- **Base path**: `/api/v1/repocreds`

### Projects

**Projects** provide RBAC groupings and policy constraints. The `project.ProjectService` in `server/project/project.proto` manages these resources.

- **Base path**: `/api/v1/projects`

### Accounts and Session Management

Authentication and account operations are split between two services. The **Account** service (`server/account/account.proto`) handles current user information, while the **Session** service (`server/session/session.proto`) manages JWT issuance and termination.

**Account endpoints** (`/api/v1/account`):

- `GET /api/v1/account` – Current account info
- `POST /api/v1/account/logout` – Logout

**Session endpoints** (`/api/v1/session`):

- `POST /api/v1/session` – Login (creates JWT)
- `DELETE /api/v1/session` – Logout

### Settings

Retrieve and modify global Argo CD configuration through the **Settings** service in `server/settings/settings.proto`.

- `GET /api/v1/settings` – Global CD settings
- `PATCH /api/v1/settings` – Partial update

### Certificates and GPG Keys

Manage cryptographic resources for secure Git operations. **Certificates** (`server/certificate/certificate.proto`) handle TLS certificates, while **GPG Keys** (`server/gpgkey/gpgkey.proto`) manage commit verification keys.

- **Certificates**: `/api/v1/certificates`
- **GPG Keys**: `/api/v1/gpgkeys`

### Notifications

Configure and trigger notifications via `notification.NotificationService` in `server/notification/notification.proto`.

- `GET /api/v1/notifications/services` – List available services
- `POST /api/v1/notifications/triggers` – Trigger notification

### Version

Retrieve server version information from `version.VersionService` in `server/version/version.proto`.

- `GET /api/v1/version`

### Webhook and Terminal Endpoints

Two special endpoints exist outside the standard `/api/v1/` pattern:

**Webhook** ([`util/webhook/webhook.go`](https://github.com/argoproj/argo-cd/blob/main/util/webhook/webhook.go)):

- `POST /api/webhook` – Receives Git provider events (push, PR, tag)

**Terminal** ([`server/application/terminal.go`](https://github.com/argoproj/argo-cd/blob/main/server/application/terminal.go)):

- `GET /terminal` – Proxies WebSocket connections for pod terminal access

## Authentication and Authorization Flow

All `/api/v1/*` routes pass through the **session middleware** (`util_session.WithAuthMiddleware`) defined in [`server/server.go`](https://github.com/argoproj/argo-cd/blob/main/server/server.go). The middleware extracts **JWT tokens** from the `Authorization: Bearer <token>` header or authentication cookies, populating the request context with principal information.

After authentication, the **RBAC enforcement engine** (`util.rbac.Enforcer`) evaluates permissions against the requested resource and HTTP verb. Requests must present valid tokens with sufficient privileges for the target endpoint.

## Working with Argo CD API Endpoints

### Listing Applications

Retrieve all applications visible to the authenticated account:

```bash
curl -s -H "Authorization: Bearer $ARGOCD_TOKEN" \
     https://argo.example.com/api/v1/applications | jq .

```

This corresponds to `application.ApplicationService.List` → `GET /api/v1/applications`.

### Creating an Application

Submit a JSON payload matching the `ApplicationCreateRequest` protobuf structure:

```bash
cat <<EOF >app.json
{
  "application": {
    "metadata": { "name": "my-app", "namespace": "argocd" },
    "spec": {
      "source": { "repoURL": "git@github.com:org/repo.git", "path": "k8s" },
      "destination": { "server": "https://kubernetes.default.svc", "namespace": "prod" }
    }
  },
  "upsert": true
}
EOF

curl -X POST -H "Authorization: Bearer $ARGOCD_TOKEN" \
     -H "Content-Type: application/json" \
     -d @app.json \
     https://argo.example.com/api/v1/applications

```

This maps to `ApplicationCreateRequest` → `POST /api/v1/applications`.

### Syncing an Application

Trigger immediate synchronization for a specific application:

```bash
curl -X POST -H "Authorization: Bearer $ARGOCD_TOKEN" \
     https://argo.example.com/api/v1/applications/my-app/sync

```

This invokes `ApplicationSyncRequest` → `POST /api/v1/applications/{name}/sync`.

### Retrieving Cluster Information

List all registered Kubernetes clusters:

```bash
curl -s -H "Authorization: Bearer $ARGOCD_TOKEN" \
     https://argo.example.com/api/v1/clusters | jq .

```

This corresponds to `ClusterService.List` → `GET /api/v1/clusters`.

### Terminating a Session

Log out and invalidate the current JWT:

```bash
curl -X DELETE -H "Authorization: Bearer $ARGOCD_TOKEN" \
     https://argo.example.com/api/v1/session

```

This maps to `SessionService.Delete` → `DELETE /api/v1/session`.

## Summary

- **Argo CD API endpoints** are exposed under `/api/v1/` via a gRPC-Gateway that translates REST requests to protobuf RPCs.
- **Core resources** include Applications, ApplicationSets, Clusters, Repositories, Projects, and Repository Credentials, each defined in dedicated `.proto` files under `server/`.
- **Authentication** requires JWT tokens passed via `Authorization: Bearer <token>` headers, validated by `util_session.WithAuthMiddleware`.
- **Special endpoints** exist at `/api/webhook` for Git events and `/terminal` for WebSocket-based pod access.
- **Code generation** via `make codegen` keeps the REST API synchronized with protobuf definitions in `pkg/apiclient/*`.

## Frequently Asked Questions

### What is the base URL for Argo CD API endpoints?

Argo CD exposes its REST API under the base path `/api/v1/`. All resource endpoints documented in the protobuf files (such as `/api/v1/applications`, `/api/v1/clusters`, and `/api/v1/repositories`) are prefixed with this base path. The server attaches the gRPC-Gateway handlers to the `/api/` route in [`server/server.go`](https://github.com/argoproj/argo-cd/blob/main/server/server.go).

### How do I authenticate to Argo CD API endpoints?

Requests must include a valid JWT token in the `Authorization: Bearer <token>` HTTP header. Alternatively, the server accepts authentication cookies. The `util_session.WithAuthMiddleware` in [`server/server.go`](https://github.com/argoproj/argo-cd/blob/main/server/server.go) validates these tokens and enforces RBAC policies via `util.rbac.Enforcer` before allowing access to protected resources.

### What is the difference between the gRPC and REST APIs in Argo CD?

Argo CD internally uses gRPC for service-to-service communication, but exposes a REST API via the **gRPC-Gateway** for external clients. The gateway translates HTTP/JSON requests to protobuf messages and invokes the appropriate gRPC methods. This allows both REST clients (like `curl`) and gRPC clients to interact with the same backend logic defined in the `*.proto` files.

### How do I trigger an application sync via the Argo CD API?

Send a `POST` request to `/api/v1/applications/{name}/sync` with your authentication header. This endpoint corresponds to the `Sync` RPC in `server/application/application.proto` and accepts optional parameters in the request body to control pruning, resource selection, and sync strategy.