---
title: "Refresh tenant connector caches"
method: POST
path: "/api/v1/connectors/refresh/{tenant_id}"
tags: ["MCP Connectors"]
---

# Refresh tenant connector caches

`POST /api/v1/connectors/refresh/{tenant_id}`

## Request

- Base URL: `https://agent.getaxonflow.com`
- URL: `https://agent.getaxonflow.com/api/v1/connectors/refresh/{tenant_id}`
- Auth: one of:
  - HTTP basic
  - API key in header `X-Internal-Service-ID` and API key in header `X-Internal-Service-Token`
- TypeScript: <https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/docs/api/v1/connectors/refresh/:tenant_id/post.ts> (a function with typed inputs; its response is checked against the schema)

Invalidates and refreshes all cached connector instances for a tenant.
Use this after updating a tenant's connector configuration.

**`{tenant_id}` is not a selector.** It is validated against the
identity `apiAuthMiddleware` resolved and a mismatch is `403`
(`platform/agent/connector_refresh_api.go:152-156`); the tenancy that
is actually refreshed always comes from the credential.

- **Basic auth:** the resolved identity is your licensed org, so this
  route can only ever refresh your own pool.
- **Internal-service credential:** the resolved identity is whatever
  `X-Tenant-ID` you send (`platform/agent/authenticator.go:127-130`),
  so an operator targets a named tenant by sending that header *and*
  the matching path segment. Naming a tenant in the path with no
  `X-Tenant-ID` is `403`, because the identity then falls back to the
  synthetic `orchestrator-internal` client id.

`stats.cached_connectors` is **structurally 0** on this route — the
refresh empties the tenant's scope immediately before the count is
taken.

## Path parameters

- `tenant_id` string, required

## Response `200`

Tenant connectors refreshed

- ConnectorRefreshResponse: Response from connector cache refresh operations. Source of truth: `platform/agent/connector_refresh_api.go` (`ConnectorRefreshResponse`, lines 61-69).
  - `success` boolean, required: Whether the refresh operation succeeded
  - `message` string, required: Human-readable status message. Also the signal for which scope the credential bought: `Tenant connector caches refreshed` vs `All connector caches refreshed`.
  - `scope` 'all' | 'tenant' | 'connector', required: Which route produced this response
  - `tenant_id` string: The authenticated tenant. Omitted on a deployment-wide refresh (internal-service credential on `POST /api/v1/connectors/refresh`), because no single tenancy describes the work done.
  - `connector` string: Connector name (when scope is connector)
  - `duration` string, required: Duration of the refresh operation
  - `stats` ConnectorRefreshStats: Cache statistics after refresh. Source of truth: `platform/agent/connector_refresh_api.go` (`RefreshStatsInfo`, lines 83-88). This object carries `cached_connectors` **and nothing else**. It used to also declare `hits`, `misses`, `evictions` and `hit_rate_percent`; no producer ever set them, so they always serialized as misleading hard zeros, and they are deployment-wide figures that disclose other tenants' cache activity. They were removed from the struct in #3067 — read them from the `deployment` block of `GET /api/v1/connectors/cache/stats` (internal-service credential) or from the un-scoped `/prometheus` gauges.
    - `cached_connectors` integer: Cached-connector count *after* the eviction, scoped to the work just done: the caller's own count on a tenant refresh (`tenantRefreshStats`, lines 404-408), the deployment-wide count on an internal-service deployment-wide refresh (`deploymentRefreshStats`, lines 415-419). Structurally `0` on `POST /api/v1/connectors/refresh` and `POST /api/v1/connectors/refresh/{tenant_id}` — those routes evict the whole scope immediately before counting it. Only informative on `.../{tenant_id}/{connector_name}`.

## Other responses

- `400`: Missing tenant_id
- `401`: No usable credential. Written by the auth middleware as `JSONError` (`platform/agent/auth.go:602`), or — when the middleware admitted the caller but resolved no tenancy — by the handler as `ErrorResponse` (`platform/agent/connector_refresh_api.go:148`).
- `403`: The `{tenant_id}` path segment does not match the authenticated tenant (`platform/agent/connector_refresh_api.go:152-156`). Refused rather than silently downgraded to the caller's own scope, so an operator who mistypes a tenant learns about it.
- `500`: Refresh failed
- `503`: Registry not initialized

---

[API](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/revisions/34d30fcb7fa1?raw)