> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="Application Service" icon="rocket" href="/api/application">
    CRUD operations for Application resources
  </Card>

  <Card title="ApplicationSet Service" icon="layer-group" href="/api/applicationset">
    Manage ApplicationSet resources and generators
  </Card>

  <Card title="Project Service" icon="folder" href="/api/appproject">
    AppProject management and RBAC policies
  </Card>

  <Card title="Cluster Service" icon="server" href="/api/cluster">
    Kubernetes cluster registration and management
  </Card>
</CardGroup>

### Configuration Services

<CardGroup cols={2}>
  <Card title="Repository Service" icon="code-branch" href="/api/repository">
    Git and Helm repository configuration
  </Card>

  <Card title="Session Service" icon="key" href="/api/authentication">
    Authentication and session management
  </Card>

  <Card title="Account Service" icon="user">
    User account and token management
  </Card>

  <Card title="Settings Service" icon="gear">
    Global Argo CD settings and configuration
  </Card>
</CardGroup>

### Security Services

<CardGroup cols={2}>
  <Card title="Certificate Service" icon="certificate">
    TLS certificate management for repositories
  </Card>

  <Card title="GPG Key Service" icon="lock">
    GPG key management for commit verification
  </Card>
</CardGroup>

## 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](/api/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

```go theme={null}
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

```bash theme={null}
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:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Use Appropriate Authentication">
    * Use service account tokens for automation
    * Use project tokens for scoped access
    * Rotate tokens regularly
  </Accordion>

  <Accordion title="Handle Streaming Connections">
    * Implement reconnection logic for watch streams
    * Set appropriate timeouts
    * Clean up connections properly
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="Optimize List Operations">
    * Use selectors to filter results
    * Use project filtering when possible
    * Consider using watch instead of polling
  </Accordion>
</AccordionGroup>

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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn how to authenticate API requests
  </Card>

  <Card title="Application API" icon="rocket" href="/api/application">
    Explore Application CRUD operations
  </Card>

  <Card title="Cluster API" icon="server" href="/api/cluster">
    Manage Kubernetes clusters
  </Card>

  <Card title="Repository API" icon="code-branch" href="/api/repository">
    Configure Git and Helm repositories
  </Card>
</CardGroup>