Lensmor Actions API

openapi: 3.2.0
info:
  title: Lensmor Actions API
  version: 0.27.0
  description: Lensmor Event Intelligence API for event discovery, exhibitor research, personnel lookup, credits, and profile matching.
  license:
    name: Lensmor Terms of Service
    url: https://www.lensmor.com/terms
servers:
- url: https://platform.lensmor.com
security:
- bearerAuth: []
tags:
- name: Actions
  description: Preflight access and credit-sensitive actions before executing them.
paths:
  /external/actions/precheck:
    post:
      tags:
      - Actions
      summary: Precheck an external action
      description: 'Evaluate whether a supported external action can run and what it is expected to cost, without executing the action or charging credits.


        Use precheck immediately before event-access, Visitor-access, contact-unlock, and other action-specific workflows. Inspect `allowed`, `should_charge`, `credits`, and `reason_code` to decide whether to continue, ask the user for confirmation, or explain why the action is unavailable.


        Precheck is advisory and read-only: it does not reserve credits, create a task, or lock the target state. Send the same action type and identifiers to the execution endpoint promptly, and still handle state or balance changes returned by that endpoint.'
      operationId: precheckExternalAction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionPrecheckRequest'
            example:
              action_type: query_event_personnel
              call_source: api
              params:
                event_id: '26855'
      responses:
        '200':
          description: Precheck decision envelope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionPrecheckResponse'
              example:
                ok: true
                action_type: query_event_personnel
                allowed: true
                should_charge: false
                credits: 0
                reason_code: ok
                biz_code: ''
                detail:
                  event_id: '26855'
                  access_mode: preview
                  preview_limit: 50
                  unlock_action_type: unlock_event_contacts
                  unlock_credits: 2000
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 429
            message: Rate limit exceeded
            errorKey: RATE_LIMIT_EXCEEDED
            traceId: 2be6d7f4-3b2d-4d11-8e2d-7a2e4c3e9a10
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 400
            message: Invalid request
            errorKey: INVALID_REQUEST
            traceId: 2be6d7f4-3b2d-4d11-8e2d-7a2e4c3e9a10
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            code: 401
            message: Invalid API key
            errorKey: INVALID_API_KEY
            traceId: 2be6d7f4-3b2d-4d11-8e2d-7a2e4c3e9a10
  schemas:
    ActionPrecheckResponse:
      type: object
      required:
      - ok
      - action_type
      - allowed
      - should_charge
      - credits
      - reason_code
      - biz_code
      - detail
      properties:
        ok:
          type: boolean
          const: true
          description: Whether the precheck itself completed successfully.
        action_type:
          type: string
          description: Action evaluated by the precheck.
        allowed:
          type: boolean
          description: Whether the action is currently allowed to proceed.
        should_charge:
          type: boolean
          description: Whether executing the action is expected to consume credits.
        credits:
          type: integer
          description: Credits expected for the action under the current state.
        reason_code:
          type: string
          enum:
          - ok
          - already_unlocked
          - unlock_in_progress
          - state_conflict
          - insufficient_balance
          - no_contacts_available
          - exceed_max_unlock_limit
          - invalid_subject
          - unsupported_action
          - not_found
          - forbidden
          - system_error
          description: Stable reason explaining the eligibility and charging decision.
        biz_code:
          type: string
          description: Business code associated with the precheck decision.
        detail:
          type: object
          additionalProperties: true
          description: Action-specific eligibility, cost, or state detail.
      additionalProperties: true
      description: Action eligibility, expected charging, reason, and action-specific detail.
    ActionPrecheckRequest:
      type: object
      required:
      - action_type
      - params
      properties:
        action_type:
          type: string
          minLength: 1
          maxLength: 100
          examples:
          - query_event_personnel
          - unlock_event_contacts
          - unlock_event_visitors
          - unlock_event_full_access
          - unlock_contact_emails
          - unlock_contact_phones
          - search_exhibitor_events
          - search_personnel_events_by_name
          - integration_status
          - integration_export_contacts
          - integration_export_exhibitors
          - others
          description: 'Action to evaluate. The listed examples are handled explicitly. Other 1–100 character strings are accepted and return `allowed: false` with `reason_code: unsupported_action`.'
          example: unlock_contact_emails
        call_source:
          type: string
          description: Caller source label, typically `api` or `agent`.
          example: api
          minLength: 1
          maxLength: 100
        params:
          type: object
          additionalProperties: true
          description: Action-specific identifiers and inputs, such as an `event_id`.
          example:
            event_id: '26855'
        locale:
          type: string
          description: Optional locale used for localized guidance or messages.
          example: en-US
          minLength: 1
          maxLength: 20
        trace_id:
          type: string
          description: Optional caller-provided trace identifier for support correlation.
          example: trace_123
          minLength: 1
          maxLength: 200
        conversation_id:
          type: string
          description: Optional conversation identifier for agent workflows.
          example: conversation_123
          minLength: 1
          maxLength: 200
        channel_message_id:
          type: string
          description: Optional channel message identifier for agent workflows.
          example: message_123
          minLength: 1
          maxLength: 200
      additionalProperties: false
      description: Read-only action eligibility and expected-credit evaluation request.
    ApiError:
      type: object
      required:
      - code
      - message
      - errorKey
      - traceId
      properties:
        code:
          type: integer
          description: Numeric or symbolic code that identifies the response or business condition.
        message:
          type: string
          description: Human-readable explanation suitable for logs or user-facing error handling.
        errorKey:
          type: string
          description: Stable machine-readable error key for branching and analytics.
        traceId:
          type: string
          description: Request trace identifier to include in support or incident reports.
        details:
          description: Optional structured business or validation context. Omitted when the error has no additional details.
      description: Shared error envelope returned by public Lensmor API endpoints.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Business sk API key
      description: 'Send the full Business API key from Settings -> API Keys, for example `Authorization: Bearer sk_your_api_key`.'