API Overview

Argo CD API architecture, access methods, and service organization

Introduction

The Argo CD API provides programmatic access to all Argo CD functionality through both gRPC and REST interfaces. The API is organized into multiple services, each responsible for managing specific resource types.

API Architecture

Argo CD uses a dual-protocol architecture:

• gRPC: Native protocol for all API operations
• REST: HTTP/JSON interface via grpc-gateway transcoding

All gRPC services are automatically exposed as REST endpoints using the /api/v1/ base path.

Available Services

The Argo CD API is organized into the following services:

Core Services

Application Service

CRUD operations for Application resources

ApplicationSet Service

Manage ApplicationSet resources and generators

Project Service

AppProject management and RBAC policies

Cluster Service

Kubernetes cluster registration and management

Configuration Services

Repository Service

Git and Helm repository configuration

Session Service

Authentication and session management

Account Service

User account and token management

Settings Service

Global Argo CD settings and configuration

Security Services

Certificate Service

TLS certificate management for repositories

GPG Key Service

GPG key management for commit verification

API Endpoints

Base URL

https://<argocd-server>/api/v1

Protocol Mapping

Each gRPC service maps to REST endpoints:

Service	gRPC Package	REST Base Path
Application	application.ApplicationService	/api/v1/applications
ApplicationSet	applicationset.ApplicationSetService	/api/v1/applicationsets
Project	project.ProjectService	/api/v1/projects
Cluster	cluster.ClusterService	/api/v1/clusters
Repository	repository.RepositoryService	/api/v1/repositories
Session	session.SessionService	/api/v1/session

Authentication

All API requests (except session creation) require authentication. See the Authentication page for details on:

• Bearer token authentication
• Cookie-based sessions
• Service account tokens
• Project tokens

API Clients

Official Clients

Argo CD provides official client libraries:

• Go: github.com/argoproj/argo-cd/v3/pkg/apiclient
• CLI: argocd CLI tool uses the API client

Using the Go Client

import (
    "github.com/argoproj/argo-cd/v3/pkg/apiclient"
    applicationpkg "github.com/argoproj/argo-cd/v3/pkg/apiclient/application"
)

client, err := apiclient.NewClient(&apiclient.ClientOptions{
    ServerAddr: "argocd-server.example.com:443",
    AuthToken:  "your-token",
    Insecure:   false,
})

conn, appClient := client.NewApplicationClient()
defer conn.Close()

apps, err := appClient.List(ctx, &application.ApplicationQuery{})

Using REST API

curl -H "Authorization: Bearer $TOKEN" \
  https://argocd-server/api/v1/applications

Streaming APIs

Several services support streaming for real-time updates:

• Application Watch: Stream application change events
• Resource Tree Watch: Stream resource tree updates
• Pod Logs: Stream container logs
• ApplicationSet Watch: Stream ApplicationSet events

Streaming endpoints use Server-Sent Events (SSE) for REST or gRPC streaming.

API Versioning

The current API version is v1. All endpoints use the /api/v1/ prefix.

• API version is separate from Argo CD release version
• Breaking changes will result in a new API version
• Multiple API versions may be supported simultaneously

Error Handling

gRPC Status Codes

The API uses standard gRPC status codes:

Code	HTTP Equivalent	Description
OK	200	Success
INVALID_ARGUMENT	400	Invalid request parameters
UNAUTHENTICATED	401	Missing or invalid authentication
PERMISSION_DENIED	403	Insufficient permissions
NOT_FOUND	404	Resource not found
ALREADY_EXISTS	409	Resource already exists
INTERNAL	500	Internal server error

Error Response Format

REST API errors return JSON:

{
  "error": "application.get",
  "message": "application 'myapp' not found",
  "code": 5
}

Rate Limiting

Argo CD does not enforce global rate limits, but specific operations may have concurrency limits:

• Login requests: Configurable via ARGOCD_MAX_CONCURRENT_LOGIN_REQUESTS_COUNT
• Sync operations: Controlled by controller settings

Best Practices

Use Appropriate Authentication

• Use service account tokens for automation
• Use project tokens for scoped access
• Rotate tokens regularly

Handle Streaming Connections

• Implement reconnection logic for watch streams
• Set appropriate timeouts
• Clean up connections properly

Implement Proper Error Handling

• Check status codes before processing responses
• Retry on transient errors (503, connection errors)
• Don’t retry on authentication errors (401, 403)

Optimize List Operations

• Use selectors to filter results
• Use project filtering when possible
• Consider using watch instead of polling

OpenAPI Specification

The complete OpenAPI specification is available at:

https://<argocd-server>/swagger.json

You can explore the interactive API documentation at:

https://<argocd-server>/swagger-ui

Next Steps

Authentication

Learn how to authenticate API requests

Application API

Explore Application CRUD operations

Cluster API

Manage Kubernetes clusters

Repository API

Configure Git and Helm repositories