Understanding the Argo CD API Structure: A Deep Dive into CRDs and Endpoints

Argo CD exposes a Kubernetes-native API built around Custom Resource Definitions (CRDs), where the Application resource acts as the central orchestrator for GitOps workflows, while separate gRPC and HTTP servers handle manifest rendering and client requests.

Understanding the Argo CD API structure requires mapping how the project translates GitOps operations into Kubernetes-style resources. The argoproj/argo-cd repository implements a layered architecture where CRDs define desired state, specialized servers manage execution, and controllers handle reconciliation. This design allows programmatic control over deployments through standard Kubernetes patterns or direct API calls.

Core API Resources and CRDs

Argo CD’s public API surface centers on four primary CRDs that encapsulate configuration and state. These resources reside in the pkg/apis directory and follow standard Kubernetes API conventions with Spec, Status, and Metadata fields.

The Application CRD

The Application resource, defined in [pkg/apis/application/v1alpha1/types.go](https://github.com/argoproj/argo-cd/blob/master/pkg/apis/application/v1alpha1/types.go), represents the declarative target state for a deployment. It contains the source repository configuration, destination cluster details, and synchronization policies required for continuous delivery.

Supporting Resources

Three additional CRDs provide the scaffolding for multi-tenant GitOps:

• AppProject ([pkg/apis/application/v1alpha1/appproject_types.go](https://github.com/argoproj/argo-cd/blob/master/pkg/apis/application/v1alpha1/appproject_types.go)): Groups applications and enforces RBAC boundaries, source repository whitelists, and destination cluster constraints.
• Cluster ([pkg/apis/cluster/v1alpha1/types.go](https://github.com/argoproj/argo-cd/blob/master/pkg/apis/cluster/v1alpha1/types.go)): Stores connection parameters and credentials for target Kubernetes clusters.
• Repository ([pkg/apis/repository/v1alpha1/types.go](https://github.com/argoproj/argo-cd/blob/master/pkg/apis/repository/v1alpha1/types.go)): Maintains access credentials and configuration for Git, Helm, or OCI artifact sources.

API Type Definitions

The Go structs that model these resources expose granular control over GitOps workflows through strongly typed fields that support Git, Helm, Kustomize, and plugin-based sources.

ApplicationSpec Deep Dive

The ApplicationSpec struct serves as the configuration blueprint. According to the source in types.go, it encapsulates:

type ApplicationSpec struct {
    Source *ApplicationSource `json:"source,omitempty"`
    Destination ApplicationDestination `json:"destination"`
    SyncPolicy *SyncPolicy `json:"syncPolicy,omitempty"`
    Project string `json:"project,omitempty"`
    Sources []ApplicationSource `json:"sources,omitempty"`
    // Additional fields for ignoreDifferences, info, etc.
}

Key fields include:

• Source: Points to a single ApplicationSource struct supporting Git repositories, Helm charts (ApplicationSourceHelm), Kustomize bases, or directory paths.
• Sources: Enables multi-source applications for scenarios requiring Helm charts from separate repositories or mixed manifest sources.
• Destination: Specifies the target cluster server URL and namespace via ApplicationDestination.
• SyncPolicy: Configures automated synchronization, pruning of removed resources, and self-healing behaviors.
• Project: Associates the application with an AppProject for RBAC enforcement.

ApplicationStatus and Health Monitoring

The ApplicationStatus struct in the same file tracks runtime state:

type ApplicationStatus struct {
    Sync SyncStatus `json:"sync,omitempty"`
    Health HealthStatus `json:"health,omitempty"`
    Conditions []ApplicationCondition `json:"conditions,omitempty"`
    Resources []ResourceStatus `json:"resources,omitempty"`
    OperationState *OperationState `json:"operationState,omitempty"`
}

This status subresource populates through reconciliation loops in [controller/app_controller.go](https://github.com/argoproj/argo-cd/blob/master/controller/app_controller.go), providing real-time visibility into sync state, resource health, and active operations.

Server Architecture and Request Flow

Argo CD distributes responsibilities across three distinct server components, each exposing specific API surfaces.

API Server vs Repo Server vs Controller

The API Server ([server/server.go](https://github.com/argoproj/argo-cd/blob/master/server/server.go)) exposes HTTP/JSON endpoints under /api/v1/ and gRPC services. It handles CRUD operations for Applications, handling requests in [server/application/application.go](https://github.com/argoproj/argo-cd/blob/master/server/application/application.go).

The Repo Server ([reposerver/server.go](https://github.com/argoproj/argo-cd/blob/master/reposerver/server.go)) operates as a gRPC backend for manifest generation. It clones repositories, resolves dependencies, and renders final Kubernetes manifests using helpers in [reposerver/repository/utils.go](https://github.com/argoproj/argo-cd/blob/master/reposerver/repository/utils.go).

The Application Controller ([controller/app_controller.go](https://github.com/argoproj/argo-cd/blob/master/controller/app_controller.go)) watches Application CRD changes, compares desired state against live cluster state, and orchestrates synchronization through the diff and sync utilities in [controller/app_utils.go](https://github.com/argoproj/argo-cd/blob/master/controller/app_utils.go).

End-to-End Request Flow

When creating an Application through the API, the flow follows this sequence:

1. Client sends POST /api/v1/applications with JSON matching the Application struct.
2. API Server validates permissions and normalizes the spec using ValidatePermissions and NormalizeApplicationSpec in util/argo/argo.go.
3. Kubernetes API persists the Application CRD in the Argo CD namespace.
4. Controller detects the change and triggers reconciliation.
5. Repo Server fetches the Git repository, processes Helm or Kustomize templates, and returns rendered manifests.
6. Controller applies manifests to the destination cluster and updates ApplicationStatus.
7. Client polls GET /api/v1/applications/{name} to retrieve updated status fields.

Practical Implementation Examples

Creating Applications via Go Client

The Argo CD Go client directly mirrors the API types. This example creates an Application using structures from pkg/apis/application/v1alpha1:

import (
    "context"
    appclient "github.com/argoproj/argo-cd/pkg/apiclient/application"
    "github.com/argoproj/argo-cd/pkg/apiclient"
    v1alpha1 "github.com/argoproj/argo-cd/pkg/apis/application/v1alpha1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

func createFrontendApp(client apiclient.Client) error {
    spec := v1alpha1.ApplicationSpec{
        Source: &v1alpha1.ApplicationSource{
            RepoURL:        "https://github.com/example/microservices",
            TargetRevision: "HEAD",
            Path:           "services/frontend",
        },
        Destination: v1alpha1.ApplicationDestination{
            Server:    "https://kubernetes.default.svc",
            Namespace: "frontend",
        },
        Project: "default",
    }

    _, err := client.NewApplication(context.Background(), &appclient.ApplicationCreateRequest{
        Application: &v1alpha1.Application{
            ObjectMeta: metav1.ObjectMeta{
                Name: "frontend-app",
            },
            Spec: spec,
        },
    })
    return err
}

Querying Status via REST API

For direct HTTP access, the API returns the ApplicationStatus structure:

curl -H "Authorization: Bearer $ARGOCD_TOKEN" \
     https://argocd.example.com/api/v1/applications/frontend-app | \
     jq '.status.sync.status, .status.health.status'

This returns the SyncStatus (Synced, OutOfSync) and HealthStatus (Healthy, Degraded, Progressing) fields defined in the CRD.

Updating Application Specifications

To modify an existing Application, such as updating a Helm chart version:

appResp, _ := client.Get(context.Background(), &appclient.ApplicationGetRequest{
    Name: "my-helm-app",
})
app := appResp.Application

app.Spec.Source.Helm.Version = "1.2.3"

_, err := client.Update(context.Background(), &appclient.ApplicationUpdateRequest{
    Application: app,
})

Summary

• Argo CD’s API structure centers on Kubernetes-style CRDs, with the Application resource in pkg/apis/application/v1alpha1/types.go serving as the primary interface for GitOps workflows.
• Three server components handle distinct responsibilities: the API Server for client requests, the Repo Server for manifest generation, and the Controller for state reconciliation.
• ApplicationSpec defines source repositories, destinations, and sync policies, while ApplicationStatus exposes real-time health and synchronization state.
• Programmatic access follows standard Kubernetes patterns through Go clients or HTTP/JSON endpoints under /api/v1/.

Frequently Asked Questions

How does the Argo CD API differ from the Kubernetes API?

The Argo CD API extends Kubernetes by registering Custom Resource Definitions that the Argo CD controllers watch. While it uses the same machinery (etcd, API server), it adds specialized endpoints for GitOps operations like manifest generation via the Repo Server and application synchronization state management that standard Kubernetes APIs do not provide.

What is the difference between the Repo Server and the API Server?

The API Server ([server/server.go](https://github.com/argoproj/argo-cd/blob/master/server/server.go)) handles external client requests, authentication, and CRUD operations on Application resources. The Repo Server ([reposerver/server.go](https://github.com/argoproj/argo-cd/blob/master/reposerver/server.go)) is an internal gRPC service that clones Git repositories, evaluates Helm charts, and generates Kubernetes manifests without exposing a public HTTP interface.

Where are the TypeScript definitions for the Argo CD API?

The web UI maintains TypeScript interfaces that mirror the Go structs in [ui/src/app/shared/models.ts](https://github.com/argoproj/argo-cd/blob/master/ui/src/app/shared/models.ts). The HTTP client implementation resides in [ui/src/app/shared/services/applications-service.ts](https://github.com/argoproj/argo-cd/blob/master/ui/src/app/shared/services/applications-service.ts), providing the frontend with typed access to the same ApplicationSpec and ApplicationStatus fields exposed by the backend.

Can I use the Argo CD API without the Kubernetes cluster directly?

Yes. While Argo CD stores data as Kubernetes CRDs, you interact with the API Server using bearer tokens or client certificates without requiring kubectl access to the underlying cluster. The Go client library in pkg/apiclient abstracts the gRPC and HTTP calls, allowing you to manage applications programmatically from external CI/CD systems or custom tooling.

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