Documented steps

Enumerate served API groups with GET /apis, which returns an APIGroupList containing each group's versions and preferredVersion. The core group is served at /api (not /apis) and omits the group segment.
Fetch the CRD definition itself: GET /apis/apiextensions.k8s.io/v1/customresourcedefinitions/{plural}.{group}.
Read spec.group, spec.scope (Namespaced or Cluster), spec.names.plural, and spec.versions[]. Choose a version with served: true, preferring the one with storage: true.
Build the base path. Namespaced: /apis/{spec.group}/{version}/namespaces/{namespace}/{spec.names.plural}. Cluster-scoped: /apis/{spec.group}/{version}/{spec.names.plural}. Example: a CRD with group stable.example.com, version v1, plural crontabs, scope Namespaced is served at /apis/stable.example.com/v1/namespaces/{ns}/crontabs.
Confirm capabilities before assuming CRUD: GET /apis/{group}/{version} returns an APIResourceList giving each resource's exact name, namespaced boolean, and supported verbs.
Perform standard operations: GET the collection to list, GET .../{name} to read, POST to the collection to create, PUT or PATCH .../{name} to update, DELETE .../{name} to remove.
Check spec.versions[].subresources.status on the CRD. If present, update status only via .../{name}/status — PUT there ignores changes to everything except the status stanza, and writes to the main resource ignore status changes.
Check spec.versions[].subresources.scale. If present, the resource exposes .../{name}/scale taking an autoscaling/v1 Scale object, wired through specReplicasPath, statusReplicasPath, and labelSelectorPath.
Apply the same query parameters as built-ins: dryRun=All, fieldValidation=Strict, fieldManager for apply, and resourceVersion for optimistic concurrency.
Use aggregated discovery for a single round trip on large clusters: request /apis with Accept: application/json;v=v2;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList (stable since v1.30).
Docs: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/ and https://kubernetes.io/docs/reference/using-api/api-concepts/

Known gotchas

application/strategic-merge-patch+json is NOT supported on any CRD-backed resource. Use JSON Patch, JSON Merge Patch, or Server-Side Apply instead.
Server-Side Apply treats custom resources without merge-strategy markers as unstructured: all lists are atomic, so applying a list takes ownership of the entire list rather than merging entries.
Subresource configuration is PER VERSION. A CRD can serve multiple versions with different subresources blocks and schemas — always read the target version's own entry rather than assuming uniformity.
When the status subresource is enabled, writes to the main resource silently ignore the status stanza. Controllers that PUT the whole object and expect status to persist will see their status updates vanish with no error.
With the status subresource enabled, .metadata.generation increments only on spec changes, not on metadata- or status-only changes — this is what makes generation/observedGeneration comparison meaningful.
For the scale subresource, specReplicasPath and statusReplicasPath are required. A missing value at specReplicasPath makes GET on /scale error; a missing statusReplicasPath value defaults to 0.
labelSelectorPath is optional but required in practice for HPA to work, and must point at a string field holding a serialized label selector — not a structured selector object.
Without the aggregated-discovery Accept header you receive the legacy unaggregated discovery document, which costs one request per group version.

Discover and access Kubernetes custom resources (CRDs) generically over REST

Documented steps

Known gotchas

Related routes

Give your agent this knowledge — and 15,700+ more routes

Need this verified for your stack — or a route we don't have yet?