# Figma HTTP API

Share the currently open Figma file with an AI agent through one HTTPS URL. The agent reads `llms.txt` and uses ordinary `GET` and `POST` requests.

```text
AI agent
   │ HTTPS API
   ▼
Local API server (:8765) ← Cloudflare Tunnel
   │ local WebSocket
   ▼
Figma API Plugin ↔ open Figma file
```

The WebSocket relay is an internal transport. It is not exposed publicly and is not an interface for agents.

## Start on Windows

Requirements: Figma Desktop, Node.js, Bun, and Cloudflared.

1. In Figma, import `src/plugin/manifest.json` as a development plugin once.
2. Start everything with one command:

   ```powershell
   .\start.cmd
   ```

The command starts the internal relay, HTTP API, Figma, Cloudflare Tunnel, and the plugin watchdog. It then tries to open the plugin and verifies that the current document answers.

Nothing is installed in Windows Startup. Re-running the command is safe and only repairs missing services.

## Plugin controls

After the server is running, normal management happens in the Figma plugin:

- API, Figma, and tunnel status;
- read-only or read/write access;
- copy/open share URL and scoped `llms.txt`;
- start, stop, or replace the Cloudflare quick tunnel;
- rotate the secret share URL;
- repair the local stack.

## Public API

Give the agent only the generated share URL:

```text
https://<host>.trycloudflare.com/s/<secret>
```

The main routes are:

| Method | Route | Purpose |
|---|---|---|
| `GET` | `/s/{secret}` | Discover exact URLs and current state |
| `GET` | `/s/{secret}/llms.txt` | Complete live API instructions |
| `GET` | `/v1/shares/{secret}/llms.txt` | Documentation for this share |
| `GET` | `/v1/shares/{secret}/{topic}/llms.txt` | Documentation for one route or operation |
| `GET` | `/v1/shares/{secret}/status` | Check readiness |
| `GET` | `/v1/shares/{secret}/capabilities` | List available Figma operations |
| `POST` | `/v1/shares/{secret}/{operation}` | Execute an operation; the body contains its parameters |
| `GET` | `/openapi.json` | OpenAPI 3.1 contract |

Example read request:

```http
POST /v1/shares/{secret}/get_document_info
Content-Type: application/json

{}
```

Write requests also require an `Idempotency-Key` header. Documentation is hierarchical: service errors link to `/llms.txt`, share errors link to `/v1/shares/{secret}/llms.txt`, and known route errors link to that route's own `llms.txt`.

## Security

- The random share URL is a bearer capability; anyone holding it gets the configured access.
- Public access can be stopped immediately from the plugin.
- Rotating the secret invalidates the previous share URL.
- Management routes under `/local/control/*` accept only loopback plugin requests and return `404` through Cloudflare.
- The internal relay binds only to `127.0.0.1`.
- Access mode and tunnel state persist across server repairs.

## Project files

| File | Purpose |
|---|---|
| `start.cmd` | Single user-facing start command |
| `src/api/` | Public API server and health probe |
| `src/relay/` | Loopback-only Figma transport |
| `src/plugin/` | Figma development plugin |
| `scripts/` | Windows bootstrap, watchdog, tunnel, and Figma launcher |