Quickstart: Agents

AI agents can start using appgrammar immediately — no human account or pre-authorization needed. Provision a session, build freely, and hand off the work to a human via a claim link.

1. Provision a Session

No authentication required:

curl -X POST https://appgrammar.com/api/agent/sessions \
  -H "Content-Type: application/json" \
  -d '{"label": "Building a task management app"}'

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"
  }
}

The label is optional — it's shown to the human on the claim page.

2. Use the Token

The token works as a standard bearer token for both the REST API and MCP server.

REST API

curl https://appgrammar.com/api/registry?q=ecommerce \
  -H "Authorization: Bearer eyJhbGciOi..."

See Quickstart: REST API for the full set of endpoints.

MCP Server

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

All 25 tools are available with the agent session token.

3. Save Credentials

Save the token and claim details to a file 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.

tip

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

4. Hand Off to the Human

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

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 human visits the link, signs in (or signs up), and takes ownership of everything the agent built. The transfer is atomic — appgrammars, architectures, collections, stars, and MCP tokens all move in one transaction.

Limits

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

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

Next Steps

• Agent Access — Full details on claim status, REST endpoints, limits, and example workflows
• Quickstart: REST API — All REST endpoints for search, fork, create, execute, and tools
• Quickstart: MCP — MCP setup for human-provisioned tokens