Handing this documentation to Claude or Codex
The single-file copy of these docs, and a ready prompt for saying «connect this service for me».
Most people integrating Segmentic now do it with an agent sitting next to them. This page is what to hand that agent, and what it will get wrong if you do not.
If you want the agent to query your account rather than write code against it, that is a different thing and it is on the MCP server page.
The three files, and which one to use
The documentation is written once, as Markdown, and every artefact below is a view of the same source. A page that renders is a page that exports, so none of these can drift from what you are reading.
| File | What it is | When to use it |
|---|---|---|
| /llms.txt | The index. One line per page, with its URL and a one-sentence description, plus a short statement of what Segmentic is. A few kilobytes. | When the agent can fetch URLs. It reads the index, then fetches the two or three pages it needs. |
| /llms-full.txt | Every English page, concatenated, with a header naming the hosts and the key types. | When the agent cannot fetch URLs, or when the job is "connect this service" and it needs the whole thing at once. |
| /docs-en.md | The same text as llms-full.txt, served as a file with a name and a download disposition. | When you want a file to attach to a message, keep in the repository, or read offline. |
| /docs-fa.md | Every Persian page as one downloadable file, segmentic-docs-fa.md. | Same job, in Persian, which is the original language of these pages. |
| /openapi.json | Both HTTP surfaces, machine readable. Valid YAML as well as JSON. | Generating a client, or feeding a tool that wants a schema rather than prose. |
curl -s https://segmentic.net/llms.txt
curl -s -o segmentic-docs.md https://segmentic.net/docs-en.md
curl -s -o segmentic-docs-fa.md https://segmentic.net/docs-fa.md
curl -s -o segmentic-openapi.json https://segmentic.net/openapi.json
llms.txt is in English even though the Persian pages are the original. The reader of that file is a model choosing which page to fetch, the convention's own examples are English, and every model in use reads an English index more reliably than a Persian one. The pages it points at exist in both languages and the Persian set is linked at the foot of it.
There is no llms-full-fa.txt. The convention names one file, and a second one under an invented name would be found by nothing. The Persian bundle is /docs-fa.md.
llms-full.txt carries a header before the first page, stating the two hosts and the two key types in the imperative. That header is not decoration. An agent handed the pages without it answers questions about hosts and keys from whatever it remembers about other analytics products, and the two most expensive mistakes it makes are using the wrong host and using the wrong kind of key.
A prompt you can paste
Copy this as it is. It is written to be the first message of a session, and everything in it is there because an agent got it wrong without it.
Connect my product to Segmentic, an event collection and messaging platform.
First, read https://segmentic.net/llms-full.txt in full. That is the entire
documentation. Do not answer from memory of other analytics products: the
hosts, the key names, the error codes and the event model are not the same,
and a plausible guess here costs me an afternoon.
There are two hosts and two kinds of key. They are not interchangeable.
Sending events, from my website or my mobile app:
host https://in.segmentic.net
key wk_seg_... public by construction, it ships inside the client
bundle, and it can only write events
Reading and managing audiences, campaigns and reports, from my backend:
host https://api.segmentic.net
key sk_seg_... secret, server side only, carries permissions
The panel a human uses: https://app.segmentic.net
Rules I want you to hold to, without me asking again:
1. Never put an sk_seg_ key anywhere that reaches a device. Not in browser
code, not in a mobile app, not in an environment variable named
NEXT_PUBLIC_ANYTHING or VITE_ANYTHING, not in a client-side config file.
If a feature needs one, the call happens on my server.
2. Before you choose any event name, read the event design page and the
event dictionary. The server does not enforce a naming convention; it
accepts almost any string. So a bad name is not an error, it is history.
3. Never guess the name of an event or a trait that already exists. Confirm
it against the schema endpoints, with the sk_seg_ key:
GET https://api.segmentic.net/v1/schema/events
GET https://api.segmentic.net/v1/schema/traits
A name that does not exist is accepted everywhere and matches nobody,
which looks identical to a real audience of zero. If you cannot reach the
schema endpoint, stop and ask me rather than guessing.
4. Before you assume a management call will work, call
GET https://api.segmentic.net/v1/whoami. It returns the exact permission
list that key carries. Call GET /v1/capabilities for which features this
deployment serves and the limits it publishes, and use those numbers
rather than hardcoding your own.
5. Read the errors page before you write any retry logic. 401 means the
credential is wrong and retrying will never fix it. 429 with the code
budget_exhausted means wait, and Retry-After says how long. 503 is
transient and worth a backoff.
6. Anything that sends a message to a real person: show me the exact call
before you make it, and do not make it until I say yes.
Start by proposing the list of events my product should send, and one line
for each saying which question it answers. Do not write any code until we
have agreed on that list.
Two things you may want to add, depending on the job. If the agent is writing a backend integration, tell it which language and framework, because the documentation shows curl and it will otherwise pick for you. If you already send events and are adding messaging, tell it to start from GET /v1/schema/events and work from the names that are already there.
What agents get wrong here specifically
These are not general warnings about language models. Each one is a failure this API produces, and most of them are named in the comments of the MCP server, which was written after watching agents use it.
It invents identifiers, and nothing tells it off. A filter naming an event that does not exist compiles cleanly and returns zero. To a model that reads as "nobody matches", not as "that event does not exist", so it reports the number and moves on. This is the single most expensive mistake here, and the reason the schema endpoints are in the prompt above.
It reads far more than it needs, and then believes it saw all of it. GET /v1/segments and GET /v1/campaigns accept limit and cursor and ignore both. Each returns the 200 most recently updated rows, including the whole filter tree of every segment, so an agent that asks "what audiences do we have" pulls those two hundred into its context. The cap is silent: no next_cursor, no has_more, no count. On an account with 250 segments the agent reports a partial list as a complete one, confidently, and there is no route to the other 50.
It loops on expensive calls. Counting an audience costs 25 units of a 600 unit per-minute budget, so 24 counts in a minute exhausts it. An agent trying filter variations will hit budget_exhausted inside a minute. Give the agent its own key: the budget is counted per key, so a runaway agent then cannot starve the key your order pipeline depends on.
It collapses rates into one percentage. SMS has no read receipt, so the open count for an SMS campaign is zero and it means nothing. Every rate in a campaign report arrives as a numerator with a named denominator, measurable_open and measurable_click beside opened and clicked. An agent that divides opened by issued reports a zero percent open rate for SMS, which is confidently wrong. Tell it to quote both numbers.
It quotes the middle of a range as if it were a measurement. The uplift section carries lift, lift_low and lift_high. The point estimate on its own is not a measurement, it is the middle of a range, and an agent that reports "the campaign lifted conversions by 11.7 percent" has thrown away the only figure that says whether the campaign worked at all.
It invents an idempotency key. On a transactional send the key must identify the real-world event, for example order-8821-shipped. An agent that generates a random one gets a fresh key on every retry, and a retry then sends a second message to a real phone.
It reads a 200 as delivered. A transactional send can answer 200 with status: "suppressed" and a reason, which means the message was deliberately not sent: an unsubscribe, a channel opt-out, a suppression, no address on file. Check status before telling anybody the notice went out.
It cannot read most validation errors. The public API answers with a code and a message for authentication, permission, budget and filter errors. Several handlers behind it answer with a plainer shape that clients cannot parse, so an agent reports http 400 and cannot say why. When that happens, make the same call yourself with curl and read the body. The full table is on the errors page.
It trusts text your own team wrote. Segment names, campaign names and the Persian descriptions reach a model as plain text with no untrusted-content wrapper. If somebody names a segment with an instruction aimed at a model, the model reads it as an instruction. Treat the free-text fields of the panel as an input channel into your agent, because that is what they are.
Checking what the agent built
Four commands, in the order worth running them.
curl -s https://api.segmentic.net/v1/whoami \
-H "Authorization: Bearer sk_seg_REPLACE_ME"
{
"tenant_id": 7,
"api_key_id": 3,
"role": "analyst",
"permissions": [
"analytics.read", "audit.read", "campaign.read", "data.export",
"event.read", "journey.read", "member.read", "profile.read",
"segment.read", "settings.read", "template.read"
],
"scoped": false
}
curl -s https://api.segmentic.net/v1/capabilities \
-H "Authorization: Bearer sk_seg_REPLACE_ME"
{
"version": "v1",
"features": {
"segments": true,
"campaigns": true,
"analytics": true,
"transactional": true,
"export": false,
"import": true,
"journeys": true,
"ingest": true,
"async_exports": true,
"campaign_approval": true
},
"limits": {
"max_page_size": 100,
"max_preview_rows": 100,
"max_batch_size": 500,
"estimate_sample": 100,
"query_timeout_sec": 30
}
}
Do not read the features values above as a sample to copy. Each flag is exactly whether that subsystem is wired on that deployment, so it differs per install, and reading it is the whole point of it. Three of them, export, import and journeys, gate no route on this mux at all: true does not give you a public endpoint.
Those limits are published rather than documented so that no client and no agent hardcodes a number we later change. If the agent wrote 500 into a batching loop instead of reading max_batch_size, that is a review comment.
curl -s https://api.segmentic.net/v1/schema/events \
-H "Authorization: Bearer sk_seg_REPLACE_ME"
Read last_seen on every row, not just volume. An event with a large volume and a last seen date three weeks ago is an integration that broke, and volume alone looks healthy for a month afterwards, because the window is ninety days.
Then grep what ships to the browser. This is the check nobody runs and the one that matters most:
grep -r "sk_seg_" ./dist ./build ./.next ./public 2>/dev/null
grep -rn "NEXT_PUBLIC_.*SEG\|VITE_.*SEG" ./src 2>/dev/null
Anything the first command finds is a secret you now have to revoke, from Settings, Connections and integrations, API keys in the panel. Revocation takes effect on the next request.