OppticsDevelopers
Opptics · Guides API

Let the agent write the guide. Let a human aim it.

Your agent already knows the buyer, the problem, and the order to tell the story in. Give it an API key and it can write that story into Opptics. Mapping moments to the real interface stays with the person who knows the app.

Create an API keyRead the reference
Guides created through the API are drafts. Someone maps the moments in the extension before reps ever see them.
POST /v1/guides
curl https://api.opptics.team/v1/guides \
  -H "Authorization: Bearer $OPPTICS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Pulseflow for ops leaders",
    "product": "pulseflow",
    "brief": { "buyer": "Priya · Operations" },
    "moments": [
      { "title": "Start where the pain is",
        "what_it_does": "Surfaces failed runs in one view",
        "why_it_matters": "Teams find customer impact sooner",
        "when_relevant": "Failure discovery is reactive",
        "intent": "open Runs and filter to Failed" }
    ]
  }'

The round trip

01

Agent writes

Brief, moments and steps — all written as intent.

02

Opptics drafts

The guide exists, unpublished, with no mapped targets.

03

A person maps it

They click through the described moments in the extension.

04

Publish and assign

The guide becomes ordinary, assignable product learning.

POST/v1/guidesguides:write

Creates a draft guide with its brief and moments in one call. The guide is invisible to reps and cannot be assigned until every step has a target. Idempotent on Idempotency-Key.

Parameters
titlestringShown to reps in the assignment card.
productstringSlug of an approved product domain in this workspace.
briefobjectBuyer, company shape, problem, existing tools, and the sentence to beat.
moments[]arrayOrdered moments with title, what_it_does, why_it_matters, when_relevant, intent, and marked.
moments[].intentstringMapping direction only. It does not replace the three teaching fields.
moments[].markedbooleanTrue asks the rep to answer in their own words. Two or three per guide.
moments[].steps[]arrayOptional clicks within one moment, described in words.
Request
{
  "title": "Pulseflow for ops leaders",
  "product": "pulseflow",
  "brief": { "buyer": "Priya · Ops" },
  "moments": [
    { "title": "Start where the pain is",
      "what_it_does": "Surfaces failed runs in one view",
      "why_it_matters": "Teams find customer impact sooner",
      "when_relevant": "The buyer discovers failures reactively",
      "intent": "open Runs, filter Failed",
      "marked": false }
  ]
}
Response
{
  "id": "gd_8Kx2m",
  "status": "draft",
  "mapped": 0,
  "moments_total": 8,
  "mapping_url": "https://opptics.team/guides/gd_8Kx2m"
}
Targets are never accepted in this call. CSS selectors and XPath are rejected with 422 — mapping happens in the extension, against the live DOM.