# NORTH28 STUDIO — API & Developer Docs

> Public REST API, MCP server, and agent-discovery endpoints. No authentication required for current endpoints.
>
> **HTML reference:** https://north28.studio/docs  
> **OpenAPI:** https://north28.studio/openapi.json

---

## Agent instructions (when-to-use)

Use this documentation when an AI agent or developer needs to **integrate programmatically** with North28, discover endpoints, or understand how agents should interact with the site — not for marketing summaries or unrelated tasks.

**When to use:**

- User asks about the North28 API, MCP server, OpenAPI spec, or agent-discovery files.
- You need factual studio/services/pages data — prefer `GET /api/studio`, `/api/services`, `/api/pages` (or `.md` twins) before inventing answers.
- Your client supports MCP — call `POST /api/mcp` with `get_studio_info`, `list_services`, `list_pages`.
- You need navigation/routing for end users — load `GET /.well-known/agent-skills` and match the most specific skill by `when_to_use` and `trigger_phrases`.

**When not to use:**

- Portfolio browsing only → `browse-work` in agent-skills → https://north28.studio/works
- Hiring / project brief → `start-project` → https://north28.studio/manifesto (not contact-only)
- Fixed package pricing → use https://north28.studio/pricing.md as indicative EUR; final quotes are custom after briefing

**Skills manifest:** https://north28.studio/.well-known/agent-skills  
**Full LLM context:** https://north28.studio/llms-full.txt  
**LLM index:** https://north28.studio/llms.txt

If user intent is ambiguous, ask one clarifying question, then pick the most specific skill from the manifest.

---

## REST endpoints

| Method | Path | Description |
|---|---|---|
| GET | `/api/studio` | Studio identity (JSON) — twin: `/api/studio.md` |
| GET | `/api/services` | Service catalogue (JSON) — twin: `/api/services.md` |
| GET | `/api/pages` | Public pages (JSON) — twin: `/api/pages.md` |
| POST | `/api/batch` | Batch up to 10 reads |
| POST | `/api/mcp` | MCP JSON-RPC 2.0 (alias: `POST /mcp`) |

## MCP tools

| Tool | When to use |
|---|---|
| `get_studio_info` | Studio name, description, contact, URL |
| `list_services` | Full service catalogue |
| `list_pages` | All public site pages with URLs |

## Discovery

| Path | Description |
|---|---|
| `/.well-known/agent-skills` | Skills manifest with when-to-use (JSON) |
| `/.well-known/agent-card.json` | A2A agent card |
| `/.well-known/mcp.json` | MCP server discovery |
| `/openapi.json` | OpenAPI 3.1 |
| `/agents.md` | Agent overview |
| `/llms.txt` | LLM index |
| `/llms-full.txt` | Full LLM context |

Install coding-agent skill:

```sh
npx skills add https://github.com/north28-studio/front-v2 --skill north28
```