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.

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 it to SQLite.
• Saved prompt text follows the user's existing prompt-storage preference.
• 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 example ↓

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.1.0-beta.1.tgz

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

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

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.1.0b1.tar.gz

from ponolens_sdk import PonoLens

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