> ## 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.

# Regrade Key

> Lower one key's rung, writing `ASSURANCE_UPDATED` (v0.3 §5, §9.1bis): for when a root the key was graded under is distrusted or the evidence behind it is withdrawn  
Downgrade only: a rung is earned by evidence at registration or renewal, never asserted  
The agent's summary follows the floor across its usable keys. Mandates pinned to the key are evaluated at the new rung from their next use



## OpenAPI

````yaml /versions/2026-10-16.yaml post /agents/keys/regrade/{did}/{keyId}
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/keys/regrade/{did}/{keyId}:
    post:
      tags:
        - Agents
      summary: Regrade Key
      description: >-
        Lower one key's rung, writing `ASSURANCE_UPDATED` (v0.3 §5, §9.1bis):
        for when a root the key was graded under is distrusted or the evidence
        behind it is withdrawn  

        Downgrade only: a rung is earned by evidence at registration or renewal,
        never asserted  

        The agent's summary follows the floor across its usable keys. Mandates
        pinned to the key are evaluated at the new rung from their next use
      operationId: agents_regradeKey
      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
        - name: keyId
          required: true
          in: path
          description: 'The key id (`<did>#key-<n>`), URL-encoded: its `#` sent as `%23`.'
          schema:
            example: >-
              did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35#key-1
            type: string
        - $ref: '#/components/parameters/ApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegradeKeyBody'
      responses:
        '201':
          description: Returns a confirmation that the key is regraded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessEntity'
        '400':
          description: >-
            The body is malformed, the regrade would raise the rung or move the
            key to another root, or the key is revoked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 400
                  message:
                    type: string
                    example: >-
                      fold_failed:regrade_raises: ASSURANCE_UPDATED 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, or the
            agent holds no such key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    example: 404
                  message:
                    type: string
                    example: >-
                      unknown key
                      did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35#key-9
                  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:
    RegradeKeyBody:
      type: object
      properties:
        assurance:
          type: string
          enum:
            - pop
            - device
            - hardware
          description: 'The key''s assurance from now on: its current one or lower.'
          example: pop
        binding:
          type: string
          enum:
            - self
            - custodial
            - attested
          description: 'The key''s binding from now on: its current one or lower.'
          example: self
        root:
          type: string
          description: >-
            The key's current root, if any: a regrade never moves a key to
            another root.
        reason:
          type: string
          description: Why the key is downgraded, recorded on the agent's chain.
          example: attestation root distrusted
      required:
        - assurance
        - binding
        - reason
    SuccessEntity:
      type: object
      properties:
        ok:
          type: boolean
          description: Whether the operation was successful
          example: true
      required:
        - ok

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.