> ## 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.

# Create a trigger link

> Mint a trigger link for ``topic``.

``ttl_seconds`` is the creator's explicit choice (``null`` permanent, positive
timed; ``0``/negative → 400); a unique name is generated when omitted; a
verifier-bound topic is refused (400); ``tool_kwargs`` rides every fire, filling
only the arguments each fired hook's author left
unpinned. ``execution_key`` is the api-key identity the link's dispatch is gated on,
decided BEFORE the mint so a refusal leaves no live URL. ``require_api_key`` makes
the link's door demand an authenticated caller beside the token. Returns
``{"name", "trigger_path", "token", "topic", "expires_at"}``
— the token appears ONLY here (nothing else stores or lists it).

``created_by`` is stamped from the AMBIENT caller identity, never a request field
(which would be caller-spoofable); with the gate off there is no principal and it
is stored ``null``.



## OpenAPI

````yaml /openapi.json post /api/hooks/trigger-links
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/trigger-links:
    post:
      tags:
        - hooks
      summary: Create a trigger link
      description: >-
        Mint a trigger link for ``topic``.


        ``ttl_seconds`` is the creator's explicit choice (``null`` permanent,
        positive

        timed; ``0``/negative → 400); a unique name is generated when omitted; a

        verifier-bound topic is refused (400); ``tool_kwargs`` rides every fire,
        filling

        only the arguments each fired hook's author left

        unpinned. ``execution_key`` is the api-key identity the link's dispatch
        is gated on,

        decided BEFORE the mint so a refusal leaves no live URL.
        ``require_api_key`` makes

        the link's door demand an authenticated caller beside the token. Returns

        ``{"name", "trigger_path", "token", "topic", "expires_at"}``

        — the token appears ONLY here (nothing else stores or lists it).


        ``created_by`` is stamped from the AMBIENT caller identity, never a
        request field

        (which would be caller-spoofable); with the gate off there is no
        principal and it

        is stored ``null``.
      operationId: post_api_hooks_trigger_links
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerLinkCreate'
        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.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Conflict with the current resource state.
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Error.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    TriggerLinkCreate:
      description: >-
        Mint a trigger link for a hook ``topic``.


        ``ttl_seconds`` is REQUIRED (no default ⇒ the key must be present) and
        STRICT

        (``"3600"``, ``3600.0``, ``3600.5`` and bools all reject under one
        regime): a

        positive int is a timed link, ``null`` is a permanent link, and
        ``0``/negative

        is a loud 400 — expiry is the creator's explicit choice with no default
        and no

        product ceiling. ``execution_key`` is the api-key identity the link's
        dispatch is

        gated on — the link dies with the key — and the creator must be allowed
        to

        delegate it; each hook the dispatch reaches still fires as its OWN bound
        key.

        ``require_api_key`` makes the link's door demand an authenticated
        principal ON TOP

        of the token — one the authentication backend admits, and, when that
        principal is

        governed by a ROLE, one the ordinary ``hooks``-tag level pass admits at
        the request's

        method (``read`` for GET, ``write`` for POST); the governing policy is
        the OWNER's for

        an owned key, so a key escapes that pass exactly when its governing
        policy is admin or

        carries no role pointer. The

        default is token-only — the QR-on-a-wall case. ``topic`` must be
        non-empty, the same

        rule the stored record enforces, so the mint door never writes a link
        its own restore

        would refuse. ``tool_kwargs`` (optional) is stored on the link and
        merged into every

        fired hook's input BELOW that hook's own static ``tool_kwargs``, so it
        supplies only

        the arguments the hook's author left unpinned — a colliding key stays
        the author's.
      properties:
        execution_key:
          minLength: 1
          title: Execution Key
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Name
        require_api_key:
          default: false
          title: Require Api Key
          type: boolean
        tool_kwargs:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          title: Tool Kwargs
        topic:
          minLength: 1
          title: Topic
          type: string
        ttl_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Ttl Seconds
      required:
        - topic
        - execution_key
        - ttl_seconds
      title: TriggerLinkCreate
      type: object
    Error:
      properties:
        error:
          type: string
      required:
        - error
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey

````