Public API

Create Agent

Create an 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.

Request body

agent_namestring nullable

Stable agent name.

descriptionstring nullable

Agent description shown to users.

display_namestring nullable

Human-friendly agent name shown to users.

effort'low' | 'medium' | 'high' | 'x-high' | 'max'

Canonical effort tier names for the research graph.

goalsstring[]

Ordered goals for the agent to follow.

iconstring nullable

Icon identifier used when presenting the agent.

is_activeboolean

Whether the agent can be used to start new runs.

output_schemaobject nullable

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.

skillstring nullable

Skill or operating context for the agent.

suggested_questionsstring[]

Suggested prompts users can run with this agent.

templatestring nullable

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

use_case'research' | 'enrichment' | 'dataset_building'

Example request

{
  "goals": [
    "Find recent company announcements",
    "Summarize funding history"
  ],
  "sources": {
    "allow": [
      {
        "domains": [
          "linkedin.com",
          "crunchbase.com"
        ],
        "title": "Professional networks"
      }
    ],
    "block": [
      {
        "domains": [
          "linkedin.com",
          "crunchbase.com"
        ],
        "title": "Professional networks"
      }
    ]
  },
  "template": "linkedin_company_profiles"
}

Response

Successful Response

agent_namestring nullable

Stable agent name.

created_atstring date-time required

When the agent was created.

descriptionstring required

Agent description shown to users.

display_namestring required

Human-friendly agent name shown to users.

effort'low' | 'medium' | 'high' | 'x-high' | 'max' required

Canonical effort tier names for the research graph.

iconstring required

Icon identifier used when presenting the agent.

idstring required

Unique Agent identifier (wsa_<uuid>).

is_activeboolean required

Whether the agent can be used to start new runs.

output_schemaobject nullable required

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.

skillstring required

Skill or operating context for the agent.

updated_atstring date-time required

When the agent was last updated.

use_case'research' | 'enrichment' | 'dataset_building' required

Example response

{
  "display_name": "Company News Tracker",
  "id": "wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00",
  "sources": {
    "allow": [
      {
        "domains": [
          "linkedin.com",
          "crunchbase.com"
        ],
        "title": "Professional networks"
      }
    ],
    "block": [
      {
        "domains": [
          "linkedin.com",
          "crunchbase.com"
        ],
        "title": "Professional networks"
      }
    ]
  }
}

Create Agent

Request

Request body

Example request

Response 201Created

Example response

Changes

Response