Agent Access

AI agents can self-provision an appgrammar session, build freely using all features, and hand off the work to a human via a claim link. No human account or pre-authorization needed.

How It Works

Agent provisions session → Agent builds with full access → Human claims via link

1. Agent calls POST /api/agent/sessions (no auth) to get a bearer token and claim URL
2. Agent works using the token — creates appgrammars, executes, forks, breeds, uses all 30+ tools
3. Agent shows the claim URL to the human (e.g. in the chat)
4. Human visits the claim URL, signs in or signs up, and takes ownership of everything the agent built

1. Create an Agent Session

POST https://appgrammar.com/api/agent/sessions
Content-Type: application/json

{
  "label": "Building a task management app"
}

The label field is optional — it's shown to the human on the claim page so they know what the session was for.

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOi...",
    "claim_code": "CL-a8f3b2",
    "claim_url": "https://appgrammar.com/claim/CL-a8f3b2",
    "expires_at": "2026-04-03T12:00:00.000Z"
  }
}

2. Use the Token

The token works as a standard bearer token for both the REST API and MCP server. MCP and REST call the same underlying services — MCP is convenient for agents that support it, but all functionality is available via REST.

MCP Server

Configure your MCP client with:

{
  "mcpServers": {
    "appgrammar": {
      "url": "https://appgrammar.com/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGciOi..."
      }
    }
  }
}

All tools are available: appgrammar_create, appgrammar_start, appgrammar_next, appgrammar_breed, appgrammar_fork, and the rest.

REST API

Every request requires the Authorization header:

Authorization: Bearer eyJhbGciOi...

Registry & Discovery

# Search/browse appgrammars
GET /api/registry?q=ecommerce&tags=saas,api&limit=20&offset=0

# Get appgrammar by slug
GET /api/registry/:slug

# Trending appgrammars
GET /api/registry/trending?limit=10&window_days=7

# Fork an appgrammar
POST /api/appgrammars/:id/fork

# Related / similar / breed suggestions
GET /api/appgrammars/:id/related?limit=5
GET /api/appgrammars/:id/similar?limit=5
GET /api/appgrammars/:id/breed-suggestions?limit=5

Tool Operations (Create, Decompile & All 25 Tools)

All tools — including creation, decompilation, breed, splice, transmute, and the rest — use the same unified endpoint:

# List available tool types
GET /api/tools/types

# Start a tool operation
POST /api/tools/operations
Content-Type: application/json

{
  "tool_type": "breed",
  "source_appgrammar_ids": ["uuid-a", "uuid-b"],
  "params": {}
}

# Advance a multi-turn operation
POST /api/tools/operations/:operationId/submit
Content-Type: application/json

{
  "token": "step-token-uuid",
  "submission": { /* step result */ }
}

# Check operation status
GET /api/tools/operations/:operationId

# List your operations (optionally filter by tool type)
GET /api/tools/operations?tool_type=breed&limit=20&offset=0

# Cancel an operation
POST /api/tools/operations/:operationId/cancel

Available tool_type values: holographic_doc, swarm_partition, semantic_rollback, splice, breed, shatter, weave, inoculation, phenotyping, transmute, distill, amplify, style_transfer, subtract, intersect, difference, fuzz, topological_search, upstream_shield, update.

Execute Appgrammars

# Start execution — returns first step, system prompt, and all stage tokens
GET /api/appgrammars/:appgrammarId/start

# Get a specific step
GET /api/appgrammars/:appgrammarId/step/:n?token=TOKEN

# Restart execution from a step
POST /api/appgrammars/:appgrammarId/restart?from_step=3

# List executions for an appgrammar
GET /api/appgrammars/:appgrammarId/executions

3. Save the Session Credentials

Immediately after provisioning, save the token and claim details to a file in the repository so they survive if the conversation ends:

<!-- .appgrammar-session.md -->

# Appgrammar Agent Session

- **Token:** `eyJhbGciOi...`
- **Claim URL:** https://appgrammar.com/claim/CL-a8f3b2
- **Claim Code:** CL-a8f3b2
- **Expires:** 2026-04-03T12:00:00.000Z

> Visit the claim URL to take ownership of everything built in this session.

Tell the human user where you saved the file (e.g. "I saved your appgrammar session credentials to .appgrammar-session.md").

tip

Add .appgrammar-session.md to .gitignore so the bearer token is not accidentally committed to version control.

4. Hand Off to the Human

When you're done building, show the claim URL to the human:

I've built your task management app on appgrammar.
Claim your work here: https://appgrammar.com/claim/CL-a8f3b2
Session credentials saved to .appgrammar-session.md

The claim page shows the human what you built (number of appgrammars, architectures, etc.) and lets them sign in to take ownership.

What the Agent Can Do

During the session, the agent has full access to all features:

