---
name: clinic-ticdc
description: |
  Query TiCDC changefeed metadata through Clinic's internal canonical Data Proxy
  List and Detail APIs using an internal Clinic API key.
---

# TiCDC metadata API

Use this sub-skill for read-only TiCDC changefeed metadata. It is an **internal
Clinic API** capability: authenticate with `CLINIC_API_KEY` and use the
canonical `/data-proxy/api/v1` paths below. Do not use a TiDB Cloud JWT,
`x-session-id`, DevOps API token, or caller-supplied Dataflow metadata.

`{orgID}` is the TiDB Cloud/DBAAS org ID and `{clusterID}` is the TiDB Cloud
logical cluster ID. Clinic validates ownership and resolves the upstream
Dataflow architecture from trusted cluster metadata. Internal calls support
Starter, Essential, Dedicated, Premium, and BYOC clusters; Essential v2 is
outside this contract.

## API contract

| Operation | Method and path | Response envelope |
|-----------|-----------------|-------------------|
| List changefeeds | `GET /data-proxy/api/v1/orgs/{orgID}/clusters/{clusterID}/ticdc/changefeeds` | `{"changefeeds": [...]}` |
| Get changefeed | `GET /data-proxy/api/v1/orgs/{orgID}/clusters/{clusterID}/ticdc/changefeeds/{changefeedID}` | `{"changefeed": {...}}` |

`changefeedID` for Detail is the kernel/internal `id` from the List response,
not the business-facing `display_id`. The service rejects a kernel ID that does
not belong to the requested cluster.

Changefeed IDs, display IDs, checkpoint TSO, and RCU are strings because they
may exceed JavaScript's safe integer range. Downstream credentials are
allowlisted and redacted by Clinic; nevertheless, do not log or persist full
responses because endpoint and sink configuration can still be customer data.

## Authentication

```bash
source scripts/clinic-shell.sh
get_clinic_auth
```

`get_clinic_auth` loads the internal `CLINIC_API_KEY`. For production, use the
environment-specific protected file selected by local Clinic operating
guidance; never print the key or place it in a command history.

## Shell helpers

```bash
source scripts/clinic-shell.sh
get_clinic_auth

ORG_ID="1234567890123456789"
CLUSTER_ID="1234567890123456789"

# Returns {"changefeeds": [...]}.
clinic_ticdc_changefeeds_list "$ORG_ID" "$CLUSTER_ID"

# Select a non-empty kernel/internal ID from the List response.
CHANGEFEED_ID="cfd-example-changefeed-id"
clinic_ticdc_changefeed_get "$ORG_ID" "$CLUSTER_ID" "$CHANGEFEED_ID"
```

The List result can include a newly created changefeed with an empty `id`. Do
not call Detail for that entry until an internal/kernel ID is present.
The helper treats a non-empty changefeed ID as an opaque string and URL-encodes
it; it does not assume that the ID is numeric. The helpers also preserve an
HTTP error response body and return status 22 without requiring curl's newer
`--fail-with-body` option.

## Equivalent curl

```bash
curl -sS -w '\nHTTP %{http_code}\n' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${CLINIC_API_KEY}" \
  "${CLINIC_ENDPOINT}/data-proxy/api/v1/orgs/${ORG_ID}/clusters/${CLUSTER_ID}/ticdc/changefeeds"

curl -sS -w '\nHTTP %{http_code}\n' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer ${CLINIC_API_KEY}" \
  "${CLINIC_ENDPOINT}/data-proxy/api/v1/orgs/${ORG_ID}/clusters/${CLUSTER_ID}/ticdc/changefeeds/${CHANGEFEED_ID}"
```

## Error handling

| HTTP status | Meaning |
|-------------|---------|
| 400 | Invalid org, cluster, changefeed ID, or unsupported cluster type |
| 403 | Access denied |
| 404 | Cluster/changefeed not found, including a kernel ID from another cluster |
| 502 | Invalid canonical metadata or invalid upstream response |
| 503 | Dataflow/Dataflow-NG temporarily unavailable |
| 504 | Upstream TiCDC metadata request timed out |

Use the response `X-Trace-ID` to correlate a failure with Clinic Data Service
logs. Do not include the access key or complete changefeed configuration in
incident notes.