# Connect or rotate an external HTTPS worker

Source: <https://everruns.com/docs/api/operations/register_external_agent/>

[Docs](https://everruns.com/docs/)/[API reference](https://everruns.com/docs/api/)/[Agents & authoring](https://everruns.com/docs/api/groups/agents-authoring/)/Connect or rotate an external HTTPS worker

# Connect or rotate an external HTTPS worker

Preview

Requires dangerous-settings permission and installation enablement. Stop active turns first. The preinstalled secret is encrypted and never returned.

Public APIEverruns Cloud and self-hosted Platform

POST`/v1/agents/{agent_id}/external-worker`

See [authentication](https://everruns.com/docs/sre/runbooks/authentication/) for credentials and permissions.

## Parameters

### Path Parameters

**agent_id**

required

string

## Request Bodyrequired

Media typeapplication/json

Register a predeployed HTTPS endpoint after a signed ownership challenge.

object

**agent_id**

Agent public ID or name; the HTTP route supplies this value.

string

**endpoint_secret**

required

Preinstall this random, 32+ character secret in the endpoint. Never a user PAT.

string

**endpoint_url**

required

Verified public HTTPS URL that receives signed invocation requests.

string

### Example

```plaintext
https://sales.example.workers.dev/
```

## Responses

200

### 200

Media typeapplication/json

Public status of a customer-hosted HTTPS runtime; credentials are never exposed.

object

**enabled**

required

Whether this binding can lease new work. Disabled bindings retain routing.

boolean

**endpoint_url**

required

Verified public HTTPS URL that receives signed invocation requests.

string

**last_error**

Sanitized dispatch error, cleared after a successful invocation or registration.

string | null

**last_invoked_at**

Time of the latest invocation attempt, if any.

string | null format: date-time

### Example

```json
{
  "endpoint_url": "https://sales.example.workers.dev/"
}
```

FetchcURL

Request

```js
const url = 'https://app.everruns.com/api/v1/agents/example/external-worker';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"agent_id":"example","endpoint_secret":"example","endpoint_url":"https://sales.example.workers.dev/"}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

Request

```sh
curl --request POST \
  --url https://app.everruns.com/api/v1/agents/example/external-worker \
  --header 'Content-Type: application/json' \
  --data '{ "agent_id": "example", "endpoint_secret": "example", "endpoint_url": "https://sales.example.workers.dev/" }'
```

Additional language examples require JavaScript. The default request example is available above.

200

200 ·

```json
{
  "enabled": true,
  "endpoint_url": "https://sales.example.workers.dev/"
}
```

## Matching endpoints