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

> Explore the Argo CD API structure. Understand how CRDs like Application orchestrate GitOps workflows and discover gRPC/HTTP endpoints for manifest rendering and client requests.

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

---

**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/main/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/main/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/main/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/main/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`](https://github.com/argoproj/argo-cd/blob/main/types.go), it encapsulates:

```go
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`](https://github.com/argoproj/argo-cd/blob/master/pkg/apis/application/v1alpha1/types.go)), 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:

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

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

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

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