> ## Documentation Index > Fetch the complete documentation index at: https://docs.humanos.tech/llms.txt > Use this file to discover all available pages before exploring further. # Retire Agent > Retire the agent for good, from active or suspended: its DID is revoked and it takes no further change A retired agent cannot be resumed ## OpenAPI ````yaml /versions/2026-10-16.yaml post /agents/retire/{did} openapi: 3.1.0 info: title: Humanos API description: Humanos API version: '1.0' contact: {} servers: - url: https://api.humanos.tech security: [] tags: - name: humanosApp description: '' paths: /agents/retire/{did}: post: tags: - Agents summary: Retire Agent description: >- Retire the agent for good, from active or suspended: its DID is revoked and it takes no further change A retired agent cannot be resumed operationId: agents_retire parameters: - name: did required: true in: path description: The agent's DID, URL-encoded. schema: example: did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35 type: string - $ref: '#/components/parameters/ApiVersion' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/AgentStatusBody' responses: '201': description: Returns the agent, now retired. content: application/json: schema: $ref: '#/components/schemas/AgentSubjectEntity' '400': description: The agent is already retired, or the reason is over 200 characters. content: application/json: schema: type: object properties: statusCode: type: number example: 400 message: type: string example: >- fold_failed:event_after_retired: ACTOR_RETIRED cannot be recorded for did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35 (§5.2) error: type: string example: Bad Request '404': description: >- The agent is unknown, or another organization operates it: an organization only reads and changes its own agents. content: application/json: schema: type: object properties: statusCode: type: number example: 404 message: type: string example: actor not found error: type: string example: Not Found components: parameters: ApiVersion: name: API-Version in: header required: false schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-10-16' description: >- Pin request, response, and webhook shapes to a specific dated API version (YYYY-MM-DD). Omit to use the version pinned to your API key (set when the key is created; new keys default to the latest version). New integrations should target the latest version. schemas: AgentStatusBody: type: object properties: reason: type: string description: Why, recorded on the agent's chain. example: under review AgentSubjectEntity: type: object properties: id: type: string description: The agent's DID. example: did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35 actorType: type: string description: The kind of actor; always `agent` on these routes. enum: - agent - organization - user example: agent status: type: string description: active | suspended | retired (v0.3 §4). enum: - active - suspended - retired keys: description: The agent's keys, rotated and revoked ones included. type: array items: $ref: '#/components/schemas/AgentKeyEntity' assurance: type: string description: >- The agent's summary rung: the floor across its usable keys. Authorization reads each key's own. enum: - pop - device - hardware example: hardware binding: type: string description: The binding of the agent's summary rung. enum: - self - custodial - attested example: attested bootstrapAnchor: type: string description: >- What vouched for the agent when it was registered: an API key for every agent registered here. enum: - api_key - manual example: api_key verifiedAt: type: string description: >- When the assurance was last VERIFIED. A mandate bounds its own freshness against this (`agent.verifiedAt >= now - duration("720h")`); renewing an attestation moves it forward. example: '2026-09-02T10:15:00.000Z' root: type: string description: Trust root the attestation chained to. example: aws-nitro existedSince: type: string description: >- When the agent came to exist on the platform (v0.3 §3.1). It never moves, unlike `verifiedAt`. example: '2026-09-02T10:15:00.000Z' runtime: description: >- The runtime every usable key shares, dated by the oldest attestation among them; for reporting, never authorization. Absent when the keys do not share one. allOf: - $ref: '#/components/schemas/AgentRuntimeEntity' operator: type: object description: >- Pointer to the org-signed AFFILIATION event — presence and DID, never an inline claim — with the relation it asserts and, when it states one, when it lapses (`validUntil`). Nothing is recorded when an affiliation lapses: once `validUntil` has passed, or when the relation is not `operates`, a mandate whose rules read the operator's accreditation denies with `affiliation_invalid`. example: org: did:web:humanos.tech:org:04ad6920-e048-4dd8-9379-21c1f344df6d relation: operates affiliationEvent: sha256-ABNj6qHZ7vDpIk79rfjWOpMJtP6XBEkqRYgY2QH5ju8= required: - id - actorType - status - keys - assurance - binding - bootstrapAnchor - verifiedAt - existedSince AgentKeyEntity: type: object properties: id: type: string description: Key id — what a mandate pins (D7). example: >- did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35#key-1 publicKeyJwk: type: object description: >- P-256 public JWK (v0.3 §3.1: `publicKeyJwk`, the name the DID document uses). example: kty: EC crv: P-256 x: … 'y': … status: type: string description: >- active | rotated | revoked. `rotated` is a LABEL, not a disablement: a mandate pinned to a rotated key stays satisfiable through its successor. Only `revoked` removes a key. enum: - active - rotated - revoked example: active rotatedTo: type: string description: Succession pointer set by rotation — what D7 resolution follows. example: >- did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35#key-2 assurance: type: string description: >- The rung this key earned: authorization reads it, not the agent's summary. Absent on a key from a chain written before keys had their own rung, which the agent's summary then covers. enum: - pop - device - hardware example: pop binding: type: string description: The binding this key earned; absent when `assurance` is. enum: - self - custodial - attested example: self verifiedAt: type: string description: >- When this key's evidence was last verified. Renewing one key moves only its own. example: '2026-09-02T10:15:00.000Z' root: type: string description: Trust root this key's attestation chained to. example: aws-nitro attestation: type: object description: >- The event that carries this key's evidence, by reference (v0.3 §9.4): `event` its chain-link, `kind` the evidence type. example: event: sha256-… kind: device-self runtime: description: >- The runtime attested for this key's process (v0.3 §9.4ter). Absent means `none`. allOf: - $ref: '#/components/schemas/AgentRuntimeEntity' required: - id - publicKeyJwk - status AgentRuntimeEntity: type: object properties: class: type: string description: 'The runtime class: `none`, `app`, `host` or `tee`.' enum: - none - app - host - tee example: tee at: type: string description: >- When this class was established. Rules read it as `agent.runtimeAt`; absent or expired reads as `none`. example: '2026-09-02T10:15:00.000Z' mechanism: type: string description: >- The mechanism that produced it: `nitro`, `sev-snp`, `tdx`, `app-attest`, `play-integrity` or `tpm`. example: nitro rootFingerprint: type: - string - 'null' description: >- SHA-256 of the matched pinned root's DER, hex: the anchor the environment chained to. example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 measurementId: type: string description: >- The image identifier whose expected measurement matched (`tee` only). example: payments-agent:1.4.2 event: type: string description: >- Chain-link of the event carrying the raw attestation, by reference (v0.3 §9.4). example: sha256-ABNj6qHZ7vDpIk79rfjWOpMJtP6XBEkqRYgY2QH5ju8= required: - class - at ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.