Nimble API
Nimble Docsnimbleway.com
HomeAPI ReferenceSDKsContext Plugin
Public A P I

Create Agent

POST
/v2/agents

Create a Web Search Agent. Either pass template to materialize a pre-built template (its fields, goals, sources, and suggested questions are copied), or define the agent from scratch with display_name, goals, sources, and an optional output_schema for structured results.

Authorization

BearerAuth
AuthorizationBearer <token>

In: header

Request Body

application/json

agent_name?|

Stable agent name.

description?|

Agent description shown to users.

display_name?|

Human-friendly agent name shown to users.

effort?Effort

Default effort level for this agent's runs.

Default"high"

Value in

  • "low"
  • "medium"
  • "high"
  • "x-high"
  • "max"
goals?array<string>

Ordered goals for the agent to follow.

icon?|

Icon identifier used when presenting the agent.

is_active?Is Active

Whether the agent can be used to start new runs.

Defaulttrue
output_schema?|

JSON Schema for structured output. Root must be an object with non-empty properties or an array of objects. Hard limits: nesting depth ≤ 5, ≤ 100 properties, ≤ 500 enum values, no unsupported keywords (format, pattern, min/max*, root anyOf, standalone null). Invalid schemas return 422.

skill?|

Skill or operating context for the agent.

sources?

Source guidance for the agent.

suggested_questions?array<string>

Suggested prompts users can run with this agent.

template?|

Template name to materialize this instance from. When set, the scalar fields and child rows are copied from the template.

use_case?|

Primary use case supported by the agent.

Response Body

application/json

application/json

curl -X POST "https://example.com/v2/agents" \  -H "Content-Type: application/json" \  -d '{}'
{  "agent_name": "string",  "created_at": "2019-08-24T14:15:22Z",  "description": "string",  "display_name": "string",  "effort": "low",  "goals": [    {      "goal": "string",      "id": "string",      "order": 0    }  ],  "icon": "string",  "id": "string",  "is_active": true,  "output_schema": {},  "skill": "string",  "sources": {    "allow": [      {        "domains": [          "string"        ],        "id": "string",        "order": 0,        "title": "string"      }    ],    "avoid": "string",    "block": [      {        "domains": [          "string"        ],        "id": "string",        "order": 0,        "title": "string"      }    ],    "prioritize": "string"  },  "suggested_questions": [    {      "id": "string",      "order": 0,      "question": "string"    }  ],  "updated_at": "2019-08-24T14:15:22Z",  "use_case": "research"}

List Agents GET

List the active Web Search Agents in your account. Results are scoped to the workspace resolved from your token (or the optional `workspace_id` query parameter) and paginated with `offset`/`limit`.

Create Run POST

Creates a minimal persistent Web Search Agent and starts a run for it. The response includes `web_search_agent_id` for later agent and run queries.