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

# Register a hook

> Register a hook from its flat parameters — an UPSERT, so this is the create
path AND the edit path for a hook of that name.

Supports conditional execution (via ``condition`` or ``condition_id``), payload
transformation (via ``expr`` or ``expr_id``), and dynamic tool arguments.
``execution_key`` is the api-key identity every fire runs as; the caller's authority
to delegate it and its usability by a tokenless fire are decided BEFORE the upsert, so
a refusal stores nothing and leaves any existing hook of that name untouched. Returns
``{"registered", "name"}``; ``registered`` is ``True`` for a create and a replace
alike.



## OpenAPI

````yaml /openapi.json post /api/hooks
openapi: 3.1.0
info:
  description: The operator HTTP surface served under /api/*.
  title: tai42-skeleton API
  version: 0.1.1
servers: []
security: []
paths:
  /api/hooks:
    post:
      tags:
        - hooks
      summary: Register a hook
      description: >-
        Register a hook from its flat parameters — an UPSERT, so this is the
        create

        path AND the edit path for a hook of that name.


        Supports conditional execution (via ``condition`` or ``condition_id``),
        payload

        transformation (via ``expr`` or ``expr_id``), and dynamic tool
        arguments.

        ``execution_key`` is the api-key identity every fire runs as; the
        caller's authority

        to delegate it and its usability by a tokenless fire are decided BEFORE
        the upsert, so

        a refusal stores nothing and leaves any existing hook of that name
        untouched. Returns

        ``{"registered", "name"}``; ``registered`` is ``True`` for a create and
        a replace

        alike.
      operationId: post_api_hooks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HookRegister'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data: {}
                required:
                  - data
                type: object
          description: Success.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Malformed request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Missing or invalid api key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Forbidden.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Resource not found.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    HookRegister:
      description: >-
        The client-facing register-a-hook request body: the fields a caller
        supplies.


        ``execution_key_fingerprint`` is server-derived at bind and deliberately
        absent

        here; :class:`HookParams` is this shape plus that one stored field.
      properties:
        condition:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Condition
        condition_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Condition Id
        condition_kwargs:
          additionalProperties: true
          title: Condition Kwargs
          type: object
        execution_key:
          description: >-
            The api-key ``user_id`` the hook fires as; its live stored grants
            authorize every tool call the fire makes.
          minLength: 1
          title: Execution Key
          type: string
        expr:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Expr
        expr_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Expr Id
        expr_kwargs:
          additionalProperties: true
          title: Expr Kwargs
          type: object
        name:
          minLength: 1
          title: Name
          type: string
        tool:
          minLength: 1
          title: Tool
          type: string
        tool_kwargs:
          additionalProperties: true
          title: Tool Kwargs
          type: object
        topic:
          minLength: 1
          title: Topic
          type: string
      required:
        - name
        - topic
        - tool
        - execution_key
      title: HookRegister
      type: object
    Error:
      properties:
        error:
          type: string
      required:
        - error
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey

````