Endpoint
Authentication
Tool: get_correl8_guidelines
Call once at the start of each conversation (do not re-call). Pass user_id when you have a stable end-user id.
Returns JSON:
observations— when and how to callpost_observations(project-configurable in the app, or defaults)research— only included when this project has at least one active research study; how to conduct studies and callpost_research_answer
Tool: get_active_studies
Active research studies for a user. Pass user_id. Call before investigating a study, and again whenever you need the latest logged answer.
Returns JSON:
studies: [] when none are active for that user. Sampling, duration, and answer caps are checked server-side — eligibility_criteria is not; your agent must evaluate it against the current user/conversation before pursuing the study. Each entry’s answer is the answer already logged for this user (null if none yet). Use an entry’s 0-based index in the studies array as study_index for post_research_answer.
Tool: post_observations
Post one or more observations in a single call. Pass user_id, interaction_id, and user_sentiment once, then an observations array (minimum 1, maximum 50).
Parameters
string
required
Stable identifier for the end user (one per call).
string
required
Stable identifier for the conversation thread (one per call), e.g.
conv_9f3a2b1c.string
required
Label for all items in the call:
very negative, negative, neutral, positive, or very positive. See User sentiment.array
required
List of observation objects. Each item uses the fields below.
string
required
Short plain-text summary (one line).
string
required
Plain prose with context — what happened, why it mattered, and how to reproduce when relevant.
Response
Returns a list of created observations (same shape as RESTresults). On validation errors, the tool raises an error with details.
Tool: post_research_answer
Post a research study answer after learning what the study targets through natural conversation. Follow the research guidelines from get_correl8_guidelines and the study list from get_active_studies. Args: study_index (0-based in the studies array from get_active_studies), user_id, interaction_id, answer.
Server-side processing
After a successfulpost_observations call, tag matching and issue digest run asynchronously per observation. See Concepts for billing limits.
Custom integration (REST API)
Same batch shape atPOST /v1/project/{project_id}/observations/ with top-level user_id, interaction_id, user_sentiment, and { "observations": [ … ] }. Guidelines: GET …/correl8-guidelines/?user_id=…. Active studies: GET …/research/studies/?user_id=…. See Advanced ingestion.