Import Action

Land the tool surface agent-sdk extracted from an already-built agent as a draft action version: tool names, parameter names, types and requiredness
Extraction derives shapes and never guesses constraints, so the draft denies until a person authors its policy in the dashboard and publishes it
A re-import creates a new version rather than editing one, because a published version may already be pinned by live mandates
Proposed rules are checked against the supported CEL: a rule that would deny every call is refused, one outside the supported CEL is saved and listed in warnings

POST /agents/actions/{did}

Import Action

cURL

curl --request POST \
  --url https://api.humanos.tech/agents/actions/{did} \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "payments-agent",
  "tools": [
    {
      "name": "pay_invoice",
      "params": {
        "amount": {
          "type": "number",
          "required": true
        }
      }
    }
  ],
  "description": "Pays invoices from the company account.",
  "grantorParams": {
    "maxAmount": {
      "type": "number",
      "suggested": 500
    }
  },
  "rules": [
    {
      "name": "amount_within_limit",
      "expression": "params.amount <= userParams.maxAmount",
      "description": "The amount stays within the limit the person set."
    }
  ],
  "requiredFromTools": true
}
'

201

{
  "actionId": "507f1f77bcf86cd799439011",
  "created": true,
  "userParams": [
    "cap"
  ],
  "executionParams": [
    "load_id",
    "rate_usd"
  ],
  "suggested": {
    "cap": 500
  },
  "versionId": "urn:via:action:abc-123",
  "unchanged": false,
  "updated": false,
  "published": false,
  "warnings": [
    {
      "kind": "unsupported",
      "code": "unsupported_function",
      "message": "Rule \"rate_cap\" (unsupported): dyn() is outside the supported CEL",
      "rule": "rate_cap",
      "ruleIndex": 0,
      "param": "executionParams.rate_usd",
      "publishOnly": false
    }
  ]
}

Headers

API-Version · string

Pin request, response, and webhook shapes to a specific dated API version (YYYY-MM-DD). Omit to use the version pinned to your API key (set when the key is created; new keys default to the latest version). New integrations should target the latest version.

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"2026-10-16"

Path Parameters

did · string · required

The agent's DID, URL-encoded.

Example:

"did:web:humanos.tech:agent:2f8b6c41-9d37-4e5a-8b02-6c1d9e7a4f35"

Body

application/json

name · string · required

The action name. A re-import under the same name adds a version to that action.

Example:

"payments-agent"

tools · string[] · required

The tools, as agent-sdk's toWireTools gives them: { name, description?, params }, each parameter { type, description?, required?, role? }. Each tool is read by the import, which owns its shape.

Example:

[
  {
    "name": "pay_invoice",
    "params": {
      "amount": { "type": "number", "required": true }
    }
  }
]

description · string

Example:

"Pays invoices from the company account."

grantorParams · object

The values the person fixes in the mandate, by name: { type, items?, values?, description?, required?, suggested? }. suggested is echoed back for the agent's request and never stored in the action.

Example:

{
  "maxAmount": { "type": "number", "suggested": 500 }
}

rules · object[]

CEL rules the agent proposes for the draft. A rule that would deny every call is a 400; one outside the supported CEL is saved and listed in warnings.

Show child attributes

requiredFromTools · boolean

Carry each tool parameter's required into the draft, so verification enforces it.

Response

201

application/json

Returns the draft action version and the split of who supplies each value, with warnings when the draft holds something to change before publishing.

actionId · string · required

MongoDB identifier of the action the surface landed on.

Example:

"507f1f77bcf86cd799439011"

created · boolean · required

True when this import created the action; false when it added a version to an existing one.

Example:

true

userParams · string[] · required

The parameters the person fixes in the mandate.

Example:

["cap"]

executionParams · string[] · required

The parameters the agent supplies at each call.

Example:

["load_id", "rate_usd"]

suggested · object · required

The agent's proposed values for the person's parameters, echoed for its later request. Never stored in the action.

Example:

{ "cap": 500 }

versionId · string

URN of the action version the import wrote, or of the one it found unchanged. Use it with the version endpoints.

Example:

"urn:via:action:abc-123"

unchanged · boolean

True when the same surface was already the action's latest version: nothing was written.

Example:

false

updated · boolean

True when the latest version was a draft and its declarations were refreshed in place, its rules kept.

Example:

false

published · boolean

Whether the version returned is published, so a mandate can be asked under it now. An import never publishes.

Example:

false

warnings · object[]

What the draft was saved with although the organization cannot publish it as it is, such as a rule outside the supported CEL. Present only when there is something to say.

Show child attributes