Skip to main content
ZStack
Infrastructure/Agents

RegisterAgent

Register a new agent with the platform and obtain its assigned UUID

POST/api/v1/agents

Operation ID

RegisterAgent

Since

1.0.0

Execution Mode

Synchronous

Auth Context

Auth Required

Auth Context

Send these values as request headers when calling this API.

AuthorizationstringRequired

Bearer Token

X-Tenant-IDstring

X-Tenant-ID

Request Inputs

application/json

Body Fields

  • name
    StringRequired

    Human-readable name for the new agent

    Example: prod-agent-01

  • type
    StringRequired

    Type of the agent (log, metric, trace)

    Example: log

  • version
    StringRequired

    Version of the agent binary being registered

    Example: 1.2.3

  • endpoint
    StringRequired

    Reachable endpoint of the agent

    Example: http://192.168.1.10:7890

  • platformId
    StringRequired

    UUID of the platform this agent is associated with

    Example: plat-001-abc

Responses

200 OK
200 OK

On success, this API returns the following response structure.

  • uuid
    String

    Unique identifier of the agent instance

    Example: agent-abc123-def456

  • name
    String

    Human-readable name of the agent

    Example: prod-agent-01

  • type
    String

    Type of the agent (e.g. log, metric, trace)

    Example: log

  • version
    String

    Current version of the agent binary

    Example: 1.2.3

  • status
    String

    Current status of the agent (online, offline, delayed)

    Example: online

  • endpoint
    String

    gRPC or HTTP endpoint of the agent

    Example: http://192.168.1.10:7890

  • platformId
    String

    UUID of the platform this agent belongs to

    Example: plat-001-abc

  • region
    String

    Deployment region of the agent

    Example: us-east-1

  • labels
    String

    JSON string of key-value labels attached to this agent

    Example: {"env":"prod","team":"ops"}

  • lastHeartbeatAt
    String

    Last heartbeat at

    Example: 2026-01-15T08:00:00Z

  • createDate
    String

    Create date

    Example: 2026-01-15T08:00:00Z

  • lastOpDate
    String

    Last op date

    Example: 2026-01-15T08:00:00Z