HTTP operations¶

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

Candidate public v1 HTTPS API. Clients talk only to eve-iac-agent. Native EVE REST is not a client API.

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.

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.

GET /api/v1/health

• Auth: none
• Timeout: 15000 ms
• Response data: HealthData

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

POST /api/v1/login

• Auth: none
• Timeout: 15000 ms
• Request: LoginRequest
• Response data: LoginData

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

POST /api/v1/logout

• Auth: Bearer
• Timeout: 15000 ms
• Request: LogoutRequest
• Response data: StatusOkData

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

GET /api/v1/session

• Auth: Bearer
• Timeout: 15000 ms
• Response data: SessionData

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

GET /api/v1/capabilities

• Auth: Bearer
• Timeout: 15000 ms
• Response data: CapabilitiesData

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.

POST /api/v1/schema

• Auth: Bearer
• Timeout: 15000 ms
• Request: GetPublicSchemaRequest
• Response data: SchemaData

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

GET /api/v1/templates

• Auth: Bearer
• Timeout: 15000 ms
• Response data: TemplatesData

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

GET /api/v1/templates/catalog

• Auth: Bearer
• Timeout: 15000 ms
• Response data: TemplateCatalogData

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

GET /api/v1/templates/{id}

• Auth: Bearer
• Timeout: 15000 ms
• Response data: TemplateDetail

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

GET /api/v1/templates/{id}/images

• Auth: Bearer
• Timeout: 15000 ms
• Response data: TemplateImagesData

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

GET /api/v1/templates/{id}/attributes

• Auth: Bearer
• Timeout: 15000 ms
• Response data: TemplateAttributesData

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

GET /api/v1/network-types

• Auth: Bearer
• Timeout: 15000 ms
• Response data: NetworkTypesData

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

GET /api/v1/authoring/networks/{id}

• Auth: Bearer
• Timeout: 15000 ms
• Response data: NetworkAuthoring

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

GET /api/v1/icons

• Auth: Bearer
• Timeout: 15000 ms
• Response data: IconsData

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.

GET /api/v1/folders

• Auth: Bearer
• Timeout: 15000 ms
• Response data: FoldersData

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

GET /api/v1/authoring/icons.zip

• Auth: Bearer
• Timeout: 0 ms

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

GET /api/v1/authoring/revision

• Auth: Bearer
• Timeout: 0 ms
• Response data: AuthoringRevisionData

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

GET /api/v1/authoring/snapshot

• Auth: Bearer
• Timeout: 0 ms
• Response data: AuthoringSnapshotData

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

POST /api/v1/authoring/link-completions

• Auth: Bearer
• Timeout: 15000 ms
• Request: CompleteLinkInterfacesRequest
• Response data: InterfacesData

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

POST /api/v1/authoring/interfaces

• Auth: Bearer
• Timeout: 15000 ms
• Request: PreviewInterfacesRequest
• Response data: InterfacesData

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

POST /api/v1/projects/validate

• Auth: Bearer
• Timeout: 15000 ms
• Request: ValidateProjectRequest
• Response data: ValidateData

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

POST /api/v1/projects/import

• Auth: Bearer
• Timeout: 300000 ms
• Request: ImportProjectRequest
• Response data: ImportData

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

POST /api/v1/projects/plan

• Auth: Bearer
• Timeout: 180000 ms
• Request: PlanProjectRequest
• Response data: PlanData

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

POST /api/v1/projects/deploy

• Auth: Bearer
• Timeout: 300000 ms
• Request: DeployProjectRequest
• Response data: DeployData

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

POST /api/v1/projects/reconcile

• Auth: Bearer
• Timeout: 300000 ms
• Request: ReconcileProjectRequest
• Response data: ReconcileData

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

POST /api/v1/projects/destroy

• Auth: Bearer
• Timeout: 180000 ms
• Request: DestroyProjectRequest
• Response data: DestroyData

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

POST /api/v1/projects/status

• Auth: Bearer
• Timeout: 15000 ms
• Request: GetProjectStatusRequest
• Response data: ProjectStatusData

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

POST /api/v1/projects/inspect

• Auth: Bearer
• Timeout: 300000 ms
• Request: InspectProjectRequest
• Response data: InspectionData

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

POST /api/v1/projects/public

• Auth: Bearer
• Timeout: 15000 ms
• Request: GetPublicProjectRequest
• Response data: PublicData

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

POST /api/v1/projects/edit

• Auth: Bearer
• Timeout: 15000 ms
• Request: EditProjectRequest
• Response data: EditResult

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

POST /api/v1/projects/config

