Harvv API

openapi: 3.1.0
info:
  title: Harvv API
  version: '2026-11-11'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-11: 9 operation(s) read from 3 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Harvv has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 4
    documentation: 5
    pages-with-code: 2
    pages-read: 3
  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://harvv.com/docs/api
  - https://harvv.com/docs/mcp
  - https://harvv.com/pixel-source
paths:
  /customer/api-keys:
    get:
      operationId: get_customer_api_keys
      tags:
      - Customer
      summary: List your keys. Never returns the secret again.
      description: GET /customer/api-keys
      x-source: https://harvv.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_customer_api_keys
      tags:
      - Customer
      summary: Create a key. The only time the full value is returned.
      description: POST /customer/api-keys
      x-source: https://harvv.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCustomerApiKeysRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /customer/api-keys/{id}:
    delete:
      operationId: delete_customer_api_keys_id
      tags:
      - Customer
      summary: Revoke a key immediately.
      description: DELETE /customer/api-keys/:id
      x-source: https://harvv.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /mcp:
    post:
      operationId: post_mcp
      tags:
      - Mcp
      summary: Harvv runs a hosted Model Context Protocol server so AI coding agents can read your behavioral findings and install the pixel without
        leaving the editor.
      description: 'The MCP server speaks JSON‑RPC 2.0 over streamable HTTP. Clients POST a JSON body with the fields above and include the headers
        `Content-Type: application/json`, `Authorization: Bearer <YOUR_TOKEN>`, and `Accept: application/json, text/event-stream`.'
      x-source: https://harvv.com/docs/mcp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMcpRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMcpResponse'
      x-evidence:
        kind: documentation
  /v1/outcomes:
    post:
      operationId: post_v1_outcomes
      tags:
      - Outcomes
      summary: POST /v1/outcomes
      x-source: https://harvv.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1OutcomesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://harvv.com/v1/outcomes  -H \"Authorization: Bearer hv_live_xxx\"  -H \"Content-Type: application/json\"\
          \  -d '{\n \"site_id\": \"your-pixel-key\",\n \"session_id\": \"61b7df69a4c2e8f1\",\n \"outcome\": \"kyc_approved\",\n \"properties\"\
          : { \"approval_tier\": \"instant\", \"score\": 87 }\n }' \n Field Required Notes \n site_id Yes Your pixel key, from the install snippet\
          \ \n session_id Yes The 16-character ID fr"
  /v1/sites:
    get:
      operationId: get_v1_sites
      tags:
      - Sites
      summary: GET /v1/sites
      x-source: https://harvv.com/docs/api
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1SitesResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -H \"Authorization: Bearer hv_live_xxx\"  https://harvv.com/v1/sites \n Returns { \"sites\": [ ... ] } . \n Site stats\
          \ \n GET /v1/sites/:id/stats \n Param Values Default \n period today , 7d , 30d 7d \n Anything else falls back to 7 days rather than\
          \ erroring. "
  /v1/sites/{id}/friction:
    get:
      operationId: get_v1_sites_id_friction
      tags:
      - Sites
      summary: Friction elements
      description: GET /v1/sites/:id/friction
      x-source: https://harvv.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: period
        in: query
        required: false
        schema:
          type: string
        description: 'Period for data, default 7d. Allowed values: 7d, 30d.'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1SitesIdFrictionResponse'
      x-evidence:
        kind: documentation
  /v1/sites/{id}/issues/{issueId}:
    get:
      operationId: get_v1_sites_id_issues_issueId
      tags:
      - Sites
      summary: One finding in full, including the plain-language title and the suggested fix.
      description: GET /v1/sites/:id/issues/:issue_id
      x-source: https://harvv.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: issueId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/sites/register:
    post:
      operationId: post_v1_sites_register
      tags:
      - Sites
      summary: Creates a site and returns its pixel key.
      description: POST /v1/sites/register
      x-source: https://harvv.com/docs/api
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostCustomerApiKeysRequest:
      type: object
      properties:
        name:
          type: string
          description: Name for the API key.
      required:
      - name
    PostMcpRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          description: JSON‑RPC version, always "2.0".
        id:
          type: integer
          description: Client‑generated request identifier.
        method:
          type: string
          description: MCP method to invoke, e.g. "tools/call".
        params:
          type: object
          description: Parameters for the method. For tools/call the object contains "name" (tool name) and "arguments" (tool‑specific arguments).
      required:
      - jsonrpc
      - id
      - method
      - params
    PostMcpResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          description: JSON‑RPC version, "2.0".
        id:
          type: integer
          description: Echoes the request id.
        result:
          type: object
          description: Tool‑specific result payload when the call succeeds.
        error:
          type: object
          description: Error object when the call fails (e.g., 401 with reason code).
    PostV1OutcomesRequest:
      type: object
      properties:
        site_id:
          type: string
        session_id:
          type: string
        outcome:
          type: string
        properties:
          type: object
          properties:
            approval_tier:
              type: string
            score:
              type: integer
    GetV1SitesResponse:
      type: object
      properties:
        sites:
          type: array
          items: {}
    GetV1SitesIdFrictionResponse:
      type: object
      properties:
        dead_clicks:
          type: array
          description: Top 15 dead clicks.
        rage_clicks:
          type: array
          description: Top 15 rage clicks.
        dashboard_url:
          type: string
          description: Link to dashboard.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Customer
- name: Mcp
- name: Outcomes
- name: Sites