Argo Applications API

openapi: 3.1.0
info:
  title: Argo CD Applications API
  description: The Argo CD API provides REST endpoints for managing GitOps continuous delivery on Kubernetes. It enables creating and managing applications, projects, repositories, clusters, and certificates. The API supports syncing application state to match the desired state declared in Git, querying health and sync status, managing access control, and configuring notifications. All operations require authentication via bearer token obtained from the session endpoint.
  version: v2.x
  contact:
    name: Argo CD Community
    url: https://argo-cd.readthedocs.io/en/stable/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://localhost/api/v1
  description: Argo CD Server (default in-cluster address)
security:
- bearerAuth: []
tags:
- name: Applications
  description: Operations for creating, querying, syncing, and deleting Argo CD GitOps applications.
paths:
  /applications:
    get:
      operationId: listApplications
      summary: Argo CD Argo List Applications
      description: Returns a list of all Argo CD applications, optionally filtered by project, namespace, or name. Each application includes its current sync status, health status, source configuration, and destination cluster details.
      tags:
      - Applications
      parameters:
      - $ref: '#/components/parameters/projectParam'
      - name: name
        in: query
        description: Filter applications by name.
        schema:
          type: string
      - name: namespace
        in: query
        description: Filter applications by destination namespace.
        schema:
          type: string
      - name: appNamespace
        in: query
        description: The application namespace to filter by.
        schema:
          type: string
      responses:
        '200':
          description: List of applications.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationList'
        '401':
          description: Unauthorized. Missing or invalid authentication token.
        '403':
          description: Forbidden. Insufficient permissions.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createApplication
      summary: Argo CD Argo Create an Application
      description: Creates a new Argo CD application from the provided Application manifest. The application must reference a valid project, source repository, and destination cluster. Optionally upsert to update an existing application with the same name.
      tags:
      - Applications
      parameters:
      - name: upsert
        in: query
        description: If true, perform an upsert rather than a create, updating the application if it already exists.
        schema:
          type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application'
      responses:
        '200':
          description: Application created or updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '400':
          description: Bad request. Invalid application specification.
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{name}:
    get:
      operationId: getApplication
      summary: Argo CD Argo Get an Application
      description: Returns the full specification and current status of a named Argo CD application, including sync status, health status, resource tree, and operation state.
      tags:
      - Applications
      parameters:
      - $ref: '#/components/parameters/appNameParam'
      - name: appNamespace
        in: query
        description: Application namespace.
        schema:
          type: string
      responses:
        '200':
          description: Application details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '401':
          description: Unauthorized.
        '404':
          description: Application not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateApplication
      summary: Argo CD Argo Update an Application
      description: Replaces the specification of an existing Argo CD application with the provided manifest. Used to update source, destination, sync policy, or other application configuration.
      tags:
      - Applications
      parameters:
      - $ref: '#/components/parameters/appNameParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application'
      responses:
        '200':
          description: Updated application.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
        '404':
          description: Application not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteApplication
      summary: Argo CD Argo Delete an Application
      description: Deletes the named Argo CD application. Optionally cascades deletion to all managed Kubernetes resources in the destination cluster.
      tags:
      - Applications
      parameters:
      - $ref: '#/components/parameters/appNameParam'
      - name: cascade
        in: query
        description: Cascade deletion to managed Kubernetes resources.
        schema:
          type: boolean
          default: true
      - name: propagationPolicy
        in: query
        description: Kubernetes resource deletion propagation policy (foreground, background, orphan).
        schema:
          type: string
          enum:
          - foreground
          - background
          - orphan
      responses:
        '200':
          description: Application deleted.
        '401':
          description: Unauthorized.
        '404':
          description: Application not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{name}/sync:
    post:
      operationId: syncApplication
      summary: Argo CD Argo Sync an Application
      description: Triggers a synchronization of the named Argo CD application, reconciling the live Kubernetes state with the desired state from the Git source. Supports selective resource sync, dry-run mode, force sync, and prune of removed resources.
      tags:
      - Applications
      parameters:
      - $ref: '#/components/parameters/appNameParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncRequest'
      responses:
        '200':
          description: Sync operation initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '401':
          description: Unauthorized.
        '404':
          description: Application not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{name}/rollback:
    post:
      operationId: rollbackApplication
      summary: Argo CD Argo Rollback an Application
      description: Rolls back the named application to a previous deployed revision. Requires the ID of a history entry from the application's deployment history.
      tags:
      - Applications
      parameters:
      - $ref: '#/components/parameters/appNameParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  format: int64
                  description: History ID of the revision to roll back to.
                prune:
                  type: boolean
                  description: Whether to prune resources removed in the target revision.
                dryRun:
                  type: boolean
                  description: Preview rollback without applying changes.
      responses:
        '200':
          description: Rollback initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        '401':
          description: Unauthorized.
        '404':
          description: Application not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    appNameParam:
      name: name
      in: path
      required: true
      description: The name of the Argo CD application.
      schema:
        type: string
    projectParam:
      name: project
      in: query
      description: Filter by project name.
      schema:
        type: string
  schemas:
    SyncPolicy:
      type: object
      description: Policy controlling how and when the application is synchronized.
      properties:
        automated:
          type: object
          description: Configuration for automatic synchronization.
          properties:
            prune:
              type: boolean
              description: Automatically delete resources removed from the source.
              default: false
            selfHeal:
              type: boolean
              description: Automatically sync when live state drifts from desired state.
              default: false
            allowEmpty:
              type: boolean
              description: Allows apps to have an empty source.
              default: false
        syncOptions:
          type: array
          description: List of sync option flags (e.g., CreateNamespace=true, PrunePropagationPolicy=foreground).
          items:
            type: string
        retry:
          type: object
          description: Retry configuration for failed sync operations.
          properties:
            limit:
              type: integer
              format: int64
              description: Maximum number of retry attempts. -1 for unlimited.
            backoff:
              type: object
              description: Backoff strategy for retries.
              properties:
                duration:
                  type: string
                  description: Initial retry backoff duration.
                factor:
                  type: integer
                  format: int64
                  description: Multiplicative factor applied to duration on each retry.
                maxDuration:
                  type: string
                  description: Maximum duration between retries.
    Application:
      type: object
      description: An Argo CD Application represents a deployed set of Kubernetes resources managed through GitOps.
      properties:
        apiVersion:
          type: string
          description: API version, always argoproj.io/v1alpha1.
        kind:
          type: string
          description: Resource kind, always Application.
        metadata:
          type: object
          description: Kubernetes object metadata.
          properties:
            name:
              type: string
              description: Application name.
            namespace:
              type: string
              description: Application namespace.
        spec:
          $ref: '#/components/schemas/ApplicationSpec'
        status:
          $ref: '#/components/schemas/ApplicationStatus'
    SyncRequest:
      type: object
      description: Request body for triggering an application sync operation.
      properties:
        revision:
          type: string
          description: Specific Git revision to sync to. Defaults to the current target revision.
        dryRun:
          type: boolean
          description: Preview sync without applying changes.
        prune:
          type: boolean
          description: Delete resources no longer defined in the source.
        strategy:
          type: object
          description: Sync strategy configuration.
          properties:
            apply:
              type: object
              description: Use kubectl apply sync strategy.
              properties:
                force:
                  type: boolean
                  description: Force resource updates through delete and recreate.
            hook:
              type: object
              description: Use hook-based sync strategy.
              properties:
                force:
                  type: boolean
                  description: Force resource updates.
        resources:
          type: array
          description: Specific resources to sync (partial sync).
          items:
            type: object
            properties:
              group:
                type: string
                description: Kubernetes API group.
              kind:
                type: string
                description: Resource kind.
              name:
                type: string
                description: Resource name.
              namespace:
                type: string
                description: Resource namespace.
    ApplicationList:
      type: object
      description: A list of Argo CD applications.
      properties:
        items:
          type: array
          description: Array of application objects.
          items:
            $ref: '#/components/schemas/Application'
    ApplicationSpec:
      type: object
      description: Desired state specification for an Argo CD application.
      required:
      - destination
      - project
      - source
      properties:
        source:
          $ref: '#/components/schemas/ApplicationSource'
        destination:
          $ref: '#/components/schemas/ApplicationDestination'
        project:
          type: string
          description: Argo CD project this application belongs to.
        syncPolicy:
          $ref: '#/components/schemas/SyncPolicy'
        ignoreDifferences:
          type: array
          description: Resource fields to ignore when computing sync status.
          items:
            type: object
            properties:
              group:
                type: string
                description: Kubernetes API group.
              kind:
                type: string
                description: Kubernetes resource kind.
              jsonPointers:
                type: array
                items:
                  type: string
                description: JSON Pointer paths to ignore.
    ApplicationSource:
      type: object
      description: Git or Helm chart source for the application manifests.
      required:
      - repoURL
      properties:
        repoURL:
          type: string
          description: URL of the Git repository or Helm chart repository.
          format: uri
        path:
          type: string
          description: Path within the repository where manifests are located. Used for Git repositories.
        targetRevision:
          type: string
          description: Git branch, tag, or commit SHA to deploy. Defaults to HEAD.
        chart:
          type: string
          description: Helm chart name. Used when repoURL points to a Helm registry.
        helm:
          type: object
          description: Helm-specific source configuration.
          properties:
            valueFiles:
              type: array
              items:
                type: string
              description: List of Helm value file paths.
            values:
              type: string
              description: Inline Helm values as a YAML string.
            releaseName:
              type: string
              description: Helm release name override.
        kustomize:
          type: object
          description: Kustomize-specific source configuration.
          properties:
            namePrefix:
              type: string
              description: Prefix to append to all resource names.
            nameSuffix:
              type: string
              description: Suffix to append to all resource names.
            images:
              type: array
              items:
                type: string
              description: List of image overrides in name=tag format.
    ApplicationStatus:
      type: object
      description: Observed state and operational status of an Argo CD application.
      properties:
        sync:
          type: object
          description: Current sync status.
          properties:
            status:
              type: string
              description: Sync status (Synced, OutOfSync, Unknown).
              enum:
              - Synced
              - OutOfSync
              - Unknown
            revision:
              type: string
              description: Deployed Git revision (commit SHA).
        health:
          type: object
          description: Current health status.
          properties:
            status:
              type: string
              description: Health status (Healthy, Progressing, Degraded, Suspended, Missing, Unknown).
              enum:
              - Healthy
              - Progressing
              - Degraded
              - Suspended
              - Missing
              - Unknown
            message:
              type: string
              description: Human-readable health status message.
        operationState:
          type: object
          description: State of the current or most recent operation.
          properties:
            phase:
              type: string
              description: Operation phase (Running, Failed, Succeeded, Error, Terminating).
            message:
              type: string
              description: Human-readable operation status message.
            startedAt:
              type: string
              format: date-time
              description: When the operation started.
            finishedAt:
              type: string
              format: date-time
              description: When the operation finished.
    ApplicationDestination:
      type: object
      description: Target Kubernetes cluster and namespace for application deployment.
      properties:
        server:
          type: string
          description: Kubernetes API server URL of the target cluster. Use https://kubernetes.default.svc for the in-cluster target.
          format: uri
        name:
          type: string
          description: Name of the registered cluster. Mutually exclusive with server.
        namespace:
          type: string
          description: Target namespace in the destination cluster.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from the POST /session endpoint using username/password or from an external OIDC provider configured in Argo CD.
externalDocs:
  description: Argo CD API Documentation
  url: https://argo-cd.readthedocs.io/en/stable/developer-guide/api-docs/