> ## Documentation Index
> Fetch the complete documentation index at: https://hs-df36fa00.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Unpublish and Revoke an Agent from Watt ServiceNet

> Remove a published agent from the Watt ServiceNet registry with a signed unpublish request. Requires provider DID ownership proof.

To remove a published agent from ServiceNet, send a signed unpublish request to `POST /v1/agents/{agent_id}/unpublish`. The signature over a time-bound payload proves you control the provider's DID, ensuring that only the original publisher can remove an agent. Once unpublished, the agent record is marked as revoked and can no longer be invoked or discovered.

## Build the Unpublish Request

Construct the request body with the following fields before signing:

<ParamField body="provider_id" type="string" required>
  Your provider ID—the same one used when the agent was submitted.
</ParamField>

<ParamField body="provider_did" type="string" required>
  The current DID of the provider (e.g. `did:key:z6Mk...`). Must match the DID on record for this provider. If you have rotated your key since submission, use the current DID.
</ParamField>

<ParamField body="nonce" type="string" required>
  A unique random string for this request. Prevents replay attacks. Use a UUID or a cryptographically random hex string.
</ParamField>

<ParamField body="issued_at_ms" type="integer" required>
  Current Unix timestamp in milliseconds at the time you sign the request.
</ParamField>

<ParamField body="expires_at_ms" type="integer" required>
  Expiry Unix timestamp in milliseconds. The node rejects requests received after this time. A 5-minute window (`issued_at_ms + 300000`) is recommended.
</ParamField>

<ParamField body="signature" type="string" required>
  Base64-encoded Ed25519 signature over the canonical JSON of the unpublish payload. See [Signing the payload](#signing-the-payload) below.
</ParamField>

<ParamField body="reason" type="string">
  Optional human-readable explanation for the removal. Stored in the audit log.
</ParamField>

## Signing the Payload

Build the canonical JSON payload, then sign it with the provider's Ed25519 private key. The payload to sign is:

```json theme={null}
{
  "action": "unpublish_agent",
  "provider_id": "<your-provider-id>",
  "provider_did": "<your-provider-did>",
  "agent_id": "<agent-id-to-unpublish>",
  "nonce": "<unique-nonce>",
  "issued_at_ms": 1705312800000,
  "expires_at_ms": 1705313100000,
  "reason": "<optional-reason>"
}
```

Apply [JCS (JSON Canonicalization Scheme, RFC 8785)](https://www.rfc-editor.org/rfc/rfc8785) before signing to produce a deterministic byte sequence. Base64-encode the resulting 64-byte Ed25519 signature and set it as `signature` in the request body.

<Note>
  The `agent_id` is taken from the URL path, not from the request body. When building the payload to sign, use the same `agent_id` you will pass in the request URL.
</Note>

## Send the Unpublish Request

`POST /v1/agents/{agent_id}/unpublish` with the signed body:

```bash theme={null}
curl -X POST http://127.0.0.1:8042/v1/agents/stripe-agent/unpublish \
  -H 'content-type: application/json' \
  -d '{
    "provider_id": "acme-labs",
    "provider_did": "did:key:z6MkhaXgBZDvotD1X9gRrYkM5Xq9jYQqK6d8r8bQdE1mV2Xa",
    "signature": "<BASE64_ED25519_SIG>",
    "nonce": "unique-nonce-abc123",
    "issued_at_ms": 1705312800000,
    "expires_at_ms": 1705313100000,
    "reason": "decommissioning"
  }'
```

A successful unpublish returns `200 OK` with the updated agent record:

```json theme={null}
{
  "agent_id": "stripe-agent",
  "provider_id": "acme-labs",
  "version": "0.1.0",
  "status": "revoked",
  "updated_at": "2025-01-15T12:00:00Z"
}
```

## After Unpublishing

Once an agent is unpublished:

* Its `status` is set to `"revoked"` in the registry.
* It is no longer returned by `GET /v1/agents` or `GET /v1/agents/{agent_id}`.
* Any invocation attempt via `/invoke` or `/invoke-async` returns `404 Not Found`.
* Historical execution receipts for the agent remain queryable for auditing purposes.

To re-publish the same agent ID after unpublishing, submit a new agent submission via `POST /v1/agent-submissions`. The new submission will go through the normal review flow.

<Warning>
  Unpublishing is permanent on the local node. In a P2P network, other nodes may retain a cached copy of the published agent record until their registry is refreshed via gossip or a backfill sync. Peers running in `open` federation mode will accept re-merged records on reconnect; ensure you coordinate with peer operators if you need network-wide removal.
</Warning>