# Ramon integration skill

Use Ramon to collect privacy-conscious browser interaction signals for a survey,
then retrieve a Human Score through an explicitly initiated server-side workflow.

## Sources of truth

- Documentation: https://docs.getramon.com
- OpenAPI: https://api.getramon.com/openapi/doc
- Interactive reference: https://api.getramon.com/openapi/ui
- Documentation MCP after package publication:
  `npx -y @modeleven/ramon-docs-mcp`

The OpenAPI document is canonical for paths, schemas, and response codes. The
documentation MCP is read-only. Use the REST API for integration operations.

## Safety and authority

- Keep the `rmn_int_...` integration key on the server. Never place it in the
  participant page, browser bundle, logs, prompts, or tool arguments.
- Use the public `trackingKey` only with the Ramon browser embed.
- Keep participant-facing flows fail-open when Ramon is unavailable.
- Start scoring or request deletion only after an authorized instruction from
  the integrating organization.
- Treat Human Score as review evidence. It is not identity proof, a calibrated
  probability, or sufficient by itself for a consequential decision.
- Do not send survey answers, participant attributes, names, email addresses,
  or other direct identifiers to Ramon.

## Required inputs

- Ramon API base URL, normally `https://api.getramon.com`
- Server-side organization integration key
- Stable external survey ID, unique within the Ramon organization
- Stable UUID for each survey response
- Survey name

## Integration workflow

1. Confirm the key and organization with `GET /integrations/v1/context`.
2. Provision the survey idempotently with
   `PUT /integrations/v1/surveys/{externalSurveyId}` and `{ "name": "..." }`.
3. Store the returned `surveyId`, `trackingKey`, `collectorApiUrl`, and
   `embedScriptUrl`.
4. Configure the browser embed with the public values. Use the same response
   UUID for `sessionId` and `interviewId` when possible.
5. Verify capture with
   `POST /integrations/v1/surveys/{surveyId}/sessions/lookup`.
6. When explicitly authorized, start a scoring run with
   `POST /integrations/v1/surveys/{surveyId}/scoring-runs`, then poll
   `GET /integrations/v1/surveys/{surveyId}/scoring-runs/{runId}`.
7. Read scores through session lookup after the run completes.
8. When explicitly authorized to delete a source response, request deletion at
   `DELETE /integrations/v1/surveys/{surveyId}/sessions/by-reference/{reference}`
   and poll `GET /integrations/v1/surveys/{surveyId}/session-deletions/{reference}`.

## Operational rules

- Send the integration key as `Authorization: Bearer ...`.
- Respect the limit of 120 Integration API requests per key per minute and the
  `Retry-After` header on `429` responses.
- Provisioning is idempotent for an organization and external survey ID.
- Session lookup accepts one to 100 UUID references and preserves input order.
- Scoring and deletion are asynchronous; poll at a bounded interval until a
  terminal `completed` or `failed` state.
- Retry only bounded, transient failures. Surface permanent failures to an
  authorized operator.

## Verification

Run one non-production response through provisioning, embed loading, event
capture, session lookup, authorized scoring, score lookup, authorized deletion,
and deletion polling. Verify that no private integration key appears in browser
code or network requests.