Hive Civilization Vault Visits API

The vault-visits API from Hive Civilization — 9 operation(s) for vault-visits.

Documentation GitHub OpenAPI

Operations 9

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /v1/vault/visit Record a vault page visit beacon · Vault Visit #

Ask an LLM

“How do I log that someone opened a vault page, with dwell time and scroll depth?”

“Does every visit beacon trigger a notification or only one per session?”

Tell an agent

Record a visit to vault {slug} from session {visitor_session}.

Log a {event} beacon on vault {slug} with {dwell_s} seconds dwell and {scroll_pct}% scroll.

GET /v1/vault/visits/recent List the most recent vault visits · Visits Recent #

Ask an LLM

“Who has opened any of my vault pages most recently?”

“Can I read the latest raw entries from the visit log?”

Tell an agent

Show the {limit} most recent vault visits.

Read the latest entries across all vault visit logs.

GET /v1/vault/visits/by-slug Get visit history for one vault · Visits By Slug #

Ask an LLM

“Every visit to one specific vault, newest first — where do I get that?”

“Does the per-vault history separate real viewers from bots?”

Tell an agent

Show all visits to vault {slug}.

Get the last {limit} visits and bot classification for vault {slug}.

GET /v1/vault/visits/by-company Summarize visits across all vaults · Visits By Company #

Ask an LLM

“What does an at-a-glance summary of every tracked vault look like, one row each?”

“Which vaults have any visits at all?”

Tell an agent

Summarize visit counts for every tracked vault.

Give me the per-vault dashboard rollup.

GET /v1/vault/visits/health Check the vault visit tracker's health · Visits Health #

Ask an LLM

“Is the vault visit tracking service healthy?”

“Can I confirm the visit beacon endpoint is working?”

Tell an agent

Check vault visit tracker health.

Confirm the visit tracking service is up.

GET /v1/vault/visits/leaderboard Rank vaults by engagement · Visits Leaderboard #

Ask an LLM

“Which vaults are getting the most engagement from unique viewers and re-opens?”

“What is the engagement score used to rank vaults?”

Tell an agent

Rank my vaults by engagement intensity.

Show the vault engagement leaderboard.

GET /v1/vault/visits/forwards Find vaults forwarded to new viewers · Visits Forwards #

Ask an LLM

“Has any prospect forwarded a vault to a colleague?”

“Can I see the per-viewer breakdown for vaults opened by a second person?”

Tell an agent

List vaults that were forwarded to a second viewer.

Show which vaults were shared internally by prospects.

POST /v1/vault/visits/register-label Attach a human label to a vault slug · Register Label #

Ask an LLM

“Can I name a new vault slug without redeploying?”

“Do runtime labels override labels defined in code?”

Tell an agent

Label vault {slug} as {label}.

Register the name {label} for slug {slug}.

GET /v1/vault/visits/labels List vault slug labels · List Labels #

Ask an LLM

“Which human-readable names are mapped to each vault slug?”

“Can I see both code-defined and runtime vault labels?”

Tell an agent

List all vault slug labels.

Show every slug-to-label mapping.

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/thehiveryiq-com:thehiveryiq-com-vault-visits-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: HiveMorph v0.1 Vault Visits API
  description: 'Polymorphic agent runtime — single shape (Merchant), single supermodel (W2 MERCHANT). Three gates: NEED + YIELD + CLEAN-MONEY.'
  version: 0.1.0
