---
title: "Refresh the caller's connector caches"
method: POST
path: "/api/v1/connectors/refresh"
tags: ["MCP Connectors"]
---

# Refresh the caller's connector caches

`POST /api/v1/connectors/refresh`

## Request

- Base URL: `https://agent.getaxonflow.com`
- URL: `https://agent.getaxonflow.com/api/v1/connectors/refresh`
- 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/post.ts> (a function with typed inputs; its response is checked against the schema)

Invalidates and refreshes cached connector instances.
Use this after configuration changes or deployments.

**The scope depends on which credential you present**
(`platform/agent/connector_refresh_api.go:184-216`):

| Credential | Scope | `message` | `tenant_id` |
|---|---|---|---|
| Basic auth (tenant) | the authenticated tenant's connectors only | `Tenant connector caches refreshed` | present |
| Internal-service | every tenant's connectors | `All connector caches refreshed` | **absent** |

**Performance impact:** the next request for each evicted connector
incurs factory-creation overhead.

**Authentication.** This route is wrapped in `apiAuthMiddleware`
(`platform/agent/connector_refresh_api.go:123`) and the tenancy comes
from the authenticated identity — a caller can no longer evict another
tenant's pool. Supply **either**:

- `Authorization: Basic base64(clientId:clientSecret)` — the tenant
  lane (no credentials are required when
  `DEPLOYMENT_MODE=community`); or
- `X-Internal-Service-ID` + `X-Internal-Service-Token` — the
  operator lane, which is the only way to trigger a deployment-wide
  eviction.

*(Historical note: these four routes were registered with no auth
middleware at all — #2883. They are authenticated as of #3067; the
pre-#3067 "deploy behind network-level controls" advisory no longer
applies.)*

`stats.cached_connectors` is **structurally 0** on this route: the
refresh empties the scope immediately before the count is taken. That
is the success signal, not a failure.

## Response `200`

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

- `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`).
- `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)