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

# Create a new agent



## OpenAPI

````yaml /api-reference/openapi.json post /v2/agents
openapi: 3.1.0
info:
  title: Base39 API
  description: Base39 API
  version: 1.0.0
  contact:
    name: Base39 Team
    url: https://base39.com.br
    email: suporte@base39.com.br
  termsOfService: https://base39.com.br/termos
  license:
    name: Proprietary
    url: https://base39.com.br/termos
servers:
  - url: http://localhost:3000
    description: Local
  - url: https://api.dev.base39.cloud
    description: Development
  - url: https://api.base39.com.br
    description: Production
security:
  - OAuth2: []
tags:
  - name: pages
    description: Profiles and reports pages
  - name: pipelines
    description: Pipeline boards (kanban) of pages
  - name: blocks
    description: Blocks operations
  - name: search
    description: Search across content
  - name: targets
    description: Lookup targets via datasets
  - name: CognitoTriggers
    description: Cognito triggers
paths:
  /v2/agents:
    post:
      tags:
        - agents
      summary: Create a new agent
      operationId: agent_create
      parameters:
        - name: global
          required: false
          in: query
          description: Create as global agent (requires super scope)
          schema:
            type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgent'
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          description: Invalid request body or slug already exists
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Requires admin or editor role (super for global)
components:
  schemas:
    CreateAgent:
      type: object
      properties:
        name:
          type: string
          description: Agent name
          maxLength: 255
        slug:
          type: string
          description: URL-safe slug
          maxLength: 255
        description:
          type: string
          nullable: true
        icon:
          type: object
          nullable: true
        status:
          type: string
          enum:
            - available
            - draft
            - native
            - internal
          default: available
        target_type:
          type: string
          description: |-
            Target entity type (optional)
            Defines which entity type this agent is designed for
            Examples: 'company', 'company_group', 'person', 'lawsuit'
          enum:
            - company
            - company_group
            - person
            - lawsuit
        format:
          type: string
          description: Agent format
          enum:
            - markdown
            - pptx
            - docx
          default: markdown
        source_file_id:
          type: string
          description: File upload ID for the source agent file (required for pptx/docx)
          example: file_abc123
        pptx_metadata:
          description: PPTX presentation metadata (for pptx format agents)
          allOf:
            - $ref: '#/components/schemas/PptxMetadata'
        model:
          type: string
          maxLength: 100
        instructions:
          type: string
          nullable: true
        execution_mode:
          type: string
          description: How page-run tasks are sent to the managed agent
          enum:
            - iterative
            - one_shot
          default: one_shot
        steps:
          type: array
          items:
            $ref: '#/components/schemas/AgentStepInput'
        evaluations:
          type: array
          items:
            $ref: '#/components/schemas/AgentStepEvaluationInput'
        skills_mode:
          type: string
          description: >-
            auto grants every skill visible to the org; custom uses skill_ids;
            disabled grants none
          enum:
            - auto
            - custom
            - disabled
        skill_ids:
          maxItems: 20
          type: array
          items:
            type: string
        tools_mode:
          type: string
          description: >-
            auto grants every published custom tool of the org; custom uses
            custom_tool_ids; disabled grants none
          enum:
            - auto
            - custom
            - disabled
        custom_tool_ids:
          maxItems: 20
          type: array
          items:
            type: string
        subagent_ids:
          maxItems: 20
          description: Subagent IDs this agent coordinates as a multiagent
          type: array
          items:
            type: string
        tool_configs:
          maxItems: 128
          type: array
          items:
            $ref: '#/components/schemas/AgentToolConfigInput'
        mcp_servers:
          maxItems: 20
          type: array
          items:
            $ref: '#/components/schemas/AgentMcpServerConfigInput'
        web_access:
          $ref: '#/components/schemas/AgentWebAccessInput'
      required:
        - name
        - slug
    Agent:
      type: object
      properties:
        object:
          type: string
          example: page
          description: Object type
          title: Object
          x-locale-pt-br-title: Objeto
        id:
          type: string
          example: p_abc123
          description: Unique identifier
          title: ID
          x-locale-pt-br-title: ID
        createdAt:
          format: date-time
          type: string
          example: '2024-01-15T10:30:00.000Z'
          description: Creation timestamp
          title: Created at
          x-locale-pt-br-title: Criado em
        updatedAt:
          format: date-time
          type: string
          example: '2024-01-15T14:45:00.000Z'
          description: Last update timestamp
          title: Updated at
          x-locale-pt-br-title: Atualizado em
        createdBy:
          type: object
          example:
            object: user
            id: u_abc123
            apiKeyId: bsk_abc123
          description: Principal who created this object
          properties:
            object:
              type: string
              enum:
                - user
                - service_account
              example: user
            id:
              type: string
              example: u_abc123
            apiKeyId:
              type: string
              example: bsk_abc123
          title: Created by
          x-locale-pt-br-title: Criado por
        updatedBy:
          type: object
          example:
            object: user
            id: u_abc123
            apiKeyId: bsk_abc123
          description: Principal who last updated this object
          properties:
            object:
              type: string
              enum:
                - user
                - service_account
                - webhook
                - stream
              example: user
            id:
              type: string
              example: u_abc123
            apiKeyId:
              type: string
              example: bsk_abc123
          title: Updated by
          x-locale-pt-br-title: Atualizado por
        name:
          type: string
          description: Agent name
          example: Project Management Agent
        slug:
          type: string
          description: URL-friendly slug
          example: project-management
        description:
          type: string
          description: Agent description
          example: Manage projects with Kanban boards
          nullable: true
        icon:
          description: Agent icon
          nullable: true
          allOf:
            - $ref: '#/components/schemas/IconOutput'
        status:
          type: string
          description: Agent publication status
          enum:
            - available
            - draft
            - native
            - internal
        target_type:
          type: string
          description: Target entity type
          example: company
          nullable: true
        format:
          type: string
          description: Agent format
          enum:
            - markdown
            - pptx
            - docx
          nullable: true
        source_file_id:
          type: string
          description: Source file upload ID (for pptx/docx agents)
          nullable: true
        pptx_metadata:
          description: PPTX presentation metadata (for pptx agents)
          nullable: true
          allOf:
            - $ref: '#/components/schemas/PptxMetadata'
        has_steps:
          type: boolean
          description: Whether the agent has configured steps
          default: false
        steps:
          type: array
          items:
            $ref: '#/components/schemas/AgentStepInput'
        evaluations:
          type: array
          items:
            $ref: '#/components/schemas/AgentStepEvaluationInput'
        execution_mode:
          type: string
          enum:
            - iterative
            - one_shot
          default: one_shot
        versions:
          type: array
          description: Version history for PPTX agent analyses
          items:
            type: object
            properties:
              name:
                type: string
                description: Version identifier (ISO timestamp)
              fileId:
                type: string
                description: Reference to source file
              createdAt:
                type: string
                description: When this version was created
          default: []
        current_version:
          type: string
          description: Currently active version (ISO timestamp)
          nullable: true
        orgId:
          type: string
          description: Organization ID
          example: org_123
        datasets:
          type: array
          description: Distinct dataset slugs used across all steps of this agent
          items:
            type: string
          example:
            - empresas
            - pessoas
        sync_at:
          type: string
          description: Last successful managed sync timestamp
          nullable: true
        sync_status:
          type: string
          description: Managed sync status
          enum:
            - pending
            - preparing
            - ready
            - error
        sync_error:
          type: string
          description: Last managed sync error
          nullable: true
        skills_mode:
          type: string
          description: >-
            auto grants every skill visible to the org; custom uses skill_ids;
            disabled grants none
          enum:
            - auto
            - custom
            - disabled
        skill_ids:
          type: array
          description: Skill IDs enabled for this agent
          items:
            type: string
        instructions:
          type: string
          nullable: true
        tools_mode:
          type: string
          description: >-
            auto grants every published custom tool of the org; custom uses
            custom_tool_ids; disabled grants none
          enum:
            - auto
            - custom
            - disabled
        custom_tool_ids:
          type: array
          description: Custom tool IDs enabled for this agent
          items:
            type: string
        subagent_ids:
          type: array
          description: Subagent IDs this agent coordinates as a multiagent
          items:
            type: string
        knowledge_file_ids:
          type: array
          description: File upload IDs that make up this agent knowledge base
          items:
            type: string
        web_access:
          $ref: '#/components/schemas/AgentWebAccessInput'
        tool_configs:
          description: Built-in tool permissions
          type: array
          items:
            $ref: '#/components/schemas/AgentToolConfigInput'
        mcp_servers:
          description: MCP servers wired to this agent
          type: array
          items:
            $ref: '#/components/schemas/AgentMcpServerConfigInput'
      required:
        - object
        - id
        - createdAt
        - updatedAt
        - name
        - slug
        - status
        - steps
        - evaluations
        - execution_mode
        - orgId
        - sync_status
        - web_access
        - tool_configs
        - mcp_servers
    PptxMetadata:
      type: object
      properties:
        slideWidth:
          type: number
          description: Slide width in EMUs
        slideHeight:
          type: number
          description: Slide height in EMUs
        slideCount:
          type: number
          description: Total number of slides
        title:
          type: string
          description: Presentation title
        author:
          type: string
          description: Presentation author
      required:
        - slideWidth
        - slideHeight
        - slideCount
    AgentStepInput:
      type: object
      properties:
        id:
          type: string
          description: Stable step ID. Generated by the server when omitted.
        type:
          type: string
          enum:
            - audio
            - bookmark
            - breadcrumb
            - bulleted_list_item
            - callout
            - chart_area
            - chart_bar
            - chart_line
            - chart_pie
            - child_database
            - child_page
            - code
            - markdown
            - column
            - column_list
            - data_view
            - divider
            - embed
            - equation
            - file
            - flex
            - graph_visualization
            - heading_1
            - heading_2
            - heading_3
            - heatmap
            - image
            - inline_database_block
            - link_preview
            - map
            - mention
            - numbered_list_item
            - paragraph
            - pdf
            - quote
            - synced_block
            - tab
            - table
            - table_of_contents
            - table_row
            - tabs
            - agent
            - to_do
            - toggle
            - video
            - slide
        order:
          type: number
          minimum: 1
        content:
          type: object
          description: Type-specific step content
        outputExample:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
        structuredOutput:
          $ref: '#/components/schemas/OpenAIJsonSchemaFormat'
        agentFileId:
          type: string
          nullable: true
        previewFileId:
          type: string
          nullable: true
        version:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        instructions:
          type: string
          description: Task sent to the agent
          nullable: true
        evaluations:
          default: []
          type: array
          items:
            $ref: '#/components/schemas/AgentStepEvaluationInput'
        promptId:
          type: string
          nullable: true
      required:
        - type
        - order
        - evaluations
    AgentStepEvaluationInput:
      type: object
      properties:
        type:
          type: string
          enum:
            - outcome
        rubric:
          type: string
          description: Criteria used to validate the task result
        maxIterations:
          type: number
          description: >-
            Correction attempts the evaluator may request before delivering the
            result
          minimum: 1
          maximum: 20
      required:
        - type
        - rubric
    AgentToolConfigInput:
      type: object
      properties:
        name:
          type: string
          enum:
            - bash
            - edit
            - read
            - write
            - glob
            - grep
            - web_fetch
            - web_search
        enabled:
          type: boolean
        permission_policy:
          type: string
          enum:
            - always_allow
            - always_ask
      required:
        - name
        - enabled
        - permission_policy
    AgentMcpServerConfigInput:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
        connection_account_id:
          type: string
        enabled:
          type: boolean
        permission_policy:
          type: string
          enum:
            - always_allow
            - always_ask
        tools:
          type: array
          items:
            $ref: '#/components/schemas/AgentMcpToolConfigInput'
      required:
        - name
        - url
        - enabled
        - permission_policy
        - tools
    AgentWebAccessInput:
      type: object
      properties:
        enabled:
          type: boolean
        allowedHosts:
          type: array
          items:
            type: string
        allowEveryUrl:
          type: boolean
      required:
        - enabled
        - allowedHosts
        - allowEveryUrl
    IconOutput:
      type: object
      properties:
        type:
          type: string
          enum:
            - emoji
            - external
            - file_upload
            - domain
            - file
            - lucide
            - dicebear
            - brand
        emoji:
          type: string
          example: page_icon
        external:
          $ref: '#/components/schemas/ExternalFileOutput'
        file_upload:
          $ref: '#/components/schemas/FileUploadOutput'
        domain:
          type: string
          example: acme.com
        file:
          $ref: '#/components/schemas/InternalFileOutput'
        lucide:
          type: string
          example: file-text
        brand:
          type: string
          example: github
          description: Simple Icons brand slug (logo and color resolved automatically)
        dicebear:
          $ref: '#/components/schemas/DicebearIconPayloadOutput'
        background:
          type: string
          enum:
            - blue
            - red
            - pattern-red
            - pattern-blue
            - pattern-red-1
            - pattern-red-2
            - pattern-red-3
            - pattern-blue-1
            - pattern-blue-2
            - pattern-blue-3
        empty:
          type: boolean
          example: true
        updatedBy:
          type: string
          example: dataset:empresas
    OpenAIJsonSchemaFormat:
      type: object
      properties:
        type:
          type: string
          enum:
            - json_schema
        name:
          type: string
          description: Schema name used by OpenAI Structured Outputs
        description:
          type: string
          description: Optional schema description used by the model
        strict:
          type: boolean
          description: Whether strict schema adherence is enabled
        schema:
          type: object
          description: JSON Schema object
          additionalProperties: true
      required:
        - type
        - name
        - schema
    AgentMcpToolConfigInput:
      type: object
      properties:
        name:
          type: string
        enabled:
          type: boolean
        permission_policy:
          type: string
          enum:
            - always_allow
            - always_ask
      required:
        - name
        - enabled
        - permission_policy
    ExternalFileOutput:
      type: object
      properties:
        url:
          type: string
          example: https://example.com/image.jpg
      required:
        - url
    FileUploadOutput:
      type: object
      properties:
        id:
          type: string
          example: fu_abc123
      required:
        - id
    InternalFileOutput:
      type: object
      properties:
        url:
          type: string
          example: https://s3.amazonaws.com/...
        expiryTime:
          type: string
          example: '2024-01-15T10:30:00.000Z'
      required:
        - url
        - expiryTime
    DicebearIconPayloadOutput:
      type: object
      properties:
        style:
          type: string
          enum:
            - notionists-neutral
        seed:
          type: string
          example: 0256de50-f90c-49a8-81f0-3988b2b89d8d
        backgroundColor:
          type: string
          example: b6e3f4,b6e3f4
          description: Hex color(s), comma-separated for gradients
        options:
          $ref: '#/components/schemas/DicebearIconOptionsOutput'
      required:
        - style
        - seed
        - backgroundColor
    DicebearIconOptionsOutput:
      type: object
      properties:
        brows:
          type: string
        eyes:
          type: string
        glasses:
          type: string
        lips:
          type: string
        nose:
          type: string
        flip:
          type: boolean
        rotate:
          type: number
        scale:
          type: number
        radius:
          type: number
        size:
          type: number
        backgroundType:
          type: string
          enum:
            - solid
            - gradientLinear
        backgroundRotation:
          type: array
          items:
            type: number
        translateX:
          type: number
        translateY:
          type: number
        clip:
          type: boolean
        randomizeIds:
          type: boolean
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://id.local.base39.cloud/oauth2/authorize
          tokenUrl: https://id.local.base39.cloud/oauth2/token
          scopes:
            profile: Read user profile
            email: Read user email
            openid: OpenID authentication
      description: OAuth2 Authorization Code flow

````