Skip to main content
The Rancher API provides a comprehensive REST interface for managing Kubernetes clusters, projects, nodes, and workloads across multiple cloud providers and infrastructure platforms.

​
API Architecture

Rancher provides multiple API groups organized by functionality:

​
Management API (management.cattle.io/v3)

The Management API is the primary interface for cluster-level operations:
  • Clusters: Create and manage Kubernetes clusters
  • Projects: Multi-tenant project management
  • Authentication: User, token, and RBAC management
  • Node Management: Node pools, node templates, and node drivers
  • Cloud Credentials: Manage credentials for cloud providers

​
Provisioning API (provisioning.cattle.io/v1)

The Provisioning API handles RKE2 and K3s cluster provisioning:
  • RKE2/K3s Clusters: Provision and configure clusters
  • Machine Pools: Define node pool configurations
  • Agent Customization: Customize cluster and fleet agents

​
Project API (project.cattle.io/v3)

The Project API manages project-scoped resources:
  • Workloads: Deployments, StatefulSets, DaemonSets, CronJobs
  • Namespaces: Namespace management within projects
  • Secrets: Service accounts, certificates, credentials

​
API Endpoints

​
Base URL

https://<rancher-server>/v3

​
Common Endpoints

GET    /v3/clusters
GET    /v3/clusters/{id}
POST   /v3/clusters
PUT    /v3/clusters/{id}
DELETE /v3/clusters/{id}

​
API Versioning

Rancher uses API versioning to maintain compatibility:

​
Management API Versions

  • v3: Current stable version for management operations
  • Backward compatibility maintained within major versions
  • Deprecated fields marked with annotations

​
Provisioning API Versions

  • v1: Current version for RKE2/K3s provisioning
  • Replaces legacy RKE (v1beta1) provisioning

​
API Group Format

<resource>.<group>/<version>
Examples:
  • clusters.management.cattle.io/v3
  • clusters.provisioning.cattle.io/v1
  • workloads.project.cattle.io/v3

​
Request Format

All API requests use JSON format: 
{
  "type": "cluster",
  "name": "my-cluster",
  "spec": {
    "displayName": "My Production Cluster",
    "description": "Production workload cluster"
  }
}

​
Response Format

API responses include:
  • Resource data: The requested resource
  • Metadata: Creation time, labels, annotations
  • Status: Current state and conditions
  • Links: Related resources and actions
{
  "id": "c-abcdef",
  "type": "cluster",
  "links": {
    "self": "https://rancher-server/v3/clusters/c-abcdef",
    "nodes": "https://rancher-server/v3/clusters/c-abcdef/nodes"
  },
  "metadata": {
    "name": "my-cluster",
    "creationTimestamp": "2024-01-01T00:00:00Z"
  },
  "spec": { ... },
  "status": { ... }
}

​
Rate Limiting

Rancher implements rate limiting to protect API stability:
  • Default: 100 requests per minute per user
  • Configurable via settings
  • Rate limit headers included in responses

​
Error Handling

API errors follow standard HTTP status codes:
CodeMeaning
400Bad Request - Invalid input
401Unauthorized - Invalid or missing authentication
403Forbidden - Insufficient permissions
404Not Found - Resource does not exist
409Conflict - Resource already exists
422Unprocessable Entity - Validation error
500Internal Server Error
Error response format: 
{
  "type": "error",
  "status": 400,
  "code": "InvalidFormat",
  "message": "Field 'spec.displayName' is required"
}

​
Next Steps

Authentication

Learn how to authenticate API requests

Clusters

Manage Kubernetes clusters

Projects

Multi-tenant project management

Workloads

Deploy and manage applications

Build docs developers (and LLMs) love

Get started for freeTalk to us