{"openapi":"3.0.3","info":{"title":"Ramon Integration API","version":"1.0.0","description":"Public API for integrating Ramon behavioural signal collection and survey scoring into a survey platform."},"servers":[{"url":"https://api.getramon.com","description":"Production"}],"tags":[{"name":"Browser collector","description":"Unauthenticated browser event ingestion."},{"name":"Integration","description":"Authenticated survey-platform operations."}],"paths":{"/event/{key}/{identifier}":{"post":{"tags":["Browser collector"],"operationId":"collectEvents","summary":"Submit a batch of browser events","description":"The Ramon embed sends behavioural events to this endpoint. A deleted session is accepted but its events are discarded.","security":[],"parameters":[{"$ref":"#/components/parameters/TrackingKey"},{"$ref":"#/components/parameters/SessionIdentifier"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectorEventBatch"}}}},"responses":{"201":{"description":"Events were accepted for asynchronous processing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventIngestionResult"}}}},"202":{"description":"The session has been deleted; events were discarded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscardedEventIngestionResult"}}}}}}},"/integrations/v1/context":{"get":{"tags":["Integration"],"operationId":"getIntegrationContext","summary":"Get the integration-key context","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The organization and integration key context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationContextResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/OrganizationNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/integrations/v1/limesurvey/instances/{instanceId}/surveys/{externalSurveyId}":{"put":{"tags":["Integration"],"operationId":"provisionLimeSurveySurvey","summary":"Provision or update a LimeSurvey survey","description":"Idempotently provisions a Ramon survey for one LimeSurvey instance and external survey ID. Repeating the request updates metadata and returns the same Ramon survey ID.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/LimeSurveyInstanceId"},{"$ref":"#/components/parameters/LimeSurveyExternalSurveyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimeSurveyProvisionRequest"}}}},"responses":{"200":{"description":"The survey is provisioned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurveyProvisionResponse"}}}},"400":{"$ref":"#/components/responses/InvalidLimeSurveyProvisioningInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ProvisioningFailure"}}}},"/integrations/v1/surveys/{surveyId}/sessions/lookup":{"post":{"tags":["Integration"],"operationId":"lookupSurveySessions","summary":"Look up captured sessions and scores","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionLookupRequest"}}}},"responses":{"200":{"description":"One result for every submitted external reference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionLookupResponse"}}}},"400":{"$ref":"#/components/responses/InvalidSessionLookupInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/SurveyNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/integrations/v1/surveys/{surveyId}/scoring-runs":{"post":{"tags":["Integration"],"operationId":"startSurveyScoringRun","summary":"Start a survey scoring run","description":"Creates a scoring run and returns immediately. Poll the scoring-run endpoint until its status is no longer `running`. A concurrent active run is reused.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/SurveyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartScoringRunRequest"}}}},"responses":{"202":{"description":"A scoring run was started or an active run was reused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoringRunResponse"}}}},"400":{"$ref":"#/components/responses/InvalidScoringRunInput"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/SurveyNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/integrations/v1/surveys/{surveyId}/scoring-runs/{runId}":{"get":{"tags":["Integration"],"operationId":"getSurveyScoringRun","summary":"Get a scoring-run status","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/SurveyId"},{"$ref":"#/components/parameters/ScoringRunId"}],"responses":{"200":{"description":"The current scoring-run status and counters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoringRunResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/ScoringRunNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/integrations/v1/surveys/{surveyId}/sessions/by-reference/{reference}":{"delete":{"tags":["Integration"],"operationId":"requestSessionDeletion","summary":"Request deletion of one session","description":"Creates an asynchronous deletion request. The operation is idempotent for completed deletions and creates a tombstone so late-arriving collector events are discarded.","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/SurveyId"},{"$ref":"#/components/parameters/ExternalReference"}],"responses":{"202":{"description":"The deletion was requested. Poll its status until it is no longer `pending`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDeletionResponse"}}}},"400":{"$ref":"#/components/responses/InvalidSessionReference"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/SurveyNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/integrations/v1/surveys/{surveyId}/session-deletions/{reference}":{"get":{"tags":["Integration"],"operationId":"getSessionDeletion","summary":"Get a session-deletion status","security":[{"bearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/SurveyId"},{"$ref":"#/components/parameters/ExternalReference"}],"responses":{"200":{"description":"The current deletion status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDeletionResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/SessionDeletionNotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Ramon integration key","description":"An organization integration key in the `Authorization: Bearer <key>` request header."}},"parameters":{"TrackingKey":{"name":"key","in":"path","required":true,"description":"The tracking key returned while provisioning the survey.","schema":{"type":"string","minLength":1}},"SessionIdentifier":{"name":"identifier","in":"path","required":true,"description":"A browser-session identifier. UUIDs are recommended.","schema":{"type":"string","minLength":1}},"LimeSurveyInstanceId":{"name":"instanceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"LimeSurveyExternalSurveyId":{"name":"externalSurveyId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{1,10}$"}},"SurveyId":{"name":"surveyId","in":"path","required":true,"description":"Ramon survey ID returned by provisioning.","schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}},"ScoringRunId":{"name":"runId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"}},"ExternalReference":{"name":"reference","in":"path","required":true,"description":"The external response reference associated with a session.","schema":{"type":"string","format":"uuid"}}},"responses":{"Unauthorized":{"description":"The Bearer integration key is missing, invalid, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"OrganizationNotFound":{"description":"The organization that owns the integration key no longer exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SurveyNotFound":{"description":"The survey does not exist or does not belong to the integration key organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScoringRunNotFound":{"description":"The scoring run does not exist for this survey.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SessionDeletionNotFound":{"description":"No deletion request exists for this session reference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidLimeSurveyProvisioningInput":{"description":"The instance ID, external survey ID, or provisioning body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidSessionLookupInput":{"description":"The lookup body must contain one to 100 UUID external references.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidScoringRunInput":{"description":"The scoring request body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidSessionReference":{"description":"The session reference must be a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ProvisioningFailure":{"description":"The survey could not be provisioned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"More than 120 requests were made with this integration key in one minute.","headers":{"Retry-After":{"description":"Seconds to wait before retrying the request.","schema":{"type":"integer","example":60}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"CollectorEventBatch":{"type":"object","required":["events"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/CollectorEvent"}}}},"CollectorEvent":{"description":"A JSON event value. The official Ramon embed sends objects with `type`, `timestamp` (Unix milliseconds), and event-specific `data` fields.","example":{"type":"mousemove","timestamp":1735689600000,"data":{"x":120,"y":345}}},"EventIngestionResult":{"type":"object","required":["success","count"],"properties":{"success":{"type":"boolean","example":true},"count":{"type":"integer","minimum":0,"example":3}}},"DiscardedEventIngestionResult":{"allOf":[{"$ref":"#/components/schemas/EventIngestionResult"},{"type":"object","required":["deleted"],"properties":{"deleted":{"type":"boolean","enum":[true]}}}]},"IntegrationContextResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["organization","key"],"properties":{"organization":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","example":"org_acme"},"name":{"type":"string","example":"Acme Research"}}},"key":{"type":"object","required":["prefix","label","scopes"],"properties":{"prefix":{"type":"string","example":"a1b2c3d4e5f6"},"label":{"type":"string","example":"LimeSurvey production"},"scopes":{"type":"array","items":{"type":"string"},"example":["integration:surveys:write"]}}}}}}},"LimeSurveyProvisionRequest":{"type":"object","required":["name","pluginVersion","limeSurveyVersion"],"properties":{"name":{"type":"string","pattern":"\\S","description":"Trimmed value must be 1 to 200 characters.","example":"Customer satisfaction 2026"},"pluginVersion":{"type":"string","pattern":"\\S","description":"Trimmed value must be 1 to 30 characters.","example":"1.0.0"},"limeSurveyVersion":{"type":"string","pattern":"\\S","description":"Trimmed value must be 1 to 60 characters.","example":"7.0.0"}}},"SurveyProvisionResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["surveyId","trackingKey","collectorApiUrl","embedScriptUrl"],"properties":{"surveyId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"trackingKey":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"collectorApiUrl":{"type":"string","format":"uri","example":"https://api.getramon.com"},"embedScriptUrl":{"type":"string","format":"uri","example":"https://embed.getramon.com/ramon.js"}}}}},"SessionLookupRequest":{"type":"object","required":["externalReferences"],"properties":{"externalReferences":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}}}},"SessionLookupResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SessionLookupRow"}}}},"SessionLookupRow":{"type":"object","required":["externalReference","captured","eventCount","firstEventAt","lastEventAt","humanScorePercent","scoreBand","scoredAt","modelVersion"],"properties":{"externalReference":{"type":"string","format":"uuid"},"captured":{"type":"boolean"},"eventCount":{"type":"integer","minimum":0},"firstEventAt":{"type":"string","format":"date-time","nullable":true},"lastEventAt":{"type":"string","format":"date-time","nullable":true},"humanScorePercent":{"type":"number","minimum":0,"maximum":100,"nullable":true},"scoreBand":{"type":"string","enum":["automation-like","review","human-like"],"nullable":true},"scoredAt":{"type":"string","format":"date-time","nullable":true},"modelVersion":{"type":"string","nullable":true}}},"StartScoringRunRequest":{"type":"object","properties":{"force":{"type":"boolean","default":false,"description":"Re-score sessions that already have a score."}}},"ScoringRunResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ScoringRun"}}},"ScoringRun":{"type":"object","required":["id","surveyId","force","status","total","scored","skipped","failed","failures","createdAt","startedAt"],"properties":{"id":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"surveyId":{"type":"string","pattern":"^[a-fA-F0-9]{24}$"},"force":{"type":"boolean"},"status":{"type":"string","enum":["running","completed","failed"]},"total":{"type":"integer","minimum":0},"scored":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"failures":{"type":"array","items":{"$ref":"#/components/schemas/ScoringFailure"}},"error":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ScoringFailure":{"type":"object","required":["sessionId","message"],"properties":{"sessionId":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}},"SessionDeletionResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SessionDeletion"}}},"SessionDeletion":{"type":"object","required":["reference","status","attempts","requestedAt","updatedAt","completedAt","error"],"properties":{"reference":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","completed","failed"]},"attempts":{"type":"integer","minimum":0},"requestedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"error":{"type":"string","nullable":true}}}}}}