Skip to main content

Report agent liveness

POST /api/v1/agents/heartbeat

Allowed roles: agent.

Authentication​

The following OpenAPI alternatives describe accepted authentication. Browser mutations also require the canonical Origin header.

[
  {
    "organizationCredential": []
  },
  {
    "browserSession": []
  }
]

Parameters​

[]

Request body​

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "scannerVersion": {
            "type": "string",
            "maxLength": 40,
            "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$"
          },
          "pythonVersion": {
            "type": "string",
            "maxLength": 40,
            "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$"
          }
        },
        "required": []
      }
    }
  }
}

Responses​

{
  "200": {
    "description": "Success",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "ok": {
              "const": true
            },
            "serverTime": {
              "type": "string",
              "format": "date-time"
            },
            "configuration": {
              "type": [
                "object",
                "null"
              ]
            }
          },
          "required": [
            "ok",
            "serverTime"
          ]
        }
      }
    }
  },
  "400": {
    "description": "Validation error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "401": {
    "description": "Missing/expired/revoked credential",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "403": {
    "description": "Insufficient role",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "404": {
    "description": "Not found",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "409": {
    "description": "State or idempotency conflict",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "413": {
    "description": "Body too large",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "415": {
    "description": "Unsupported media type",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "429": {
    "description": "Request budget exhausted; respect Retry-After",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    },
    "headers": {
      "Retry-After": {
        "schema": {
          "type": "integer",
          "minimum": 1
        },
        "description": "Seconds until sufficient budget is expected; concurrent traffic may consume replenished capacity."
      }
    }
  },
  "500": {
    "description": "Internal error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  },
  "503": {
    "description": "Not configured",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  }
}

References such as #/components/schemas/Asset resolve in shared schemas. Download the OpenAPI contract for client generation. This page is generated; it describes the implemented development API, not planned endpoints.