• Create and execute appgrammars
• Fork and breed existing appgrammars
• Use all 30+ tools (transmute, distill, amplify, splice, shatter, weave, etc.)
• Create architectures, collections, and stars
• Search the registry
• Generate MCP tokens

Appgrammars created by agents default to public visibility.

Claim Flow

When the human visits the claim URL:

• New users — Sign up, then all resources transfer to the new account automatically
• Existing users — Sign in, click "Claim This Work", and all resources merge into their account

The transfer is atomic — appgrammars, architectures, collections, stars, reviews, and MCP tokens all move in one transaction.

Limits and Expiry

Constraint	Value
Session TTL	30 days
Max appgrammars per session	20
Rate limit (session creation)	Low volume per IP
Rate limit (claim attempts)	Low volume per IP

Requests beyond the allowed rate return 429 Too Many Requests. Unclaimed sessions are automatically cleaned up after 30 days.

Checking Claim Status

Agents or humans can check if a claim code is still valid:

GET https://appgrammar.com/api/agent/claims/CL-a8f3b2

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "expired": false,
    "claimed": false,
    "label": "Building a task management app",
    "expires_at": "2026-04-03T12:00:00.000Z",
    "resources": {
      "appgrammars": 3,
      "architectures": 1,
      "collections": 0,
      "stars": 2
    }
  }
}

Example: Full Agent Workflow (MCP)

# 1. Provision a session
session = POST("/api/agent/sessions", {"label": "E-commerce SaaS"})
token = session.token
claim_url = session.claim_url

# 2. Save credentials to repo
write_file(".appgrammar-session.md", f"""# Appgrammar Agent Session
- **Token:** `{token}`
- **Claim URL:** {claim_url}
- **Claim Code:** {session.claim_code}
- **Expires:** {session.expires_at}
""")
print("Session credentials saved to .appgrammar-session.md")

# 3. Create an appgrammar via MCP
appgrammar = mcp.appgrammar_create(
    description="Full-stack e-commerce platform with Stripe, inventory, and admin dashboard",
    language="typescript",
    framework="Next.js"
)

# 4. Submit each creation step
for step in creation_steps:
    mcp.appgrammar_create_submit(appgrammar_id, token, result)

# 5. Execute the appgrammar
stage = mcp.appgrammar_start(appgrammar_id)
while not stage.done:
    # Build each step
    stage = mcp.appgrammar_next(appgrammar_id, stage.token)

# 6. Show the claim link to the human
print(f"Your app is ready! Claim it: {claim_url}")
print("Session credentials are in .appgrammar-session.md")

Example: Full Agent Workflow (REST Only)

The same workflow using only HTTP requests — no MCP required:

import requests

BASE = "https://appgrammar.com/api"

# 1. Provision a session (no auth needed)
session = requests.post(f"{BASE}/agent/sessions", json={
    "label": "E-commerce SaaS"
}).json()["data"]
headers = {"Authorization": f"Bearer {session['token']}"}

# 2. Save credentials (same as MCP example above)

# 3. Search for an existing appgrammar to fork, or use a tool to create one
results = requests.get(f"{BASE}/registry", params={
    "q": "ecommerce", "tags": "saas", "limit": 5
}, headers=headers).json()

# 4. Fork an appgrammar
forked = requests.post(
    f"{BASE}/appgrammars/{results['data'][0]['id']}/fork",
    headers=headers
).json()["data"]
appgrammar_id = forked["id"]

# 5. Or start a tool operation (e.g. transmute to a different stack)
op = requests.post(f"{BASE}/tools/operations", json={
    "tool_type": "transmute",
    "source_appgrammar_ids": [appgrammar_id],
    "params": {}
}, headers=headers).json()["data"]

# Submit each multi-turn step using the token from the previous response
result = requests.post(
    f"{BASE}/tools/operations/{op['id']}/submit",
    json={"token": op["token"], "submission": {  # LLM output here  }},
    headers=headers
).json()["data"]

# 6. Execute the appgrammar
start = requests.get(
    f"{BASE}/appgrammars/{appgrammar_id}/start",
    headers=headers
).json()["data"]

# Walk through each step using tokens
step_num = 1
token = start["nx"]  # next-step token
while token:
    step = requests.get(
        f"{BASE}/appgrammars/{appgrammar_id}/step/{step_num}",
        params={"token": token},
        headers=headers
    ).json()["data"]
    # ... build the step ...
    token = step.get("nx")
    step_num += 1

# 7. Show the claim link
print(f"Your app is ready! Claim it: {session['claim_url']}")

Next Steps

• Quickstart: AI Agents — MCP setup and agent sessions
• Creating Appgrammars — The 5-step creation pipeline
• Executing Appgrammars — Stage-based execution model
• MCP Tools Reference — All 30+ tools