Skip to main content
POST
Create an agent

Authorizations

Authorization
string
header
required

An API key, sent as Authorization: Bearer stfy_live_…. See Authentication for how to get one and which scopes it needs.

Body

application/json
instructions
string
required

What the agent is told to do

Required string length: 1 - 100000
name
string
required
Required string length: 1 - 255
context
enum<string>
default:global

global (runs about nothing in particular) or account

Available options:
global,
account
description
string | null

What the agent is for, shown in the Agents tab

Maximum string length: 4000
knowledge_bases
string[]

The knowledge bases it searches, by id from GET /v1/knowledge_bases

Maximum array length: 100
Required string length: 1 - 255
max_tool_calls
integer
default:60

The most tool calls it makes in one run

Required range: 1 <= x <= 200
reasoning
enum<string>
default:auto

How much it reasons before it answers

Available options:
auto,
low,
medium,
high
skills
string[]

The skills it may load, by key from GET /v1/skills

Maximum array length: 100
Required string length: 1 - 255
status
enum<string>
default:active

active, or draft to keep it out of use

Available options:
active,
draft
tools
ToolkitIn · object[]

The toolkits it may use

Maximum array length: 50

Response

201 - application/json

Successful Response

context
enum<string>
required

global (runs about nothing in particular) or account (runs about one account)

Available options:
global,
account
created_at
string | null
required

ISO 8601 UTC

created_by
string | null
required

The user who built it, an id from GET /v1/objects/user/records; null for a Statisfy agent, or a user who is gone

customized
boolean
required

Whether this workspace changed a Statisfy agent from its defaults; false for a workspace's own

description
string | null
required
id
string
required
instructions
string
required

What the agent is told to do

knowledge_bases
string[]
required

The knowledge bases it searches, by id. Those it shares are in GET /v1/knowledge_bases; one holding its own uploaded files is not

max_tool_calls
integer
required

The most tool calls it makes in one run

name
string
required
reasoning
enum<string>
required

How much it reasons before it answers

Available options:
auto,
low,
medium,
high
skills
string[]
required

The skills it may load, by key from GET /v1/skills

source
enum<string>
required

statisfy (shipped by Statisfy, in the app's Statisfy Library) or workspace (built by this workspace)

Available options:
statisfy,
workspace
status
enum<string>
required

active, draft or archived

Available options:
draft,
active,
archived
tools
AgentToolkit · object[]
required
updated_at
string | null
required

ISO 8601 UTC