• Auth: Bearer
• Timeout: 15000 ms
• Request: GetProjectConfigRequest
• Response data: ConfigData

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

POST /api/v1/projects/config/edit

• Auth: Bearer
• Timeout: 15000 ms
• Request: EditProjectConfigRequest
• Response data: ConfigEditData

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.

POST /api/v1/projects/open

• Auth: Bearer
• Timeout: 30000 ms
• Request: OpenProjectRequest
• Response data: OpenData

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

POST /api/v1/projects/consoles

• Auth: Bearer
• Timeout: 30000 ms
• Request: ListProjectConsolesRequest
• Response data: ConsolesData

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

POST /api/v1/projects/exec

• Auth: Bearer
• Timeout: 180000 ms
• Request: ExecProjectRequest
• Response data: BulkResult

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

POST /api/v1/projects/export-config

• Auth: Bearer
• Timeout: 1800000 ms
• Request: ExportProjectConfigRequest
• Response data: ExportConfigData

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

POST /api/v1/projects/links/quality

• Auth: Bearer
• Timeout: 30000 ms
• Request: ApplyLinkQualityRequest
• Response data: LinkQualityData

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

POST /api/v1/projects/links/suspend

• Auth: Bearer
• Timeout: 30000 ms
• Request: SetLinkSuspendRequest
• Response data: LinkSuspendData

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

POST /api/v1/projects/capture

• Auth: Bearer
• Timeout: 30000 ms
• Request: StartCaptureRequest
• Response data: CaptureData

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

POST /api/v1/projects/traffic/attach

• Auth: Bearer
• Timeout: 30000 ms
• Request: AttachTrafficRequest
• Response data: TrafficAttachData

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

POST /api/v1/console/exec

• Auth: Bearer
• Timeout: 15000 ms
• Request: ExecConsoleRequest
• Response data: ConsoleExecData

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

POST /api/v1/console/exec-many

• Auth: Bearer
• Timeout: 15000 ms
• Request: ExecConsoleManyRequest
• Response data: ConsoleExecManyData

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

POST /api/v1/console/sessions

• Auth: Bearer
• Timeout: 30000 ms
• Request: CreateConsoleSessionRequest
• Response data: ConsoleSessionData

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

POST /api/v1/console/sessions/list

• Auth: Bearer
• Timeout: 15000 ms
• Request: ListConsoleSessionsRequest
• Response data: ConsoleSessionListData

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

POST /api/v1/console/sessions/get

• Auth: Bearer
• Timeout: 15000 ms
• Request: GetConsoleSessionRequest
• Response data: ConsoleSessionData

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

POST /api/v1/console/sessions/close

• Auth: Bearer
• Timeout: 15000 ms
• Request: CloseConsoleSessionRequest
• Response data: ConsoleSessionData

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

POST /api/v1/console/history

• Auth: Bearer
• Timeout: 15000 ms
• Request: GetConsoleHistoryRequest
• Response data: ConsoleHistoryData

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

POST /api/v1/console/wait

• Auth: Bearer
• Timeout: 615000 ms
• Request: WaitConsoleRequest
• Response data: ConsoleWaitData

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

POST /api/v1/console/run

• Auth: Bearer
• Timeout: 615000 ms
• Request: RunConsoleRequest
• Response data: ConsoleRunData

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

POST /api/v1/console/attach

• Auth: Bearer
• Timeout: 30000 ms
• Request: AttachConsoleRequest
• Response data: ConsoleAttachData

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

GET /api/v1/console/stream/{ticket}

• Auth: Bearer
• Timeout: 15000 ms

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

GET /api/v1/projects/traffic/stream/{ticket}

• Auth: Bearer
• Timeout: 15000 ms

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

POST /api/v1/oob/start

• Auth: Bearer
• Timeout: 30000 ms
• Request: StartOobRequest
• Response data: OobStatusData

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

POST /api/v1/oob/status

• Auth: Bearer
• Timeout: 15000 ms
• Request: GetOobStatusRequest
• Response data: OobStatusData

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

POST /api/v1/oob/credentials

• Auth: Bearer
• Timeout: 30000 ms
• Request: GetOobCredentialsRequest
• Response data: OobCredentialsData

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

POST /api/v1/oob/stop

• Auth: Bearer
• Timeout: 30000 ms
• Request: StopOobRequest
• Response data: OobStatusData

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

POST /api/v1/oob/open

• Auth: Bearer
• Timeout: 15000 ms
• Request: OpenOobRequest
• Response data: OobOpenData

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

GET /api/v1/oob/stream/{ticket}

• Auth: Bearer
• Timeout: 15000 ms