HTMLRadar API

openapi: 3.1.0
info:
  title: HTMLRadar API
  version: '2026-11-11'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-11: 15 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; HTMLRadar has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 1
    documentation: 14
    pages-with-code: 1
    pages-read: 1
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-11'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://htmlradar.com/docs/api
paths:
  /api/v1/documents:
    get:
      operationId: get_api_v1_documents
      tags:
      - Api
      summary: GET /api/v1/documents The account’s documents, newest first, with how many links point at each one.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: before
        in: query
        required: false
        schema:
          type: string
        description: Paging token.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1DocumentsResponse'
      x-evidence:
        kind: documentation
  /api/v1/documents/{id}/attachments:
    get:
      operationId: get_api_v1_documents_id_attachments
      tags:
      - Api
      summary: The HTMLRadar API is the same set of calls the dashboard and the MCP server use to create tracked links, list them, read who opened
        one, change a link’s settings, manage a document’s files, revoke a l
      description: Lists files attached to a document.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1DocumentsIdAttachmentsResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_documents_id_attachments
      tags:
      - Api
      summary: POST /api/v1/documents/{id}/attachments POST attaches one file.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1DocumentsIdAttachmentsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1DocumentsIdAttachmentsResponse'
      x-evidence:
        kind: documentation
  /api/v1/documents/{id}/attachments/{attachmentid}:
    delete:
      operationId: delete_api_v1_documents_id_attachments_attachmentid
      tags:
      - Api
      summary: DELETE /api/v1/documents/{id}/attachments/{attachmentId} Removes one file from a document.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: attachmentid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteApiV1DocumentsIdAttachmentsAttachmentidResponse'
      x-evidence:
        kind: documentation
  /api/v1/documents/{id}/html:
    get:
      operationId: get_api_v1_documents_id_html
      tags:
      - Api
      summary: GET /api/v1/documents/{id}/html A document’s current contents, so they can be changed and sent back to /replace.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: query
        in: query
        required: false
        schema:
          type: string
        description: Search term for passages.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1DocumentsIdHtmlResponse'
      x-evidence:
        kind: documentation
  /api/v1/documents/{id}/reading-records:
    get:
      operationId: get_api_v1_documents_id_reading_records
      tags:
      - Api
      summary: GET /api/v1/documents/{id}/reading-records The same reading the report shows, as a CSV file.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: share
        in: query
        required: false
        schema:
          type: string
        description: Filter by link.
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/documents/{id}/replace:
    post:
      operationId: post_api_v1_documents_id_replace
      tags:
      - Api
      summary: POST /api/v1/documents/{id}/replace Puts new content behind every link already sent.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1DocumentsIdReplaceRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1DocumentsIdReplaceResponse'
      x-evidence:
        kind: documentation
  /api/v1/me:
    get:
      operationId: get_api_v1_me
      tags:
      - Api
      summary: GET /api/v1/me reports whether this key works, and which plan it is on.
      x-source: https://htmlradar.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1MeResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_me
      tags:
      - Api
      summary: POST /api/v1/me
      x-source: https://htmlradar.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1MeRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1MeResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl https://htmlradar.com/api/v1/me  -H \"Authorization: Bearer hr_live_…\" response — 200 {\n \"user_id\": \"c1a2b3c4-…\"\
          ,\n \"email\": \"you@example.com\",\n \"tier\": \"free\",\n \"free_links_used\": 1,\n \"free_links_cap\": 2,\n \"key_read_only\": false,\n\
          \ \"team_read_only\": false,\n \"reads_contents\": true,\n \"permission_version\": 1,\n \"current_permission_version\": 2,\n \"update_available\"\
          : true,\n \"update_url\": \"https://html"
  /api/v1/shares:
    get:
      operationId: get_api_v1_shares
      tags:
      - Api
      summary: GET /api/v1/shares The account’s links, newest first, fifty at a time.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: before
        in: query
        required: false
        schema:
          type: string
        description: Paging token.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1SharesResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_v1_shares
      tags:
      - Api
      summary: POST /api/v1/shares Turns HTML into a tracked link, or adds a second link to a document you already created.
      x-source: https://htmlradar.com/docs/api
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1SharesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1SharesResponse'
      x-evidence:
        kind: documentation
  /api/v1/shares/{id}:
    get:
      operationId: get_api_v1_shares_id
      tags:
      - Api
      summary: GET /api/v1/shares/{id} GET returns the link’s current settings in the shape PATCH takes them.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1SharesIdResponse'
      x-evidence:
        kind: documentation
    patch:
      operationId: patch_api_v1_shares_id
      tags:
      - Api
      summary: PATCH /api/v1/shares/{id} PATCH changes a link’s settings in place.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchApiV1SharesIdRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchApiV1SharesIdResponse'
      x-evidence:
        kind: documentation
  /api/v1/shares/{id}/activity:
    get:
      operationId: get_api_v1_shares_id_activity
      tags:
      - Api
      summary: GET /api/v1/shares/{id}/activity Whether the link was opened, by whom, how long they read, how far they scrolled, and which sections
        they read.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: include_detail
        in: query
        required: false
        schema:
          type: boolean
        description: Include nested detail per reader.
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1SharesIdActivityResponse'
      x-evidence:
        kind: documentation
  /api/v1/shares/{id}/revoke:
    post:
      operationId: post_api_v1_shares_id_revoke
      tags:
      - Api
      summary: POST /api/v1/shares/{id}/revoke Switches a link off.
      x-source: https://htmlradar.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1SharesIdRevokeRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1SharesIdRevokeResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiV1DocumentsResponse:
      type: object
      properties:
        documents:
          type: array
          description: List of document objects.
        next_before:
          type: string
          description: Token for next page.
    GetApiV1DocumentsIdAttachmentsResponse:
      type: object
      properties:
        attachments:
          type: array
          description: List of attached files
    PostApiV1DocumentsIdAttachmentsRequest:
      type: object
      properties:
        filename:
          type: string
        content_base64:
          type: string
      required:
      - filename
      - content_base64
    PostApiV1DocumentsIdAttachmentsResponse:
      type: object
      properties:
        attachment_id:
          type: string
        document_id:
          type: string
        filename:
          type: string
        mime_type:
          type: string
        size_bytes:
          type: integer
    DeleteApiV1DocumentsIdAttachmentsAttachmentidResponse:
      type: object
      properties:
        attachment_id:
          type: string
        document_id:
          type: string
        filename:
          type: string
        removed:
          type: boolean
    GetApiV1DocumentsIdHtmlResponse:
      type: object
      properties:
        document_id:
          type: string
        title:
          type: string
        version:
          type: integer
        html:
          type: string
        image_references:
          type: integer
        stored_bytes:
          type: integer
    PostApiV1DocumentsIdReplaceRequest:
      type: object
      properties:
        html:
          type: string
          description: Whole page HTML.
        edits:
          type: array
          description: List of find/replace pairs.
        expected_version:
          type: integer
          description: Current version from GET /documents.
        request_id:
          type: string
          description: Idempotency token.
    PostApiV1DocumentsIdReplaceResponse:
      type: object
      properties:
        document_id:
          type: string
        version:
          type: integer
        links_unchanged:
          type: boolean
    GetApiV1MeResponse:
      type: object
      properties:
        user_id:
          type: string
        email:
          type: string
        tier:
          type: string
        free_links_used:
          type: integer
        free_links_cap:
          type: integer
        key_read_only:
          type: boolean
        team_read_only:
          type: boolean
        reads_contents:
          type: boolean
        permission_version:
          type: integer
        current_permission_version:
          type: integer
        update_available:
          type: boolean
        update_url:
          type: string
    PostApiV1MeRequest:
      type: object
      properties:
        html:
          type: string
        recipient_label:
          type: string
    PostApiV1MeResponse:
      type: object
      properties:
        user_id:
          type: string
        email:
          type: string
        tier:
          type: string
        free_links_used:
          type: integer
        free_links_cap:
          type: integer
        key_read_only:
          type: boolean
        team_read_only:
          type: boolean
        reads_contents:
          type: boolean
        permission_version:
          type: integer
        current_permission_version:
          type: integer
        update_available:
          type: boolean
        update_url:
          type: string
    GetApiV1SharesResponse:
      type: object
      properties:
        shares:
          type: array
          description: List of share objects.
        next_before:
          type: string
          description: Token for next page.
    PostApiV1SharesRequest:
      type: object
      properties:
        html:
          type: string
          description: Full markup. Up to 5 MB.
        url:
          type: string
          description: Accepted in the shape, but URL mode is not live on the API yet.
        document_id:
          type: string
          description: A second link on a document you already created.
        title:
          type: string
          description: The document's <title>
        recipient_label:
          type: string
          description: Who the link is for.
        require_email:
          type: boolean
          description: Ask for an email before the document opens.
        verify_email:
          type: boolean
          description: Mails a six‑digit code to the address the reader types on the gate.
        password:
          type: string
          description: Extra gate on top of the email gate. At least 8 characters.
        allow_comments:
          type: boolean
          description: Whether readers can comment.
        lock_deck:
          type: boolean
          description: Blocks save and print.
        show_watermark:
          type: boolean
          description: Shows a faint watermark when lock_deck is true.
        allowed_email_domains:
          type: array
          description: Only these domains may open it.
        allowed_emails:
          type: array
          description: Only these exact addresses may open it.
        expires_in_hours:
          type: number
          description: The link stops working after it.
        slug:
          type: string
          description: Custom link name.
        domain_id:
          type: string
          description: Account default or custom domain.
    PostApiV1SharesResponse:
      type: object
      properties:
        share_id:
          type: string
        document_id:
          type: string
        url:
          type: string
        dashboard_url:
          type: string
    GetApiV1SharesIdResponse:
      type: object
      properties:
        share_id:
          type: string
        url:
          type: string
        settings_version:
          type: integer
        settings:
          type: object
          description: Current settings.
    PatchApiV1SharesIdRequest:
      type: object
      properties:
        recipient_label:
          type: string
        require_email:
          type: boolean
        verify_email:
          type: boolean
        password:
          type: string
        allow_comments:
          type: boolean
        lock_deck:
          type: boolean
        show_watermark:
          type: boolean
        allowed_email_domains:
          type: array
        allowed_emails:
          type: array
        expires_at:
          type: string
        expires_in_hours:
          type: number
        show_sender:
          type: string
        notify_first_open:
          type: boolean
        add_allowed_emails:
          type: array
        remove_allowed_emails:
          type: array
        add_allowed_email_domains:
          type: array
        remove_allowed_email_domains:
          type: array
        expected_settings_version:
          type: integer
    PatchApiV1SharesIdResponse:
      type: object
      properties:
        share_id:
          type: string
        url:
          type: string
        settings_version:
          type: integer
        settings:
          type: object
    GetApiV1SharesIdActivityResponse:
      type: object
      properties:
        share_id:
          type: string
        url:
          type: string
        opened:
          type: boolean
        viewers:
          type: array
          description: List of viewer objects.
    PostApiV1SharesIdRevokeRequest:
      type: object
      properties:
        revoked:
          type: boolean
          description: Set false to un-revoke.
    PostApiV1SharesIdRevokeResponse:
      type: object
      properties:
        share_id:
          type: string
        url:
          type: string
        revoked:
          type: boolean
        revoked_at:
          type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api