Productmind API

Agent definitions

An agent definition describes an agent that an automation can run: its instructions, model and tools. List Productmind's standard agents and your own, create, update and delete definitions (deleting a customized standard agent resets it), list the tools an agent may use, and queue a run of one. Creating, changing and running definitions needs automations to be available to your organization. See Definitions.


List agent definitions for a workspace

GET
https://api.productmind.ai
/workspaces/{workspaceId}/agent-definitions

Returns the custom agents available in this workspace: the system definitions shipped in code (as standard, or customized where this workspace has overridden one) followed by the workspace's own custom definitions. An uncustomized standard carries a synthetic standard:<slug> id and has no stored row.

List agent definitions for a workspace › path Parameters

workspaceId
​string · required

Workspace UUID

List agent definitions for a workspace › Responses

200

List of agent definitions

​AgentDefinitionDTO[] · required
​object
​object

Create an agent definition

POST
https://api.productmind.ai
/workspaces/{workspaceId}/agent-definitions

Creates a custom agent. The first save against a standard definition's slug creates the workspace's override row — it is a create, not an update. Requires the automation feature flag.

Create an agent definition › path Parameters

workspaceId
​string · required

Workspace UUID

Create an agent definition › Request Body

slug
​string · minLength: 2 · maxLength: 64 · pattern: ^[a-z0-9]+(-[a-z0-9]… · required

Unique per workspace. Immutable after creation — it IS the agent_id.

name
​string · minLength: 1 · maxLength: 200 · required
instructions
​string · minLength: 1 · maxLength: 32000 · required

The agent's SYSTEM PROMPT — who it is and how it works. Per-run data arrives as the invocation's input and context, never from here.

​
enabled
​boolean
Default: true
Default: {"tier":"quick"}
tools
​string[] · maxItems: 100

Tool registry keys. Validated against the live catalog on write.

Default: []
​AgentDefinitionMcpServer[] · maxItems: 10
Default: []
Default: {}
toolsRequiringApproval
​string[] · maxItems: 100
Default: []
​

Create an agent definition › Responses

Created agent definition

​AgentDefinitionDTO · required

List the tools an agent definition may use

GET
https://api.productmind.ai
/workspaces/{workspaceId}/agent-definitions/tools

The live tool catalog: the agent server's built-in tools plus every MCP-exposed operation on this API, de-duplicated (a built-in shadows its MCP twin). Each entry says whether it writes (mutating) and whether a definition holding it can still run on the asynchronous queue (asyncEligible).

List the tools an agent definition may use › path Parameters

workspaceId
​string · required

Workspace UUID

List the tools an agent definition may use › Responses

200

Tool catalog

​AgentToolCatalogEntry[] · required
​object
​object

Get an agent definition by slug

GET
https://api.productmind.ai
/workspaces/{workspaceId}/agent-definitions/{slug}

Resolves one definition, falling back to the code-defined standard when this workspace has no override row — a standard with no row is a first-class result, not a 404. Returns 404 for an unknown slug, a disabled definition, or an organization without the automation flag.

Get an agent definition by slug › path Parameters

workspaceId
​string · required

Workspace UUID

slug
​string · required

The definition's slug — its agent_id

Get an agent definition by slug › Responses

200

Agent definition

​AgentDefinitionDTO · required

Update an agent definition

PUT
https://api.productmind.ai
/workspaces/{workspaceId}/agent-definitions/{slug}

Edits an override row and bumps its version. Send the version you read: a write carrying a stale version is rejected rather than silently overwriting a concurrent edit. The slug is immutable.

Update an agent definition › path Parameters

workspaceId
​string · required

Workspace UUID

slug
​string · required

The definition's slug — its agent_id

Update an agent definition › Request Body

name
​string · minLength: 1 · maxLength: 200
​
instructions
​string · minLength: 1 · maxLength: 32000

The agent's SYSTEM PROMPT — who it is and how it works. Per-run data arrives as the invocation's input and context, never from here.

enabled
​boolean
tools
​string[] · maxItems: 100

Tool registry keys. Validated against the live catalog on write.

​AgentDefinitionMcpServer[] · maxItems: 10
toolsRequiringApproval
​string[] · maxItems: 100
​
version
​integer · max: 9007199254740991

Update an agent definition › Responses

200

Updated agent definition

​AgentDefinitionDTO · required

Delete an agent definition

DELETE
https://api.productmind.ai
/workspaces/{workspaceId}/agent-definitions/{slug}

Removes the stored row. For a customized standard that IS the reset — the workspace falls back to the code-defined default and the version counter restarts on the next customization. For a custom definition it is an ordinary delete.

Delete an agent definition › path Parameters

workspaceId
​string · required

Workspace UUID

slug
​string · required

The definition's slug — its agent_id

Delete an agent definition › Responses

200

Deleted

No data returned

Queue an asynchronous run of an agent definition

POST
https://api.productmind.ai
/workspaces/{workspaceId}/agent-definitions/{slug}/execute

Publishes an agent.execute message and returns immediately; the run reports its usage and terminal status through a worker callback. Rejected when the definition holds a tool barred from the asynchronous path (update-*, delete-*, merge-*, bulk-*) or an MCP server with no allowedTools — such a definition can still be run synchronously. The run acts as the calling user.

Queue an asynchronous run of an agent definition › path Parameters

workspaceId
​string · required

Workspace UUID

slug
​string · required

The definition's slug — its agent_id

Queue an asynchronous run of an agent definition › Request Body

input
​string · maxLength: 50000

The per-run instruction. Leads the user message. Omit it for an agent whose instructions already describe the whole job.

​AgentTrigger

What caused this run. Rendered after input. Defaults to a by-hand trigger.

Queue an asynchronous run of an agent definition › Responses

200

Run queued

No data returned