# Build an app on the REST API

> What your agent can build on Anectico's REST API, where it runs, which credential it holds, and which operations an app may rely on.

Canonical page: https://anectico.com/docs/apps/architecture/


Your agent can build a program on Anectico's REST API: a status board for your team, a support page
that shows a customer's recent problems, a chat bot that answers "who is on call?", or a nightly
report. This page is the architecture every such program follows.

## Who does what

| Anectico supplies | Your agent and you supply |
| --- | --- |
| The REST API, its credentials, the API contract, limits and a skill that teaches your agent | The program's code, written by your agent in your own workspace |
| | Hosting, deployment, secrets and operation of the program |
| | Authentication and authorization of your program's own users |

Anectico does not host your app, deploy it, run it, generate a frontend or scaffold for it, or keep it
running. There is no app catalogue, no app builder and no "create app" operation, and Anectico runs no
model or maintenance job on your app's behalf.

## Where the program runs

An app runs on a backend you control. A browser, chat frame or mobile app talks to that backend.
A separately approved [browser aggregate view](/docs/apps/browser-aggregate-view) may read a fixed
projection directly with a five-minute token; its management parent stays on your backend.
A deliberately public [static aggregate page](/docs/apps/static-aggregate-view) needs no
backend and publishes only its finite, revocable projection credential.

