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

> Master the Argo CD API with this comprehensive guide. Learn to interact effectively using both REST and gRPC for seamless automation and integration with your CI/CD workflows.

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

---

**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`](https://github.com/argoproj/argo-cd/blob/main/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.

```bash
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:

```http
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:

```bash

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

```go
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`](https://github.com/argoproj/argo-cd/blob/main/ui/src/app/shared/services/requests.ts) to prefix URLs with `/api/v1` and handle credentials:

```typescript
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`](https://github.com/argoproj/argo-cd/blob/main/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:

```json
{
  "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`](https://github.com/argoproj/argo-cd/blob/main/server/rbacpolicy/rbacpolicy.go) and registered in [`server/server.go`](https://github.com/argoproj/argo-cd/blob/main/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`](https://github.com/argoproj/argo-cd/blob/main/server/server.go).