# Page Systems docs

Page Systems lets a chat agent send the person a small mobile web page (a flight picker, a form, a cart to review) instead of asking question after question in chat. The person answers on their phone, and the answer comes back into the same conversation.

## How it works

1. **Create.** The agent calls one tool with a typed page spec: a `title` and a `page`, the page type and its data (see [Page types](/docs/pages)).
2. **Link.** Page Systems validates the spec, hosts the page, and returns its `url`. The agent sends the link in chat; it unfurls with a preview.
3. **Answer.** The person opens the page, makes their choices, and taps its one Submit button. A page only collects the answer; it never sends the person to another site and never takes a payment. Pages stay open for 1 hour unless the spec sets `expiresAt` (at most 30 days).
4. **Confirmation.** Once the answer is accepted, the page closes and says only "Thank you." This confirms Page Systems has the answer, not that your agent acted on it. Opening the link again shows the same screen: never the page content or the answer. If the spec sets `returnLink`, the screen also shows a button to it (an https URL or an `sms:` number) until the page expires; it is a plain link the person may follow, never opened automatically, and the person can always return on their own.
5. **Result.** The answer is validated against the page type's result schema and delivered back: eve agents get a message in the same session; other integrations poll or receive a callback ([REST API](/docs/api)).

## Quickstart: eve

Coding agents: follow the [install guide](/docs/install.md), which has the exact steps and checks.

1. Install the extension (`Terminal`):

   ```
   npm install @pagesystems/eve
   ```
2. Mount it in one file (`agent/extensions/pages.ts`):

   ```
   export { default } from "@pagesystems/eve";
   ```
3. Add your API key (`.env.local (and your Vercel project)`):

   ```
   PAGE_SYSTEMS_API_KEY=ap_live_...
   ```

The extension adds the tools `pages__list_page_types`, `pages__get_page_type_schema`, `pages__create_page`, `pages__get_page_result` and `pages__cancel_page`, and a skill with the workflow. It bundles no page types: the model reads them, their schemas and their guidance from Page Systems, so new page types work without an update. When the person submits, the session receives a message starting with `[Page Systems]` that holds the result.

## Quickstart: AI SDK

`@pagesystems/ai-sdk` is a thin client for four API calls, as AI SDK tools: `list_page_types`, `get_page_type_schema`, `create_page` (returns `{ url, id, expiresAt }` for the model to send as a link) and `get_page_result`. It bundles no page types, so new ones work without an update. Page Systems hosts and renders every page. Set `PAGE_SYSTEMS_API_KEY`; `createPageSystemsClient()` gives you the same four calls without the AI SDK.

```ts
import { pageSystemsTools } from '@pagesystems/ai-sdk';
import { isStepCount, streamText } from 'ai';

const result = streamText({
  model,
  messages,
  tools: pageSystemsTools(),
  // Several steps: list_page_types, get_page_type_schema, then create_page.
  stopWhen: isStepCount(5),
});
```

To tell the model when to send a page, [add the skill to your system prompt](#add-the-skill-to-your-system-prompt).

## Quickstart: REST

List the page types with `GET /v1/page-types`, read one type's JSON Schema and guidance with `GET /v1/page-types/:type`, create a page with `POST /v1/pages` and your API key, send the returned `url`, then read the answer with `GET /v1/pages/:id/result` or wait for a callback. See the [REST API](/docs/api).

## Quickstart: MCP

Connect an MCP client that can send a custom header (Claude Code, Cursor and most desktop and CLI clients) to `https://pagesystems.ai/mcp` with your API key, and your model can send pages directly. Connectors that require OAuth sign-in, such as claude.ai on the web, cannot connect yet. **Try it in the [Playground](https://pagesystems.ai/dashboard/playground) in your dashboard:** it creates a key and fills it into these steps, then shows the pages your model creates and the answers that come back.

1. Claude Code (`Terminal`):

   ```
   claude mcp add --transport http page-systems https://pagesystems.ai/mcp --header "Authorization: Bearer ap_live_..."
   ```
2. Cursor and other MCP clients (`mcp.json`):

   ```
   {
     "mcpServers": {
       "page-systems": {
         "url": "https://pagesystems.ai/mcp",
         "headers": {
           "Authorization": "Bearer ap_live_..."
         }
       }
     }
   }
   ```
3. Then ask your model (`Prompt`):

   ```
   Use page-systems to send me a restaurant picker for dinner tonight, with three options. Give me the link, and tell me what I picked once I answer.
   ```

To tell the model when to send a page, [add the skill to your system prompt](#add-the-skill-to-your-system-prompt).

The server offers these tools:

| Tool | What it does |
| --- | --- |
| `list_page_types` | List every supported page type (flight_picker, time_slots, form, ...) with what it is for and when to use it, plus general guidance for using pages well. Start here. |
| `get_page_type_schema` | One page type's JSON Schema for create_page's input and for the answer, a minimal example spec, and its guidance (when to use it, how to fill its fields, examples, common errors). |
| `validate_spec` | Check a page spec without creating a page. Returns "valid" or the exact errors create_page would return. |
| `create_page` | Create a hosted page and get its url to send to the person. Counts as one page on the account. The input is the page spec without version and branding. The page only collects the answer; it never books, reserves or buys anything. |
| `get_page_result` | Read a page's status and, once the person submitted, their answer. Safe to call repeatedly. |
| `cancel_page` | Cancel an open page so it stops accepting answers. |

## Add the skill to your system prompt

The guidance on when a page beats a chat question and how to use pages well is served as an Agent Skill (SKILL.md) by `GET /v1/skill`, generated from the same guidance the API returns. Fetch it once when your agent starts, not on every turn, and append it to the system prompt. With the AI SDK:

```ts
import { pageSystemsTools, getPageSystemsSkill } from '@pagesystems/ai-sdk';
import { isStepCount, streamText } from 'ai';

const skill = await getPageSystemsSkill(); // once, at agent start
const result = streamText({ model, system: [yourInstructions, skill].join('\n\n'), messages, tools: pageSystemsTools(), stopWhen: isStepCount(5) });
```

MCP clients can also add it as the `page_systems_skill` prompt. Anywhere else (REST, a skills folder): `curl -o SKILL.md https://pagesystems.ai/v1/skill`. The same file is at [https://pagesystems.ai/docs/skill.md](https://pagesystems.ai/docs/skill.md). The eve extension loads this skill itself when a session starts.

## API keys

Create a key in the [dashboard](https://pagesystems.ai/dashboard/keys). Keys start with `ap_live_` and are shown once. The Free plan includes 1,000 pages a month.

## Install guides

- [eve](/docs/install)
- [MCP clients](/docs/install/mcp)
- [OpenAI Agents SDK](/docs/install/openai-agents)
- [Claude Agent SDK](/docs/install/claude-agent-sdk)
- [LangChain / LangGraph](/docs/install/langchain)
- [Mastra](/docs/install/mastra)
- [Google ADK](/docs/install/google-adk)
- [CrewAI](/docs/install/crewai)
- [Pydantic AI](/docs/install/pydantic-ai)
- [AI SDK](/docs/install/ai-sdk)

## More

- [Page types](/docs/pages): every page type, its fields, examples and result.
- [REST API](/docs/api): endpoints, callbacks, limits and errors.
- [Data handling](/docs/data-handling): what is stored, for how long, and what pages must not collect.
- [Branding](/docs/branding): your name, logo and accent color on pages.