| Host | Credential |
| --- | --- |
| Your server or internal-tool backend | A dedicated [project-scoped API key](/docs/reference/authentication#project-scope) for this app, kept in the server's secret store. |
| A chat bot's backend | The same: the key stays on the bot's server, which checks each workspace and user request itself. |
| A scheduled job | A dedicated, least-scope project key in the scheduler's secret store, with a fixed project and explicit time windows. |
| A browser page or chat frame | Calls your backend. Your backend signs in its own users and exposes a fixed API for the data they may see. Never put an Anectico management key in browser code, storage, source maps, URLs or logs. |
| A static page sharing a public aggregate | A reviewed publishable grant for one saved result, expiring within 30 days; anyone copying its credential can read that projection. The management parent never reaches the page. |
| A mobile app | Calls your backend. The app binary contains no management key. Sending your app's own telemetry still uses the SDK's separate capture credential. |

Give each app its own key, name and expiry, with only the scopes the app reads. Revoking that key
stops the app's next request. It does not stop your process, delete data the app already copied, or
undo an action that was already accepted. Your program's caches, exports, logs and messages are yours
to retain and delete; Anectico's erasure cannot reach them. The credential each host holds, the
permissions a status board needs, and how to stop an app are in
[Authentication and API keys](/docs/reference/authentication#which-credential-each-host-holds) and
[Revoke an agent's access](/docs/agents/revoke-agent-access#stop-an-app-that-reads).

A read-only key is not safe to publish because it cannot write: project-wide reads can disclose
customer data. CORS does not protect a key either. It only decides whether a browser may read a
response, not whether a request runs.

A separately reviewed [browser aggregate view](/docs/apps/browser-aggregate-view) uses an immutable
grant, exact origins and a five-minute token minted by its backend parent. Other clients keep the
backend pattern above.

## Which operations an app may rely on

Not every REST operation is an app operation. Each operation has an audience and an app
qualification.

| Audience | What it is for | App use |
| --- | --- | --- |
| App data | Your data and configuration, read or changed with a project key | As qualified below |
| Customer control | Keys, members, billing, privacy, connections, agent control, data export | Done by you or your agent with explicit authority and confirmation, never from the app's runtime key |
| SDK intake | Telemetry, replay, surveys, flag and experiment delivery from SDKs and build tools | Only through the SDK's own credential |
| Protocol | Sign-in, MCP, discovery documents, webhook and alert receivers, probes, heartbeats, Live displays | Each keeps its own credential; none of them is an app key |
| Operator | Platform administration and health | Never |

| Qualification | Meaning for your app |
| --- | --- |
| Supported | In the app contract, with its scopes, bounds, paging, polling advice and content limits stated. |
| Restricted | Usable only after a named limit or correctness condition is met; do not build a polling app on it yet. |
| Experimental | Not yet reviewed for apps; its fields and bounds can change without notice. |
| Excluded | Not for apps. |

Today the supported operations are:

| Operation | Scopes | What it returns |
| --- | --- | --- |
| `GET /api/v1/analytics/insights/{id}` | `insights:read` | One saved insight definition and its revision. It does not run the insight. |
| `GET /api/v1/analytics/results/{result_id}` | `analytics:read`, `persons:read`, plus the result's own source scopes for its payload | A saved analytics result. Reading it runs no query, and a ready result never changes. Poll a pending result with backoff, no more than once every five seconds. |
| `GET /api/v1/oncall/schedules/{id}/on-call` | `oncall:read`, `projects:read`, `members:read` | Whether someone is on call for one schedule at one instant, and their member ID. Never their contact details. |

Each of these is held to the key's project. The list grows as more operations are reviewed and their
limits are published. Service health, trace search, replay steps, person lists, analytics execution,
time-windowed telemetry reads and writes are restricted until their limits, coverage reporting and
write recovery are published.

## Stability before the first supported release

Anectico is in early access. Until the first supported release:

- any route or response shape may change, with no deprecation period;
- every contract is experimental, including those of supported operations;
- pin the exact Anectico release and contract you tested, and re-test before moving; the deployment
  you call publishes its contract with a digest, and [Pin the contract your app is built on](/docs/apps/contract)
  shows how your agent fetches and verifies it.

At the first supported release, the release notes will name the exact set of supported app operations
and their compatibility and deprecation policy. The promise starts at that release. Other `/api/v1`
operations do not become stable app operations by being listed in the REST reference.

## Worked examples

Four runnable programs show the whole job, each with its host, project, permissions, secret, contract
pin, the qualification of every operation it calls and what that qualification means for it:

| Example | Host | Reads |
| --- | --- | --- |
| [Team status board](/docs/apps/status-board) | Your server, many signed-in viewers | The service snapshot, once a minute |
| [Support page](/docs/apps/support-page) | Your support tool's backend | A person search and one person's counts |
| [Slack on-call bot](/docs/apps/slack-bot) | Your bot's backend | Who is on call for one schedule |
| [Nightly report](/docs/apps/nightly-script) | Your scheduler | Every page of issues in a window, and a saved analytics result |

They share [Give an app its own key](/docs/apps/credentials) and
[Polling, retries and refusals](/docs/apps/polling-and-streaming).

## Ask your agent to build it

Install the skill pack (`anectico skill install`) and describe the program in your own words. The
[build-an-app skill](/docs/agents/skills#anectico-build-an-app) teaches your agent the whole job: read
and pin the contract your deployment serves, choose the operations and say which are restricted, give
the program its own key, write it with placeholders for every secret, handle each refusal and unknown
state, run it on real data, prove that it follows changed data and that its access can be stopped, and
hand it back with its limits. The skill is ready to install, which is not evidence that any host has
run it end to end.

## Related

- [Your agent builds on the API](/docs/agents/build-on-the-api): the idea, what you review, and what has been run
- [Pin the contract your app is built on](/docs/apps/contract)
- [REST API conventions](/docs/reference/rest-api)
- [API keys and project scope](/docs/reference/authentication)
- [Limits](/docs/reference/limits)

## Browser aggregate sharing

The approved browser aggregate protocol is separate from the backend examples. It supplies no hosted
builder, runtime or app catalogue. Your backend authenticates visitors and mints a temporary token for
one approved saved result; the management key stays on that backend.

See [Share a saved aggregate with a browser page](/docs/apps/browser-aggregate-view) for the full
credential, theft, lifetime, privacy and external-copy contract.