Go API reference¶

Generated from eve-iac OpenAPI/semantics. Do not edit manually.

Public methods on *eveiac.Client. Module path: github.com/eve-iac/eve-iac/sdk/go/eveiac.

How-to is the workflow guide. This page is the operation reference.

EVE IaC model¶

YAML is IaC intent: what you want the lab to be. The EVE UNL is the persisted native lab definition. Live observation is what EVE is doing right now, and it can differ from both. planProject asks what would have to change. reconcileProject with to_eve makes EVE match IaC intent. reconcileProject with from_eve turns the current UNL definition into new IaC intent. getProjectStatus is the lightweight live poll. inspectProject is the rich structural observation.

• IaC intent. The YAML project, and the public JSON of that YAML. It describes what you want the lab to be. It is not a live observation.
• EVE UNL definition. EVE's persisted lab file. It is not the same thing as transient runtime state.
• Live observation. What is happening in EVE right now: node run state, runtime link quality, and other operational facts that can differ from the UNL.
• Structural observation. The rich inspect snapshot: nodes, interfaces, networks, links, and presentation, with runtime metadata attached. It is not the lightweight poll.
• to_eve. Make EVE match IaC intent.
• from_eve. Turn the current EVE UNL definition into new IaC intent. It is not a capture of transient runtime state, and it is not importProject.

Pointer semantics:

• nil pointer = omitted on the wire
• eveiac.Ptr(false) = explicit false
• eveiac.Ptr(0) = explicit zero
• Typed structs may not represent every explicit-null case; Client.Do is the escape hatch

timeoutMs ...int overrides the operation timeout when a value is passed.

Every method takes context.Context. Cancel the context to abort the HTTP call.

Connection / Authentication¶

GetHealth¶

Family: Session

Purpose¶

Tells you whether this eve-iac-agent process is reachable and which build is running. No project and no token are required.

Mental model¶

Is the agent up?

Use when¶

• checking connectivity before login
• reading the agent version

Do not use when¶

• you need lab or node state

Reads¶

• the agent process

Changes¶

Nothing. Read-only.

Signature¶

func (c *Client) GetHealth(ctx context.Context, timeoutMs ...int) (*HealthData, error)

• HTTP: GET /api/v1/health
• operationId: getHealth
• Authentication: none
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

HealthData

Field	Go type	Required	Semantics
status (Status)	*string	no
tls (Tls)	*bool	no
version (Version)	*string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "status": "ok",
  "tls": true,
  "version": "0.9.0-1"
}

Processing the result¶

Typical field access after a successful call:

health, err := client.GetHealth(ctx)
if health != nil && health.Status != nil && *health.Status != "ok" { return err }

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

health, err := client.GetHealth(ctx)
if err != nil {
    return err
}
_ = health

Login¶

Family: Session

Purpose¶

Opens an agent session and returns the bearer token later calls send.

Mental model¶

Sign me in.

Use when¶

• starting a client session

Do not use when¶

• you already have a token; use getSession to check it

Reads¶

• the username and password you send

Changes¶

Creates an agent session.

Related¶

• getSession
• logout

Signature¶

func (c *Client) Login(ctx context.Context, body LoginRequest, timeoutMs ...int) (*LoginData, error)

• HTTP: POST /api/v1/login
• operationId: login
• Authentication: none
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	LoginRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: LoginRequest¶

This request type is the same wire shape as LoginRequest.

Field	Go type	Required	Semantics
username (Username)	string	yes
password (Password)	string	yes

Returns¶

LoginData

Field	Go type	Required	Semantics
token (Token)	*string	no
username (Username)	*string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Human login omits token. --json includes token — store as EVE_IAC_TOKEN, never log stdout in CI.

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "username": "admin"
}

Processing the result¶

Typical field access after a successful call:

login, err := client.Login(ctx, eveiac.LoginRequest{Username: "admin", Password: "secret"})
token := ""
if login.Token != nil { token = *login.Token }

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
invalid_credentials	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport

Example¶

session, err := client.Login(ctx, eveiac.LoginRequest{Username: "admin", Password: "secret"})
if err != nil {
    return err
}
token := ""
if session.Token != nil {
    token = *session.Token
}
client, err = eveiac.NewClient(eveiac.Config{URL: url, Token: token, CAPEM: caPEM})

Logout¶

Family: Session

Purpose¶

Ends the agent session that belongs to the current bearer token.

Mental model¶

Sign me out.

Use when¶

• discarding a token you no longer want to use

Reads¶

• the current session

Changes¶

Deletes that agent session.

Related¶

• login

Signature¶

func (c *Client) Logout(ctx context.Context, body LogoutRequest, timeoutMs ...int) (*StatusOkData, error)

• HTTP: POST /api/v1/logout
• operationId: logout
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	LogoutRequest	no	Optional; empty object is sent when omitted.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: LogoutRequest¶

This request type is the same wire shape as LogoutRequest.

No object fields (see type).

Returns¶

StatusOkData

Field	Go type	Required	Semantics
status (Status)	*string	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

_, err := client.Logout(ctx, eveiac.LogoutRequest{})

GetSession¶

Family: Session

Purpose¶

Checks that the bearer token is still a live agent session.

Mental model¶

Am I still signed in?

Use when¶

• probing a stored token before other calls

Do not use when¶

• you need lab state

Reads¶

• the current agent session

Changes¶

Nothing. Read-only.

Related¶

• login
• logout

Signature¶

func (c *Client) GetSession(ctx context.Context, timeoutMs ...int) (*SessionData, error)

• HTTP: GET /api/v1/session
• operationId: getSession
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

SessionData

Field	Go type	Required	Semantics
username (Username)	*string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "username": "admin"
}

Processing the result¶

Typical field access after a successful call:

sess, _ := client.GetSession(ctx)
_ = sess.Username

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetSession(ctx)

GetCapabilities¶

Family: Session

Purpose¶

Reports what this agent build can do for each project mode.

Mental model¶

What can this agent do?

Use when¶

• deciding which project operations the connected agent supports

Reads¶

• agent capability flags

Changes¶

Nothing. Read-only.

How-to¶

• Start, stop, and wipe lab nodes

Signature¶

func (c *Client) GetCapabilities(ctx context.Context, timeoutMs ...int) (*CapabilitiesData, error)

• HTTP: GET /api/v1/capabilities
• operationId: getCapabilities
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

CapabilitiesData

Field	Go type	Required	Semantics
eveReachable (EveReachable)	*bool	no
eveBaseUrl (EveBaseUrl)	*string	no
features (Features)	map[string]bool	no
projectModes (ProjectModes)	map[string]ProjectModeCaps	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "eveReachable": true,
  "eveBaseUrl": "https://127.0.0.1",
  "features": {
    "import": true,
    "inspect": true
  },
  "projectModes": {
    "create": {
      "topology_mutation": true,
      "reconcile": true
    },
    "load": {
      "topology_mutation": false,
      "lifecycle": {
        "start": true,
        "stop": true,
        "wipe": true
      }
    }
  }
}

Processing the result¶

Typical field access after a successful call:

caps, _ := client.GetCapabilities(ctx)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetCapabilities(ctx)

Templates / Metadata¶

GetPublicSchema¶

Family: Metadata

Purpose¶

Returns selected fragments of the public IaC JSON Schema so an editor can validate YAML intent.

Mental model¶

What shape is IaC intent allowed to have?

Use when¶

• loading schema fragments for an editor

Do not use when¶

• you need a lab, a template list, or live EVE state

Reads¶

• the embedded public schema

Changes¶

Nothing. Read-only.

Important semantics¶

• Lazy public JSON Schema fragments from the canonical eve-iac-v1 embed. sections required minItems 1. Unknown or empty sections: 400 invalid_request, no partial map. Response sections preserves request order. revision is lowercase SHA-256 of exact embed bytes. Not lab YAML, not live template/network/interface capabilities. No all=true.

Signature¶

func (c *Client) GetPublicSchema(ctx context.Context, body GetPublicSchemaRequest, timeoutMs ...int) (*SchemaData, error)

• HTTP: POST /api/v1/schema
• operationId: getPublicSchema
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	GetPublicSchemaRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: GetPublicSchemaRequest¶

This request type is the same wire shape as SchemaRequest.

Field	Go type	Required	Semantics
sections (Sections)	[]string	yes

Returns¶

SchemaData

Field	Go type	Required	Semantics
revision (Revision)	string	yes	Lowercase hex SHA-256 of the exact embedded canonical schema bytes. Same value for every fragment in the response.
sections (Sections)	map[string]any	yes	Map keyed by requested section name, preserving request order. Values are JSON Schema documents, not a compact DTO.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "revision": "f7f8d72c113b156e85907c716d4cfcc934179ecde0a0101f6937d7b0376b2399",
  "sections": {
    "traffic_filters": {
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/trafficFilter"
      }
    }
  }
}

Processing the result¶

Typical field access after a successful call:

