buildmymcpserver/apps/web/app/docs/api-reference/page.tsx

import {
  DocsTitle,
  DocsLead,
  DocsH2,
  DocsP,
  DocsCode,
  Mono,
} from '@/components/docs-page';

export const metadata = { title: 'API reference — BuildMyMCPServer docs' };

export default function ApiReference() {
  return (
    <>
      <DocsTitle kicker="Reference">API reference</DocsTitle>
      <DocsLead>
        Every endpoint on the control plane. Authenticated routes use the session cookie set by
        the magic-link verify call.
      </DocsLead>

      <DocsH2 id="auth">Auth</DocsH2>
      <DocsP>
        <Mono>POST /v1/auth/magic-link</Mono> — body <Mono>{`{"email":"…"}`}</Mono> — emails (or
        prints in dev) a one-time link.
      </DocsP>
      <DocsP>
        <Mono>POST /v1/auth/verify</Mono> — body <Mono>{`{"token":"…"}`}</Mono> — exchanges the
        token for a session cookie.
      </DocsP>
      <DocsP><Mono>GET /v1/auth/me</Mono> — returns the current session user + org.</DocsP>
      <DocsP><Mono>POST /v1/auth/logout</Mono> — destroys the session.</DocsP>

      <DocsH2 id="servers">Servers</DocsH2>
      <DocsP><Mono>GET /v1/servers</Mono> — list servers in the current org.</DocsP>
      <DocsP>
        <Mono>POST /v1/servers/preview</Mono> — body <Mono>{`{"prompt":"…"}`}</Mono> — runs Claude
        synchronously, validates the spec, caches it, returns <Mono>{`{ previewId, source, spec }`}</Mono>.
      </DocsP>
      <DocsP>
        <Mono>POST /v1/servers</Mono> — body <Mono>{`{name, slug, prompt, secrets, previewId?}`}</Mono>
        — creates the server, queues the build, returns the server + build records.
      </DocsP>
      <DocsP>
        <Mono>GET /v1/servers/:id</Mono> — server detail with the latest 10 build records.
      </DocsP>
      <DocsP>
        <Mono>POST /v1/servers/:id/iterate</Mono> — body <Mono>{`{prompt, secrets}`}</Mono> —
        queues a new version build.
      </DocsP>
      <DocsP><Mono>DELETE /v1/servers/:id</Mono> — removes the server and tears down the container.</DocsP>

      <DocsH2 id="builds">Builds</DocsH2>
      <DocsP>
        <Mono>GET /v1/builds/:id</Mono> — build record + persisted logs.
      </DocsP>
      <DocsP>
        <Mono>WS /v1/builds/:id/stream</Mono> — live event stream of build events:
        <Mono>status</Mono>, <Mono>log</Mono>, <Mono>done</Mono>, <Mono>error</Mono>.
      </DocsP>

      <DocsH2 id="oauth">OAuth (clients of generated servers, not dashboard)</DocsH2>
      <DocsP>
        <Mono>GET /oauth/.well-known/oauth-authorization-server</Mono> — RFC 8414 metadata.
      </DocsP>
      <DocsP><Mono>GET /oauth/jwks</Mono> — RS256 public key for verifying access tokens.</DocsP>
      <DocsP><Mono>POST /oauth/register</Mono> — RFC 7591 dynamic client registration.</DocsP>
      <DocsP><Mono>GET /oauth/authorize</Mono> — authorization code endpoint, requires session.</DocsP>
      <DocsP><Mono>POST /oauth/token</Mono> — code exchange + refresh.</DocsP>

      <DocsH2 id="examples">Curl example</DocsH2>
      <DocsCode
        label="full lifecycle"
        code={`# 1. magic link
curl -X POST http://localhost:4000/v1/auth/magic-link -d '{"email":"me@x.dev"}'
# (grab token from API console)

# 2. verify -> session
curl -c cookies.txt -X POST http://localhost:4000/v1/auth/verify -d '{"token":"…"}'

# 3. preview
curl -b cookies.txt -X POST http://localhost:4000/v1/servers/preview \\
  -d '{"prompt":"echo server with one tool: echo(message)"}'

# 4. build
curl -b cookies.txt -X POST http://localhost:4000/v1/servers \\
  -d '{"name":"Echo","slug":"echo","prompt":"…","secrets":{},"previewId":"…"}'`}
      />
    </>
  );
}