How to Interact with the Argo CD API: A Complete Guide for REST and gRPC

Argo CD exposes a REST-style HTTP API under the /api/v1 path that is transcoded from gRPC protobuf definitions, supporting both session-based cookie authentication and JWT Bearer tokens.

The Argo CD API is the primary interface for programmatic management of applications, clusters, and repositories in the argoproj/argo-cd repository. Built on gRPC with HTTP/JSON transcoding, it allows you to automate deployments, query sync status, and manage configurations from scripts, custom tools, or the web UI.

Argo CD API Architecture Overview

The API is implemented in the server package and follows a gRPC-gateway pattern. Each protobuf RPC uses the google.api.http option to map methods to HTTP verbs and URL patterns, which the API server then routes to appropriate Go handlers.

Key architectural components include:

• Protobuf service definitions (e.g., server/session/session.proto, server/application/application.proto) – Declare the API surface with HTTP method annotations.
• gRPC-gateway (generated via make codegen) – Translates incoming HTTP requests to gRPC calls.
• Go server (server/server.go) – Registers HTTP routes, applies RBAC enforcement, and forwards calls to service implementations.
• Client libraries (pkg/apiclient/...) – Provide Go wrappers auto-generated from protobuf definitions.

Authentication Methods

All API requests require authentication. Argo CD supports two primary mechanisms for HTTP clients.

Session Cookies

After authenticating via POST /api/v1/session with username and password credentials, the server returns an HTTP-Only cookie named argocd.token. Subsequent requests automatically include this cookie.

curl -X POST https://argo.example.com/api/v1/session \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'

JWT Bearer Tokens

The session endpoint also returns a JWT in the JSON response token field. Use this in the Authorization header for programmatic access:

Authorization: Bearer <token>

Core Mode Exception

When using the --core flag or ARGOCD_CORE environment variable, the CLI bypasses the REST API entirely and communicates directly with the Kubernetes API server. This mode does not apply to standalone HTTP API consumers.

Common API Endpoints

The API surface covers all major Argo CD resources. Here are the most frequently used endpoints defined in their respective protobuf files:

• /api/v1/session (POST) – Create login session. Defined in server/session/session.proto.
• /api/v1/session/userinfo (GET) – Retrieve current user details.
• /api/v1/applications (GET) – List all applications. Defined in server/application/application.proto.
• /api/v1/applications/{name} (GET, PUT) – Get or update a specific application (e.g., trigger sync).
• /api/v1/clusters (GET, POST) – List or register clusters. Defined in server/cluster/cluster.proto.
• /api/v1/repositories (GET) – List Git/Helm repositories. Defined in server/repository/repository.proto.
• /api/v1/projects (GET) – List projects. Defined in server/project/project.proto.
• /api/v1/settings (GET) – Retrieve global Argo CD settings. Defined in server/settings/settings.proto.

Practical Code Examples

Authenticate and Query Applications with cURL

This example logs in, extracts the JWT, and lists all applications:

# Obtain authentication token

TOKEN=$(curl -s -X POST https://argo.example.com/api/v1/session \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}' | \
  jq -r .token)

# List applications using Bearer authentication

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

References: Login endpoint is defined in server/session/session.proto; applications endpoint is in server/application/application.proto.

Using the Official Go Client Library

The pkg/apiclient package provides type-safe access. Connect using your server address and token obtained from the session endpoint:

package main

import (
	"context"
	"log"

	"github.com/argoproj/argo-cd/pkg/apiclient"
	appClient "github.com/argoproj/argo-cd/pkg/apiclient/application"
	"github.com/argoproj/argo-cd/pkg/apiclient/client"
)

func main() {
	// Initialize client with server details and auth token
	conn, err := client.NewClient(&apiclient.ClientOptions{
		ServerAddr: "https://argo.example.com",
		AuthToken:  "your-jwt-token",
		Insecure:   true, // Use only with self-signed certificates
	}).NewApplicationClient()
	if err != nil {
		log.Fatalf("client error: %v", err)
	}
	defer conn.Close()

	// List all applications
	resp, err := conn.List(context.Background(), &appClient.ApplicationQuery{})
	if err != nil {
		log.Fatalf("list error: %v", err)
	}
	for _, app := range resp.Items {
		log.Printf("App: %s - Sync: %s", app.Metadata.Name, app.Status.Sync.Status)
	}
}

Reference: The Go client is generated from protobuf definitions in pkg/apiclient/....

TypeScript Requests for Web UI Integration

The Argo CD UI uses a central HTTP helper located in ui/src/app/shared/services/requests.ts to prefix URLs with /api/v1 and handle credentials:

import { Requests } from './requests';

// Get current user information
Requests.get('/api/v1/session/userinfo')
  .then(user => console.log('Logged in as:', user.username));

// Retrieve all projects
Requests.get('/api/v1/projects')
  .then(projects => projects.forEach(p => console.log('Project:', p.metadata.name)));

Reference: File ui/src/app/shared/services/requests.ts demonstrates how the React frontend constructs API calls.

Error Handling

All API errors return standard HTTP status codes with a JSON error envelope. Expect responses in this format:

{
  "status": "Failure",
  "message": "application not found",
  "code": 404
}

Clients should treat non-2xx responses as failures and inspect the message field for diagnostic information.

Summary

• Base path: All endpoints reside under /api/v1 at your Argo CD server host.
• Authentication: Obtain tokens via POST /api/v1/session (defined in server/session/session.proto) and pass them as Bearer tokens or session cookies.
• Access patterns: Use raw HTTP/REST calls, the generated Go client in pkg/apiclient, or the TypeScript service pattern from the UI code.
• Key resources: Applications (server/application/application.proto), clusters (server/cluster/cluster.proto), and repositories (server/repository/repository.proto) expose the most commonly used endpoints.
• RBAC enforcement: All requests pass through the authorization layer implemented in server/rbacpolicy/rbacpolicy.go and registered in server/server.go.

Frequently Asked Questions

What is the base URL for all Argo CD API requests?

All endpoints use the prefix /api/v1 relative to your Argo CD server host (e.g., https://argo.example.com/api/v1/applications). This path is mapped through the gRPC-gateway transcoding defined in the various .proto files in the server directory.

How do I obtain an authentication token for API calls?

Send a POST request to /api/v1/session with a JSON body containing username and password. The response includes a token field containing the JWT and sets an argocd.token cookie. Use either the Authorization header (Bearer <token>) or the cookie for subsequent requests.

Can I use the Argo CD API without the REST server?

No, standard API interaction requires the Argo CD API server running. However, if using the CLI with --core mode or the ARGOCD_CORE environment variable, operations bypass the REST API and communicate directly with Kubernetes. This mode is specific to the CLI and does not expose the HTTP endpoints described here.

Where are the API endpoint definitions located?

The REST routes are declared in protobuf files under server/. For example, application endpoints are defined in server/application/application.proto, cluster endpoints in server/cluster/cluster.proto, and session management in server/session/session.proto. The Go server implementation that registers these routes resides in server/server.go.

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