Connect your AI tool to PonoLens.

Protocol v1 beta

Local reporting protocol

The endpoint is POST /api/developer/v1/events on the loopback-only PonoLens collector. The desktop app issues a separate revocable credential to each integration and stores only its hash. No PonoLens cloud service receives these events.

Developer tokens begin with plint_. They are separate from the plhook_ credentials that PonoLens automatically installs in its managed built-in harness bridges. Do not copy a managed harness credential into another tool. Reconnecting either kind of integration rotates its credential.

Protocol 1.1

Discover capabilities before sending an event

Call GET /api/developer/v1/capabilities with the integration token, or use testConnection() in JavaScript and test_connection() in Python. The response identifies supported event types, fields, limits, and the token's exact permissions without recording a receipt.

Download the capability schema ↓

Request

Every event identifies its schema, integration, event type, session, and time. Content belongs in a type-specific data object. Unknown top-level fields are rejected so integrations do not accidentally send extra information.

{
  "schema": "ponolens.event.v1",
  "integration": "example-agent",
  "event": "prompt.submitted",
  "sessionId": "session-123",
  "occurredAt": "2026-09-21T20:00:00.000Z",
  "data": {
    "content": "Summarize this change",
    "destination": "Example AI Provider",
    "cwd": "/Users/example/project"
  }
}

Download the JSON Schema ↓

Initial event types

The beta contract does not accept command output, model responses, screenshots, raw environment variables, credentials, or token maps.

Response

Version 1 is Report Only. A successful response confirms whether PonoLens retained a redacted receipt. It never claims that an action was blocked.

{
  "accepted": true,
  "recorded": true,
  "reportOnly": true,
  "receiptId": "local-receipt-id"
}

HTTP 202 means the event was accepted. Validation, authentication, and size failures return a non-success status without echoing sensitive values.

Privacy and security rules

• Requests stay on loopback and use one revocable credential per integration.
• PonoLens redacts the complete event before writing the normal receipt to SQLite.
• Saved prompt text follows the user's existing prompt-storage preference.
• When redaction is on and the packaged Mac vault is available, a prompt original may be stored separately as Mac-bound encrypted data for false-positive review. The encrypted original is excluded from Search, reports, and API responses.
• Commands, paths, tool inputs, and auxiliary strings are always redacted before storage.
• Command output and model output are not accepted.
• Report Only failures do not stop the developer's AI tool.
• An event is never labeled blocked unless a future supported synchronous adapter proves the action was stopped.

Examples

Send the same event from any language

Open the desktop app and choose Settings → Developer integrations → Generate token. Copy the token when it appears—it is shown once—then expose it to your local development process:

export PONOLENS_INTEGRATION_TOKEN='plint_…'

The event's integration value must exactly match the name used when generating the token.

curl

curl -X POST http://127.0.0.1:4317/api/developer/v1/events \
  -H "Authorization: Bearer $PONOLENS_INTEGRATION_TOKEN" \
  -H "Content-Type: application/json" \
  --data @event.json

JavaScript without an SDK

const response = await fetch(
  "http://127.0.0.1:4317/api/developer/v1/events",
  {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.PONOLENS_INTEGRATION_TOKEN}`,
      "content-type": "application/json"
    },
    body: JSON.stringify(event)
  }
);

if (!response.ok) throw new Error(`PonoLens returned ${response.status}`);

Download the JavaScript event example ↓ · Download the connection check ↓

Optional packages

Beta SDKs

The SDK packages are available here for beta testing and are not yet listed in the npm or PyPI public registries. They remain optional: direct HTTP/JSON integrations use the same versioned contract.

JavaScript / TypeScript

npm install https://ponolens.com/developers/downloads/ponolens-sdk-0.2.0-beta.1.tgz

import { PonoLens } from "@ponolens/sdk";

const client = new PonoLens({
  token: process.env.PONOLENS_INTEGRATION_TOKEN,
  integration: "example-agent"
});

await client.testConnection();

await client.promptSubmitted({
  sessionId: "session-123",
  occurredAt: new Date().toISOString(),
  data: { content: "Summarize this change", destination: "Example Provider" }
});

Python

python -m pip install https://ponolens.com/developers/downloads/ponolens-sdk-0.2.0b1.tar.gz

from ponolens_sdk import PonoLens

client = PonoLens(token=token, integration="example-agent")
client.test_connection()
client.prompt_submitted(
    session_id="session-123",
    occurred_at=datetime.now(timezone.utc).isoformat(),
    data={"content": "Summarize this change"},
)