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

# Create registration

> Creates a registration with boundary, webhook and filters.



## OpenAPI

````yaml /open-api/en/geo-alarm_version-1.json post /v1/alarms/geometries/register
openapi: 3.1.0
info:
  title: OpenAPI definition
  version: v0
servers:
  - url: https://api.iklim.co
    description: Production server
  - url: https://api-test.iklim.co
    description: Test server
security: []
tags:
  - name: Geo Alarm Registrations
    description: CRUD & lookup endpoints for geo-based alarm registrations
paths:
  /v1/alarms/geometries/register:
    post:
      tags:
        - Geo Alarm Registrations
      summary: Create registration
      description: Creates a registration with boundary, webhook and filters.
      operationId: register
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeoRegistration'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/RegistrationResponse'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
components:
  schemas:
    GeoRegistration:
      type: object
      description: Registration payload (boundary, webhook, and filters)
      properties:
        registrationId:
          type: string
          format: uuid
          description: Registration UUID
          example: f7587d9e-2481-4b4c-818d-c8d1946851b7
        recipientId:
          type: string
          description: >-
            Recipient identifier. The recipient ID must be unique and comply
            with the US-ASCII character set.
          example: Recipient 1
        boundary:
          $ref: '#/components/schemas/BoundarySchemaWrapper'
        webhook:
          $ref: '#/components/schemas/Webhook'
          description: Webhook configuration
        filter:
          $ref: '#/components/schemas/GeoFilter'
          description: Alarm filters
    RegistrationResponse:
      type: object
      description: Registration response (timestamps and warnings)
      properties:
        registrationId:
          type: string
          format: uuid
          description: Registration UUID
          example: f7587d9e-2481-4b4c-818d-c8d1946851b7
        recipientId:
          type: string
          description: >-
            Recipient identifier. The recipient ID must be unique and comply
            with the US-ASCII character set.
          example: Recipient 1
        boundary:
          $ref: '#/components/schemas/BoundarySchemaWrapper'
        webhook:
          $ref: '#/components/schemas/Webhook'
          description: Webhook configuration
        filter:
          $ref: '#/components/schemas/GeoFilter'
          description: Alarm filters
        createdAt:
          type: string
          format: date-time
          description: Creation time
          example: '2025-01-01T10:15:30Z'
        updatedAt:
          type: string
          format: date-time
          description: Last update time
          example: '2025-01-01T11:15:30Z'
        warnings:
          type: array
          description: Warnings
          example:
            - warning-1
            - warning-2
          items:
            type: string
    StandardErrorResponse:
      type: object
      description: Standard API error response structure
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the error occurred
          example: YYYY-mm-DDTHH:MM:SS.nnnnnnnnn
        status:
          type: integer
          format: int32
          description: HTTP status code
          example: XXX
        error:
          type: string
          description: Error name or type
          example: Error Name
          minLength: 1
        message:
          type: string
          description: Main error message
          example: Error Message
          minLength: 1
        messages:
          type: array
          description: Additional detailed error messages
          items:
            type: string
        path:
          type: string
          description: Request path that caused the error
          example: /endpoint/uri/here
          minLength: 1
      required:
        - error
        - message
        - path
        - status
        - timestamp
    BoundarySchemaWrapper:
      description: >-
        <section><h3>Alarm registration boundary</h3><p>Defines the geographic
        scope to monitor for alarm conditions. The concrete boundary type is
        selected via the <code>type</code> discriminator field; supply only the
        fields that belong to the chosen
        subtype.</p><ul><li><strong>ADMINISTRATIVE</strong> – boundary
        identified by city (<code>cityId</code>), district
        (<code>districtId</code>), and optionally neighborhood
        (<code>neighborhoodId</code>).</li><li><strong>POLYGON</strong> –
        arbitrary closed polygon defined by a list of exterior ring coordinates
        (WGS84).</li><li><strong>H3INDEX</strong> – boundary defined by a single
        Uber H3 cell address.</li></ul></section>
      discriminator:
        propertyName: type
        mapping:
          ADMINISTRATIVE:
            $ref: '#/components/schemas/RegisterAdministrativeBoundary'
          POLYGON:
            $ref: '#/components/schemas/RegisterPolygonBoundary'
          H3INDEX:
            $ref: '#/components/schemas/RegisterH3IndexBoundary'
      oneOf:
        - $ref: '#/components/schemas/RegisterAdministrativeBoundary'
        - $ref: '#/components/schemas/RegisterPolygonBoundary'
        - $ref: '#/components/schemas/RegisterH3IndexBoundary'
    Webhook:
      type: object
      description: >-
        <section><h3>Outbound callback configuration for alarm
        notifications</h3><p>When the first alarm record is created for a user
        account, the webhook information provided in the request is stored and
        associated with that account. Only one webhook can be defined per
        account. This association is not related to <em>recipientId</em>; it is
        directly tied to the account of the user logged into the service. If the
        webhook needs to be modified, the <code>update</code> service must be
        used.</p><p>For subsequent alarm records, sending the webhook
        information again is not required. In such cases, the previously defined
        webhook for the requesting user’s account is used automatically. The
        <code>accountId</code> field within the webhook object is optional; if
        provided, the webhook of the corresponding account is applied, and if
        omitted, the default webhook of the requesting user’s account is
        used.</p><p>Users with the <code>POWER_USER</code> or <code>ADMIN</code>
        role may create alarm records on behalf of another account by specifying
        that account’s <code>accountId</code>. This is only possible if the
        target account already has at least one existing alarm record—and
        therefore a webhook—registered in the system. If no webhook exists for
        the target account, it must be created first.</p></section>
      properties:
        accountId:
          type: string
          format: uuid
          description: >-
            Account UUID owning this webhook (optional; defaults to caller
            account).
          example: 2f04f1b5-1c0a-4c4e-b0a7-0ba6e9b7f2e1
        url:
          type: string
          description: Destination HTTPS endpoint to receive callbacks.
          example: https://api.customer.com/alerts/callback
        httpMethod:
          type: string
          description: HTTP method to use when delivering payloads.
          enum:
            - POST
            - PUT
            - GET
          example: POST
        contentType:
          type: string
          description: Content type of the delivered payload.
          example: application/json
        authentication:
          $ref: '#/components/schemas/AuthWrapper'
          description: Authentication settings for securing deliveries.
        requestHeaders:
          $ref: '#/components/schemas/MapTypeSchema'
          description: >-
            Custom HTTP headers to include with every webhook delivery request.
            Format: {"Header-Name":"value","Another-Header":"value"}
          example:
            source: iklim.co
            custom-header: value
        deliveryPolicy:
          $ref: '#/components/schemas/DeliveryPolicy'
          description: Delivery policy (timeouts & retries).
    GeoFilter:
      type: object
      description: swagger.schema.filter
      properties:
        lightning:
          $ref: '#/components/schemas/LightningFilter'
          description: Lightning Filter
        thunderstorm:
          $ref: '#/components/schemas/ThunderstormFilter'
          description: Thunderstorm filter
        precipitation:
          $ref: '#/components/schemas/PrecipitationFilter'
          description: Precipitation filter
    RegisterAdministrativeBoundary:
      type: object
      description: Administrative boundary (city/district/neighbourhood)
      properties:
        type:
          type: string
          enum:
            - ADMINISTRATIVE
            - POLYGON
            - H3INDEX
          writeOnly: true
        cityId:
          type: integer
          format: int64
          description: City ID
          example: 6
        districtId:
          type: integer
          format: int64
          description: District ID
          example: 557
        neighborhoodId:
          type: integer
          format: int64
          description: Neighbourhood ID
          example: 55766
      required:
        - cityId
    RegisterPolygonBoundary:
      type: object
      description: swagger.schema.boundary.polygon
      properties:
        type:
          type: string
          enum:
            - ADMINISTRATIVE
            - POLYGON
            - H3INDEX
          writeOnly: true
        polygon:
          $ref: '#/components/schemas/GeoPolygon'
          description: GeoPolygon object (WGS84)
    RegisterH3IndexBoundary:
      type: object
      description: swagger.schema.boundary.h3
      properties:
        type:
          type: string
          enum:
            - ADMINISTRATIVE
            - POLYGON
            - H3INDEX
          writeOnly: true
        h3Address:
          type: string
          description: Unique H3 address. Represented as hexadecimal string.
          example: 8928308280fffff
    AuthWrapper:
      description: Authentication envelope with discriminator field "type".
      discriminator:
        propertyName: type
        mapping:
          BASIC:
            $ref: '#/components/schemas/BasicAuthentication'
          JWT_TOKEN:
            $ref: '#/components/schemas/JwtAuthentication'
          API_KEY:
            $ref: '#/components/schemas/ApiKeyAuthentication'
          HMAC_SIGNATURE:
            $ref: '#/components/schemas/HmacAuthentication'
      oneOf:
        - $ref: '#/components/schemas/BasicAuthentication'
        - $ref: '#/components/schemas/JwtAuthentication'
        - $ref: '#/components/schemas/ApiKeyAuthentication'
        - $ref: '#/components/schemas/HmacAuthentication'
    MapTypeSchema:
      type: object
      example:
        key-1: value-1
        key-2: value-2
      properties:
        key:
          type: string
          example: key-1
        value:
          type: string
          example: value-1
    DeliveryPolicy:
      type: object
      description: Delivery timeout and retry behavior.
      properties:
        timeout:
          type: integer
          format: int64
          description: Request timeout in seconds.
          example: 60
        maxRetries:
          type: integer
          format: int32
          description: Maximum number of retry attempts.
          example: 3
        retryDelay:
          type: integer
          format: int32
          description: Delay between retries in seconds.
          example: 10
    LightningFilter:
      type: object
      description: Lightning event filter
      properties:
        type:
          type: string
          description: Lightning event type
          enum:
            - FLASH_CLOUD_TO_GROUND
            - PULSE_IN_CLOUD
          example: FLASH_CLOUD_TO_GROUND
        peakCurrent:
          type: number
          format: double
          description: Peak current (Amp, negative for CG strikes typical)
          example: -12.5
        inCloudHeight:
          type: number
          format: double
          description: In-cloud discharge height (meters)
          example: 4500
    ThunderstormFilter:
      type: object
      description: Thunderstorm event filter
      properties:
        intersectsAffectedPolygon:
          type: boolean
          description: Event affected area polygon must intersect registered polygon
          example: true
        intersectsCellPolygon:
          type: boolean
          description: Event cell polygon must intersect registered polygon
          example: false
        severityThreshold:
          type: string
          description: Minimum severity threshold to trigger
          enum:
            - LOW
            - MEDIUM
            - HIGH
          example: MEDIUM
        speedThreshold:
          type: number
          format: double
          description: Minimum storm speed (km/h)
          example: 20
    PrecipitationFilter:
      type: object
      description: Precipitation event filter
      properties:
        intensities:
          type: array
          description: Allowed precipitation intensities
          example:
            - LIGHT
            - MODERATE
          items:
            type: string
            enum:
              - DRIZZLE
              - LIGHT
              - MODERATE
              - HEAVY
              - VERY_HEAVY
              - EXTREME
    GeoPolygon:
      type: object
      properties:
        exterior:
          type: array
          description: The exterior ring of the polygon, defined by a list of GeoPoints.
          example:
            - lng: 32.85
              lat: 39.93
            - lng: 32.86
              lat: 39.93
            - lng: 32.86
              lat: 39.94
            - lng: 32.85
              lat: 39.94
            - lng: 32.85
              lat: 39.93
          items:
            $ref: '#/components/schemas/GeoPoint'
        holes:
          type: array
          description: >-
            A list of interior rings (holes). Each hole is defined by its own
            list of GeoPoints. Can be null or empty if there are no holes.
          example:
            - - lng: 32.852
                lat: 39.932
              - lng: 32.853
                lat: 39.932
              - lng: 32.853
                lat: 39.933
              - lng: 32.852
                lat: 39.933
              - lng: 32.852
                lat: 39.932
          items:
            type: array
            items:
              $ref: '#/components/schemas/GeoPoint'
      required:
        - exterior
    BasicAuthentication:
      type: object
      description: HTTP Basic authentication.
      properties:
        type:
          type: string
          description: Authentication type discriminator.
          enum:
            - BASIC
            - JWT_TOKEN
            - API_KEY
            - HMAC_SIGNATURE
          example: API_KEY
          writeOnly: true
        username:
          type: string
          description: Username for Basic auth.
          example: alert-user
        password:
          type: string
          description: Password for Basic auth.
          example: '******'
    JwtAuthentication:
      type: object
      description: Bearer JWT token authentication.
      properties:
        type:
          type: string
          description: Authentication type discriminator.
          enum:
            - BASIC
            - JWT_TOKEN
            - API_KEY
            - HMAC_SIGNATURE
          example: API_KEY
          writeOnly: true
        jwtToken:
          type: string
          description: Pre-issued JWT token to include as Authorization header.
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....
    ApiKeyAuthentication:
      type: object
      description: API key authentication (header and/or query).
      properties:
        type:
          type: string
          description: Authentication type discriminator.
          enum:
            - BASIC
            - JWT_TOKEN
            - API_KEY
            - HMAC_SIGNATURE
          example: API_KEY
          writeOnly: true
        apiKey:
          type: string
          description: API key value to send with request.
          example: x-1234567890abcdef
        asQueryParameter:
          type: boolean
          description: If true, send API key as query parameter.
          example: false
        asHeader:
          type: boolean
          description: If true, send API key as request header.
          example: true
    HmacAuthentication:
      type: object
      description: HMAC signature authentication with clientId/secret.
      properties:
        type:
          type: string
          description: Authentication type discriminator.
          enum:
            - BASIC
            - JWT_TOKEN
            - API_KEY
            - HMAC_SIGNATURE
          example: API_KEY
          writeOnly: true
        clientId:
          type: string
          description: Client identifier used in signature preimage.
          example: bem-portal
        secret:
          type: string
          description: Shared secret used to compute HMAC.
          example: '******'
        algorithm:
          type: string
          description: HMAC algorithm to use.
          enum:
            - HmacSHA1
            - HmacSHA256
            - HmacSHA384
            - HmacSHA512
            - HmacMD5
          example: HmacSHA256
    GeoPoint:
      type: object
      properties:
        lng:
          type: number
          format: double
          description: Longitude coordinate.
          example: 32.857358
          maximum: 180
          minimum: -180
        lat:
          type: number
          format: double
          description: Latitude coordinate.
          example: 39.93504
          maximum: 90
          minimum: -90
      required:
        - lat
        - lng

````