canonical: https://jentic.com/apis/glean.ly/glean-ly # Glean.ly API The Glean.ly API powers the Glean.ly research repository - a tool product teams use to capture experiments, facts, insights, and conclusions from user research and product analytics. Agents can read and write the structured research artefacts that connect raw observations to themes, labels, and tags, enabling automated ingestion of survey results, analytics findings, and synthesis output. Authentication is OAuth 2.0 via oauth.glean.ly and Bearer tokens issued by that flow. ## For AI agents Capture and read research artefacts - experiments, facts, insights, conclusions, themes, and labels - from a Glean.ly research repository. ## Scope Does not handle event tracking, A/B test execution, or quantitative data warehousing - use for capturing and reading Glean.ly research artefacts only. ## Capabilities - Create, read, and update experiments and the facts captured against them - Record insights derived from research and link them to source experiments - Capture conclusions that synthesise insights into shippable decisions - Manage the themes, labels, and tags taxonomy used across the repository - Authenticate via OAuth 2.0 against the oauth.glean.ly authorisation server - Connect a research repository to product analytics ingestion pipelines ## Use cases ### Survey Result Ingestion Push structured survey findings into Glean.ly so the research team can theme and synthesise them. POST `/api/experiment` creates the experiment shell, POST `/api/experiment/{id}/fact` records each individual finding, and POST `/api/insight` captures the synthesised observation that downstream conclusions reference. Example prompt: Create an experiment titled 'Pricing Survey Q2 2026', add 5 facts with respondent quotes, and post one insight tagged 'pricing' ### Insight-to-Decision Audit Trail Build an audit trail that connects shipped product decisions back to the research insights that supported them. Conclusions in Glean.ly link to the insights they synthesise, and the API exposes those edges so an agent can render a 'why we shipped this' page from the conclusion id alone. Example prompt: Fetch conclusion id 7821 and return its title plus every linked insight id and source experiment ### Taxonomy Maintenance Keep the themes, labels, and tags vocabulary tidy across a growing repository. The `/api/themes`, `/api/labels`, and `/api/tags` endpoints let an agent enumerate the current taxonomy, detect duplicates or near-duplicates by string similarity, and re-tag artefacts that drift from the canonical names. Example prompt: List every theme via `/api/themes`, group by lowercased name, and return any pair of themes whose names match after stripping whitespace ### AI Agent Research Capture Use Jentic to let an AI agent file new facts and insights into Glean.ly the moment a user shares them in chat. The agent issues an intent like 'log a research insight', Jentic resolves POST `/api/insight`, executes it with the OAuth Bearer token from the vault, and returns the new artefact id for confirmation. Example prompt: Through Jentic, post an insight 'Users abandon checkout when shipping cost is hidden' linked to experiment id 9911 and return the new id ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/api/experiment` | Create an experiment record | | POST | `/api/experiment/{id}/fact` | Add a fact to an experiment | | POST | `/api/insight` | Record an insight | | POST | `/api/conclusion` | Record a conclusion linking insights | | GET | `/api/themes` | List repository themes | | GET | `/api/labels` | List repository labels | | GET | `/authorizeRoute` | Begin the OAuth 2.0 authorisation flow | ## Key resources - **Authentication** — OAuth 2.0 authorisation flow at oauth.glean.ly - **Experiments** — Research projects and the facts captured under them - **Facts** — Individual observations recorded against an experiment - **Insights** — Synthesised findings derived from one or more facts - **Conclusions** — Decisions or recommendations that link insights - **Metadata** — Themes, labels, and tags taxonomy across the repository ## Why Jentic - **Setup:** Wiring Glean.ly by hand means learning its bearer auth over its OAuth host and tracking which artefact endpoints capture experiments, insights, and conclusions. Through Jentic you install once, import the Glean.ly API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** Glean.ly puts the experiment id in the URL path (`/api/experiment/{id}/fact`), so a rule can pin your agent to one experiment: it can attach facts there and nothing else. You choose the operations it may call, so it records insights and conclusions only when you include those operations. - **Credential handling:** Your Glean.ly OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'record a research insight' or 'log an experiment conclusion', and Jentic returns the matching Glean.ly operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **PostHog API** — Product analytics events that feed into research insights captured in Glean.ly - **Amplitude API** — Behavioural analytics platform whose cohort findings drop into Glean.ly experiments - **Mixpanel API** — Event analytics whose insights can be filed as facts under a Glean.ly experiment ## FAQ ### What authentication does the Glean.ly API use? Glean.ly uses OAuth 2.0 with the authorisation server at oauth.glean.ly. Begin the flow at /authorizeRoute and exchange the code for a Bearer token. Through Jentic the issued token is held in your Jentic One instance and the agent only ever sees a scoped execution credential. ### Can I record an insight programmatically with the Glean.ly API? Yes. POST `/api/insight` accepts a payload describing the observation and the linked source artefact ids. Pair it with POST `/api/experiment` and POST `/api/experiment/{id}/fact` to ingest a full chain of evidence under one experiment in a single agent run. ### What are the rate limits for the Glean.ly API? Glean.ly does not publish a numeric per-token rate limit; in practice the API is sized for human-pace research-ops use and bursts above a few requests per second on write endpoints may return HTTP 429. Back off briefly and retry, and prefer batching facts under one experiment. ### How do I capture a conclusion through Jentic with Glean.ly? Search Jentic for 'record a research conclusion', load POST `/api/conclusion`, and execute with the OAuth token from the vault. Pass the linked insight ids and a clear conclusion title so the audit trail back to the supporting research is preserved in the repository. ### Does the Glean.ly API expose the themes and labels taxonomy? Yes. GET `/api/themes` returns every theme defined in the repository, GET `/api/labels` returns the labels, and the matching POST endpoints let an agent add to the taxonomy when a new piece of research introduces a category. Use these endpoints to keep tagging consistent at scale. ### Is the Glean.ly API free? API access is included in the standard Glean.ly research-repository plans rather than billed separately. Pricing tiers depend on workspace seat count and storage; consult the Glean.ly sales site for the current plan that fits your team size and research volume. ### Can I limit what my agent is allowed to do with the Glean.ly API? Yes. Jentic One is self-hosted by you, so your own rules decide which Glean.ly operations and credentials the agent can use. Because Glean.ly carries the experiment id in the URL path (`/api/experiment/{id}/fact`), a rule can pin the agent to a single experiment so it attaches facts there and nowhere else. You also choose the operation set, so it records insights via POST `/api/insight` or conclusions via POST `/api/conclusion` only when you include those operations, and it never reaches the themes or labels endpoints unless you grant them.