Skip to content
Nodus

List or watch agents

GET
/apis/nodus.dev/v1/namespaces/{namespace}/agents
 
curl --request GET \
  --url https://example.com/apis/nodus.dev/v1/namespaces/example/agents

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
namespace
required
string

The project.

Query Parameters

Section titled “ Query Parameters ”
labelSelector
string
fieldSelector
string
limit
string
continue
string
watch
string
resourceVersion
string
allowWatchBookmarks
string
timeoutSeconds
string

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

OK

Media type application/json
object
apiVersion
string
items
required
Array<object>

Agent is a durable agent definition: a system prompt, the Claude access it runs on and its cost cap. Each run executes the agent loop in its own Sandbox, and a change to the spec applies to the runs created after it.

object
apiVersion
string
kind
string
metadata
object
annotations
object
key
additional properties
string
creationTimestamp
string
deletionGracePeriodSeconds
integer format: int64
deletionTimestamp
string
finalizers
Array<string>
nullable
generateName
string
generation
integer format: int64
labels
object
key
additional properties
string
managedFields
Array<object>
nullable
object
apiVersion
string
fieldsType
string
fieldsV1
object
key
additional properties
manager
string
operation
string
subresource
string
time
string
name
string
namespace
string
ownerReferences
Array<object>
nullable
object
apiVersion
required
string
blockOwnerDeletion
boolean
controller
boolean
kind
required
string
name
required
string
uid
required
string
resourceVersion
string
selfLink
string
uid
string
spec
required

AgentSpec describes an Agent.

object
env

Env configures tool processes. Store credentials in project Secrets and use valueFrom.secretKeyRef.

Array<object>
nullable

EnvVar is one environment variable: a literal value or a Secret key.

object
name
required

Name matches ^[A-Za-z_][A-Za-z0-9_]*$.

string
value

Value is the literal value.

string
valueFrom

EnvVarSource names where an env value comes from.

object
secretKeyRef

SecretKeySelector selects one key of a Secret.

object
key
required

Key is the key within it.

string
name
required

Name is the Secret.

string
image

Image is the Sandbox image each run’s tools execute in; nodus/agent-tools when empty.

string
maxParallelAgents

MaxParallelAgents caps concurrent subagents in one shared sandbox, from 1 to 32; 8 when zero. The parent chooses the actual count for each task within this ceiling.

integer format: int32
maxTokens

MaxTokens bounds the output of each model call; 8192 when zero.

integer format: int64
maxToolCalls

MaxToolCalls bounds the tool calls of one turn; 50 when zero.

integer format: int32
model

AgentModel is spec.model.

object
access

Access is Nodus (legacy managed Claude, the default), OnDemand or BYOK. Hosted is reserved and rejected.

string
apiKeyField

APIKeyField selects a key in APIKeySecret; defaults to ANTHROPIC_API_KEY or OPENAI_API_KEY. A Secret containing exactly one value may use any field name.

string
apiKeySecret

APIKeySecret names the project Secret holding the model API key. Required for BYOK.

string
baseURL

BaseURL is an HTTPS API base including /v1, for BYOK only. Empty uses the protocol’s official API.

string
families

Families limits the Claude families the router may pick (haiku, sonnet, opus, fable); every family when empty. Access Nodus only.

Array<string>
nullable
name

Name selects an OnDemand catalog model (or endpoint/name) or a BYOK model id. Required for OnDemand and OpenAI BYOK; Anthropic BYOK defaults to Sonnet.

string
port

Port is reserved for future hosted inference; currently rejected.

integer format: int32
protocol

Protocol is Anthropic or OpenAI. BYOK defaults to Anthropic.

string
sandbox

Sandbox is reserved for future hosted inference; currently rejected.

string
workspace

Workspace is reserved for future hosted inference; currently rejected.

string
network

Network sets egress for the container.

object
egress

Egress is the outbound network policy.

object
allow

Allow lists DNS names or *.suffix patterns (AllowList only; at most 128).

Array<string>
nullable
policy

Policy is Deny, AllowList or Open.

string
presets

Presets add curated host lists such as python-packages or huggingface.

Array<string>
nullable
perRunMaxCostUSD

PerRunMaxCostUSD is the model cost cap of each Nodus or OnDemand run, 0.01 to 1000; “1.00” when empty. A run is created with the cap its Agent has at that moment and keeps it. Before each model call the run checks that the call at its largest, the whole request as input and spec.maxTokens of output, fits under the cap; when it does not, the run waits (MaxCostReached) and makes no more calls. BYOK has no Nodus token charge; the provider account has separate budgets.

