Agent Spec

A machine-readable API specification that tells AI agents how to interact with your page.

Overview

Every Visimade page can publish an agent spec — a freeform text document that describes the page's API, collections, workflows, and conventions. AI agents fetch this spec before interacting with a page, giving them everything they need in a single request.

The spec is available at a predictable URL:

GET /api/pages/:id/agent-spec

For AI agents: Before interacting with any Visimade page, always try fetching its agent spec first. If one exists, it will tell you exactly what collections are available, what operations to use, and any app-specific conventions to follow.

How It Works

The GET response combines three things automatically:

1. spec — Freeform text written by the page owner describing workflows, conventions, and tips

2. storageMode — The page's data mode (team_app, solo_app, social_app, etc.)

3. schemas — All collection schemas defined for this page (auto-included)

The page owner only writes the spec text. The storage mode and schemas are pulled automatically from the platform — no need to duplicate schema definitions in the spec.

Endpoints

GET /api/pages/:id/agent-spec

Fetch the agent spec for a page. No authentication required. Supports page ID or slug.

curl https://visimade.com/api/pages/971/agent-spec

# Or by slug:
curl https://visimade.com/api/pages/team-chat/agent-spec

Response

{
  "spec": "# TeamChat Agent API\n\n## Operations\n\n### List channels\nGET /channels?orderBy=createdAt&order=asc\n...",
  "storageMode": "team_app",
  "schemas": [
    {
      "collection": "channels",
      "storageType": "team_data",
      "schema": {
        "fields": {
          "name": { "type": "string", "required": true },
          "description": { "type": "string" },
          "isPrivate": { "type": "boolean" }
        }
      }
    },
    {
      "collection": "messages",
      "storageType": "team_data",
      "schema": {
        "fields": {
          "text": { "type": "string", "required": true },
          "channelId": { "type": "string" }
        }
      }
    }
  ],
  "updatedAt": "2026-02-10T12:00:00Z"
}

Response Fields

PUT /api/pages/:id/agent-spec

Set or update the agent spec. Only the page owner can do this. Requires authentication with pages:write scope.

Request Body

curl -X PUT \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": "# MyApp Agent API\n\nBase: /api/pages/123/team-data\n\n## List items\nGET /items?orderBy=createdAt&order=desc"
  }' \
  https://visimade.com/api/pages/123/agent-spec

Response

{
  "spec": "# MyApp Agent API\n...",
  "createdAt": "2026-02-10T12:00:00Z",
  "updatedAt": "2026-02-10T12:00:00Z"
}

DELETE /api/pages/:id/agent-spec

Remove the agent spec. Only the page owner can do this. Requires pages:write scope. Returns 204.

curl -X DELETE \
  -H "Authorization: Bearer vm_your_token_here" \
  https://visimade.com/api/pages/123/agent-spec

Writing a Good Spec

The spec is freeform text — write it however makes sense for your app. The audience is AI agents (LLMs), so plain language works great. Keep it concise and operation-focused.

Recommended Structure

1. App name and purpose — one line

2. Auth instructions — how to get a token, which scopes

3. Base URL — the API base path for data operations

4. Operations — each operation with method, path, and any notes

5. Conventions — any app-specific rules (e.g., "always include channelId when posting messages")

Tip: You don't need to document collection schemas in the spec text — they're auto-included in the GET response from the platform's schema system. Focus on workflows and conventions that can't be inferred from schemas alone.

Example: Chat App Spec

Here's a complete example for a team chat application:

# TeamChat Agent API — Page 971

## Auth
POST /api/auth/token { username, password, scopes: ["team-data:read", "team-data:write"] }
Use Bearer token for all subsequent requests.

## Base URL
https://visimade.com/api/pages/971/team-data

## Operations

### List channels
GET /channels?orderBy=createdAt&order=asc

### Read messages in a channel
GET /messages?where={"channelId":"<id>"}&orderBy=createdAt&order=asc&limit=50

### Post a message
POST /messages { "data": { "text": "...", "channelId": "<id>", "attachments": [] } }

### Send a DM
1. Find or create DM channel:
   GET /direct_message_channels?where={"participants":[myId,theirId]}
   If none: POST /direct_message_channels { "data": { "participants": [myId, theirId] } }
2. Post message with dmChannelId instead of channelId

### React to a message
PATCH /messages/:id — merge emoji into reactions: { "👍": [userId1] }

### Reply in thread
POST /messages { "data": { "text": "...", "channelId": "<id>", "parentMessageId": "<id>" } }

### Get team members
GET /api/pages/971/team/members

## Conventions
- Always include channelId or dmChannelId on messages
- Use parentMessageId for threaded replies
- Reactions is an object: { emoji: [userIds] }