> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an agent

> Creates a workspace agent from its name and instructions, with the toolkits, skills and knowledge bases it may use. It is active unless `status=draft`. Needs agent_studio:write; a digital worker's own key can't. Answers with the agent as GET /v1/agents/{agent_id} shows it. Skills, toolkits, tools and knowledge bases are checked: one the workspace can't use is a 422. An agent is a custom agent from Agent Studio's Agents tab: instructions it follows, and the toolkits, skills and knowledge bases it may use. `source` says whether Statisfy ships it or the workspace built it.



## OpenAPI

````yaml /api/statisfy-api.openapi.json post /v1/agents
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/agents:
    post:
      tags:
        - agents
      summary: Create an agent
      description: >-
        Creates a workspace agent from its name and instructions, with the
        toolkits, skills and knowledge bases it may use. It is active unless
        `status=draft`. Needs agent_studio:write; a digital worker's own key
        can't. Answers with the agent as GET /v1/agents/{agent_id} shows it.
        Skills, toolkits, tools and knowledge bases are checked: one the
        workspace can't use is a 422. An agent is a custom agent from Agent
        Studio's Agents tab: instructions it follows, and the toolkits, skills
        and knowledge bases it may use. `source` says whether Statisfy ships it
        or the workspace built it.
      operationId: agents_create
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                context:
                  default: global
                  description: global (runs about nothing in particular) or account
                  enum:
                    - global
                    - account
                  title: Context
                  type: string
                description:
                  anyOf:
                    - maxLength: 4000
                      type: string
                    - type: 'null'
                  default: null
                  description: What the agent is for, shown in the Agents tab
                  title: Description
                instructions:
                  description: What the agent is told to do
                  maxLength: 100000
                  minLength: 1
                  title: Instructions
                  type: string
                knowledge_bases:
                  description: >-
                    The knowledge bases it searches, by id from GET
                    /v1/knowledge_bases
                  items:
                    maxLength: 255
                    minLength: 1
                    type: string
                  maxItems: 100
                  title: Knowledge Bases
                  type: array
                max_tool_calls:
                  default: 60
                  description: The most tool calls it makes in one run
                  maximum: 200
                  minimum: 1
                  title: Max Tool Calls
                  type: integer
                name:
                  maxLength: 255
                  minLength: 1
                  title: Name
                  type: string
                reasoning:
                  default: auto
                  description: How much it reasons before it answers
                  enum:
                    - auto
                    - low
                    - medium
                    - high
                  title: Reasoning
                  type: string
                skills:
                  description: The skills it may load, by key from GET /v1/skills
                  items:
                    maxLength: 255
                    minLength: 1
                    type: string
                  maxItems: 100
                  title: Skills
                  type: array
                status:
                  default: active
                  description: active, or draft to keep it out of use
                  enum:
                    - active
                    - draft
                  title: Status
                  type: string
                tools:
                  description: The toolkits it may use
                  items:
                    $ref: '#/components/schemas/ToolkitIn'
                  maxItems: 50
                  title: Tools
                  type: array
              required:
                - name
                - instructions
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDetail'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    ToolkitIn:
      additionalProperties: false
      properties:
        excluded:
          description: Tools it may not use
          items:
            maxLength: 255
            minLength: 1
            type: string
          maxItems: 100
          title: Excluded
          type: array
        guidance:
          anyOf:
            - maxLength: 4000
              type: string
            - type: 'null'
          default: null
          description: What it is told about when and how to use this toolkit
          title: Guidance
        toolkit:
          description: The toolkit's key, from GET /v1/agents/toolkits
          maxLength: 255
          minLength: 1
          title: Toolkit
          type: string
        tools:
          anyOf:
            - const: all
              type: string
            - items:
                maxLength: 255
                minLength: 1
                type: string
              maxItems: 100
              type: array
          default: all
          description: >-
            "all" (every tool, and those added later), or the names of the tools
            it may use
          title: Tools
      required:
        - toolkit
      title: ToolkitIn
      type: object
    AgentDetail:
      properties:
        context:
          description: >-
            global (runs about nothing in particular) or account (runs about one
            account)
          enum:
            - global
            - account
          title: Context
          type: string
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO 8601 UTC
          title: Created At
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The user who built it, an id from GET /v1/objects/user/records; null
            for a Statisfy agent, or a user who is gone
          title: Created By
        customized:
          description: >-
            Whether this workspace changed a Statisfy agent from its defaults;
            false for a workspace's own
          title: Customized
          type: boolean
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        id:
          title: Id
          type: string
        instructions:
          description: What the agent is told to do
          title: Instructions
          type: string
        knowledge_bases:
          description: >-
            The knowledge bases it searches, by id. Those it shares are in GET
            /v1/knowledge_bases; one holding its own uploaded files is not
          items:
            type: string
          title: Knowledge Bases
          type: array
        max_tool_calls:
          description: The most tool calls it makes in one run
          title: Max Tool Calls
          type: integer
        name:
          title: Name
          type: string
        reasoning:
          description: How much it reasons before it answers
          enum:
            - auto
            - low
            - medium
            - high
          title: Reasoning
          type: string
        skills:
          description: The skills it may load, by key from GET /v1/skills
          items:
            type: string
          title: Skills
          type: array
        source:
          description: >-
            statisfy (shipped by Statisfy, in the app's Statisfy Library) or
            workspace (built by this workspace)
          enum:
            - statisfy
            - workspace
          title: Source
          type: string
        status:
          description: active, draft or archived
          enum:
            - draft
            - active
            - archived
          title: Status
          type: string
        tools:
          items:
            $ref: '#/components/schemas/AgentToolkit'
          title: Tools
          type: array
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO 8601 UTC
          title: Updated At
      required:
        - id
        - name
        - description
        - status
        - source
        - customized
        - context
        - created_by
        - created_at
        - updated_at
        - instructions
        - reasoning
        - max_tool_calls
        - tools
        - skills
        - knowledge_bases
      title: AgentDetail
      type: object
    AgentToolkit:
      properties:
        excluded:
          description: Tools of the toolkit it may not use
          items:
            type: string
          title: Excluded
          type: array
        guidance:
          anyOf:
            - type: string
            - type: 'null'
          description: What it is told about when and how to use this toolkit
          title: Guidance
        toolkit:
          description: The toolkit's key, such as crm or slack
          title: Toolkit
          type: string
        tools:
          anyOf:
            - const: all
              type: string
            - items:
                type: string
              type: array
          description: '"all", or the names of the toolkit''s tools it may use'
          title: Tools
      required:
        - toolkit
        - tools
        - excluded
        - guidance
      title: AgentToolkit
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.