Skip to main content
API Explorer|API Explorer
Infrastructure/Agents
POSTAgentSince 1.0SynchronousAuth Required

RegisterAgent

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

Execution Availability

Try It Out

Submit a mock request using the current auth context and example-driven inputs.

Request Inputs

Body Fields

  • nameStringRequired

    Human-readable name for the new agent

    Example: prod-agent-01

  • typeStringRequired

    Type of the agent (log, metric, trace)

    Example: log

  • versionStringRequired

    Version of the agent binary being registered

    Example: 1.2.3

  • endpointStringRequired

    Reachable endpoint of the agent

    Example: http://192.168.1.10:7890

  • platformIdStringRequired

    UUID of the platform this agent is associated with

    Example: plat-001-abc

Responses

200 OK

On success, this API returns the following response structure.

  • uuidString

    Unique identifier of the agent instance

    Example: agent-abc123-def456

  • nameString

    Human-readable name of the agent

    Example: prod-agent-01

  • typeString

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

    Example: log

  • versionString

    Current version of the agent binary

    Example: 1.2.3

  • statusString

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

    Example: online

  • endpointString

    gRPC or HTTP endpoint of the agent

    Example: http://192.168.1.10:7890

  • platformIdString

    UUID of the platform this agent belongs to

    Example: plat-001-abc

  • regionString

    Deployment region of the agent

    Example: us-east-1

  • labelsString

    JSON string of key-value labels attached to this agent

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

  • lastHeartbeatAtString

    Last heartbeat at

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

  • createDateString

    Create date

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

  • lastOpDateString

    Last op date

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

Endpoint

POST/api/v1/agents

/api/v1/agents

Operation ID

RegisterAgent

Permalink

Request Example

curl -X POST '{host}/api/v1/agents' -H 'Authorization: Bearer {token}' -H 'Content-Type: application/json' -d '{"name":"prod-agent-01","type":"log","version":"1.2.3","endpoint":"http://192.168.1.10:7890","platformId":"plat-001-abc","region":"us-east-1","labels":"{\"env\":\"prod\"}"}'

Response Example

200
{
  "uuid": "agent-abc123-def456",
  "name": "prod-agent-01",
  "type": "log",
  "version": "1.2.3",
  "status": "online",
  "endpoint": "http://192.168.1.10:7890",
  "platformId": "plat-001-abc",
  "region": "us-east-1"
}

Change History

This API has no change history records yet.

View all change history