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

# Register event

> Register an event type for automations.



## OpenAPI

````yaml /en/automations-api/api-reference/openapi-automations.json post /v1/events
openapi: 3.0.3
info:
  title: 'Notifique API v1: Automations and events'
  version: 1.0.0
  description: >-
    Definition of **events** (name + optional `payload` schema), **automations**
    as a graph (trigger by event or **inbound message** on a channel, delays,
    conditions, including **`source: "message"`** on inbound, **`endFlow`** to
    end a branch, multi-channel sends, contact updates, etc.) and **trigger**
    via `POST /v1/events/send`. Auth: `Authorization: Bearer sk_live_...` or
    `x-api-key` header. All bodies use **camelCase**.


    **Scopes:** `events:read` | `events:write` | `automations:read` |
    `automations:write`. Send steps (`sendTemplate`, direct emails, etc.) still
    require the matching channel send keys.


    **Pagination:** query `page` (≥1, default 1) and `limit` (1 to 100, default
    20), as strings or coherent numbers.


    **Blocked workspace** returns **402** with `Payment Required`.


    **Onboarding:** on any `/v1` route, if onboarding is incomplete, middleware
    returns **403** with `code: ONBOARDING_REQUIRED` (body similar to other
    403s).
servers:
  - url: https://api.notifique.dev
    description: Production
security:
  - ntfAutoBearerAuth: []
  - ntfAutoApiKeyHeader: []
tags:
  - name: Eventos
    description: CRUD de definições de evento + disparo `POST /v1/events/send`.
  - name: Automações
    description: CRUD de automações, stop e listagem de runs.
  - name: Runs
    description: Histórico e detalhe de execuções (`AutomationRun` + passos).
paths:
  /v1/events:
    post:
      tags:
        - Eventos
      summary: Register event
      description: Register an event type for automations.
      operationId: ntfAuto_createEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NtfAuto_EventCreateBody'
      responses:
        '200':
          $ref: '#/components/responses/NtfAuto_EventCreate200'
        '400':
          $ref: '#/components/responses/NtfAuto_EventCreate400'
        '401':
          $ref: '#/components/responses/NtfAuto_401'
        '402':
          $ref: '#/components/responses/NtfAuto_402'
        '403':
          $ref: '#/components/responses/NtfAuto_403EventsWrite'
        '409':
          $ref: '#/components/responses/NtfAuto_EventNameConflict'
components:
  schemas:
    NtfAuto_EventCreateBody:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          example: user.created
        schemaJson:
          $ref: '#/components/schemas/NtfAuto_EventPayloadSchema'
    NtfAuto_EventPayloadSchema:
      type: object
      additionalProperties:
        type: string
        enum:
          - string
          - number
          - boolean
          - date
        description: '`date`: string ISO-8601 parseável no disparo.'
      description: 'Objeto plano: nome do campo → tipo esperado no `payload`.'
    NtfAuto_EventCreateResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: object
          required:
            - id
            - name
            - createdAt
          properties:
            id:
              type: string
            name:
              type: string
            createdAt:
              type: string
              format: date-time
    NtfAuto_ErrorWithOptionalCode:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
        message:
          type: string
        code:
          type: string
    NtfAuto_ErrorEnvelope401:
      type: object
      required:
        - success
        - error
        - message
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
          example: Unauthorized
        message:
          type: string
    NtfAuto_ErrorPaymentRequired:
      type: object
      required:
        - success
        - error
        - message
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
          enum:
            - Payment Required
        message:
          type: string
          example: Plan expired or suspended
    NtfAuto_ErrorForbiddenScope:
      type: object
      required:
        - success
        - error
        - message
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
          enum:
            - Forbidden
        message:
          type: string
    NtfAuto_ErrorConflict:
      type: object
      required:
        - success
        - error
        - message
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
          enum:
            - Conflict
        message:
          type: string
  responses:
    NtfAuto_EventCreate200:
      description: Evento criado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NtfAuto_EventCreateResponse'
    NtfAuto_EventCreate400:
      description: >-
        Nome inválido (`INVALID_EVENT_NAME`), prefixo `notifique:`, ou
        `schemaJson` inválido (`INVALID_EVENT_SCHEMA`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NtfAuto_ErrorWithOptionalCode'
          examples:
            invalidName:
              value:
                success: false
                error: Bad Request
                message: Invalid event name
                code: INVALID_EVENT_NAME
            invalidSchema:
              value:
                success: false
                error: schemaJson must be a flat object
                code: INVALID_EVENT_SCHEMA
                message: schemaJson must be a flat object
    NtfAuto_401:
      description: >-
        Chave ausente ou inválida. No middleware global de `/v1` também ocorre
        quando não há API Key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NtfAuto_ErrorEnvelope401'
          examples:
            route:
              value:
                success: false
                error: Unauthorized
                message: Invalid or missing API Key
                code: UNAUTHORIZED
            middleware:
              value:
                success: false
                error: Unauthorized
                message: >-
                  API Key is required. Provide Authorization: Bearer <key> or
                  x-api-key header.
                code: UNAUTHORIZED
    NtfAuto_402:
      description: Plano expirado ou workspace suspenso.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NtfAuto_ErrorPaymentRequired'
          example:
            success: false
            error: Payment Required
            message: Plan expired or suspended
            code: WORKSPACE_BLOCKED
    NtfAuto_403EventsWrite:
      description: Sem escopo `events:write`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NtfAuto_ErrorForbiddenScope'
          example:
            success: false
            error: Forbidden
            message: 'Missing scope: events:write'
            code: FORBIDDEN
    NtfAuto_EventNameConflict:
      description: Já existe evento com o mesmo nome no workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NtfAuto_ErrorConflict'
          example:
            success: false
            error: Conflict
            message: An event with this name already exists
            code: CONFLICT
  securitySchemes:
    ntfAutoBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: '`Authorization: Bearer sk_live_...`'
    ntfAutoApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Mesmo valor da chave, sem prefixo Bearer.

````