tags:
- name: vault-visits
paths:
  /v1/vault/visit:
    post:
      tags:
      - vault-visits
      summary: Vault Visit
      description: Record a vault page beacon. One Pushover ping per visitor session.
      operationId: vault_visit_v1_vault_visit_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VisitEvent'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/vault/visits/recent:
    get:
      tags:
      - vault-visits
      summary: Visits Recent
      description: 'Operator-only — read recent visits from the JSONL log.

        No auth at this stage; the URL is undocumented. Move behind auth before publishing.'
      operationId: visits_recent_v1_vault_visits_recent_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/vault/visits/by-slug:
    get:
      tags:
      - vault-visits
      summary: Visits By Slug
      description: 'Per-slug visit history. Returns ALL visits for one slug, newest first,

        plus a classification summary that uses the corrected three-tier

        bot-classification logic (LinkedIn-anonymous-aware).'
      operationId: visits_by_slug_v1_vault_visits_by_slug_get
      parameters:
      - name: slug
        in: query
        required: true
        schema:
          type: string
          title: Slug
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 200
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/vault/visits/by-company:
    get:
      tags:
      - vault-visits
      summary: Visits By Company
      description: 'Aggregate visit summary across ALL tracked slugs. One row per slug.

        Useful for an operator-side dashboard at a glance.'
      operationId: visits_by_company_v1_vault_visits_by_company_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/vault/visits/health:
    get:
      tags:
      - vault-visits
      summary: Visits Health
      operationId: visits_health_v1_vault_visits_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/vault/visits/leaderboard:
    get:
      tags:
      - vault-visits
      summary: Visits Leaderboard
      description: 'Slugs ranked by engagement intensity = unique_viewers × open_count.


        Re-opens count multiplicatively because the second open by the same

        viewer means absorption; a third open from a NEW fingerprint means

        the vault was forwarded internally — the strongest signal we get.'
      operationId: visits_leaderboard_v1_vault_visits_leaderboard_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/vault/visits/forwards:
    get:
      tags:
      - vault-visits
      summary: Visits Forwards
      description: 'Slugs where the vault has been forwarded to a 2nd+ viewer.


        This is the highest signal in the system — a prospect didn''t just

        open the vault, they sent it to a colleague. Returns one row per

        slug with forwarded=True, with the per-viewer breakdown.'
      operationId: visits_forwards_v1_vault_visits_forwards_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /v1/vault/visits/register-label:
    post:
      tags:
      - vault-visits
      summary: Register Label
      description: 'Attach a human label to a slug at runtime, no deploy required.

        Persists to disk so the label survives restarts. Code-defined

        SLUG_LABELS still take precedence — this is a runtime overlay for

        new vaults you spin up between deploys.'
      operationId: register_label_v1_vault_visits_register_label_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabelRegister'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/vault/visits/labels:
    get:
      tags:
      - vault-visits
      summary: List Labels
      description: Show all known slug → label mappings (code + runtime).
      operationId: list_labels_v1_vault_visits_labels_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    LabelRegister:
      properties:
        slug:
          type: string
          maxLength: 64
          minLength: 4
          title: Slug
        label:
          type: string
          maxLength: 80
          minLength: 1
          title: Label
      type: object
      required:
      - slug
      - label
      title: LabelRegister
    VisitEvent:
      properties:
        slug:
          type: string
          maxLength: 64
          minLength: 4
          title: Slug
        u:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: U
          description: ?u= tag from URL — primary or fallback identity
        visitor_session:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Visitor Session
          description: random ID from sessionStorage
        referrer:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Referrer
        event:
          type: string
          pattern: ^(open|dwell|scroll|close)$
          title: Event
          default: open
        dwell_s:
          anyOf:
          - type: integer
            maximum: 86400.0
            minimum: 0.0
          - type: 'null'
          title: Dwell S
        scroll_pct:
          anyOf:
          - type: integer
            maximum: 100.0
            minimum: 0.0
          - type: 'null'
          title: Scroll Pct
        ua:
          anyOf:
          - type: string
            maxLength: 400
          - type: 'null'
          title: Ua
      type: object
      required:
      - slug
      title: VisitEvent
x-provenance:
  method: harvested
  publisher: Hive Civilization
  source: https://receipts.thehiveryiq.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)

Hive Civilization Vault Visits API

Operations 9

Documentation

Specifications

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification