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

# Retrieve a sample event

> Returns a sample event of one type, with the same fields and the same fixed example shortcut as a test send. Its ID starts with `evt_sample_`. Nothing is stored or sent. Use it to build a receiver before an endpoint exists. Needs API access (Basic and above), not the Business plan.



## OpenAPI

````yaml /openapi.json get /v1/webhooks/sample
openapi: 3.1.0
info:
  title: Lora API
  version: 1.0.0
  description: >-
    Lora REST API for managing workspace shortcuts, folders, tags, webhook
    endpoints, and QR codes.


    ## Versioning

    All stable endpoints are prefixed with `/v1/`. Breaking changes ship under a
    new path prefix (for example `/v2/`).

    Non-breaking additions (new optional fields, new endpoints) may land in the
    current version.

    Deprecated endpoints are announced in the [developer
    docs](https://uselora.dev/essentials/versioning) before removal.


    ## Authentication

    Send `Authorization: Bearer <api_key>` on every request except `GET /v1/qr`,
    which also accepts anonymous callers. API keys are workspace-scoped and
    carry named scopes (for example `shortcuts.write`); each scoped operation's
    `security` requirement lists the one scope it needs (`GET /v1/qr` needs
    none), so request a key with only those.


    ## Errors

    4xx and 5xx responses use a typed JSON envelope: `{ error, code?, requestId,
    traceId?, fieldErrors?, required_scope?, current_plan?, required_capability?
    }`.

    See components `ErrorResponse`, `ErrorWithFieldErrors`,
    `PaymentRequiredError`, `ForbiddenError`, `PayloadTooLargeError`, and
    `InternalError`.


    ## Rate limits

    Successful responses include `RateLimit-Limit`, `RateLimit-Remaining`, and
    `RateLimit-Reset` (IETF RateLimit fields).

    429 responses include `Retry-After` (seconds). Authenticated callers are
    bucketed per API key; anonymous QR endpoints are bucketed per IP.


    ## Discovery

    - OpenAPI spec: `GET https://api.uselora.com/openapi.json` (also `GET
    https://api.uselora.com/`)

    - RFC 9727 catalog: `GET https://www.uselora.com/.well-known/api-catalog`

    - MCP manifest: `GET https://www.uselora.com/.well-known/mcp` (server card
    at `/.well-known/mcp/server-card.json`)

    - MCP Streamable HTTP endpoint: `POST https://api.uselora.com/mcp`
servers:
  - url: https://api.uselora.com
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/webhooks/sample:
    get:
      tags:
        - Webhooks
      summary: Retrieve a sample event
      description: >-
        Returns a sample event of one type, with the same fields and the same
        fixed example shortcut as a test send. Its ID starts with `evt_sample_`.
        Nothing is stored or sent. Use it to build a receiver before an endpoint
        exists. Needs API access (Basic and above), not the Business plan.
      operationId: getWebhookSample
      parameters:
        - description: The event type to return a sample of.
          in: query
          name: event
          required: true
          schema:
            enum:
              - shortcut.created
              - shortcut.updated
              - shortcut.deleted
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEvent'
          description: The sample event.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithFieldErrors'
          description: '`event` is missing or not an event type.'
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: >-
            Missing, malformed, unknown or revoked API key. A key that was
            disabled by a downgrade answers with `apikey_disabled`.
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
        '402':
          description: >-
            The workspace plan does not include API access, the requested
            capability, or enough resource capacity. The body uses
            `plan_requires_upgrade` or `quota_exceeded`. Upgrade the workspace
            or change the request; retrying the same request will not succeed.
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequiredError'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
          description: >-
            The key lacks the required scope (`insufficient_scope`, with
            `required_scope`), its owner is no longer an owner or admin of the
            workspace (`insufficient_role`), or its owner is no longer a member
            of the workspace (`no_permission`).
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded. Wait `Retry-After` seconds before retrying.
          headers:
            Retry-After:
              description: Seconds until the rate-limit window resets.
              schema:
                type: integer
                minimum: 1
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
        '500':
          description: >-
            An unexpected failure on the server. The body is `{ error:
            <message>, code: "internal_error", requestId: <id> }`, plus
            `traceId` when available. Retry idempotent operations with
            exponential backoff. A write may already have applied; reconcile its
            state before retrying.
          headers:
            X-Lora-Request-Id:
              description: >-
                Request correlation identifier. Matches the `requestId` field in
                the JSON error body.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
      security:
        - bearerAuth:
            - webhooks.read
components:
  schemas:
    WebhookEvent:
      oneOf:
        - $ref: '#/components/schemas/ShortcutCreatedEvent'
        - $ref: '#/components/schemas/ShortcutUpdatedEvent'
        - $ref: '#/components/schemas/ShortcutDeletedEvent'
      description: >-
        The body of every webhook request. Events are not ordered and delivery
        is at least once.
      type: object
      discriminator:
        propertyName: event
        mapping:
          shortcut.created: '#/components/schemas/ShortcutCreatedEvent'
          shortcut.updated: '#/components/schemas/ShortcutUpdatedEvent'
          shortcut.deleted: '#/components/schemas/ShortcutDeletedEvent'
    ErrorWithFieldErrors:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        fieldErrors:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: array
            items:
              type: string
        requestId:
          type: string
          description: >-
            Correlation identifier for support/debugging. Equals the
            `X-Lora-Request-Id` response header.
        traceId:
          description: >-
            Trace identifier when available for this request. 32-character
            lowercase hex string.
          type: string
          pattern: ^[0-9a-f]{32}$
      required:
        - error
        - requestId
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        requestId:
          type: string
          description: >-
            Correlation identifier for support/debugging. Equals the
            `X-Lora-Request-Id` response header.
        traceId:
          description: >-
            Trace identifier when available for this request. 32-character
            lowercase hex string.
          type: string
          pattern: ^[0-9a-f]{32}$
      required:
        - error
        - requestId
      additionalProperties: false
    PaymentRequiredError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          enum:
            - plan_requires_upgrade
            - quota_exceeded
        requestId:
          type: string
          description: >-
            Correlation identifier for support/debugging. Equals the
            `X-Lora-Request-Id` response header.
        traceId:
          description: >-
            Trace identifier when available for this request. 32-character
            lowercase hex string.
          type: string
          pattern: ^[0-9a-f]{32}$
        current_plan:
          description: The workspace plan when the response includes it.
          type: string
        required_capability:
          description: The required plan capability when the response includes it.
          type: string
      required:
        - error
        - code
        - requestId
      additionalProperties: false
    ForbiddenError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        requestId:
          type: string
          description: >-
            Correlation identifier for support/debugging. Equals the
            `X-Lora-Request-Id` response header.
        traceId:
          description: >-
            Trace identifier when available for this request. 32-character
            lowercase hex string.
          type: string
          pattern: ^[0-9a-f]{32}$
        required_scope:
          description: >-
            Set when `code` is `insufficient_scope`. The exact scope name the
            route required, e.g. `shortcuts.write`.
          type: string
      required:
        - error
        - requestId
      additionalProperties: false
    InternalError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          const: internal_error
        requestId:
          type: string
          description: >-
            Correlation identifier for support/debugging. Equals the
            `X-Lora-Request-Id` response header.
        traceId:
          description: >-
            Trace identifier when available for this request. 32-character
            lowercase hex string.
          type: string
          pattern: ^[0-9a-f]{32}$
      required:
        - error
        - code
        - requestId
      additionalProperties: false
    ShortcutCreatedEvent:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
          description: When the event was recorded, ISO 8601.
          examples:
            - '2026-11-02T10:15:30.000Z'
        data:
          type: object
          properties:
            additionalFolderIds:
              default: []
              description: >-
                Short IDs of additional folders visible to you, excluding the
                primary folder (`folderId`). Empty array when there are no
                visible additional folders. Set at create or replace the visible
                set with PATCH; folders you cannot see are preserved. Individual
                appearances can also be added or removed via the folder items
                endpoints.
              examples:
                - - a1b2c3d4
              type: array
              items:
                type: string
                pattern: ^[0-9abcdefghjkmnpqrstvwxyz]{8}$
            aliases:
              default: []
              description: >-
                Additional handles that resolve to this shortcut. The canonical
                slug is always `slug`; aliases are alternate names in the same
                namespace.
              examples:
                - - urlaub
                  - ferien
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 50
                pattern: ^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$
            archived:
              type: boolean
            createdAt:
              type: string
            description:
              type:
                - string
                - 'null'
            destination:
              type: string
            expiresAt:
              type:
                - string
                - 'null'
            folderId:
              type: string
              pattern: ^[0-9abcdefghjkmnpqrstvwxyz]{8}$
              description: The 8-character ID of the folder this shortcut belongs to.
              examples:
                - a1b2c3d4
            id:
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            passwordProtected:
              type: boolean
              description: >-
                Whether this shortcut requires a password before redirecting.
                The password hash is never returned.
            slug:
              type: string
            tagIds:
              default: []
              description: >-
                Tag short IDs associated with this shortcut. Empty array when
                none are applied.
              examples:
                - - a1b2c3d4
              type: array
              items:
                type: string
                pattern: ^[0-9abcdefghjkmnpqrstvwxyz]{8}$
            title:
              type:
                - string
                - 'null'
            updatedAt:
              type: string
            url:
              type: string
              description: >-
                Workspace-scoped shortcut URL. Open it to record a click and
                redirect to the destination.
              examples:
                - https://app.uselora.com/acme/short/handbook
            visibility:
              type: string
              enum:
                - PRIVATE
                - WORKSPACE
                - UNLISTED
          required:
            - additionalFolderIds
            - aliases
            - archived
            - createdAt
            - description
            - destination
            - expiresAt
            - folderId
            - id
            - passwordProtected
            - slug
            - tagIds
            - title
            - updatedAt
            - url
            - visibility
          additionalProperties: false
          description: >-
            The shortcut as it was when the event was recorded: a fixed subset
            of the shortcut object of the shortcuts API.
        event:
          type: string
          const: shortcut.created
        id:
          type: string
          description: >-
            The event's unique ID. A real event uses `evt_` and a UUID, a test
            send `evt_test_` and a UUID, and a sample from the sample operation
            `evt_sample_` and the event name. The same for every delivery, retry
            and resend of the event. Deduplicate on it, or on the `webhook-id`
            header, which carries the same value.
          examples:
            - evt_0198f2a4-7c1b-7d3e-9a52-3f6b1c2d4e5f
        reason:
          type: string
          enum:
            - inserted
            - became_visible
          description: >-
            `inserted`: the shortcut was created visible to the workspace.
            `became_visible`: an existing shortcut was made visible to the
            workspace.
      required:
        - createdAt
        - data
        - event
        - id
        - reason
      additionalProperties: false
      description: A shortcut was created or became visible to the workspace.
    ShortcutUpdatedEvent:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
          description: When the event was recorded, ISO 8601.
          examples:
            - '2026-11-02T10:15:30.000Z'
        data:
          type: object
          properties:
            additionalFolderIds:
              default: []
              description: >-
                Short IDs of additional folders visible to you, excluding the
                primary folder (`folderId`). Empty array when there are no
                visible additional folders. Set at create or replace the visible
                set with PATCH; folders you cannot see are preserved. Individual
                appearances can also be added or removed via the folder items
                endpoints.
              examples:
                - - a1b2c3d4
              type: array
              items:
                type: string
                pattern: ^[0-9abcdefghjkmnpqrstvwxyz]{8}$
            aliases:
              default: []
              description: >-
                Additional handles that resolve to this shortcut. The canonical
                slug is always `slug`; aliases are alternate names in the same
                namespace.
              examples:
                - - urlaub
                  - ferien
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 50
                pattern: ^[a-z0-9]([a-z0-9-_]*[a-z0-9])?$
            archived:
              type: boolean
            createdAt:
              type: string
            description:
              type:
                - string
                - 'null'
            destination:
              type: string
            expiresAt:
              type:
                - string
                - 'null'
            folderId:
              type: string
              pattern: ^[0-9abcdefghjkmnpqrstvwxyz]{8}$
              description: The 8-character ID of the folder this shortcut belongs to.
              examples:
                - a1b2c3d4
            id:
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            passwordProtected:
              type: boolean
              description: >-
                Whether this shortcut requires a password before redirecting.
                The password hash is never returned.
            slug:
              type: string
            tagIds:
              default: []
              description: >-
                Tag short IDs associated with this shortcut. Empty array when
                none are applied.
              examples:
                - - a1b2c3d4
              type: array
              items:
                type: string
                pattern: ^[0-9abcdefghjkmnpqrstvwxyz]{8}$
            title:
              type:
                - string
                - 'null'
            updatedAt:
              type: string
            url:
              type: string
              description: >-
                Workspace-scoped shortcut URL. Open it to record a click and
                redirect to the destination.
              examples:
                - https://app.uselora.com/acme/short/handbook
            visibility:
              type: string
              enum:
                - PRIVATE
                - WORKSPACE
                - UNLISTED
          required:
            - additionalFolderIds
            - aliases
            - archived
            - createdAt
            - description
            - destination
            - expiresAt
            - folderId
            - id
            - passwordProtected
            - slug
            - tagIds
            - title
            - updatedAt
            - url
            - visibility
          additionalProperties: false
          description: >-
            The shortcut as it was when the event was recorded. Several edits
            made in quick succession arrive as one event.
        event:
          type: string
          const: shortcut.updated
        id:
          type: string
          description: >-
            The event's unique ID. A real event uses `evt_` and a UUID, a test
            send `evt_test_` and a UUID, and a sample from the sample operation
            `evt_sample_` and the event name. The same for every delivery, retry
            and resend of the event. Deduplicate on it, or on the `webhook-id`
            header, which carries the same value.
          examples:
            - evt_0198f2a4-7c1b-7d3e-9a52-3f6b1c2d4e5f
      required:
        - createdAt
        - data
        - event
        - id
      additionalProperties: false
      description: Occurs when a shortcut is updated in your workspace.
    ShortcutDeletedEvent:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
          description: When the event was recorded, ISO 8601.
          examples:
            - '2026-11-02T10:15:30.000Z'
        data:
          type: object
          properties:
            id:
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          required:
            - id
          additionalProperties: false
          description: >-
            Only the shortcut's ID: no content of the shortcut is sent with a
            deletion. A later read of that ID through the API answers 404 or
            403.
        event:
          type: string
          const: shortcut.deleted
        id:
          type: string
          description: >-
            The event's unique ID. A real event uses `evt_` and a UUID, a test
            send `evt_test_` and a UUID, and a sample from the sample operation
            `evt_sample_` and the event name. The same for every delivery, retry
            and resend of the event. Deduplicate on it, or on the `webhook-id`
            header, which carries the same value.
          examples:
            - evt_0198f2a4-7c1b-7d3e-9a52-3f6b1c2d4e5f
        reason:
          type: string
          enum:
            - removed
            - became_hidden
          description: >-
            `removed`: the shortcut was deleted. `became_hidden`: it was made
            private or unlisted and is no longer visible to the workspace.
      required:
        - createdAt
        - data
        - event
        - id
        - reason
      additionalProperties: false
      description: >-
        A shortcut was removed, or left workspace visibility. Carries only its
        `id`.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key (`lora_sk_…`) sent as `Authorization: Bearer
        <api_key>`. Each scoped operation names the scope it requires in its
        `security` requirement, for example `shortcuts.write`; a key without it
        receives `403` with `code: insufficient_scope`. `GET /v1/qr` also
        accepts anonymous requests and requires no scope.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.