schema, err := client.GetPublicSchema(ctx, eveiac.SchemaRequest{Sections: []string{"traffic_filters", "tasks"}})
_ = schema.Revision

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetPublicSchema(ctx, eveiac.GetPublicSchemaRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

ListTemplates¶

Family: Metadata

Purpose¶

Lists the node templates this EVE can place in a lab.

Mental model¶

Which node templates exist?

Use when¶

• building a template picker

Do not use when¶

• you need one template's images or attributes; use getTemplate, listTemplateImages, or listTemplateAttributes

Reads¶

• the EVE template catalog

Changes¶

Nothing. Read-only.

Related¶

• getTemplate
• getTemplateCatalog

Signature¶

func (c *Client) ListTemplates(ctx context.Context, query *ListTemplatesQuery, timeoutMs ...int) (*TemplatesData, error)

• HTTP: GET /api/v1/templates
• operationId: listTemplates
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
query	ListTemplatesQuery (*ListTemplatesQuery)	no	Query object. Omit the argument to send no query string.
timeoutMs	...int	no	Override the 15000 ms default.

Query schema: ListTemplatesQuery¶

Field	Go type	Required	Semantics
provisioned (Provisioned)	*string	no	Only the string true filters to provisioned templates. Omitted means all.

Returns¶

TemplatesData

Field	Go type	Required	Semantics
templates (Templates)	[]Template	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "templates": [
    {
      "id": "iol",
      "description": "IOL",
      "type": "qemu",
      "provisioned": true,
      "configSupported": true
    },
    {
      "id": "vpcs",
      "description": "VPCS",
      "type": "vpcs",
      "provisioned": true,
      "configSupported": true
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

data, _ := client.ListTemplates(ctx, nil)
for _, t := range data.Templates { _ = t.ID }

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

all, err := client.ListTemplates(ctx, nil)
listed, err := client.ListTemplates(ctx, &eveiac.ListTemplatesQuery{Provisioned: eveiac.Ptr("true")})

GetTemplateCatalog¶

Family: Presentation

Purpose¶

Maps each template name to its description and device family so a canvas can choose an icon. This is presentation metadata, not IaC intent and not a node.

Mental model¶

How should this template be drawn?

Use when¶

• choosing a device graphic

Do not use when¶

• you are writing topology YAML

Reads¶

• the presentation catalog

Changes¶

Nothing. Read-only.

Important semantics¶

• Presentation only. Not desired state. An unknown or empty device_family is normalized to other by the agent. The response is not a Project or a Node and must not be written back as topology.

Related¶

• listTemplates
• listIcons

Signature¶

func (c *Client) GetTemplateCatalog(ctx context.Context, timeoutMs ...int) (*TemplateCatalogData, error)

• HTTP: GET /api/v1/templates/catalog
• operationId: getTemplateCatalog
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

TemplateCatalogData

Field	Go type	Required	Semantics
templates (Templates)	map[string]TemplateFamily	yes

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetTemplateCatalog(ctx)

GetTemplate¶

Family: Metadata

Purpose¶

Returns one template's authoring detail, including the canonical template id.

Mental model¶

What is this template?

Use when¶

• inspecting one template before placing a node

Reads¶

• that EVE template

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS data.id is the canonical template. Unknown id: 404 unknown_template. Never success with an empty body for a missing template.

Related¶

• listTemplates
• listTemplateImages
• listTemplateAttributes

Signature¶

func (c *Client) GetTemplate(ctx context.Context, id string, timeoutMs ...int) (*TemplateDetail, error)

• HTTP: GET /api/v1/templates/{id}
• operationId: getTemplate
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
id	string	yes	Path parameter
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

TemplateDetail

Field	Go type	Required	Semantics
id (ID)	*string	no
description (Description)	*string	no
type (Type)	*string	no
provisioned (Provisioned)	*bool	no
configSupported (ConfigSupported)	*bool	no
icon (Icon)	*string	no
images (Images)	[]TemplateImage	no
default (Default)	*string	no
image_requirement (ImageRequirement)	*string	no
attributes (Attributes)	[]TemplateAttribute	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "id": "iol",
  "description": "IOL",
  "type": "qemu",
  "provisioned": true,
  "configSupported": true,
  "default": "iol-2024",
  "images": [
    {
      "id": "iol-2024",
      "available": true
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

tpl, _ := client.GetTemplate(ctx, "iol")

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_template	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

data, err := client.GetTemplate(ctx, "iol")

ListTemplateImages¶

Family: Metadata

Purpose¶

Lists the images available for one template.

Mental model¶

Which images can this template boot?

Use when¶

• offering an image choice for a node

Reads¶

• images for that template

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS data.template is the canonical template. Unknown id: 404 unknown_template. Never success with an empty body for a missing template.

Related¶

• getTemplate

Signature¶

func (c *Client) ListTemplateImages(ctx context.Context, id string, timeoutMs ...int) (*TemplateImagesData, error)

• HTTP: GET /api/v1/templates/{id}/images
• operationId: listTemplateImages
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
id	string	yes	Path parameter
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

TemplateImagesData

Field	Go type	Required	Semantics
template (Template)	*string	no
type (Type)	*string	no
provisioned (Provisioned)	*bool	no
default (Default)	*string	no
images (Images)	[]TemplateImage	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_template	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

data, err := client.ListTemplateImages(ctx, "iol")

ListTemplateAttributes¶

Family: Metadata

Purpose¶

Lists the authoring attributes for one template.

Mental model¶

Which settings does this template expose?

Use when¶

• building a node form

Reads¶

• attributes for that template

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS data.template is the canonical template. Unknown id: 404 unknown_template. Never success with an empty body for a missing template.

Related¶

• getTemplate

Signature¶

func (c *Client) ListTemplateAttributes(ctx context.Context, id string, timeoutMs ...int) (*TemplateAttributesData, error)

• HTTP: GET /api/v1/templates/{id}/attributes
• operationId: listTemplateAttributes
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
id	string	yes	Path parameter
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

TemplateAttributesData

Field	Go type	Required	Semantics
template (Template)	*string	no
type (Type)	*string	no
attributes (Attributes)	[]TemplateAttribute	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_template	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

data, err := client.ListTemplateAttributes(ctx, "iol")

ListNetworkTypes¶

Family: Metadata

Purpose¶

Lists the network types EVE can place in a lab.

Mental model¶

Which network types exist?

Use when¶

• building a network picker

Reads¶

• the EVE network-type catalog

Changes¶

Nothing. Read-only.

Related¶

• getNetworkAuthoring

Signature¶

func (c *Client) ListNetworkTypes(ctx context.Context, timeoutMs ...int) (*NetworkTypesData, error)

• HTTP: GET /api/v1/network-types
• operationId: listNetworkTypes
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

NetworkTypesData

Field	Go type	Required	Semantics
types (Types)	[]NetworkType	no
natOnly (NatOnly)	*bool	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.ListNetworkTypes(ctx)

GetNetworkAuthoring¶

Family: Metadata

Purpose¶

Returns the authoring detail for one network type.

Mental model¶

How do I author this network?

Use when¶

• building a form for one network type

Reads¶

• that network type

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS data.id is the canonical network type. Unknown id: 404 unknown_network_type.

Related¶

• listNetworkTypes

Signature¶

func (c *Client) GetNetworkAuthoring(ctx context.Context, id string, timeoutMs ...int) (*NetworkAuthoring, error)

• HTTP: GET /api/v1/authoring/networks/{id}
• operationId: getNetworkAuthoring
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
id	string	yes	Path parameter
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

NetworkAuthoring

Field	Go type	Required	Semantics
id (ID)	*string	no
label (Label)	*string	no
icon (Icon)	*string	no
supported (Supported)	*bool	no
attributes (Attributes)	[]TemplateAttribute	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "id": "bridge",
  "label": "bridge",
  "supported": true,
  "attributes": [
    {
      "name": "smart",
      "label": "Smart Bridge",
      "kind": "integer",
      "group": "manage",
      "values": [
        "0",
        "1"
      ]
    },
    {
      "name": "pnet_out",
      "label": "Uplink",
      "kind": "enum",
      "group": "manage",
      "values": [
        "",
        "pnet0",
        "nat0"
      ]
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

data, _ := client.GetNetworkAuthoring(ctx, "bridge")

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_network_type	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

data, err := client.GetNetworkAuthoring(ctx, "bridge")

ListIcons¶

Family: Presentation

Purpose¶

Lists the node and network icon names the canvas can draw.

Mental model¶

Which icons exist?

Use when¶

• resolving an icon name

Do not use when¶

• you need the icon bytes; use getAuthoringIconsZip

Reads¶

• the icon index

Changes¶

Nothing. Read-only.

Related¶

• getAuthoringIconsZip
• getTemplateCatalog

Signature¶

func (c *Client) ListIcons(ctx context.Context, timeoutMs ...int) (*IconsData, error)

• HTTP: GET /api/v1/icons
• operationId: listIcons
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

IconsData

Field	Go type	Required	Semantics
icons (Icons)	[]Icon	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.ListIcons(ctx)

ListFolders¶

Family: Metadata

Purpose¶

Lists EVE lab folders under a path so a user can pick where a lab lives.

Mental model¶

Which lab folders are here?

Use when¶

• browsing the EVE lab tree

Do not use when¶

• the path is a .unl lab file

Reads¶

• EVE lab folders

Changes¶

Nothing. Read-only.

Signature¶

func (c *Client) ListFolders(ctx context.Context, query *ListFoldersQuery, timeoutMs ...int) (*FoldersData, error)

• HTTP: GET /api/v1/folders
• operationId: listFolders
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
query	ListFoldersQuery (*ListFoldersQuery)	no	Query object. Omit the argument to send no query string.
timeoutMs	...int	no	Override the 15000 ms default.

Query schema: ListFoldersQuery¶

Field	Go type	Required	Semantics
path (Path)	*string	no	EVE folder path. Omitted or empty means labs root /. Not a .unl lab path.

Returns¶

FoldersData

Field	Go type	Required	Semantics
path (Path)	*string	no
parent (Parent)	*string	no	Parent folder path. Empty at labs root.
folders (Folders)	[]FolderEntry	no
labs (Labs)	[]FolderEntry	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "path": "/Customers",
  "parent": "/",
  "folders": [
    {
      "name": "ACME",
      "path": "/Customers/ACME",
      "lock": false
    }
  ],
  "labs": [
    {
      "name": "OSPF.unl",
      "path": "/Customers/OSPF.unl",
      "lock": false
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

root, _ := client.ListFolders(ctx, nil)
nested, _ := client.ListFolders(ctx, &eveiac.ListFoldersQuery{Path: eveiac.Ptr("/Customers")})

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

root, err := client.ListFolders(ctx, nil)
nested, err := client.ListFolders(ctx, &eveiac.ListFoldersQuery{Path: eveiac.Ptr("/Customers")})

GetAuthoringIconsZip¶

Family: Presentation

Purpose¶

Downloads one zip of the node and network icon files for the canvas.

Mental model¶

Give me the icon files.

Use when¶

• caching icon bytes for a canvas

Reads¶

• the process-memoized icon archive

Changes¶

Nothing. Read-only.

Performance¶

Built once per agent process. A later call returns that archive.

Important semantics¶

• Raw application/zip of node/ and network/. Not a JSON envelope. Built once per agent process, together with the authoring snapshot. A file EVE cannot serve is omitted. timeoutMs 0 waits until that pull finishes.

Related¶

• listIcons
• getAuthoringRevision

Signature¶

func (c *Client) GetAuthoringIconsZip(ctx context.Context, timeoutMs ...int) (any, error)

• HTTP: GET /api/v1/authoring/icons.zip
• operationId: getAuthoringIconsZip
• Authentication: Bearer token required
• Default timeout: 0 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	...int	no	Override the 0 ms default.

Returns¶

Unnamed JSON object.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetAuthoringIconsZip(ctx)

GetAuthoringRevision¶

Family: Metadata

Purpose¶

Returns the hash of the authoring catalog this agent process has memoized, so a client can skip a full snapshot.

Mental model¶

Has the authoring catalog changed?

Use when¶

• deciding whether to reload templates, networks, and icons

Reads¶

• the process-memoized authoring snapshot

Changes¶

Nothing. Read-only.

Important semantics¶

• Lowercase SHA-256 of the process-memoized authoring snapshot. iconsRevision is the SHA-256 of the icon zip and is present on success, because the snapshot and the zip are stored together. timeoutMs 0 waits until that pull finishes. Not the health version and not POST /api/v1/schema revision. A new EVE image is invisible until the agent process restarts.

Related¶

• getAuthoringSnapshot

Signature¶

func (c *Client) GetAuthoringRevision(ctx context.Context, timeoutMs ...int) (*AuthoringRevisionData, error)

• HTTP: GET /api/v1/authoring/revision
• operationId: getAuthoringRevision
• Authentication: Bearer token required
• Default timeout: 0 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	...int	no	Override the 0 ms default.

Returns¶

AuthoringRevisionData

Field	Go type	Required	Semantics
revision (Revision)	string	yes
iconsRevision (IconsRevision)	*string	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetAuthoringRevision(ctx)

GetAuthoringSnapshot¶

Family: Metadata

Purpose¶

Returns the static authoring catalog for this agent process: templates, families, network authoring, and icon indexes. Icon bytes are not included.

Mental model¶

Give me the authoring catalog.

Use when¶

• loading the canvas catalog once per agent process

Reads¶

• the process-memoized authoring snapshot

Changes¶

Nothing. Read-only.

Performance¶

Memoized for the agent process. A new EVE image is invisible until the agent restarts.

Important semantics¶

• Static templates, family catalog, network authoring, and icon indexes for one agent process. Icon bytes are omitted. timeoutMs 0 waits until the catalog pull finishes. Further revision calls return the same memo.

Related¶

• getAuthoringRevision
• getAuthoringIconsZip

Signature¶

func (c *Client) GetAuthoringSnapshot(ctx context.Context, timeoutMs ...int) (*AuthoringSnapshotData, error)

• HTTP: GET /api/v1/authoring/snapshot
• operationId: getAuthoringSnapshot
• Authentication: Bearer token required
• Default timeout: 0 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
timeoutMs	...int	no	Override the 0 ms default.

Returns¶

AuthoringSnapshotData

Field	Go type	Required	Semantics
revision (Revision)	string	yes
templates (Templates)	[]TemplateDetail	yes
catalog (Catalog)	TemplateCatalogData	yes
networkTypes (NetworkTypes)	NetworkTypesData	yes
networks (Networks)	[]NetworkAuthoring	yes
icons (Icons)	[]Icon	yes
netIcons (NetIcons)	[]Icon	yes
cluster (Cluster)	[]ClusterMember	no	GET /api/cluster members loaded with the authoring snapshot. id is the sat key stored in topology.yml. name is the label shown in the node form. -1 any and 0 local are added by the form when absent.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetAuthoringSnapshot(ctx)

CompleteLinkInterfaces¶

Family: Metadata

Purpose¶

Lists the interfaces of a node that already exists in IaC intent, including which ones are already used.

Mental model¶

Which interfaces can I connect on this node?

Use when¶

• completing a link endpoint while editing intent

Do not use when¶

• the node is not in the project yet; use previewInterfaces for a template

Reads¶

• the packed project and the template interface map

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS is InterfacesData: source=node, canonical template, IaC node key, items[{name,type,used}]. Unknown node: 400 unknown_node. Unknown template: 404 unknown_template.

Related¶

• previewInterfaces

Signature¶

func (c *Client) CompleteLinkInterfaces(ctx context.Context, body CompleteLinkInterfacesRequest, timeoutMs ...int) (*InterfacesData, error)

• HTTP: POST /api/v1/authoring/link-completions
• operationId: completeLinkInterfaces
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	CompleteLinkInterfacesRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: CompleteLinkInterfacesRequest¶

This request type is the same wire shape as AuthoringPayload.

Field	Go type	Required	Semantics
dir (Dir)	*string	no	Rejected when non-empty.
yaml (YAML)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
template (Template)	*string	no
attributes (Attributes)	map[string]any	no
excludeUsed (ExcludeUsed)	*bool	no
eth_format (EthFormat)	*string	no

Returns¶

InterfacesData

Field	Go type	Required	Semantics
source (Source)	*string	no	Whether this result is a template preview or an existing IaC node.
template (Template)	*string	no	Canonical resolved template id.
node (Node)	*string	no	IaC node key when source=node. omitted: all nodes. empty string: all nodes. named: that IaC node key
items (Items)	[]Iface	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "source": "node",
  "node": "core_r1",
  "template": "iol",
  "items": [
    {
      "name": "e0/0",
      "type": "ethernet",
      "used": true
    },
    {
      "name": "s0/0",
      "type": "serial",
      "used": false
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

data, _ := client.CompleteLinkInterfaces(ctx, req)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_template	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

data, err := client.CompleteLinkInterfaces(ctx, eveiac.CompleteLinkInterfacesRequest{Template: eveiac.Ptr("iol")})

PreviewInterfaces¶

Family: Metadata

Purpose¶

Lists the interface names a template would have, before a node exists in the project.

Mental model¶

Which interfaces would this template have?

Use when¶

• previewing interfaces for a template

Do not use when¶

• the node already exists in intent; use completeLinkInterfaces

Reads¶

• the template interface map

Changes¶

Nothing. Read-only.

Important semantics¶

• SUCCESS is InterfacesData: source=template, canonical template, items[{name,type}] without used. Unknown template: 404 unknown_template.

Related¶

• completeLinkInterfaces

Signature¶

func (c *Client) PreviewInterfaces(ctx context.Context, body PreviewInterfacesRequest, timeoutMs ...int) (*InterfacesData, error)

• HTTP: POST /api/v1/authoring/interfaces
• operationId: previewInterfaces
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	PreviewInterfacesRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: PreviewInterfacesRequest¶

This request type is the same wire shape as AuthoringPayload.

Field	Go type	Required	Semantics
dir (Dir)	*string	no	Rejected when non-empty.
yaml (YAML)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
template (Template)	*string	no
attributes (Attributes)	map[string]any	no
excludeUsed (ExcludeUsed)	*bool	no
eth_format (EthFormat)	*string	no

Returns¶

InterfacesData

Field	Go type	Required	Semantics
source (Source)	*string	no	Whether this result is a template preview or an existing IaC node.
template (Template)	*string	no	Canonical resolved template id.
node (Node)	*string	no	IaC node key when source=node. omitted: all nodes. empty string: all nodes. named: that IaC node key
items (Items)	[]Iface	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "source": "template",
  "template": "ceos",
  "items": [
    {
      "name": "Ethernet1",
      "type": "ethernet"
    },
    {
      "name": "Ethernet2",
      "type": "ethernet"
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

data, _ := client.PreviewInterfaces(ctx, req)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
unknown_template	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

data, err := client.PreviewInterfaces(ctx, eveiac.PreviewInterfacesRequest{Template: eveiac.Ptr("iol")})

Projects¶

ValidateProject¶

Family: Intent

Purpose¶

Checks the packed IaC intent and returns every public-path error. A failed check is still HTTP 200 with valid set to false.

Mental model¶

Is my IaC intent valid?

Use when¶

• checking topology YAML before plan or reconcile

Do not use when¶

• you want to compare intent with EVE; use planProject
• you want to change EVE

Reads¶

• the packed IaC intent

Changes¶

Nothing. Read-only.

Important semantics¶

• HTTP 200 data is {valid, errors[]}. valid=false is not an HTTP error. Errors use dotted public paths and stable codes. Global validation of the complete topology.

Related¶

• planProject
• editProject

Signature¶

func (c *Client) ValidateProject(ctx context.Context, body ValidateProjectRequest, timeoutMs ...int) (*ValidateData, error)

• HTTP: POST /api/v1/projects/validate
• operationId: validateProject
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ValidateProjectRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: ValidateProjectRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ValidateData

Field	Go type	Required	Semantics
valid (Valid)	bool	yes
errors (Errors)	[]ValidationError	yes

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "valid": true,
  "errors": []
}

Processing the result¶

Typical field access after a successful call:

ok, err := client.ValidateProject(ctx, packed)
if ok != nil && !ok.Valid { return fmt.Errorf("validate failed") }

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.ValidateProject(ctx, eveiac.ValidateProjectRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

ImportProject¶

Family: Lifecycle

Purpose¶

Imports an existing EVE lab into IaC intent. The source lab is left unchanged. No managed lab is created; deploy is a separate step. This is not from_eve.

Mental model¶

Import this EVE lab as IaC intent. Do not deploy.

Use when¶

• adopting an existing EVE lab path as a new IaC project

Do not use when¶

• you want the current UNL definition to replace YAML intent of an existing project; use reconcileProject with from_eve
• you want to create the managed lab; use deployProject

Reads¶

• the source EVE lab

Changes¶

Returns IaC intent for the client to write. Does not modify source_lab and does not create a managed lab.

Important semantics¶

• Reads source_lab and returns IaC intent. Does not deploy, clone, or otherwise mutate EVE. Does not mutate source_lab. from_eve is not this operation. managed_lab is the later deploy target, not a lab that was created.

Related¶

• reconcileProject
• deployProject

Signature¶

func (c *Client) ImportProject(ctx context.Context, body ImportProjectRequest, timeoutMs ...int) (*ImportData, error)

• HTTP: POST /api/v1/projects/import
• operationId: importProject
• Authentication: Bearer token required
• Default timeout: 300000 ms

Parameters¶

Parameter	Type	Required	Description
body	ImportProjectRequest	yes	Request body.
timeoutMs	...int	no	Override the 300000 ms default.

Request schema: ImportProjectRequest¶

lab is required. Import reads source_lab into IaC intent. It does not deploy and it does not mutate source_lab. managed_lab is the later deploy target. It is not from_eve reconcile.

Field	Go type	Required	Semantics
lab (Lab)	string	yes
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ImportData

Field	Go type	Required	Semantics
name (Name)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
mode (Mode)	*string	no
source_lab (SourceLab)	*string	no
managed_lab (ManagedLab)	*string	no
lab (Lab)	*string	no
state (State)	any	no
source (Source)	any	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Response includes yaml/files on first import. Never mutate source_lab.

{
  "mode": "import",
  "source_lab": "/Customers/OSPF.unl",
  "managed_lab": "/IaC/OSPF.unl",
  "lab": "/IaC/OSPF.unl",
  "name": "OSPF",
  "state": {
    "node_ids": {
      "n_1": 3,
      "n_2": 4
    }
  }
}

Processing the result¶

Typical field access after a successful call:

imp, _ := client.ImportProject(ctx, req)
if imp.ManagedLab != nil { _ = *imp.ManagedLab }

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
lab_locked_mid_apply	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

imported, err := client.ImportProject(ctx, eveiac.ImportProjectRequest{
    Lab:      "/IaC/example.unl",
    Manifest: eveiac.Ptr(manifest),
    YAML:     eveiac.Ptr(yaml),
    Files:    files,
})
// Import writes IaC intent. It does not deploy. It is not reconcile from_eve.

PlanProject¶

Family: Planning

Purpose¶

Compares IaC intent with the EVE lab and returns the work that would be required. It never writes the project files and it never changes EVE.

Mental model¶

What would have to change?

Use when¶

• previewing a to_eve or from_eve change
• collecting the plan identity a later confirm must send

Do not use when¶

• you want the change applied; use reconcileProject
• you only need live node state; use getProjectStatus

Reads¶

• IaC intent and the current EVE lab

Changes¶

Nothing. Read-only.

Performance¶

A dry run. Heavier than getProjectStatus because it compares intent with the lab.

Important semantics¶

• Omitted direction is to_eve.
• The plan identity is direction-scoped. Do not reuse a to_eve identity for from_eve.
• Dry-run. Omitted direction is to_eve. Never writes Local files or EVE.

Related¶

• reconcileProject
• getPublicProject
• inspectProject

How-to¶

• Plan changes without applying them
• Make EVE match IaC intent

Signature¶

func (c *Client) PlanProject(ctx context.Context, body PlanProjectRequest, timeoutMs ...int) (*PlanData, error)

• HTTP: POST /api/v1/projects/plan
• operationId: planProject
• Authentication: Bearer token required
• Default timeout: 180000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	PlanProjectRequest	yes	Request body.
timeoutMs	...int	no	Override the 180000 ms default.

Request schema: PlanProjectRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

PlanData

Field	Go type	Required	Semantics
lab (Lab)	*string	no
exists (Exists)	*bool	no
summary (Summary)	*PlanSummary	no
operations (Operations)	[]PlanAction	no
actions (Actions)	[]PlanAction	no
applicable (Applicable)	*bool	no
blocked (Blocked)	[]PlanAction	no
text (Text)	*string	no
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
locked (Locked)	*bool	no
lock (Lock)	*int	no
direction (Direction)	*string	no	omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
unsupported (Unsupported)	[]string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "/IaC/demo.unl",
  "exists": true,
  "direction": "to_eve",
  "applicable": true,
  "plan_identity": "abc123def456",
  "actions": [
    {
      "op": "update_node",
      "key": "n_1",
      "summary": "config changed"
    },
    {
      "op": "restart_node",
      "key": "n_1",
      "summary": "running node needs restart"
    }
  ],
  "summary": {
    "create": 0,
    "update": 1,
    "delete": 0,
    "restart": 1
  }
}

Processing the result¶

Typical field access after a successful call:

plan, _ := client.PlanProject(ctx, packed)
if plan.PlanIdentity != nil { identity = *plan.PlanIdentity }

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
invalid_direction	Contractual/known for this call or its transport
plan_stale	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.PlanProject(ctx, eveiac.PlanProjectRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

DeployProject¶

Family: Lifecycle

Purpose¶

Creates the managed EVE lab from this project. If the managed lab already exists, the call fails unless replace is set, in which case the existing lab is removed and created again.

Mental model¶

Create the managed lab.

Use when¶

• the project does not yet have a managed lab

Do not use when¶

• the lab already exists and you only want to update it; use reconcileProject
• you only want a diff; use planProject

Reads¶

• the packed project

Changes¶

Creates the managed EVE lab. replace also stops, wipes, and deletes the previous one.

Related¶

• reconcileProject
• destroyProject

Signature¶

func (c *Client) DeployProject(ctx context.Context, body DeployProjectRequest, timeoutMs ...int) (*DeployData, error)

• HTTP: POST /api/v1/projects/deploy
• operationId: deployProject
• Authentication: Bearer token required
• Default timeout: 300000 ms

Parameters¶

Parameter	Type	Required	Description
body	DeployProjectRequest	yes	Request body.
timeoutMs	...int	no	Override the 300000 ms default.

Request schema: DeployProjectRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

DeployData

Field	Go type	Required	Semantics
lab (Lab)	*string	no
nodes (Nodes)	*int	no
links (Links)	*int	no
state (State)	any	no
unsupported (Unsupported)	[]string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "/IaC/demo.unl",
  "state": {
    "node_ids": {
      "n_1": 3,
      "n_2": 4
    }
  }
}

Processing the result¶

Typical field access after a successful call:

dep, _ := client.DeployProject(ctx, packed)
_ = dep.Lab

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
lab_exists	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
lab_locked_mid_apply	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.DeployProject(ctx, eveiac.DeployProjectRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

ReconcileProject¶

Family: Reconciliation

Purpose¶

Applies one direction. to_eve makes the EVE lab match IaC intent. from_eve reads the current EVE UNL definition and returns it as the new IaC intent. from_eve does not capture transient runtime state and it is not importProject.

Mental model¶

to_eve: make EVE match my intent. from_eve: make the current UNL definition my new intent.

Use when¶

• pushing IaC intent into EVE
• adopting the current UNL definition as the new YAML intent

Do not use when¶

• you only want the diff; use planProject
• you want a live node poll; use getProjectStatus
• you want to adopt a source lab as new IaC intent; use importProject

Reads¶

• IaC intent and the current EVE UNL definition

Changes¶

to_eve can change EVE. from_eve returns new IaC intent and does not perform mutating EVE writes.

Important semantics¶

• An unsupported plan action means to_eve performs zero EVE mutations.
• confirm=true on to_eve may stop nodes classified requires_stop only after the live-safe work, and only with a matching plan identity.
• from_eve confirm does not authorize a stop.
• to_eve mutates EVE only when no PlanAction is unsupported; any unsupported action means zero EVE mutations and the plan stays inspectable. from_eve updates Local from the managed lab with no mutating EVE writes. from_eve is not Import. When the plan has no unsupported action, confirm=true on to_eve stops classified requires_stop nodes only after live-safe work. applicable is a summary and must not gate execution.

Related¶

• planProject
• importProject
• getPublicProject

How-to¶

• Make EVE match IaC intent
• Make the current EVE lab definition the new intent

Signature¶

func (c *Client) ReconcileProject(ctx context.Context, body ReconcileProjectRequest, timeoutMs ...int) (*ReconcileData, error)

• HTTP: POST /api/v1/projects/reconcile
• operationId: reconcileProject
• Authentication: Bearer token required
• Default timeout: 300000 ms

Parameters¶

Parameter	Type	Required	Description
body	ReconcileProjectRequest	yes	Request body.
timeoutMs	...int	no	Override the 300000 ms default.

Request schema: ReconcileProjectRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ReconcileData

Field	Go type	Required	Semantics
lab (Lab)	*string	no
direction (Direction)	*string	no	omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
status (Status)	*string	no
applied (Applied)	*int	no
skippedPrune (SkippedPrune)	*int	no
fullDeploy (FullDeploy)	*bool	no
applicable (Applicable)	*bool	no	Summary only: full immediate convergence is possible (no requires_stop, no unsupported, not locked). Must not gate execution.
desired_updated (DesiredUpdated)	*bool	no
live (Live)	map[string]any	no
requires_stop (RequiresStop)	map[string]any	no
unsupported (Unsupported)	map[string]any	no	Object {changes, messages} on reconcile. Plan still uses string[].
runtime (Runtime)	map[string]any	no
summary (Summary)	*PlanSummary	no
operations (Operations)	[]PlanAction	no	The plan that was considered. Classification is not proof that a call was sent.
executed (Executed)	[]ReconcileStep	no	Side effects this reconcile actually performed or refused. effect is applied, failed, skipped, or pending_stop.
text (Text)	*string	no	Human-readable execution report. Same facts as executed.
blocked (Blocked)	[]PlanAction	no
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
state (State)	any	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
source (Source)	any	no
manifest (Manifest)	*string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "/IaC/demo.unl",
  "applied": 2,
  "direction": "to_eve",
  "applicable": true,
  "state": {
    "node_ids": {
      "n_1": 3
    }
  }
}

Processing the result¶

Typical field access after a successful call:

rec, _ := client.ReconcileProject(ctx, req)
if rec.Applied != nil { _ = *rec.Applied }

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
invalid_direction	Contractual/known for this call or its transport
plan_stale	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
lab_locked_mid_apply	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

applied, err := client.ReconcileProject(ctx, eveiac.ReconcileProjectRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files, Direction: eveiac.Ptr("to_eve")})
pulled, err := client.ReconcileProject(ctx, eveiac.ReconcileProjectRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files, Direction: eveiac.Ptr("from_eve")})
// to_eve makes EVE match IaC intent. from_eve makes the UNL definition the new intent.

DestroyProject¶

Family: Lifecycle

Purpose¶

Deletes the managed EVE lab. Omitted wipe still wipes the nodes first.

Mental model¶

Delete the managed lab.

Use when¶

• removing the managed lab this project owns

Do not use when¶

• you want to stop nodes and keep the lab; use execProject with stop

Reads¶

• the managed lab path

Changes¶

Deletes the managed EVE lab. Omitted wipe wipes nodes; explicit wipe false deletes the lab without that wipe.

Related¶

• deployProject
• execProject

Signature¶

func (c *Client) DestroyProject(ctx context.Context, body DestroyProjectRequest, timeoutMs ...int) (*DestroyData, error)

• HTTP: POST /api/v1/projects/destroy
• operationId: destroyProject
• Authentication: Bearer token required
• Default timeout: 180000 ms

Parameters¶

Parameter	Type	Required	Description
body	DestroyProjectRequest	yes	Request body.
timeoutMs	...int	no	Override the 180000 ms default.

Request schema: DestroyProjectRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

DestroyData

Field	Go type	Required	Semantics
lab (Lab)	*string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "/IaC/demo.unl"
}

Processing the result¶

Typical field access after a successful call:

_, err := client.DestroyProject(ctx, packed)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
lab_locked_mid_apply	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.DestroyProject(ctx, eveiac.DestroyProjectRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

GetProjectStatus¶

Family: Observation

Purpose¶

Returns a lightweight view of the project's current live EVE state, including node runtime states and current link impairments, without rebuilding the structural lab model.

Mental model¶

What is alive right now?

Use when¶

• polling running, stopped, starting, or busy node state
• updating a live UI overlay
• reading current runtime netem
• building monitoring or automation
• checking runtime state from an SDK or from eve-iac status

Do not use when¶

• you need nodes, interfaces, links, and presentation as a structural model; use inspectProject
• you need YAML intent; use getPublicProject
• you want to modify EVE

Reads¶

• project context
• the current EVE runtime lab
• EVE nodes/status

Changes¶

Nothing. Read-only.

Performance¶

Lightweight and suitable for polling, including the canvas once per second. When a runtime lab exists the agent uses the existing lab lookup plus one nodes/status request. It does not export the lab, rebuild topology, read configs, or call each node.

Important semantics¶

• live omitted means there is no runtime lab. That is not an empty lab.
• live.available true is an authoritative successful live read. nodes is always an array and netem is always an object.
• A successful empty nodes array or empty netem object is an authoritative empty result. Do not treat it as a failed read.
• live.available false means the nodes/status read failed. nodes and netem are omitted. The project status call stays HTTP 200 so existing context readers keep working.
• A missing netem side means effective delay 0, jitter 0, loss 0, and bandwidth 0. The response does not include a present zero side.
• joined false means runtime rows were read but they are not all mapped to IaC identities.
• GetLab lock behavior is unchanged: a lock lookup failure stays locked false and HTTP 200.
• Project context plus a lightweight live read. Existing fields stay mode, labs, capabilities, and lock. When runtime_lab is set, live is one GET nodes/status: nodes and netem. A missing netem side is 0,0,0,0 and is omitted. live.available false means that query failed; nodes and netem are then omitted. No runtime lab omits live. Not a lab snapshot and not YAML intent.

Related¶

• inspectProject
• getPublicProject
• planProject
• reconcileProject

How-to¶

• Observe a live lab
• Build a live UI or monitoring loop
• Apply runtime link quality

Signature¶

func (c *Client) GetProjectStatus(ctx context.Context, body GetProjectStatusRequest, timeoutMs ...int) (*ProjectStatusData, error)

• HTTP: POST /api/v1/projects/status
• operationId: getProjectStatus
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	GetProjectStatusRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: GetProjectStatusRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ProjectStatusData

Field	Go type	Required	Semantics
mode (Mode)	*string	no
source_lab (SourceLab)	*string	no
managed_lab (ManagedLab)	*string	no
runtime_lab (RuntimeLab)	*string	no
capabilities (Capabilities)	*ProjectModeCaps	no
locked (Locked)	*bool	no
lock (Lock)	*int	no
live (Live)	*ProjectLiveStatus	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "mode": "create",
  "runtime_lab": "/IaC/demo.unl",
  "managed_lab": "/IaC/demo.unl",
  "capabilities": {
    "topology_mutation": true,
    "reconcile": true,
    "destroy": true,
    "lifecycle": {
      "start": true,
      "stop": true,
      "wipe": true
    }
  },
  "locked": false
}

Processing the result¶

Typical field access after a successful call:

st, _ := client.GetProjectStatus(ctx, packed)
_ = st.RuntimeLab

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

status, err := client.GetProjectStatus(ctx, eveiac.GetProjectStatusRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})
if err != nil {
    return err
}
if status != nil && status.Live != nil && status.Live.Available != nil && *status.Live.Available {
    for _, node := range status.Live.Nodes {
        key, label := "", ""
        if node.Key != nil {
            key = *node.Key
        }
        if node.StateLabel != nil {
            label = *node.StateLabel
        }
        fmt.Printf("%s: %s\n", key, label)
    }
}

InspectProject¶

Family: Observation

Purpose¶

Builds a rich structural observation of the EVE lab: nodes, templates, interfaces, networks, links, topology, presentation, config sets, and the runtime metadata attached to that model.

Mental model¶

What does the current EVE lab look like?

Use when¶

• the first canvas load
• a structural refresh
• resolving node and interface identities
• discovering links and presentation objects

Do not use when¶

• you only need live node state or runtime netem; use getProjectStatus
• you need YAML intent; use getPublicProject
• you are polling every second

Reads¶

• the EVE lab structure and the runtime metadata attached to it

Changes¶

Nothing. Read-only.

Performance¶

A rich structural observation. It is more expensive than getProjectStatus. Do not use it as a high-frequency poll.

Important semantics¶

• For frequent runtime polling, use getProjectStatus. For a structural snapshot, use inspectProject.
• A missing netem side means effective delay 0, jitter 0, loss 0, and bandwidth 0, and is omitted.
• The runtime request flag remains a temporary alias of the getProjectStatus poll.
• Observation, not desired state. Node key is the current repo/state identity join (logical IaC key when mapped); native id is runtime metadata. Not topology.yml. Use getPublicProject for the public IaC JSON tree. Live node state and netem belong on getProjectStatus. A missing netem side is 0,0,0,0 and is omitted. The runtime request flag remains a temporary alias of that poll.

Related¶

• getProjectStatus
• getPublicProject

How-to¶

• Load the structural lab model
• Build a live UI or monitoring loop

Signature¶

func (c *Client) InspectProject(ctx context.Context, body InspectProjectRequest, timeoutMs ...int) (*InspectionData, error)

• HTTP: POST /api/v1/projects/inspect
• operationId: inspectProject
• Authentication: Bearer token required
• Default timeout: 300000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	InspectProjectRequest	yes	Request body.
timeoutMs	...int	no	Override the 300000 ms default.

Request schema: InspectProjectRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

InspectionData

Field	Go type	Required	Semantics
observation (Observation)	*bool	no
desired_state (DesiredState)	*bool	no
mode (Mode)	*string	no
source_lab (SourceLab)	any	no
managed_lab (ManagedLab)	any	no
runtime_lab (RuntimeLab)	*string	no
capabilities (Capabilities)	*ProjectModeCaps	no
cached (Cached)	*bool	no
nodes (Nodes)	[]InspectNode	no
netem (Netem)	*AppliedNetem	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Large observation payload is under additional keys when present. LOAD mode sets desired_state=false.

{
  "mode": "load",
  "observation": true,
  "desired_state": false,
  "runtime_lab": "/Customers/OSPF.unl",
  "cached": false,
  "capabilities": {
    "topology_mutation": false,
    "reconcile": false,
    "destroy": false,
    "lifecycle": {
      "start": true,
      "stop": true,
      "wipe": true
    }
  }
}

Processing the result¶

Typical field access after a successful call:

insp, _ := client.InspectProject(ctx, packed)
_ = insp.RuntimeLab

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

observed, err := client.InspectProject(ctx, eveiac.InspectProjectRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files, Refresh: eveiac.Ptr(true)})
// Structural snapshot. Poll live node state with GetProjectStatus.

GetPublicProject¶

Family: Intent

Purpose¶

Returns the current IaC intent as public JSON, the same information as topology.yml or eve-presentation.yml. It does not read live EVE.

Mental model¶

What do I currently want?

Use when¶

• reading or selecting a subtree of YAML intent
• checking presentation intent

Do not use when¶

• you need live node state; use getProjectStatus
• you need the structural EVE snapshot; use inspectProject

Reads¶

• topology.yml or eve-presentation.yml in the packed project

Changes¶

Nothing. Read-only.

Important semantics¶

• An optional path selects a subtree. An optional filter is an exact IaC key on /nodes, /networks, or /links.
• file is topology or presentation. A missing presentation file returns present false.
• Canonical public IaC JSON isomorphic to topology.yml or eve-presentation.yml. Optional RFC 6901 path selects a subtree. Optional filter is an exact IaC key on /nodes, /networks, or /links only. file=topology|presentation. Absent presentation returns {present:false}. Never reads state/Internal. Does not inspect live EVE.

Related¶

• editProject
• getProjectStatus
• inspectProject
• planProject

How-to¶

• Use traffic filters

Signature¶

func (c *Client) GetPublicProject(ctx context.Context, body GetPublicProjectRequest, timeoutMs ...int) (*PublicData, error)

• HTTP: POST /api/v1/projects/public
• operationId: getPublicProject
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	GetPublicProjectRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: GetPublicProjectRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

PublicData

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

topology, err := client.GetPublicProject(ctx, eveiac.GetPublicProjectRequest{YAML: eveiac.Ptr(yaml), Files: files, File: eveiac.Ptr("topology")})
// IaC intent. This does not read live EVE.

EditProject¶

Family: Intent

Purpose¶

Applies a batch of JSON edits to topology.yml and validates the result before anything is written. It does not deploy, plan, or reconcile.

Mental model¶

Change my IaC intent.

Use when¶

• adding, updating, or deleting nodes, networks, or links in YAML intent

Do not use when¶

• you want EVE to change now; use reconcileProject after the edit
• you want to edit startup-config blobs; use editProjectConfig

Reads¶

• topology.yml

Changes¶

Rewrites topology.yml when the batch validates. applied false writes nothing.

Important semantics¶

• Batch canonical JSON mutations of topology.yml only. One read/parse/apply/validate/serialize. A node or network delete may include deterministic repairs (dangling link match-delete, configset entry remove) in the same in-memory transaction; repairs is omitted when there are none. The invalid intermediate is never serialized. HTTP 200 data is {applied, operations, changed?, valid, errors[], yaml?, repairs?}. applied=false writes nothing. Does not deploy, plan, or reconcile. yaml is a persist sidecar; MCP strips it from the model-visible result.

Related¶

• getPublicProject
• validateProject
• reconcileProject

How-to¶

• Use traffic filters

Signature¶

func (c *Client) EditProject(ctx context.Context, body EditProjectRequest, timeoutMs ...int) (*EditResult, error)

• HTTP: POST /api/v1/projects/edit
• operationId: editProject
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	EditProjectRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: EditProjectRequest¶

This request type is the same wire shape as EditRequest.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.
operations (Operations)	[]EditOperation	yes	Bounded canonical mutations applied as one in-memory transaction. Not RFC 6902 JSON Patch.

Returns¶

EditResult

Field	Go type	Required	Semantics
applied (Applied)	bool	yes
operations (Operations)	int	yes
changed (Changed)	*EditChanged	no
valid (Valid)	bool	yes
errors (Errors)	[]ValidationError	yes
yaml (YAML)	*string	no	Canonical topology.yml after a successful edit. Clients persist it locally. MCP strips this field from the model-visible result. Never an Internal/native dump.
repairs (Repairs)	[]EditOperation	no	Deterministic closures the agent added to a node or network delete in this same transaction. Omitted when the requested operations were already coherent. Clients do not compute or replay these operations.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "applied": true,
  "operations": 10,
  "changed": {
    "nodes": [
      "r1",
      "r2",
      "r3",
      "r4"
    ],
    "links": 6
  },
  "valid": true,
  "errors": []
}

Processing the result¶

Typical field access after a successful call:

edited, _ := client.EditProject(ctx, req)
if !edited.Applied { return fmt.Errorf("edit not applied") }

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.EditProject(ctx, eveiac.EditProjectRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

GetProjectConfig¶

Family: Intent

Purpose¶

Reads startup-config blobs that belong to IaC intent: an index, one blob, or a literal search.

Mental model¶

What startup config do I intend?

Use when¶

• listing, fetching, or searching startup-config text

Do not use when¶

• you want to change a blob; use editProjectConfig
• you want live node state

Reads¶

• packed startup-config files

Changes¶

Nothing. Read-only.

Important semantics¶

• Startup-config index/get/search. operation is index|get|search. lab in SUCCESS is topology name:, never an EVE or IaC path. Never returns configs/ paths. Empty blob is present=true bytes=0 with sha256 of zero bytes. Missing blob is present=false (sha256 omitted). Omitted packed files is 400 config_unavailable, not present=false. files:{} is authoritative absence. Search is literal substring; query required max 256 chars; limit omitted=20 max 50 hits; context_lines omitted=0 max 3; per-config max 1 MiB is config_too_large. Zero matches is SUCCESS results={}.

Related¶

• editProjectConfig

Signature¶

func (c *Client) GetProjectConfig(ctx context.Context, body GetProjectConfigRequest, timeoutMs ...int) (*ConfigData, error)

• HTTP: POST /api/v1/projects/config
• operationId: getProjectConfig
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	GetProjectConfigRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: GetProjectConfigRequest¶

This request type is the same wire shape as ConfigReadRequest.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.
operation (Operation)	string	yes	Discriminates the read. Not OpenAPI oneOf.
template (Template)	*string	no	Exact template id filter for index/search.
present (Present)	*bool	no	index only. true = blobs present, false = missing. Omitted = both.
query (Query)	*string	no	search only. Literal substring. Required. Max 256 characters. Empty is invalid_request.
case_sensitive (CaseSensitive)	*bool	no	search only. Omitted = case-insensitive.
limit (Limit)	*int	no	search only. Total match hits, not configs. Omitted = 20. Max 50. No OpenAPI default.
context_lines (ContextLines)	*int	no	search only. Neighbor lines around each hit. Omitted = 0. Max 3. No OpenAPI default.

Returns¶

ConfigData

Field	Go type	Required	Semantics
lab (Lab)	*string	no
scope (Scope)	map[string]any	no
entries (Entries)	map[string]ConfigIndexEntry	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
template (Template)	*string	no
configset (Configset)	*string	no
present (Present)	*bool	no
bytes (Bytes)	*int	no
sha256 (Sha256)	*string	no
content (Content)	*string	no
query (Query)	*string	no
truncated (Truncated)	*bool	no
results (Results)	map[string]ConfigSearchNode	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "mesh",
  "node": "ceos1",
  "template": "ceos",
  "configset": "default",
  "present": true,
  "bytes": 842,
  "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "content": "hostname ceos1\n"
}

Processing the result¶

Typical field access after a successful call:

cfg, _ := client.GetProjectConfig(ctx, req)
_ = cfg.Present

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_configset	Contractual/known for this call or its transport
config_too_large	Contractual/known for this call or its transport
config_unavailable	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetProjectConfig(ctx, eveiac.GetProjectConfigRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

EditProjectConfig¶

Family: Intent

Purpose¶

Puts or deletes startup-config blobs and updates the config library in IaC intent. It does not deploy the lab.

Mental model¶

Change the startup config I intend.

Use when¶

• writing or removing a startup-config blob

Do not use when¶

• LOAD mode
• you want the change pushed to EVE; deploy or reconcile after this

Reads¶

• packed startup-config files and the config library

Changes¶

Writes startup-config blobs and library binds when the whole batch validates. A conflict writes nothing.

Important semantics¶

• Batch put/delete of startup-config blobs. Preflight all, then apply library binds in memory and ValidateDir before SUCCESS. expected_sha256 mismatch is 409 config_conflict with zero writes. PUT auto-binds configsets..=rel and fills an empty node selector. Selector none with no op.configset is invalid_request. Selector none plus explicit op.configset writes that library and does not change the selector. DELETE drops the blob and library map entry; keeps an empty configsets. when a node still selects it; does not clear nodes.*.configset. HTTP 200 data is {lab, applied, operations, changed}; files/yaml/deleted are persist sidecars stripped by MCP. Invalid resulting YAML is 400 invalid_request with no sidecars. LOAD is forbidden. Does not deploy.

Related¶

• getProjectConfig

Signature¶

func (c *Client) EditProjectConfig(ctx context.Context, body EditProjectConfigRequest, timeoutMs ...int) (*ConfigEditData, error)

• HTTP: POST /api/v1/projects/config/edit
• operationId: editProjectConfig
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	EditProjectConfigRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: EditProjectConfigRequest¶

This request type is the same wire shape as ConfigEditRequest.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.
operations (Operations)	[]ConfigEditOp	yes	Preflight all, then write. Not a multi-file transaction.

Returns¶

ConfigEditData

Field	Go type	Required	Semantics
lab (Lab)	string	yes
applied (Applied)	bool	yes
operations (Operations)	int	yes
changed (Changed)	map[string]ConfigChanged	yes
files (Files)	map[string]string	no	Changed blobs keyed by project-relative configs/ path. Persist sidecar. MCP strips this field.
yaml (YAML)	*string	no	Canonical topology.yml when configsets or node selectors changed. Persist sidecar. MCP strips this field.
deleted (Deleted)	[]string	no	Project-relative configs/ paths to unlink. Persist sidecar. MCP strips this field.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "lab": "mesh",
  "applied": true,
  "operations": 1,
  "changed": {
    "ceos1": {
      "configset": "default",
      "present": true,
      "bytes": 14,
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}

Processing the result¶

Typical field access after a successful call:

edited, _ := client.EditProjectConfig(ctx, req)
if !edited.Applied { return fmt.Errorf("config edit not applied") }

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_configset	Contractual/known for this call or its transport
config_too_large	Contractual/known for this call or its transport
config_conflict	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.EditProjectConfig(ctx, eveiac.EditProjectConfigRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

OpenProject¶

Family: Session

Purpose¶

Confirms the runtime lab exists and returns a short-lived URL that opens it in the browser UI.

Mental model¶

Open this lab in the browser.

Use when¶

• handing a user a browser URL for the runtime lab

Do not use when¶

• you need node state or the structural model

Reads¶

• the runtime lab

Changes¶

Issues a browser token.

Signature¶

func (c *Client) OpenProject(ctx context.Context, body OpenProjectRequest, timeoutMs ...int) (*OpenData, error)

• HTTP: POST /api/v1/projects/open
• operationId: openProject
• Authentication: Bearer token required
• Default timeout: 30000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	OpenProjectRequest	yes	Request body.
timeoutMs	...int	no	Override the 30000 ms default.

Request schema: OpenProjectRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

OpenData

Field	Go type	Required	Semantics
url (URL)	*string	no
ttl (TTL)	*int	no
lab (Lab)	*string	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "url": "https://eve.example/#/lab/abc123"
}

Processing the result¶

Typical field access after a successful call:

open, _ := client.OpenProject(ctx, packed)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.OpenProject(ctx, eveiac.OpenProjectRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

Execution / Consoles¶

ListProjectConsoles¶

Family: Console

Purpose¶

Lists the console endpoints for nodes in the runtime lab, including whether each node is mapped to an IaC key.

Mental model¶

Where can I attach a console?

Use when¶

• discovering console targets before attach or exec

Do not use when¶

• you want to send a command; use execConsole or runConsole

Reads¶

• nodes in the runtime lab

Changes¶

Nothing. Read-only.

Related¶

• attachConsole
• execConsole

Signature¶

func (c *Client) ListProjectConsoles(ctx context.Context, body ListProjectConsolesRequest, timeoutMs ...int) (*ConsolesData, error)

• HTTP: POST /api/v1/projects/consoles
• operationId: listProjectConsoles
• Authentication: Bearer token required
• Default timeout: 30000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ListProjectConsolesRequest	yes	Request body.
timeoutMs	...int	no	Override the 30000 ms default.

Request schema: ListProjectConsolesRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ConsolesData

Field	Go type	Required	Semantics
lab (Lab)	*string	no
html5 (Html5)	*bool	no
consoles (Consoles)	[]ConsoleRecord	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "consoles": [
    {
      "node": "n_1",
      "name": "R1",
      "status": "running",
      "protocol": "telnet",
      "host": "127.0.0.1",
      "port": 32769
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

cons, _ := client.ListProjectConsoles(ctx, packed)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.ListProjectConsoles(ctx, eveiac.ListProjectConsolesRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

ExecProject¶

Family: Lifecycle

Purpose¶

Starts, stops, or wipes nodes in the runtime lab. One call covers the listed IaC keys, or every node when the selection is omitted.

Mental model¶

Start, stop, or wipe these nodes.

Use when¶

• starting nodes
• stopping nodes
• wiping node disks

Do not use when¶

• you want to delete the lab; use destroyProject
• you want to change topology; use reconcileProject

Reads¶

• the runtime lab and the selected node keys

Changes¶

Starts, stops, or wipes the selected nodes.

Important semantics¶

• Omitted stopmode is the automatic mode. Explicit 0 is a graceful stop and is different from omitting the field.
• action is start|stop|wipe. nodes is one bulk call for that IaC key list. Omitted nodes uses node. Omitted or empty node means all nodes. Success data is BulkResult with stable lowercase keys. Omitted stopmode is 3; explicit 0 is graceful.

Related¶

• getProjectStatus
• destroyProject

How-to¶

• Start, stop, and wipe lab nodes

Signature¶

func (c *Client) ExecProject(ctx context.Context, body ExecProjectRequest, timeoutMs ...int) (*BulkResult, error)

• HTTP: POST /api/v1/projects/exec
• operationId: execProject
• Authentication: Bearer token required
• Default timeout: 180000 ms

Parameters¶

Parameter	Type	Required	Description
body	ExecProjectRequest	yes	Request body.
timeoutMs	...int	no	Override the 180000 ms default.

Request schema: ExecProjectRequest¶

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	string	yes
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

BulkResult

Field	Go type	Required	Semantics
requested (Requested)	int	yes
started (Started)	int	yes
already_running (AlreadyRunning)	int	yes
already_starting (AlreadyStarting)	int	yes
stopped (Stopped)	int	yes
already_stopped (AlreadyStopped)	int	yes
wiped (Wiped)	int	yes
failed (Failed)	int	yes
invalid (Invalid)	int	yes

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "requested": 2,
  "started": 2,
  "already_running": 0,
  "already_starting": 0,
  "stopped": 0,
  "already_stopped": 0,
  "wiped": 0,
  "failed": 0,
  "invalid": 0
}

Processing the result¶

Typical field access after a successful call:

bulk, _ := client.ExecProject(ctx, eveiac.ExecProjectRequest{Action: "start", Lab: packed.Lab})
if bulk.Failed != nil && *bulk.Failed > 0 { return fmt.Errorf("exec failed") }

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
lab_locked_mid_apply	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.ExecProject(ctx, eveiac.ExecProjectRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files, Action: "start"})

ExportProjectConfig¶

Family: Startup config

Purpose¶

Writes the running configuration into the chosen EVE startup-config set so a later from_eve can adopt that blob. It does not change IaC files.

Mental model¶

Save the running configuration into this startup-config set.

Use when¶

• the useful configuration is the one running on the node
• a later reconcile from_eve should adopt that startup-config

Do not use when¶

• you want to edit the IaC startup library; use editProjectConfig
• you want to adopt the lab into the project now; use reconcileProject direction from_eve after this call
• you want the running text returned to the client

Reads¶

• the runtime lab, its configsets, and the selected nodes

Changes¶

Replaces the chosen set's startup-config blob on the lab. Restores the node config selector when it had to be switched for the native export.

Important semantics¶

• confirm is enforced by MCP and the CLI. The agent performs the export for a managed lab.
• A node failure does not undo nodes already exported. failed and selector_restore_failed are separate.
• Copies the running NOS configuration into an existing EVE startup-config set. configset is required: default, or the name of a set already on the lab. An unknown name is 400 unknown_configset and creates nothing. nodes is an optional IaC key list; omitted nodes uses node; omitted both means every config-capable node. config -1 is skipped. Stopped nodes are still exported and an EVE refusal such as 80084 or 80061 is failed for that node only. This is not editProjectConfig, not reconcile from_eve, and not a capture returned to the client. topology.yml and configs/** are not written. LOAD and source_lab are 403 operation_not_allowed. A locked lab is refused before writes.

Related¶

• editProjectConfig
• reconcileProject
• execProject

How-to¶

• Copy the running configuration into a startup-config set

Signature¶

func (c *Client) ExportProjectConfig(ctx context.Context, body ExportProjectConfigRequest, timeoutMs ...int) (*ExportConfigData, error)

• HTTP: POST /api/v1/projects/export-config
• operationId: exportProjectConfig
• Authentication: Bearer token required
• Default timeout: 1800000 ms

Parameters¶

Parameter	Type	Required	Description
body	ExportProjectConfigRequest	yes	Request body.
timeoutMs	...int	no	Override the 1800000 ms default.

Request schema: ExportProjectConfigRequest¶

This request type is the same wire shape as ExportConfigRequest.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	string	yes	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ExportConfigData

Field	Go type	Required	Semantics
lab (Lab)	string	yes
configset (Configset)	string	yes
nodes (Nodes)	[]ExportConfigNode	yes

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Copies the running NOS configuration into an existing EVE startup-config set. Does not write topology.yml or configs/**. A later from_eve adopts the blob. Unknown set is unknown_configset and creates nothing. LOAD and source_lab are refused.

{
  "lab": "/Lab.unl",
  "configset": "default",
  "nodes": [
    {
      "key": "n_1",
      "id": 1,
      "status": "exported"
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

saved, _ := client.ExportProjectConfig(ctx, map[string]any{"lab": lab, "configset": "default", "nodes": []string{"n_1"}})
_ = saved.Configset

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_configset	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
lab_locked	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.ExportProjectConfig(ctx, eveiac.ExportProjectConfigRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

ApplyLinkQuality¶

Family: Runtime interaction

Purpose¶

Applies live delay, jitter, loss, and bandwidth to one Ethernet link identified by public YAML endpoints. It does not rewrite topology.yml.

Mental model¶

Impair this live link.

Use when¶

• setting or clearing live netem on an Ethernet link
• persisting that impairment into the UNL when save is true

Do not use when¶

• you only want to read the current impairment; use getProjectStatus
• the link is serial

Reads¶

• the public YAML link identity

Changes¶

Changes live netem on the matched link. save true also asks EVE to persist it in the UNL.

Important semantics¶

• Omitted impairment clears live netem on that side.
• Omitted save is live only and does not rewrite topology.yml.
• Public YAML identity (n_1 + interface). Optional save=true sends native save=1 (UNL persist for an admin session on an unlocked lab); omitted save is live-only. persisted follows save. Does not rewrite topology.yml. LOAD allowed like exec. Serial is 400 serial_impairment_unsupported. Unknown match is 400 unknown_link. Native lock is not required for the live apply.

Related¶

• getProjectStatus
• setLinkSuspend

How-to¶

• Apply runtime link quality

Signature¶

func (c *Client) ApplyLinkQuality(ctx context.Context, body ApplyLinkQualityRequest, timeoutMs ...int) (*LinkQualityData, error)

• HTTP: POST /api/v1/projects/links/quality
• operationId: applyLinkQuality
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	ApplyLinkQualityRequest	yes	Request body.
timeoutMs	...int	no	Override the 30000 ms default.

Request schema: ApplyLinkQualityRequest¶

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.
match (Match)	PublicLinkMatch	yes
source_impairment (SourceImpairment)	*LinkImpairment	no
destination_impairment (DestinationImpairment)	*LinkImpairment	no
save (Save)	*bool	no	When true, native quality save=1 persists NETEM into the UNL (admin session, unlocked lab). Omitted or false is live-only save=0. Never writes topology.yml.

Returns¶

LinkQualityData

Field	Go type	Required	Semantics
applied (Applied)	bool	yes
persisted (Persisted)	bool	yes
match (Match)	*PublicLinkMatch	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Omitted save is live-only (persisted false, native save=0). save=true / CLI --save persists NETEM into the UNL when the session is admin and the lab is unlocked. Neither rewrites topology.yml. Observe inspectProject.

{
  "applied": true,
  "persisted": false,
  "match": {
    "endpoints": [
      {
        "node": "n_1",
        "interface": "e0/0"
      },
      {
        "node": "n_2",
        "interface": "e0/1"
      }
    ]
  }
}

Processing the result¶

Typical field access after a successful call:

q, _ := client.ApplyLinkQuality(ctx, req)
_ = q.Applied

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_link	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_interface	Contractual/known for this call or its transport
unknown_network	Contractual/known for this call or its transport
serial_impairment_unsupported	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.ApplyLinkQuality(ctx, eveiac.ApplyLinkQualityRequest{
    Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files,
    Match: eveiac.PublicLinkMatch{Endpoints: []eveiac.PublicLinkEndpoint{
        {Node: eveiac.Ptr("n_1"), Interface: eveiac.Ptr("e0/0")},
        {Node: eveiac.Ptr("n_2"), Interface: eveiac.Ptr("e0/1")},
    }},
    SourceImpairment: &eveiac.LinkImpairment{Delay: eveiac.Ptr(50), Loss: eveiac.Ptr(1)},
    Save: eveiac.Ptr(true),
})

SetLinkSuspend¶

Family: Runtime interaction

Purpose¶

Suspends or resumes a live link identified by public YAML endpoints. Suspend is not an IaC intent field and is not written to topology.yml.

Mental model¶

Pause or resume this live link.

Use when¶

• suspending a live link
• resuming a live link

Do not use when¶

• you want the flag stored in YAML
• you want to read it back from getProjectStatus; this poll does not carry suspend

Reads¶

• the public YAML link identity

Changes¶

Suspends or resumes the matched live link.

Important semantics¶

• suspended true suspends and false resumes.
• Omitted side means both node endpoints.
• Observe suspend on a structural inspect, not on the status poll.
• Public YAML identity. suspended true/false maps to native PUT /suspend or /resume. Omitted side is both. Never YAML *_suspend. LOAD allowed. Observe inspect runtime source_suspend. Native lock is not required.

Related¶

• inspectProject
• applyLinkQuality

How-to¶

• Suspend and resume a link

Signature¶

func (c *Client) SetLinkSuspend(ctx context.Context, body SetLinkSuspendRequest, timeoutMs ...int) (*LinkSuspendData, error)

• HTTP: POST /api/v1/projects/links/suspend
• operationId: setLinkSuspend
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	SetLinkSuspendRequest	yes	Request body.
timeoutMs	...int	no	Override the 30000 ms default.

Request schema: SetLinkSuspendRequest¶

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.
match (Match)	PublicLinkMatch	yes
suspended (Suspended)	bool	yes	true = native suspend; false = native resume. Required; omitted is 400 invalid_request.
side (Side)	*string	no	source, destination, or both. Omitted/empty is both. Wire-distinct from explicit both.

Returns¶

LinkSuspendData

Field	Go type	Required	Semantics
applied (Applied)	bool	yes
suspended (Suspended)	bool	yes
side (Side)	*string	no
match (Match)	*PublicLinkMatch	no
targets (Targets)	[]LinkSuspendTarget	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Runtime TAP suspend. Never a topology.yml field. Observe inspect runtime source_suspend.

{
  "applied": true,
  "suspended": true,
  "side": "both",
  "match": {
    "endpoints": [
      {
        "node": "n_1",
        "interface": "e0/0"
      },
      {
        "node": "n_2",
        "interface": "e0/1"
      }
    ]
  },
  "targets": [
    {
      "node": "n_1",
      "interface": "e0/0"
    },
    {
      "node": "n_2",
      "interface": "e0/1"
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

s, _ := client.SetLinkSuspend(ctx, req)
_ = s.Suspended

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_link	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_interface	Contractual/known for this call or its transport
unknown_network	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.SetLinkSuspend(ctx, eveiac.SetLinkSuspendRequest{
    Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files,
    Match: eveiac.PublicLinkMatch{Endpoints: []eveiac.PublicLinkEndpoint{
        {Node: eveiac.Ptr("n_1"), Interface: eveiac.Ptr("e0/0")},
        {Node: eveiac.Ptr("n_2"), Interface: eveiac.Ptr("e0/1")},
    }},
    Suspended: true,
})

StartCapture¶

Family: Capture

Purpose¶

Starts a packet capture on one node interface and returns an HTML5 capture URL.

Mental model¶

Capture packets on this interface.

Use when¶

• opening a capture window for one interface

Do not use when¶

• you want a traffic-stream ticket; use attachTraffic

Reads¶

• the public node and interface

Changes¶

Starts a capture docker for that interface.

Important semantics¶

• Closing the browser tab does not stop the capture docker.
• Public node and interface. Native capture_mode=1. HTML5 URL only. evecapture:// is 400. LOAD allowed. Closing the tab does not stop the docker. No MCP tool.

Related¶

• attachTraffic

How-to¶

• Capture traffic

Signature¶

func (c *Client) StartCapture(ctx context.Context, body StartCaptureRequest, timeoutMs ...int) (*CaptureData, error)

• HTTP: POST /api/v1/projects/capture
• operationId: startCapture
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	StartCaptureRequest	yes	Request body.
timeoutMs	...int	no	Override the 30000 ms default.

Request schema: StartCaptureRequest¶

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	string	yes	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.
interface (Interface)	string	yes	Interface name on that node.

Returns¶

CaptureData

Field	Go type	Required	Semantics
node (Node)	string	yes	omitted: all nodes. empty string: all nodes. named: that IaC node key
interface (Interface)	string	yes
url (URL)	string	yes

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_interface	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.StartCapture(ctx, eveiac.StartCaptureRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files, Node: eveiac.Ptr("n_1"), Interface: eveiac.Ptr("e0/0")})

AttachTraffic¶

Family: Capture

Purpose¶

Creates a ticket for a translated traffic stream. The agent keeps native EVE ids and dials the EVE traffic socket.

Mental model¶

Let me watch this lab's traffic.

Use when¶

• obtaining a ticket before streamTraffic

Do not use when¶

• you want a packet-capture page; use startCapture

Reads¶

• the runtime lab

Changes¶

Issues a one-time traffic ticket.

Important semantics¶

• Ticket for the translated traffic stream. Agent dials EVE /traffic-ws. Native ids stay on the agent. LOAD allowed. No MCP tool.

Related¶

• streamTraffic
• startCapture

How-to¶

• Use traffic filters

Signature¶

func (c *Client) AttachTraffic(ctx context.Context, body AttachTrafficRequest, timeoutMs ...int) (*TrafficAttachData, error)

• HTTP: POST /api/v1/projects/traffic/attach
• operationId: attachTraffic
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	AttachTrafficRequest	yes	Request body.
timeoutMs	...int	no	Override the 30000 ms default.

Request schema: AttachTrafficRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

TrafficAttachData

Field	Go type	Required	Semantics
stream (Stream)	string	yes
transport (Transport)	string	yes

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
operation_not_allowed	Contractual/known for this call or its transport
lab_busy	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
unknown_node	Contractual/known for this call or its transport
unknown_interface	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

attached, err := client.AttachTraffic(ctx, eveiac.AttachTrafficRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

ExecConsole¶

Family: Console

Purpose¶

Sends one command to a node console and returns when the prompt comes back.

Mental model¶

Run one command on this console.

Use when¶

• a single show, ping, or similar command

Do not use when¶

• you need an ordered expect and send script; use runConsole

Reads¶

• the node console

Changes¶

Writes the command to the console and reads the reply.

Important semantics¶

• Joins or opens the Hub whether session_id is omitted or present. A missing session reopens once. Completes on prompt return after the send. Server clamps timeout_ms to exec max 60000.

Related¶

• runConsole
• attachConsole

How-to¶

• Execute console commands

Signature¶

func (c *Client) ExecConsole(ctx context.Context, body ExecConsoleRequest, timeoutMs ...int) (*ConsoleExecData, error)

• HTTP: POST /api/v1/console/exec
• operationId: execConsole
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	ExecConsoleRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: ExecConsoleRequest¶

This request type is the same wire shape as ConsolePayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
manifest (Manifest)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command (Command)	*string	no
commands (Commands)	[]string	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms (TimeoutMs)	*int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets (Targets)	[]ConsoleTarget	no
session_id (SessionID)	*string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq (AfterSeq)	*int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode (Mode)	*ConsoleWriteMode	no
pattern (Pattern)	*string	no	Go regexp for waitConsole.
max_bytes (MaxBytes)	*int	no	Bounded history tail for getConsoleHistory.
steps (Steps)	[]ConsoleRunStep	no
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ConsoleExecData

Field	Go type	Required	Semantics
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name (Name)	*string	no
console_type (ConsoleType)	*string	no
command (Command)	*string	no
output (Output)	*string	no
duration_ms (DurationMs)	*int	no
timed_out (TimedOut)	*bool	no
truncated (Truncated)	*bool	no
prompt (Prompt)	*string	no
session_id (SessionID)	*string	no
match (Match)	*string	no
phase (Phase)	*string	no	Interaction phase: discovering, ready, executing, paging, interactive, auth_required, error.
recovered (Recovered)	*bool	no	True when a missing session was reopened for this call.
rx_to (RxTo)	*int	no	Receive sequence of the last byte belonging to this command.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "output": "Cisco IOS Software, Version 15.2(4)M6\n",
  "node": "n_1"
}

Processing the result¶

Typical field access after a successful call:

out, _ := client.ExecConsole(ctx, req)
_ = out.Output

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

data, err := client.ExecConsole(ctx, eveiac.ExecConsoleRequest{Lab: eveiac.Ptr(lab), Node: eveiac.Ptr("n_1"), Command: eveiac.Ptr("show version")})

ExecConsoleMany¶

Family: Console

Purpose¶

Sends one command to several node consoles. A failure on one target stays on that target.

Mental model¶

Run one command on each of these consoles.

Use when¶

• the same command on several nodes

Do not use when¶

• you need a scripted dialogue; use runConsole

Reads¶

• each target console

Changes¶

Writes the command to each selected console.

Important semantics¶

• Joins the Hub for each target. One target failure stays on that target. Server clamps timeout_ms to exec max 60000.

Related¶

• execConsole

How-to¶

• Execute console commands

Signature¶

func (c *Client) ExecConsoleMany(ctx context.Context, body ExecConsoleManyRequest, timeoutMs ...int) (*ConsoleExecManyData, error)

• HTTP: POST /api/v1/console/exec-many
• operationId: execConsoleMany
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	ExecConsoleManyRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: ExecConsoleManyRequest¶

This request type is the same wire shape as ConsolePayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
manifest (Manifest)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command (Command)	*string	no
commands (Commands)	[]string	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms (TimeoutMs)	*int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets (Targets)	[]ConsoleTarget	no
session_id (SessionID)	*string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq (AfterSeq)	*int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode (Mode)	*ConsoleWriteMode	no
pattern (Pattern)	*string	no	Go regexp for waitConsole.
max_bytes (MaxBytes)	*int	no	Bounded history tail for getConsoleHistory.
steps (Steps)	[]ConsoleRunStep	no
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ConsoleExecManyData

Field	Go type	Required	Semantics
results (Results)	[]any	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "results": [
    {
      "node": "n_1",
      "output": "R1#",
      "ok": true
    },
    {
      "node": "n_2",
      "output": "R2#",
      "ok": true
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

many, _ := client.ExecConsoleMany(ctx, req)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

data, err := client.ExecConsoleMany(ctx, eveiac.ExecConsoleManyRequest{Lab: eveiac.Ptr(lab)})

CreateConsoleSession¶

Family: Console

Purpose¶

Creates or joins the console session for one node so later commands can reuse it.

Mental model¶

Hold this console open.

Use when¶

• preparing a session before several commands

Reads¶

• the node console

Changes¶

Creates or joins a console session.

Important semantics¶

• Creates or joins Hub lease for (lab, node). Default mode interact when omitted.

Related¶

• execConsole
• closeConsoleSession

Signature¶

func (c *Client) CreateConsoleSession(ctx context.Context, body CreateConsoleSessionRequest, timeoutMs ...int) (*ConsoleSessionData, error)

• HTTP: POST /api/v1/console/sessions
• operationId: createConsoleSession
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	CreateConsoleSessionRequest	yes	Request body.
timeoutMs	...int	no	Override the 30000 ms default.

Request schema: CreateConsoleSessionRequest¶

This request type is the same wire shape as ConsolePayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
manifest (Manifest)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command (Command)	*string	no
commands (Commands)	[]string	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms (TimeoutMs)	*int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets (Targets)	[]ConsoleTarget	no
session_id (SessionID)	*string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq (AfterSeq)	*int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode (Mode)	*ConsoleWriteMode	no
pattern (Pattern)	*string	no	Go regexp for waitConsole.
max_bytes (MaxBytes)	*int	no	Bounded history tail for getConsoleHistory.
steps (Steps)	[]ConsoleRunStep	no
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ConsoleSessionData

Field	Go type	Required	Semantics
session_id (SessionID)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name (Name)	*string	no
console_type (ConsoleType)	*string	no
mode (Mode)	*ConsoleWriteMode	no
state (State)	*string	no
created_at (CreatedAt)	*string	no
last_activity (LastActivity)	*string	no
observers (Observers)	*int	no
writers (Writers)	*int	no
owner (Owner)	*string	no	Exclusive writer owner when mode is exclusive.
phase (Phase)	*string	no	Interaction phase. state remains the TCP lifecycle.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "session_id": "sess-7f3a",
  "node": "n_1",
  "name": "R1",
  "console_type": "telnet",
  "mode": "interact",
  "state": "open",
  "observers": 1,
  "writers": 1
}

Processing the result¶

Typical field access after a successful call:

sess, _ := client.CreateConsoleSession(ctx, req)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.CreateConsoleSession(ctx, eveiac.CreateConsoleSessionRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

ListConsoleSessions¶

Family: Console

Purpose¶

Lists the console sessions the agent currently holds.

Mental model¶

Which console sessions are open?

Use when¶

• finding a session id

Reads¶

• agent console sessions

Changes¶

Nothing. Read-only.

Related¶

• getConsoleSession
• closeConsoleSession

Signature¶

func (c *Client) ListConsoleSessions(ctx context.Context, body ListConsoleSessionsRequest, timeoutMs ...int) (*ConsoleSessionListData, error)

• HTTP: POST /api/v1/console/sessions/list
• operationId: listConsoleSessions
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	ListConsoleSessionsRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: ListConsoleSessionsRequest¶

This request type is the same wire shape as ConsolePayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
manifest (Manifest)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command (Command)	*string	no
commands (Commands)	[]string	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms (TimeoutMs)	*int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets (Targets)	[]ConsoleTarget	no
session_id (SessionID)	*string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq (AfterSeq)	*int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode (Mode)	*ConsoleWriteMode	no
pattern (Pattern)	*string	no	Go regexp for waitConsole.
max_bytes (MaxBytes)	*int	no	Bounded history tail for getConsoleHistory.
steps (Steps)	[]ConsoleRunStep	no
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ConsoleSessionListData

Field	Go type	Required	Semantics
sessions (Sessions)	[]ConsoleSessionData	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "sessions": [
    {
      "session_id": "sess-7f3a",
      "node": "n_1",
      "mode": "interact",
      "state": "open"
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

listed, _ := client.ListConsoleSessions(ctx, req)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.ListConsoleSessions(ctx, eveiac.ListConsoleSessionsRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

GetConsoleSession¶

Family: Console

Purpose¶

Returns one console session by id.

Mental model¶

Is this console session still here?

Use when¶

• checking one session before reuse

Reads¶

• that console session

Changes¶

Nothing. Read-only.

Related¶

• listConsoleSessions

Signature¶

func (c *Client) GetConsoleSession(ctx context.Context, body GetConsoleSessionRequest, timeoutMs ...int) (*ConsoleSessionData, error)

• HTTP: POST /api/v1/console/sessions/get
• operationId: getConsoleSession
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	GetConsoleSessionRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: GetConsoleSessionRequest¶

This request type is the same wire shape as ConsolePayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
manifest (Manifest)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command (Command)	*string	no
commands (Commands)	[]string	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms (TimeoutMs)	*int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets (Targets)	[]ConsoleTarget	no
session_id (SessionID)	*string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq (AfterSeq)	*int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode (Mode)	*ConsoleWriteMode	no
pattern (Pattern)	*string	no	Go regexp for waitConsole.
max_bytes (MaxBytes)	*int	no	Bounded history tail for getConsoleHistory.
steps (Steps)	[]ConsoleRunStep	no
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ConsoleSessionData

Field	Go type	Required	Semantics
session_id (SessionID)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name (Name)	*string	no
console_type (ConsoleType)	*string	no
mode (Mode)	*ConsoleWriteMode	no
state (State)	*string	no
created_at (CreatedAt)	*string	no
last_activity (LastActivity)	*string	no
observers (Observers)	*int	no
writers (Writers)	*int	no
owner (Owner)	*string	no	Exclusive writer owner when mode is exclusive.
phase (Phase)	*string	no	Interaction phase. state remains the TCP lifecycle.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "session_id": "sess-7f3a",
  "node": "n_1",
  "mode": "exclusive",
  "state": "open",
  "owner": "agent-session-1",
  "writers": 1
}

Processing the result¶

Typical field access after a successful call:

sess, _ := client.GetConsoleSession(ctx, req)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetConsoleSession(ctx, eveiac.GetConsoleSessionRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

CloseConsoleSession¶

Family: Console

Purpose¶

Closes one console session.

Mental model¶

Release this console.

Use when¶

• dropping a session you no longer need

Reads¶

• that console session

Changes¶

Closes the session.

Related¶

• createConsoleSession

Signature¶

func (c *Client) CloseConsoleSession(ctx context.Context, body CloseConsoleSessionRequest, timeoutMs ...int) (*ConsoleSessionData, error)

• HTTP: POST /api/v1/console/sessions/close
• operationId: closeConsoleSession
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	CloseConsoleSessionRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: CloseConsoleSessionRequest¶

This request type is the same wire shape as ConsolePayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
manifest (Manifest)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command (Command)	*string	no
commands (Commands)	[]string	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms (TimeoutMs)	*int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets (Targets)	[]ConsoleTarget	no
session_id (SessionID)	*string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq (AfterSeq)	*int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode (Mode)	*ConsoleWriteMode	no
pattern (Pattern)	*string	no	Go regexp for waitConsole.
max_bytes (MaxBytes)	*int	no	Bounded history tail for getConsoleHistory.
steps (Steps)	[]ConsoleRunStep	no
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ConsoleSessionData

Field	Go type	Required	Semantics
session_id (SessionID)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name (Name)	*string	no
console_type (ConsoleType)	*string	no
mode (Mode)	*ConsoleWriteMode	no
state (State)	*string	no
created_at (CreatedAt)	*string	no
last_activity (LastActivity)	*string	no
observers (Observers)	*int	no
writers (Writers)	*int	no
owner (Owner)	*string	no	Exclusive writer owner when mode is exclusive.
phase (Phase)	*string	no	Interaction phase. state remains the TCP lifecycle.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "session_id": "sess-7f3a",
  "node": "n_1",
  "state": "closed"
}

Processing the result¶

Typical field access after a successful call:

closed, _ := client.CloseConsoleSession(ctx, req)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.CloseConsoleSession(ctx, eveiac.CloseConsoleSessionRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

GetConsoleHistory¶

Family: Console

Purpose¶

Returns the recent bytes the console session has already received. It is not the result of a new command.

Mental model¶

What did this console already print?

Use when¶

• reading the tail of a session

Do not use when¶

• you want to send a command; use execConsole

Reads¶

• the session receive ring

Changes¶

Nothing. Read-only.

Important semantics¶

• Bounded tail of the Hub ring (max 65536 bytes). end_seq is the newest retained receive sequence. after_seq returns only newer bytes and sets truncated when that sequence has left the ring. History is not the current command result.

Related¶

• execConsole
• waitConsole

Signature¶

func (c *Client) GetConsoleHistory(ctx context.Context, body GetConsoleHistoryRequest, timeoutMs ...int) (*ConsoleHistoryData, error)

• HTTP: POST /api/v1/console/history
• operationId: getConsoleHistory
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	GetConsoleHistoryRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: GetConsoleHistoryRequest¶

This request type is the same wire shape as ConsolePayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
manifest (Manifest)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command (Command)	*string	no
commands (Commands)	[]string	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms (TimeoutMs)	*int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets (Targets)	[]ConsoleTarget	no
session_id (SessionID)	*string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq (AfterSeq)	*int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode (Mode)	*ConsoleWriteMode	no
pattern (Pattern)	*string	no	Go regexp for waitConsole.
max_bytes (MaxBytes)	*int	no	Bounded history tail for getConsoleHistory.
steps (Steps)	[]ConsoleRunStep	no
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ConsoleHistoryData

Field	Go type	Required	Semantics
session_id (SessionID)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
text (Text)	*string	no	Bounded raw console tail (UTF-8 interpretation).
truncated (Truncated)	*bool	no
byte_count (ByteCount)	*int	no
available_bytes (AvailableBytes)	*int	no	Bytes retained in the Hub ring (max 65536).
end_seq (EndSeq)	*int	no	Receive sequence of the newest byte retained in the ring.

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Ephemeral Hub ring tail only; not persistent audit history.

{
  "session_id": "sess-7f3a",
  "node": "n_1",
  "text": "Router>enable\\nRouter#",
  "truncated": false,
  "byte_count": 18,
  "available_bytes": 18
}

Processing the result¶

Typical field access after a successful call:

hist, _ := client.GetConsoleHistory(ctx, req)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetConsoleHistory(ctx, eveiac.GetConsoleHistoryRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

WaitConsole¶

Family: Console

Purpose¶

Waits until the console output matches a regular expression, or until the wait times out.

Mental model¶

Tell me when the console prints this.

Use when¶

• waiting for a prompt or a banner

Do not use when¶

• you also need to send text; use runConsole

Reads¶

• the console session output

Changes¶

Blocks on the session until the pattern matches, the wait times out, or the call is cancelled.

Important semantics¶

• Go regexp pattern; max timeout_ms 600000; timed_out distinguishable from cancel.

Related¶

• runConsole
• getConsoleHistory

Signature¶

func (c *Client) WaitConsole(ctx context.Context, body WaitConsoleRequest, timeoutMs ...int) (*ConsoleWaitData, error)

• HTTP: POST /api/v1/console/wait
• operationId: waitConsole
• Authentication: Bearer token required
• Default timeout: 615000 ms

Parameters¶

Parameter	Type	Required	Description
body	WaitConsoleRequest	yes	Request body.
timeoutMs	...int	no	Override the 615000 ms default.

Request schema: WaitConsoleRequest¶

This request type is the same wire shape as ConsolePayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
manifest (Manifest)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command (Command)	*string	no
commands (Commands)	[]string	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms (TimeoutMs)	*int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets (Targets)	[]ConsoleTarget	no
session_id (SessionID)	*string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq (AfterSeq)	*int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode (Mode)	*ConsoleWriteMode	no
pattern (Pattern)	*string	no	Go regexp for waitConsole.
max_bytes (MaxBytes)	*int	no	Bounded history tail for getConsoleHistory.
steps (Steps)	[]ConsoleRunStep	no
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ConsoleWaitData

Field	Go type	Required	Semantics
session_id (SessionID)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
matched (Matched)	*bool	no
match (Match)	*string	no
text (Text)	*string	no	Matched snippet.
duration_ms (DurationMs)	*int	no
timed_out (TimedOut)	*bool	no
truncated (Truncated)	*bool	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

{
  "session_id": "sess-7f3a",
  "node": "n_1",
  "matched": true,
  "match": "Router#",
  "text": "Router#",
  "duration_ms": 42,
  "timed_out": false,
  "truncated": false
}

Processing the result¶

Typical field access after a successful call:

waited, _ := client.WaitConsole(ctx, req)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.WaitConsole(ctx, eveiac.WaitConsoleRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

RunConsole¶

Family: Console

Purpose¶

Runs an ordered expect and send script on one console. Use execConsole for a single command.

Mental model¶

Play this dialogue on the console.

Use when¶

• a multi-step console dialogue

Do not use when¶

• a single show, ping, or traceroute; use execConsole

Reads¶

• the console session

Changes¶

Sends the script's bytes and records the transcript of this run.

Important semantics¶

• Interactive expect/send on the Hub. An expect after send matches only bytes received after that send. Transcript is this run. Not the path for a single show, ping, or traceroute. failed_step is 0-based; send_secret redacted; max timeout_ms 600000.

Related¶

• execConsole
• waitConsole

Signature¶

func (c *Client) RunConsole(ctx context.Context, body RunConsoleRequest, timeoutMs ...int) (*ConsoleRunData, error)

• HTTP: POST /api/v1/console/run
• operationId: runConsole
• Authentication: Bearer token required
• Default timeout: 615000 ms

Parameters¶

Parameter	Type	Required	Description
body	RunConsoleRequest	yes	Request body.
timeoutMs	...int	no	Override the 615000 ms default.

Request schema: RunConsoleRequest¶

This request type is the same wire shape as ConsolePayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
manifest (Manifest)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command (Command)	*string	no
commands (Commands)	[]string	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms (TimeoutMs)	*int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets (Targets)	[]ConsoleTarget	no
session_id (SessionID)	*string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq (AfterSeq)	*int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode (Mode)	*ConsoleWriteMode	no
pattern (Pattern)	*string	no	Go regexp for waitConsole.
max_bytes (MaxBytes)	*int	no	Bounded history tail for getConsoleHistory.
steps (Steps)	[]ConsoleRunStep	no
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ConsoleRunData

Field	Go type	Required	Semantics
session_id (SessionID)	*string	no
ok (Ok)	*bool	no
failed_step (FailedStep)	*int	no	0-based failed step index; -1 when ok.
steps (Steps)	[]ConsoleRunStepResult	no
transcript (Transcript)	*string	no	Bytes received after the sends in this run, up to the completing match.
truncated (Truncated)	*bool	no
duration_ms (DurationMs)	*int	no
prompt (Prompt)	*string	no
phase (Phase)	*string	no
rx_to (RxTo)	*int	no
recovered (Recovered)	*bool	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

send_secret values appear as ******** in sent/transcript; never include real secrets in samples.

{
  "session_id": "sess-7f3a",
  "ok": true,
  "failed_step": -1,
  "duration_ms": 120,
  "truncated": false,
  "transcript": "Press RETURN to get started\\nRouter>enable\\nRouter#",
  "steps": [
    {
      "index": 0,
      "expect": "Press RETURN",
      "sent": "",
      "matched": "Press RETURN",
      "duration_ms": 10
    },
    {
      "index": 1,
      "expect": "Router>",
      "sent": "enable",
      "matched": "Router>",
      "duration_ms": 15
    },
    {
      "index": 2,
      "expect": "Router#",
      "sent": "********",
      "matched": "Router#",
      "duration_ms": 12
    }
  ]
}

Processing the result¶

Typical field access after a successful call:

ran, _ := client.RunConsole(ctx, req)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
console_busy	Contractual/known for this call or its transport
console_connect_failed	Contractual/known for this call or its transport
console_timeout	Contractual/known for this call or its transport
command_timeout	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
too_many_consoles	Contractual/known for this call or its transport
unsupported_console	Contractual/known for this call or its transport
node_not_found	Contractual/known for this call or its transport
node_not_running	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.RunConsole(ctx, eveiac.RunConsoleRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

AttachConsole¶

Family: Console

Purpose¶

Returns a ticket for an interactive or read-only console stream. Omitted mode is interact.

Mental model¶

Attach me to this console.

Use when¶

• opening a terminal
• watching a console without writing

Do not use when¶

• you only need one command result; use execConsole

Reads¶

• the node console

Changes¶

Opens or joins a console session and issues a stream ticket.

Important semantics¶

• Omitted mode is interact. Optional session_id joins or creates Hub-backed stream context. Ticket/stream semantics unchanged.

Related¶

• streamConsole
• execConsole

Signature¶

func (c *Client) AttachConsole(ctx context.Context, body AttachConsoleRequest, timeoutMs ...int) (*ConsoleAttachData, error)

• HTTP: POST /api/v1/console/attach
• operationId: attachConsole
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	AttachConsoleRequest	yes	Request body.
timeoutMs	...int	no	Override the 30000 ms default.

Request schema: AttachConsoleRequest¶

This request type is the same wire shape as ConsolePayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
manifest (Manifest)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
command (Command)	*string	no
commands (Commands)	[]string	no	Ordered commands on the joined Hub. Each command completes when the prompt returns after that command is sent.
timeout_ms (TimeoutMs)	*int	no	execConsole max 60000. waitConsole/runConsole max 600000. Default 10000 when omitted.
targets (Targets)	[]ConsoleTarget	no
session_id (SessionID)	*string	no	Optional Hub session. Omit to join or open the Hub for the node. A missing session reopens once. console_busy is not expiry.
after_seq (AfterSeq)	*int	no	getConsoleHistory only. Return bytes newer than this receive sequence. truncated is set when the sequence has left the ring.
mode (Mode)	*ConsoleWriteMode	no
pattern (Pattern)	*string	no	Go regexp for waitConsole.
max_bytes (MaxBytes)	*int	no	Bounded history tail for getConsoleHistory.
steps (Steps)	[]ConsoleRunStep	no
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

ConsoleAttachData

Field	Go type	Required	Semantics
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
name (Name)	*string	no
console_type (ConsoleType)	*string	no
stream (Stream)	*string	no
transport (Transport)	*string	no
session_id (SessionID)	*string	no
mode (Mode)	*ConsoleWriteMode	no

JSON wire shape¶

On success the transport unwraps the HTTP envelope and the SDK returns a typed model. The object below is the same shape as CLI --json stdout (the agent data object, not the envelope).

Omitted mode is interact. stream is a relative ticket path; success streamConsole uses 101 eve-telnet.

{
  "node": "n_1",
  "name": "R1",
  "console_type": "telnet",
  "stream": "/api/v1/console/stream/abc123",
  "transport": "eve-telnet",
  "mode": "interact"
}

Processing the result¶

Typical field access after a successful call:

att, _ := client.AttachConsole(ctx, req)

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
browser_token_invalid	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport

Example¶

attached, err := client.AttachConsole(ctx, eveiac.AttachConsoleRequest{Lab: eveiac.Ptr(lab), Node: eveiac.Ptr("n_1")})

StreamConsole¶

Family: Console

Purpose¶

Upgrades a console ticket to the raw console byte stream.

Mental model¶

Give me the console bytes.

Use when¶

• attaching a terminal after attachConsole

Reads¶

• the console ticket

Changes¶

Opens a byte stream. Writes on that stream go to the console when the session mode allows them.

Related¶

• attachConsole

Signature¶

func (c *Client) StreamConsole(ctx context.Context, ticket string, timeoutMs ...int) (net.Conn, error)

• HTTP: GET /api/v1/console/stream/{ticket}
• operationId: streamConsole
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Success is HTTP 101 Switching Protocols, not a JSON envelope

Parameters¶

Parameter	Type	Required	Description
ticket	string	yes	Path parameter
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

net.Conn — upgraded telnet byte stream.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
browser_token_invalid	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport

Example¶

conn, err := client.StreamConsole(ctx, ticket)

StreamTraffic¶

Family: Capture

Purpose¶

Upgrades a traffic ticket to the byte stream of translated lab traffic.

Mental model¶

Stream the traffic bytes.

Use when¶

• reading the traffic socket after attachTraffic

Reads¶

• the traffic ticket

Changes¶

Opens a stream. It does not change the lab.

Related¶

• attachTraffic

How-to¶

• Use traffic filters

Signature¶

func (c *Client) StreamTraffic(ctx context.Context, ticket string, timeoutMs ...int) (net.Conn, error)

• HTTP: GET /api/v1/projects/traffic/stream/{ticket}
• operationId: streamTraffic
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Success is HTTP 101 Switching Protocols, not a JSON envelope

Parameters¶

Parameter	Type	Required	Description
ticket	string	yes	Path parameter
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

net.Conn — upgraded telnet byte stream.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
browser_token_invalid	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport

Example¶

conn, err := client.StreamTraffic(ctx, ticket)

StartOob¶

Family: Console

Purpose¶

Starts the OOB SSH generation for this authenticated session and runtime project, or returns it unchanged when it is already active.

Mental model¶

Open out-of-band SSH for this lab.

Use when¶

• preparing SSH access through the console hub

Do not use when¶

• you only need a browser console; use attachConsole

Reads¶

• the authenticated session and the runtime project

Changes¶

Creates the generation when it was off. Does not attach the hub.

Important semantics¶

• OFF mints one generation. ACTIVE in the same session and project returns that generation and does not rotate keys or drop live SSH.

Related¶

• getOobStatus
• getOobCredentials
• openOob
• stopOob

Signature¶

func (c *Client) StartOob(ctx context.Context, body StartOobRequest, timeoutMs ...int) (*OobStatusData, error)

• HTTP: POST /api/v1/oob/start
• operationId: startOob
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	StartOobRequest	yes	Request body.
timeoutMs	...int	no	Override the 30000 ms default.

Request schema: StartOobRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

OobStatusData

Field	Go type	Required	Semantics
active (Active)	*bool	no
username (Username)	*string	no	SSH username. Always eve-oob while active. HTTP does not authenticate this name.
user_public_key (UserPublicKey)	*string	no
host_public_key (HostPublicKey)	*string	no
host_fingerprint (HostFingerprint)	*string	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.StartOob(ctx, eveiac.StartOobRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

GetOobStatus¶

Family: Console

Purpose¶

Reports whether this session has an active OOB generation for the runtime project.

Mental model¶

Is out-of-band SSH on?

Use when¶

• checking the generation before materializing files

Reads¶

• the OOB generation for this session and project

Changes¶

Nothing. Read-only.

Related¶

• startOob
• getOobCredentials

Signature¶

func (c *Client) GetOobStatus(ctx context.Context, body GetOobStatusRequest, timeoutMs ...int) (*OobStatusData, error)

• HTTP: POST /api/v1/oob/status
• operationId: getOobStatus
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Auth replay: read/idempotent calls may retry once after agent re-auth

Parameters¶

Parameter	Type	Required	Description
body	GetOobStatusRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: GetOobStatusRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

OobStatusData

Field	Go type	Required	Semantics
active (Active)	*bool	no
username (Username)	*string	no	SSH username. Always eve-oob while active. HTTP does not authenticate this name.
user_public_key (UserPublicKey)	*string	no
host_public_key (HostPublicKey)	*string	no
host_fingerprint (HostFingerprint)	*string	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetOobStatus(ctx, eveiac.GetOobStatusRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

GetOobCredentials¶

Family: Console

Purpose¶

Returns the SSH user key, host public key, fingerprint, known_hosts line, and node snapshot for the active generation.

Mental model¶

Give me the SSH material for this generation.

Use when¶

• writing the project-local OOB runtime files

Do not use when¶

• the generation is inactive

Reads¶

• the generation keys and the current node catalogue

Changes¶

Nothing. Does not rotate keys.

Important semantics¶

• Inactive is oob_inactive, not an empty object. known_hosts may grow with the catalogue. Keys stay stable until stop.

Related¶

• startOob
• openOob

Signature¶

func (c *Client) GetOobCredentials(ctx context.Context, body GetOobCredentialsRequest, timeoutMs ...int) (*OobCredentialsData, error)

• HTTP: POST /api/v1/oob/credentials
• operationId: getOobCredentials
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	GetOobCredentialsRequest	yes	Request body.
timeoutMs	...int	no	Override the 30000 ms default.

Request schema: GetOobCredentialsRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

OobCredentialsData

Field	Go type	Required	Semantics
username (Username)	*string	no
user_private_key (UserPrivateKey)	*string	no
user_public_key (UserPublicKey)	*string	no
host_public_key (HostPublicKey)	*string	no
host_fingerprint (HostFingerprint)	*string	no
known_hosts (KnownHosts)	*string	no
nodes (Nodes)	[]OobNode	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
oob_inactive	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.GetOobCredentials(ctx, eveiac.GetOobCredentialsRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

StopOob¶

Family: Console

Purpose¶

Destroys the OOB generation for this session and project and closes its SSH sessions.

Mental model¶

Turn out-of-band SSH off.

Use when¶

• revoking the current generation

Reads¶

• the OOB generation

Changes¶

Closes live SSH, destroys keys, and invalidates tickets. Already off stays off.

Related¶

• startOob

Signature¶

func (c *Client) StopOob(ctx context.Context, body StopOobRequest, timeoutMs ...int) (*OobStatusData, error)

• HTTP: POST /api/v1/oob/stop
• operationId: stopOob
• Authentication: Bearer token required
• Default timeout: 30000 ms

Parameters¶

Parameter	Type	Required	Description
body	StopOobRequest	yes	Request body.
timeoutMs	...int	no	Override the 30000 ms default.

Request schema: StopOobRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

OobStatusData

Field	Go type	Required	Semantics
active (Active)	*bool	no
username (Username)	*string	no	SSH username. Always eve-oob while active. HTTP does not authenticate this name.
user_public_key (UserPublicKey)	*string	no
host_public_key (HostPublicKey)	*string	no
host_fingerprint (HostFingerprint)	*string	no

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.StopOob(ctx, eveiac.StopOobRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

OpenOob¶

Family: Console

Purpose¶

Issues a one-shot ticket for one catalogue node in the active generation.

Mental model¶

Give me a ticket for this node's SSH stream.

Use when¶

• the ProxyCommand is about to open the SSH byte stream

Do not use when¶

• you want the console hub attached before SSH authentication

Reads¶

• the generation and the node catalogue

Changes¶

Stores a 30s single-use ticket. Does not dial Telnet.

Important semantics¶

• Ticket only. Does not attach the hub. HTTP does not read the SSH username.

Related¶

• streamOob
• startOob

Signature¶

func (c *Client) OpenOob(ctx context.Context, body OpenOobRequest, timeoutMs ...int) (*OobOpenData, error)

• HTTP: POST /api/v1/oob/open
• operationId: openOob
• Authentication: Bearer token required
• Default timeout: 15000 ms

Parameters¶

Parameter	Type	Required	Description
body	OpenOobRequest	yes	Request body.
timeoutMs	...int	no	Override the 15000 ms default.

Request schema: OpenOobRequest¶

This request type is the same wire shape as ProjectPayload.

Field	Go type	Required	Semantics
lab (Lab)	*string	no
yaml (YAML)	*string	no
files (Files)	map[string]string	no
state (State)	any	no
source (Source)	any	no
manifest (Manifest)	*string	no
prune (Prune)	*bool	no	omitted: Go bool zero = false. to_eve still deletes a node or network whose id is in project state but whose key is absent from the desired topology, and a link absent from the desired topology. Other extra live objects are not deleted. explicit false: same semantic as omitted, distinct on the wire. explicit true: also delete extra live objects that the project never owned
wipe (Wipe)	*bool	no	explicit false: destroy lab without wiping nodes. omitted on destroy: server pointer nil means wipe nodes (true)
action (Action)	*string	no
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
nodes (Nodes)	[]string	no	execProject and exportProjectConfig IaC node keys. Omitted uses node. Omitted node and omitted nodes means all nodes.
configset (Configset)	*string	no	exportProjectConfig: default, or the name of a configset that already exists on the lab. Unknown names are not created.
id (ID)	*int	no
stopmode (Stopmode)	*int	no	0=graceful 1=poweroff 2=hibernate 3=auto. Omitted uses lifecycle.DefaultStopMode (3). Explicit 0 is graceful. No OpenAPI default. omitted: lifecycle.DefaultStopMode (3, Vue auto). explicit 0: graceful stop (0); distinct from omission. values: 0=graceful 1=poweroff 2=hibernate 3=auto
refresh (Refresh)	*bool	no	omitted: Go bool zero = false; inspect may use the session cache. explicit true: bypass inspect cache
replace (Replace)	*bool	no	omitted: Go bool zero = false; existing managed lab returns 409 lab_exists. explicit true: stop/wipe/delete then recreate
plan_identity (PlanIdentity)	*string	no	omitted: recompute the live plan. to_eve confirm=true with remaining stop-required work: omitted identity is 409 plan_stale. present: opaque token from the last plan of the same direction
direction (Direction)	*string	no	Wire string. Valid values are documented in semantics.yaml, not as an OpenAPI enum, so omitted vs to_eve vs empty vs invalid remain distinct on the wire. omitted: resolves to to_eve. empty string: resolves to to_eve. from_eve is not Import
confirm (Confirm)	*bool	no	Meaningful on reconcileProject. If any PlanAction is unsupported, to_eve performs zero EVE mutations and the plan stays inspectable. Otherwise omitted/false applies live-applicable work and does not stop nodes. true on to_eve, only when the plan has no unsupported action: after live-safe work, stop classified requires_stop nodes only when plan_identity still matches the live classified plan; omitted or stale identity is 409 plan_stale with zero StopNode. from_eve: confirm does not authorize stop. omitted: Go bool zero = false. If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise reconcile applies live-applicable work only and does not stop nodes. explicit false: same semantic as omitted, distinct on the wire. explicit true: If any PlanAction is unsupported, to_eve performs zero EVE mutations. Otherwise to_eve reconcile may stop classified requires_stop nodes, re-plan, apply, restore run state. from_eve: confirm does not authorize stop. prune still requires its own confirm/yes.
file (File)	*string	no	getPublicProject only. topology or presentation. Omitted = topology.
path (Path)	*string	no	getPublicProject only. RFC 6901 JSON Pointer. Omitted or empty = whole document. Selects only; does not transform.
filter (Filter)	*string	no	getPublicProject only. Exact IaC key. Allowed only with path /nodes, /networks, or /links. Nodes/networks: missing key is path_not_found. Links: endpoint membership, original order, empty array if none. Not jq.
dir (Dir)	*string	no	Rejected when non-empty.
out (Out)	*string	no	Rejected when non-empty.

Returns¶

OobOpenData

Field	Go type	Required	Semantics
node (Node)	*string	no	omitted: all nodes. empty string: all nodes. named: that IaC node key
ticket (Ticket)	*string	no	64-char lowercase hex. Single use. 30s TTL. Bound to this session, project, node, and generation.
stream (Stream)	*string	no	GET path for Upgrade: eve-oob.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
oob_inactive	Contractual/known for this call or its transport
invalid_request	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport

Example¶

result, err := client.OpenOob(ctx, eveiac.OpenOobRequest{Lab: eveiac.Ptr(lab), Manifest: eveiac.Ptr(manifest), YAML: eveiac.Ptr(yaml), Files: files})

StreamOob¶

Family: Console

Purpose¶

Upgrades an OOB ticket to the raw SSH byte stream. The hub attaches only after a later shell request.

Mental model¶

Give me the SSH bytes.

Use when¶

• splicing OpenSSH through the ProxyCommand

Reads¶

• the OOB ticket

Changes¶

Opens a raw SSH stream. Does not attach the hub by itself.

Related¶

• openOob

Signature¶

func (c *Client) StreamOob(ctx context.Context, ticket string, timeoutMs ...int) (net.Conn, error)

• HTTP: GET /api/v1/oob/stream/{ticket}
• operationId: streamOob
• Authentication: Bearer token required
• Default timeout: 15000 ms
• Success is HTTP 101 Switching Protocols, not a JSON envelope

Parameters¶

Parameter	Type	Required	Description
ticket	string	yes	Path parameter
timeoutMs	...int	no	Override the 15000 ms default.

Returns¶

net.Conn — upgraded telnet byte stream.

Errors¶

JSON failures become AgentError with message, status, code, and optional data. The error string is diagnostic only; key off code and HTTP status.

code	When
unauthenticated	Contractual/known for this call or its transport
expired_agent_session	Contractual/known for this call or its transport
expired_eve_session	Contractual/known for this call or its transport
browser_token_invalid	Contractual/known for this call or its transport
tls_required	Contractual/known for this call or its transport
oob_inactive	Contractual/known for this call or its transport
tls_untrusted	Contractual/known for this call or its transport
tls_pin_mismatch	Contractual/known for this call or its transport

Example¶

result, err := client.StreamOob(ctx)