# Clear a deployment's endpoint

DELETE

/v1/system/tenants/{tenantId}/deployments/{deploymentId}/endpoint

```sh
curl --request DELETE \
  --url https://example.com/v1/system/tenants/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/deployments/example/endpoint \
  --header 'Authorization: Bearer <token>'
```

Clears the endpoint before its pack service is deleted: the deployment’s endpoint is `cleared`, and calls to its tools fail closed (`pack-endpoint-cleared`), never going to another deployment. Works for a closing or suspended tenant too: that’s how its services are retired. Clearing twice keeps the first time. Takes `system:deployments`.

## Authorizations

- **[bearerAuth](https://docs.kindgi.com/v0.1.8/reference/api.md#bearerauth)**

## Parameters

### Path Parameters

**tenantId**

required

string format: uuid

The tenant’s id (a UUID).

**deploymentId**

required

string

\>= 1 characters <= 128 characters

The deployment’s id, as `GET /v1/system/deployments` lists it.

### Header Parameters

**Idempotency-Key**

string

\>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per `docs/API-ROUTE-CONVENTIONS.md` §3.1). A retry sent while the first request still runs is answered `409 idempotency-key-in-flight` with `Retry-After`, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets `409 idempotency-key-replay-withheld`, with the first request’s status and when it succeeded (from 0.1.5).

## Responses

### 200

Cleared: the deployment’s endpoint as its tenant sees it.

application/json

Its pack service’s status, when the server routes each pack call to the deployment that shipped the tool (`KINDGI_PACK_ROUTING=per-deployment`). Absent otherwise. `pending`: no pack service yet, and calls to its tools fail (`pack-endpoint-pending`) rather than go to another deployment. `ready`: calls go to its own pack service. `cleared`: its pack service was taken down, and calls fail (`pack-endpoint-cleared`). Carries no URL and no token.

object

**status**

required

string

Allowed values: pending ready cleared

**since**

required

When the status last changed.

string format: date-time

**problem**

With `pending` only: the last reason the deployment has no pack service yet, gone once the status changes. A fixed code, never free text.

object

**code**

required

One of a fixed list; a later runtime may add codes, so treat an unknown one as a reason not yet named. The server refused the endpoint it was given: `endpoint-url-invalid` (not `https`, or with user info or a path), `endpoint-host-not-allowed` (the host isn’t on the operator’s allowlist), `endpoint-name-mismatch` (the host doesn’t name this deployment’s service), `endpoint-unreachable` (the pack service didn’t answer), `endpoint-info-mismatch` (it answered as another pack or version), `image-not-allowed` (the image is outside the tenant’s repository). The pack service couldn’t be created: `tenant-not-provisioned` (the tenant has nowhere to run pack services yet), `capacity-unavailable` (no room for another pack service just now), `service-start-failed` (the image was deployed but didn’t start).

string

**since**

required

When it was recorded.

string format: date-time

##### Example

```json
{
  "status": "pending"
}
```

### 400

Malformed request body.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 401

Missing / malformed / expired / revoked bearer token.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 403

A tenant’s key or session (`system-principal-required`), or a system key without `system:deployments` (`system-scope-missing`).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 404

No such tenant (`tenant-not-found`), or no such deployment in it (`deployment-not-found`).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 409

Idempotency-Key was reused with a different body, or resource-state conflict.

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 500

Server error (unmapped domain code or framework crash).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

### 503

The operator’s access record can’t be written, so nothing was done (`access-record-unavailable`).

application/json

object

**error**

required

object

**code**

required

Stable machine-readable discriminant. Values match domain error codes (see `docs/API-ROUTE-CONVENTIONS.md` §4.3).

string

**message**

required

string

**details**

Optional, kind-specific.

object

**_key_**

additional properties

any

**requestId**

required

Server-assigned request id; also echoed via `X-Request-Id` header.

string

##### Examplegenerated

```json
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}
```

## See also

- [`PUT /v1/system/tenants/{tenantId}/deployments/{deploymentId}/endpoint`: Record where a deployment's pack service runs](https://docs.kindgi.com/v0.1.8/reference/api/operations/systemdeploymentssetendpoint.md)
- [`GET /v1/system/tenants`: List tenants](https://docs.kindgi.com/v0.1.8/reference/api/operations/systemtenantslist.md)
- [`POST /v1/system/tenants`: Create a tenant](https://docs.kindgi.com/v0.1.8/reference/api/operations/systemtenantscreate.md)
- [`GET /v1/system/tenants/{tenantId}`: Read a tenant](https://docs.kindgi.com/v0.1.8/reference/api/operations/systemtenantsget.md)
- [Error code `access-record-unavailable`](https://docs.kindgi.com/v0.1.8/reference/errors.md#access-record-unavailable)
- [Error code `deployment-not-found`](https://docs.kindgi.com/v0.1.8/reference/errors.md#deployment-not-found)
- [Error code `system-principal-required`](https://docs.kindgi.com/v0.1.8/reference/errors.md#system-principal-required)
- [Error code `system-scope-missing`](https://docs.kindgi.com/v0.1.8/reference/errors.md#system-scope-missing)
- [Error code `tenant-not-found`](https://docs.kindgi.com/v0.1.8/reference/errors.md#tenant-not-found)
- [Every error code](https://docs.kindgi.com/v0.1.8/reference/errors.md)