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

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 (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:

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):

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

Terminal (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. 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:

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:

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:

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:

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:

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.

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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}