Skip to main content
An agent reaches DATALYR two ways. Both answer the same questions about one workspace. Both can change workspace objects when a person grants a write scope. Reading needs datalyr:read and nothing else. Writing needs a named key or an OAuth token that carries the matching write scope. The original workspace Agent key carries datalyr:read forever, so no key already in circulation gained write power.

Which to pick

Pick MCP when a person drives the client and can complete a browser sign-in. The token is short-lived, and no key is stored anywhere. Pick the API when code runs without a person present. See Authentication to create a key.

In-app chat is a third surface, and it never writes

The DATALYR dashboard has its own chat agent. It holds read tools and no write tools. It authenticates with the workspace Agent key, which carries datalyr:read only. The panel has no consent screen, so nobody can grant it more. It can list, read, and run dashboards and analyses. Its Save to Reports, Add to dashboard, and Save as analysis buttons are a person’s clicks, not tools the model can call.

The MCP tools

Some tools read, and others change something or start work. report_missing_capability records what no tool could do, never the question, and reads and changes no data. tools/list is the authority: read it at the start of a session and branch on what comes back. Do not hard-code the tool set.

Read tools

Ask with analytics_query

analytics_query answers any question of the form metric by dimension, filter, and time. It takes a plan, not SQL. The workspace comes from your sign-in.
Funnels, retention, cohort LTV, and one person’s journey keep their own tools: get_funnel, get_retention, get_ltv, and get_user.

Tools that write or start work

Write scopes

Any workspace member can use a write scope over OAuth, except the ads scopes: those need an owner or admin. A named key with a write scope needs the owner to grant it. The ads scopes are the levels on Access levels and who uploads. No ads scope changes an ad account from chat: every ad write goes to a review page, where an owner or admin uploads it. The setup steps for Claude and Codex are on Connect Claude or Codex.

What an agent can change, and what stops it

An agent can change conversion rules, trackable links, saved reports, dashboards, analyses, and custom metrics. It can create and revoke share links, and draft a container script. With an ads scope, it can also propose ads and ad changes for connected ad accounts, which a person uploads from a review page: see Agent ads. It cannot do anything else. Tracking domains, filter settings, team membership, and billing have no agent surface at all. A container script is arbitrary JavaScript on every page of your site, next to your checkout. That is why a leaked key can draft one and can never ship one.

Exports return a job, not a file

create_export answers with a job id. Poll get_export_status until the state is completed, then read download.url. Two clocks run on a finished export. The signed URL lasts one hour, so fetch it on use rather than storing it. The file itself is deleted seven days after creation.

What the HTTP API adds

Every MCP data tool maps to a /v1 endpoint, so the API covers the same ground with three extras an agent framework often wants. It also carries routes MCP does not expose at all, including POST /v1/signup.

Reading a response safely

These five rules keep an agent from reporting a number that isn’t there.

Sending events is a different credential

Reading and writing do not share a key or a host. An agent that also sends events uses the write key against https://ingest.datalyr.com. See Ingest API. The write key reads nothing. Never point POST /attribution/lookup at an email address a user typed into your own product.

Machine-readable docs

Verify

  1. Ask your client: List my DATALYR workspaces.
  2. Confirm the reply names the workspace you expect.
  3. Run the curl on Authentication with your Agent key.
  4. Confirm the response names the same workspace.

When it doesn’t work

Next