> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qumo-deploy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Relay Placement Heartbeat

> Internal relay-mesh endpoint, authenticated like introspection. A relay reports that it is alive and how clients reach it; relays that stop reporting leave placement after 45 s. Mounted only when the server has a relay domain (RELAY_PUBLIC_DOMAIN), and the host must lie under it.



## OpenAPI

````yaml /api-reference/openapi.yaml put /v1/relays/{relay_id}
openapi: 3.1.0
info:
  title: Qumo Deploy REST API
  description: >
    The Qumo Deploy REST API provides programmatic control over edge relay
    clusters,

    ephemeral Relay Credential issuance, tenant lifecycle, machine identities,
    and billing.

    Authentication is operation-specific: Relay Keys authenticate relay access
    operations,

    while user sessions and Identity Tokens authenticate control-plane
    operations.
  version: 1.0.0
servers:
  - url: https://api.qumo-deploy.com
    description: Production Control Plane
  - url: http://localhost:8080
    description: Local Development / Sandbox
security:
  - BearerAuth: []
paths:
  /v1/relays/{relay_id}:
    put:
      summary: Relay Placement Heartbeat
      description: >-
        Internal relay-mesh endpoint, authenticated like introspection. A relay
        reports that it is alive and how clients reach it; relays that stop
        reporting leave placement after 45 s. Mounted only when the server has a
        relay domain (RELAY_PUBLIC_DOMAIN), and the host must lie under it.
      parameters:
        - name: relay_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-z0-9][a-z0-9-]{0,62}$
          example: qumo-relay-is1a-1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - region
                - host
                - port
                - role
                - status
              properties:
                region:
                  type: string
                  example: is1a
                host:
                  type: string
                  example: is1a-1.relay.qumo-deploy.com
                port:
                  type: integer
                  example: 4433
                role:
                  type: string
                  enum:
                    - hub
                    - edge
                status:
                  type: string
                  enum:
                    - serving
                    - draining
      responses:
        '204':
          description: Recorded
        '400':
          description: Malformed body or unknown status
        '401':
          description: Missing or invalid relay token
        '422':
          description: >-
            The relay cannot be placed (for example, a host outside the relay
            domain)
      security: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: SessionOrIdentityToken
      description: |
        User session or Identity Token. Relay Keys are not accepted.

````