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

# Register a new action

> Register a new action with Flowent. The action's webhook URL will be validated with a test request during registration.



## OpenAPI

````yaml api-reference/openapi.json post /actions
openapi: 3.1.0
info:
  title: Flowent API Gateway
  description: >-
    The Flowent API Gateway enables external developers to register and manage
    custom actions that can be used within Flowent's conversational flows. This
    API provides secure, tenant-specific extensibility for the Flowent platform.


    ## Authentication


    1. Obtain an API token from the Flowent admin panel

    2. Exchange the API token for a JWT token using the `/token/exchange`
    endpoint

    3. Use the JWT token as a Bearer token in the Authorization header for all
    requests


    ## Security


    All webhook calls are secured with HMAC-SHA256 signatures using
    tenant-specific keys.
  version: 1.0.0
  contact:
    name: Flowent API Support
    url: https://flowent.chat/support
    email: contact@flowent.chat
servers:
  - url: https://api.flowent.chat/api/v1/gateway
    description: Production server
  - url: https://staging-api.flowent.chat/api/v1/gateway
    description: Staging server
  - url: http://localhost:8080/api/v1/gateway
    description: Local development server
security: []
tags:
  - name: Authentication
    description: Token exchange and authentication operations
  - name: Actions
    description: Action registration and management operations
paths:
  /actions:
    post:
      tags:
        - Actions
      summary: Register a new action
      description: >-
        Register a new action with Flowent. The action's webhook URL will be
        validated with a test request during registration.
      operationId: createAction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionCreateRequest'
      responses:
        '201':
          description: Action created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  action:
                    $ref: '#/components/schemas/Action'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '409':
          description: Action name already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: action with name 'send_email' already exists
      security:
        - BearerAuth: []
components:
  schemas:
    ActionCreateRequest:
      type: object
      required:
        - name
        - description
        - webhook_url
        - json_schema
      properties:
        name:
          type: string
          pattern: ^[a-z0-9_]+$
          minLength: 1
          maxLength: 100
          description: Action name (lowercase, underscores, no spaces)
          example: send_email
        description:
          type: string
          minLength: 1
          maxLength: 500
          description: Human-readable description of the action
          example: Send an email to a specified recipient
        webhook_url:
          type: string
          format: uri
          description: URL where the action will be executed (must be HTTPS in production)
          example: https://your-server.com/actions/send_email
        json_schema:
          type: object
          description: JSON Schema defining the action's parameters
          example:
            type: object
            properties:
              recipient:
                type: string
                description: Email address of the recipient
              subject:
                type: string
                description: Email subject line
              body:
                type: string
                description: Email body content
            required:
              - recipient
              - subject
              - body
    Action:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique action identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        tenant_id:
          type: string
          format: uuid
          description: Tenant identifier
          example: 123e4567-e89b-12d3-a456-426614174001
        name:
          type: string
          pattern: ^[a-z0-9_]+$
          description: Action name (lowercase, underscores, no spaces)
          example: send_email
        description:
          type: string
          description: Human-readable description of the action
          example: Send an email to a specified recipient
        json_schema:
          type: object
          description: JSON Schema defining the action's parameters
          example:
            type: object
            properties:
              recipient:
                type: string
                description: Email address of the recipient
              subject:
                type: string
                description: Email subject line
              body:
                type: string
                description: Email body content
            required:
              - recipient
              - subject
              - body
        webhook_url:
          type: string
          format: uri
          description: URL where the action will be executed
          example: https://your-server.com/actions/send_email
        created_at:
          type: string
          format: date-time
          description: When the action was created
          example: '2023-01-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: When the action was last updated
          example: '2023-01-01T12:00:00Z'
  responses:
    BadRequestError:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Invalid request format
              details:
                type: string
                example: Field 'name' is required
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Invalid token
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from token exchange

````