Skip to content
Nodus

Create a Agent

POST
/apis/nodus.dev/v1/namespaces/{namespace}/agents
 
curl --request POST \
  --url https://example.com/apis/nodus.dev/v1/namespaces/example/agents \
  --header 'Content-Type: application/json' \
  --data '{ "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": { "image": "example", "maxTokens": 1, "maxToolCalls": 1, "model": { "access": "example", "apiKeySecret": "example", "families": [ "example" ], "name": "example" }, "perRunMaxCostUSD": "example", "state": "example", "system": "example" } }'

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
namespace
required
string

The project.

Query Parameters

Section titled “ Query Parameters ”
dryRun
string
fieldValidation
string
fieldManager
string

Header Parameters

Section titled “ Header Parameters ”
Idempotency-Key
string
If-Match
string

Request Bodyrequired

Section titled “ Request Bodyrequired ”
Media type application/json

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
image

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

string
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 (the default) or BYOK.

string
apiKeySecret

APIKeySecret names the project Secret that holds the Anthropic key. Access BYOK only.

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 is the Anthropic model id of every turn. Access BYOK only; a current Sonnet when empty.

string
perRunMaxCostUSD

PerRunMaxCostUSD is the cost cap of each run on Nodus’s Claude, 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. A run on the customer’s own key is not charged and has no cap to reach.

string
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
Example generated 
{
  "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": {
    "image": "example",
    "maxTokens": 1,
    "maxToolCalls": 1,
    "model": {
      "access": "example",
      "apiKeySecret": "example",
      "families": [
        "example"
      ],
      "name": "example"
    },
    "perRunMaxCostUSD": "example",
    "state": "example",
    "system": "example"
  }
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

OK

Media type application/json

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
image

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

string
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 (the default) or BYOK.

string
apiKeySecret

APIKeySecret names the project Secret that holds the Anthropic key. Access BYOK only.

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 is the Anthropic model id of every turn. Access BYOK only; a current Sonnet when empty.

string
perRunMaxCostUSD

PerRunMaxCostUSD is the cost cap of each run on Nodus’s Claude, 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. A run on the customer’s own key is not charged and has no cap to reach.

string
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
Example generated 
{
  "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": {
    "image": "example",
    "maxTokens": 1,
    "maxToolCalls": 1,
    "model": {
      "access": "example",
      "apiKeySecret": "example",
      "families": [
        "example"
      ],
      "name": "example"
    },
    "perRunMaxCostUSD": "example",
    "state": "example",
    "system": "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"
}