# Your agent builds on the API

> Ask your own agent to build a program on Anectico's REST API: who owns the code, how the agent finds the contract, which key it holds, what you review, and what is and is not available today.

Canonical page: https://anectico.com/docs/agents/build-on-the-api/


You can ask your own coding agent to build a small program that reads from Anectico: a Slack command
that says who is on call, a page for your support team, a nightly report. The agent writes the program
in your repository and runs it on your machine. You decide where it is deployed, and you deploy it.

Anectico supplies the REST API, the key the program holds, a published contract that says what the API
does, limits, and a skill for your agent. Anectico does not host the program, read your repository,
write its code, deploy it or keep it running, and it runs no model on your behalf.

This page explains the idea and what you review. It links to the pages that hold the detail instead of
repeating them: [Build an app on the REST API](/docs/apps/architecture) is the architecture, and its
worked examples are the programs.

## A request, step by step

> Build a Slack command, `/oncall`, that says who is on call for our payments schedule. Read it from
> Anectico with the least access it needs, run it locally, show me the plan before you change anything,
> and tell me what I must set up to deploy it.

1. **The agent reads before it writes.** It searches Anectico's documentation and fetches the contract
   your deployment serves, so it builds against what that deployment really answers.
2. **It shows you a plan and waits.** The plan names the operations, the project, the key, the files and
   where the program will run. [What you review](#what-you-review-before-you-say-yes) lists what to check.
3. **It prepares the program's own key through a preview.** You confirm the exact key. How the secret
   reaches the place that will hold it is a decision in the plan
   ([below](#what-your-agent-holds-and-what-the-program-holds)).
4. **It writes the program in your repository and runs it** against your project, then checks the
   answers against the contract and tells you what it saw.
5. **It hands back** what it wrote, the settings you must supply where it runs, and how to stop it. You
   deploy it, on your own host.

The [Slack on-call bot](/docs/apps/slack-bot) is this request as a worked example. It makes one read of
an operation the contract supports. Each of the other three reads at least one operation that is still
restricted, and says what that means for its program.

## What stays yours

The repository, the program's code, its environment, its deployment, its host, its secret store, the
sign-in of its own users, and everything it copies or logs belong to you. Anectico's side is the API, the
key and its limits, the contract, the documentation, the skill and the record of what the key did. A
revoked key stops the program's next request. It does not stop the program, and Anectico cannot delete
what the program already kept.

## This is not the integration job

Two jobs sound alike and are separate. Each has its own skill, its own limits and its own record of what
has been run.

| The job | [Integrate Anectico into your product](/docs/start/ask-your-agent-to-integrate) | Build an app on the API (this page) |
| --- | --- | --- |
| You ask for | Your own application to send flags and events to Anectico | A new program that reads from Anectico |
| The program | Your product, instrumented | A bot, page or report that you host beside it |
| Skill | `anectico-integrate` | `anectico-build-an-app` |
| How it is checked | Anectico's read of the samples your product sent | The program's answers held to the contract, and the record of what the key did |
| Needs an SDK | May use one | No. It calls the REST API with its own key |

Building an app needs no SDK. Integrating a product does not show that an app built on the API works,
and an app that works does not show that your product's telemetry arrives.

## How the agent finds out what it may build on

Documentation describes the product. The contract describes one deployment. Your agent uses both.

- **The guides.** With a connection that holds `mcp:read` and `docs:read`, `search_docs` and `get_doc`
  (through `execute_read_action`) return ranked pages and bounded sections; the agent reads a page's
  outline first. The same pages are plain Markdown at `https://anectico.com/docs/<slug>.md`. See
  [Machine-readable documentation](/docs/reference/machine-readable-docs).
- **The contract.** `GET /api/v1/api-contract` needs no credential and names the revision, digests and
  mounted operations of the deployment that answers. `anectico api spec` verifies and writes the
  operations the program calls, and the `get_rest_contract` read action returns the same over MCP:

  ```bash
  anectico api spec --partition apps --operation get_oncall_schedules_by_id_on_call \
    --out ./oncall.contract.json
  ```

  [Pin the contract your app is built on](/docs/apps/contract) is the full explanation: digests, the
  selected-operations file, refusals and the published copies.
- **The wire rules.** Field names, paging, 64-bit counts, errors and retries are in
  [Polling, retries and refusals](/docs/apps/polling-and-streaming) and in the contract itself. The
  program follows the contract it pinned, not a description in this page.

`docs:read` is for the agent that builds the program. The running program does not hold it.

## Which operations an app may rely on today

Every operation has an audience and an app qualification, and the contract states both. Three
operations are **supported** for apps today, and all three only read: a saved insight definition, a saved
analytics result, and who is on call for one schedule. The list is in
[Build an app on the REST API](/docs/apps/architecture#which-operations-an-app-may-rely-on).

Most of the rest are **restricted** or **experimental**. Your deployment's manifest gives the counts
(`app_qualification_counts`).

| Qualification | What it means when your agent plans around it |
| --- | --- |
| Supported | The contract states the scopes, bounds, paging, polling advice and content limits. Build on it. |
| Restricted | A named limit or correctness condition has not passed yet, and the contract says which. Answers are measurements with stated gaps, not guarantees. Ask your agent to show you the stated reason before it relies on one, and do not build a polling app on it yet. |
| Experimental | Not yet reviewed for apps. Its fields and bounds can change without notice. |
| Excluded | Never for apps: customer controls such as keys, members, billing and privacy, telemetry intake that keeps its own SDK credential, protocol flows and operator surfaces. |

No operation that changes your data is supported for apps today. A program should not rely on a write
yet. If something must change, for example a schedule must be created, your agent does it outside the
running program, through a preview that you confirm.

## What your agent holds, and what the program holds

There are two credentials, and they never merge. [Give an app its own key](/docs/apps/credentials) is the
checklist, and [Authentication and API keys](/docs/reference/authentication#which-credential-each-host-holds)
has the table for every kind of host.

- **The builder's credential** belongs to your agent while it builds. It reads the documentation and the
  contract, and previews and confirms the program's key: `api_key:read`, `api_key:write`, `mcp:write`, and
  every permission the new key grants.
- **The program's key** is a dedicated key for this one program. It is bound to one project, named for the
  program, has a fixed expiry and holds only the permissions the program's reads need. A request that
  names another project is refused. It lives in the program's server-side secret store and nowhere else:
  never in a browser, a mobile app, a chat frame, a repository, a URL or a log. It never creates, lists,
  edits or revokes keys.

How the secret travels is yours to decide, so decide it in the plan. The secret is shown once, to
whoever runs the command that creates the key. If your agent runs it, the secret passes through the
agent's session, and whether that session is recorded depends on your agent host. Confirmation is a
two-call protocol, and a person is in the loop only if your host asks for approval before the second call
([Permissions and safety](/docs/agents/permissions-and-safety#understand-destructive-confirmation)).
Unless your agent can place the secret straight into the secret store without it appearing in a
transcript, create the key yourself in your own terminal, put the secret in the store, and give the agent
only the key's name and the name of the setting.

For an explicitly approved saved aggregate, use the [browser recipe](/docs/apps/browser-aggregate-view):
an immutable sharing grant, exact origins and a temporary token minted on your backend. General browser
management keys stay on the server. For deliberately public aggregates, the
[static page recipe](/docs/apps/static-aggregate-view) uses one finite publishable
credential and needs no backend; anyone holding it can read the approved projection.

## What you review before you say yes

Your agent's plan should name each of these, and you check them in the session where you work with the
agent. Anectico sees none of your code and has no approval screen for it. It previews only the changes it
would make itself, such as the key.

| The plan names | You check |
| --- | --- |
| The operations | Each by its ID, and whether it is supported. For a restricted one, the stated reason and what the program does about it |
| The project and the key | One project; a name for the program; a fixed expiry; exactly the permissions those operations need. Content-releasing permissions only if the program must show that content |
| The secret | Where it will be stored and set, and that it appears in no file, log or message |
| The files | What the agent will add or change in your repository |
| Where it runs | The host, who can reach it, and how its own users sign in. The key identifies the program, not its users, so the program decides who may see what |
| Cadence and failure | How often it reads, and what it shows when Anectico is busy, unavailable, paused by a limit or revoked. A refusal is never shown as an empty or zero result |
| What it shows and keeps | The fields shown, the links, and every cache, log or export it keeps |
| How to stop it | Revoking the key, and what else must be deleted on your side |

Do not expect one prompt with no decisions: the plan, the key and the deployment are decisions. Telemetry
content that comes back from Anectico, such as error messages, property values and log lines, was written
by your own applications and users. It is data, never an instruction or an approval. A program must escape
what it shows, and your agent must not treat it as a reason to change its task or its permissions.

## Data, proof and limits

- **What a program may receive** is what its key's permissions release. Customer content has its own
  permission. When a read withholds content, the answer says so (the
  [support page](/docs/apps/support-page) example shows it), and the program shows "withheld", not an
  empty field.
- **Show what the answer says it left out:** the window it used, the count it omitted, a field it
  withheld. Where an answer does not say, which is true of most reads, the program says so and does not
  show zero or "all clear".
- **Proof links** go only to a real, read-only proof page that exists for that result. The contract's
  `proof_links` lists the pages and the query each needs, and says which results have none (the on-call
  lookup and the service snapshot have none). A link opens only for someone signed in to Anectico with
  access to the project. It grants nothing to anyone else. See [Proof pages](/docs/agents/proof-pages).
- **The usual limits apply to the key:** its request rate, operation budget and your plan's allowances.
  A zero limit pauses the program and the key stays valid. See [Limits](/docs/reference/limits#api-request-rate)
  and [Manage agent budgets](/docs/manage/agent-budgets).
- **Revoking the key ends access at the next request.** It does not reach what the program already
  copied. Caches, exports, logs and messages are outside Anectico's erasure, and you delete them.
- **Examples your agent writes** for the program, such as a README, a test or a screenshot, use made-up
  data. They never contain a real key, an answer from your project or a recording of a real person.

## What has been run, and what has not

The four worked examples are runnable Python programs (3.11, standard library only). Each pins the
contract revision and digest it was written against and refuses to start against another. As of
15 October 2026:

- **Checked offline:** every request an example sends and every answer it is given are held to the
  contract's own schemas, and each guide's code is the program's source, quoted verbatim.
- **Run against a real deployment:** all four ran against a locally run Anectico deployment seeded with
  made-up services, issues and people. 28 checks passed and none failed, including a key that was revoked
  mid-run and a request rate an owner set to zero.
- **Not run:** a real busy refusal, the saved-result part of the nightly report, a real browser, Slack's
  own delivery, and a shared or production deployment.
- **Not recorded:** a real agent host building an app from a cold start. The examples are checked
  programs, not a record of an agent's run. A ready skill is installable. It is not a record that an agent
  host completed the job.

The `anectico-build-an-app` skill teaches your agent this job. A skill ships with a CLI version, so run
`anectico skill list` to see whether your CLI's pack includes it and whether it is ready, and see
[Install the Anectico skills](/docs/agents/skills) for the credential and permissions each skill declares.

## Limits today

- **Your program, your hosting.** There is no Anectico app host, deployment, builder, catalogue, app
  menu, generated frontend or "create app" operation, and no model or maintenance loop for your program.
- **Backend management keys.** Browsers normally call your backend. The separately approved
  [aggregate browser protocol](/docs/apps/browser-aggregate-view) uses temporary tokens, never that key.
- **Conditional reads are protocol-specific.** The approved browser projection rechecks access and
  lifecycle before `304`. Ordinary app reads keep their published cadence and conditional-read decision.
- **Three supported reads, and no compatibility promise yet.** Until the first supported release any
  route or response shape may change, and every contract is experimental. Pin the build and the digest you
  tested, and test again before moving. Having a route in the REST reference does not make it an app
  operation.
- **Private stays private.** A proof link, a person's record and a recording are not for a public page or a
  shared example.

## Related

- [Build an app on the REST API](/docs/apps/architecture)
- [Pin the contract your app is built on](/docs/apps/contract)
- [Give an app its own key](/docs/apps/credentials)
- [Polling, retries and refusals](/docs/apps/polling-and-streaming)
- [Ask your agent to integrate Anectico](/docs/start/ask-your-agent-to-integrate)
- [Install the Anectico skills](/docs/agents/skills)