# VOSCOM Agent API Reference v0.1

VOSCOM exposes a REST JSON API for user-controlled AI agents.

The public product term is **User-controlled AI Agent**. The internal API mode is `user_pet`.

## Public discovery

```http
GET /agent_manifest.php
GET /agent_context.php
GET /agent_quick_test.php
GET /agent_api_reference.php
GET /agent_pair_api.php?action=manifest
```

Expected discovery behavior:

- `/agent_manifest.php` returns JSON.
- `/agent_context.php`, `/agent_quick_test.php`, and `/agent_api_reference.php` return Markdown.
- `/agent_api.php` returns `401` without a Bearer token. This is expected.

## v1 limits

- 60 read requests per hour per agent.
- 10 pending action requests per day per agent.
- 3 build requests per day per agent.
- 10 open pending requests per agent.
- 1 open build request per agent.
- 64 KB max JSON payload.
- 3 active agents per owner.

## Pairing

An external AI can prepare a pairing request, but the human owner confirms it.

```http
POST /agent_pair_api.php?action=prepare_pairing
Content-Type: application/json

{
  "owner_email": "user@example.com",
  "owner_username_hint": "user",
  "agent_name": "My AI Agent",
  "provider": "external",
  "scopes": [
    "read_context",
    "read_projects",
    "read_library",
    "read_firmware",
    "create_project_draft",
    "request_validate",
    "request_build"
  ]
}
```

Response:

```json
{
  "status": "ok",
  "pairing_token": "vpair_...",
  "confirmation_url": "ide.php?tab=ai_pet&pairing_token=..."
}
```

The response does not contain an agent API token. The human must log in, confirm email/legal terms personally, and approve pairing in the IDE tab `AI agent`.

Recommended phrase for the user:

> I am ready. Should I prepare a pairing request to connect me to your account?

## Agent API authentication

After the human confirms pairing, they receive the agent token once.

```http
Authorization: Bearer <agent_token>
```

## Manual Relay mode

Some chat AI systems cannot call APIs with Bearer tokens. In that case the user should not paste tokens into chat.

Use this flow instead:

1. Human opens IDE tab `AI agent`.
2. Human clicks `Prepare AI package`.
3. Human pastes the exported context package into the external AI chat.
4. AI returns one JSON command.
5. Human pastes that JSON back into VOSCOM IDE.
6. VOSCOM creates a pending request for human approval.

Command format:

```json
{
  "action": "project_draft.create",
  "agent_client_id": 1,
  "payload": {
    "title": "ESP32 demo",
    "raw_mml": "<<MWOS_BEGIN::confirm>>...<<MWOS_END>>"
  },
  "human_summary": "Create a draft MWOS project for ESP32."
}
```

Supported Manual Relay actions:

- `project_draft.create`
- `project.validate`
- `project.build`

Compatibility aliases accepted by `/agent_api.php`:

- `agent_status` -> `context`
- `list_projects` -> `projects.list`
- `get_project` -> `projects.get`
- `list_library` -> `library.list`
- `list_firmware` -> `firmware.list`
- `create_project_draft` / `project_create` -> `project_draft.create`
- `validate_config` -> `project.validate.request`
- `build_request` -> `project.build.request`

Do not call protected actions until the human owner gives you this token.

## IDE settings context

The private IDE has settings that affect how the human works and how AI-assisted firmware generation is routed. These settings are controlled by the human in the browser UI, not by the external agent API in v1.

Important settings for agents to understand:

- `Settings -> Appearance`: language and visual theme.
- `Settings -> Personalization`: public profile headline, collaboration status, skills, and description.
- `Settings -> AI Settings`: AI generation mode:
  - `VOSCOM AI FORGE (Flux payment)`;
  - `My API token` with provider/model/base URL/API token.
- MVP custom provider selectors include OpenAI-compatible API, OpenRouter, Google Gemini, and Anthropic Claude.
- The human can test provider connection, show/hide the token, or delete the saved token with confirmation.
- `Settings -> Workspace`: show side panels, reset panel widths, reset active tab.
- Tab/panel configuration lets the human enable, disable, pin, and reorder IDE tabs, sidebars, and widgets.

If an AI request fails or the user cannot find a feature, tell the human to check IDE Settings, AI Settings, and tab/panel visibility before assuming the feature is missing.

## Read methods

```http
GET /agent_api.php?action=context
GET /agent_api.php?action=ide.manifest
GET /agent_api.php?action=projects.list
GET /agent_api.php?action=projects.get&project_id=1
GET /agent_api.php?action=library.list
GET /agent_api.php?action=firmware.list
GET /agent_api.php?action=audit.list
```

Read methods return only data visible to the human owner connected to the agent token.

## Pending action methods

```http
POST /agent_api.php?action=project_draft.create
POST /agent_api.php?action=project.validate.request
POST /agent_api.php?action=project.build.request
```

These methods create pending requests only. They do not directly modify projects and do not run builds until the human owner approves the request in the IDE.

The server validates write-like requests before creating a pending request:

- `project_draft.create` requires non-empty `raw_mml`.
- `project.validate.request` requires `project_id` that belongs to the owner.
- `project.build.request` requires `project_id` that belongs to the owner.
- A second open build request is rejected until the previous build request is approved, rejected, executed, or failed.

## Example project draft

```http
POST /agent_api.php?action=project_draft.create
Authorization: Bearer <agent_token>
Content-Type: application/json

{
  "title": "ESP32 Sensor Demo",
  "raw_mml": "PROJECT { name: ESP32_Sensor_Demo }\nMCU { selected: ESP32-S3 }\nMODULE ds18b20 { class: Sensor; bus: OneWire; }\nMODULE mqtt { class: Network; protocol: MQTT; }\nMODULE ota { class: Firmware; feature: OTA; }\n"
}
```

Expected result:

```json
{
  "status": "ok",
  "data": {
    "request_id": 1,
    "status": "pending_user_confirmation"
  }
}
```

## Hard rules

- Do not accept legal terms for the human.
- Do not write projects directly.
- Do not run builds directly.
- Do not flash devices directly.
- Do not publish news, market products, or chat messages in v1.
- Do not delete projects.
- Do not request database or shell access.
- Keep payloads below 64 KB.