string
secrets

Secrets mounts project Secrets in the shared sandbox, using the Sandbox secret delivery contract.

Array<object>
nullable

SecretMount mounts one Secret, optionally pinned to a version. The bare name is accepted on write.

object
name
required

Name is the Secret.

string
version

Version pins a version; unset pins the latest at admission.

integer format: int32
state

State is Running (the default) or Stopped, which refuses new runs and leaves the queued ones alone.

string
system

System is the system prompt of every turn, up to 64 KiB.

string
kind
string
metadata
object
continue
string
remainingItemCount
integer format: int64
resourceVersion
string
selfLink
string
shardInfo
object
selector
required
string
Example generated 
{
  "apiVersion": "example",
  "items": [
    {
      "apiVersion": "example",
      "kind": "example",
      "metadata": {
        "annotations": {
          "additionalProperty": "example"
        },
        "creationTimestamp": "example",
        "deletionGracePeriodSeconds": 1,
        "deletionTimestamp": "example",
        "finalizers": [
          "example"
        ],
        "generateName": "example",
        "generation": 1,
        "labels": {
          "additionalProperty": "example"
        },
        "managedFields": [
          {
            "apiVersion": "example",
            "fieldsType": "example",
            "fieldsV1": {
              "additionalProperty": "example"
            },
            "manager": "example",
            "operation": "example",
            "subresource": "example",
            "time": "example"
          }
        ],
        "name": "example",
        "namespace": "example",
        "ownerReferences": [
          {
            "apiVersion": "example",
            "blockOwnerDeletion": true,
            "controller": true,
            "kind": "example",
            "name": "example",
            "uid": "example"
          }
        ],
        "resourceVersion": "example",
        "selfLink": "example",
        "uid": "example"
      },
      "spec": {
        "env": [
          {
            "name": "example",
            "value": "example",
            "valueFrom": {
              "secretKeyRef": {
                "key": "example",
                "name": "example"
              }
            }
          }
        ],
        "image": "example",
        "maxParallelAgents": 1,
        "maxTokens": 1,
        "maxToolCalls": 1,
        "model": {
          "access": "example",
          "apiKeyField": "example",
          "apiKeySecret": "example",
          "baseURL": "example",
          "families": [
            "example"
          ],
          "name": "example",
          "port": 1,
          "protocol": "example",
          "sandbox": "example",
          "workspace": "example"
        },
        "network": {
          "egress": {
            "allow": [
              "example"
            ],
            "policy": "example",
            "presets": [
              "example"
            ]
          }
        },
        "perRunMaxCostUSD": "example",
        "secrets": [
          {
            "name": "example",
            "version": 1
          }
        ],
        "state": "example",
        "system": "example"
      }
    }
  ],
  "kind": "example",
  "metadata": {
    "continue": "example",
    "remainingItemCount": 1,
    "resourceVersion": "example",
    "selfLink": "example",
    "shardInfo": {
      "selector": "example"
    }
  }
}

default

Section titled “ default ”

An error: a metav1.Status whose reason is a registered code.

Media type application/json

Status is the error body of every API response: a Kubernetes metav1.Status (so kubectl and client-go understand it) plus three top-level extensions that those clients ignore (ADR-028).

object
apiVersion
string
code
integer format: int32
details
object
causes
Array<object>
nullable
object
field
string
message
string
reason
string
group
string
kind
string
name
string
retryAfterSeconds
integer format: int32
uid
string
docs

Docs is the URL of the code’s docs page.

string
fix

Fix says what to do next, for example a CLI command or the field to change.

string
kind
string
message
string
metadata
object
continue
string
remainingItemCount
integer format: int64
resourceVersion
string
selfLink
string
shardInfo
object
selector
required
string
reason
string
requestId

RequestID identifies the request in logs and support tickets.

string
status
string
Example generated 
{
  "apiVersion": "example",
  "code": 1,
  "details": {
    "causes": [
      {
        "field": "example",
        "message": "example",
        "reason": "example"
      }
    ],
    "group": "example",
    "kind": "example",
    "name": "example",
    "retryAfterSeconds": 1,
    "uid": "example"
  },
  "docs": "example",
  "fix": "example",
  "kind": "example",
  "message": "example",
  "metadata": {
    "continue": "example",
    "remainingItemCount": 1,
    "resourceVersion": "example",
    "selfLink": "example",
    "shardInfo": {
      "selector": "example"
    }
  },
  "reason": "example",
  "requestId": "example",
  "status": "example"
}