diff --git a/DESIGN.md b/DESIGN.md
index 1cb2aab6e5..279606e453 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -300,6 +300,11 @@ Content sits on the Cool Shell in a grid of panels: Feed White, 8px, hairline-bo
- **Status:** the console is the one place with status colors, `success` (lane-1's green) and `warning` (lane-5's ochre) beside Rm Red. They only ever mark state (healthy, watch, failing; event levels; better or worse than the period before) and always come with an icon, a sign or a word. They are not lanes and never mark a person.
- **Charts:** drawn in SVG at their real size, one y-axis, hairline gridlines, mono 11px ticks. History is a 2px ink line; a forecast continues it as a dashed Muted Ink line over a 15% Muted Ink wash for its range, after a dashed Rail Gray "today" rule. Columns are at most 24px wide with a 2px surface gap between stacked segments. Hovering shows the inverted tooltip; every chart carries a screen-reader table.
+### API Docs
+The API docs use the Operations Console's shell (`ConsoleLayout`), for everyone, guests included: the wordmark with a bordered mono `api` chip, a sidebar grouping the guides under `guide`, the theme switch and "Back to /dev/null" (without an avatar for a guest). The header names the section and says in one line what it holds; on the right a mono `v1`.
+
+- **Guides:** read like the site's other long pages, never a card per section: one Feed White sheet on the Cool Shell, 1160px wide, 8px and hairline-bordered, whose sections follow one another with a hairline between them, each under a Section heading that links to itself. Prose at 15px, named values in a hairline list with mono keys like the settings, and code in the same code blocks as commits, highlighted on the server, its language above it.
+
### Error Pages
403, 404, 429, 500 (outside debug), and 503 render one standalone `error` page, with no app shell, for guests and signed-in users alike. A broken rail: the wordmark sits on a node in the viewer's lane (Rail Gray for guests) whose segment fades out before reaching a hollow, dangling node. Beside it, a mono git-style line (`fatal: path '/x' does not exist in 'HEAD'`), a Headline sentence saying what happened, one muted sentence saying what to do, and a single primary button ("Back to your log", "Go to the home page", or "Try again" during maintenance). A 419 is not a page: it redirects back with an error toast.
diff --git a/KNOWLEDGE_BASE.md b/KNOWLEDGE_BASE.md
index 1756750c87..411c8dab2b 100644
--- a/KNOWLEDGE_BASE.md
+++ b/KNOWLEDGE_BASE.md
@@ -579,7 +579,9 @@ The read-only JSON API at `/api/v1` requires no authentication or token, except
Subscribe in a feed reader to `/@{handle}/feed.atom` for a profile's latest **50 approved top-level commits**, including image enclosures. Feeds are public and can be cached for five minutes.
-Sources: [API routes](routes/api.php), [API controllers](app/Http/Controllers/Api), [feed generation](app/Actions/CreateUserFeed.php), [rate limits](app/Providers/AppServiceProvider.php).
+The **API docs** at `/docs/api`, linked as **API** from the aside and the user menu, are readable by everyone. Their Introduction says what the API is for, its base URL and format, with a first request anyone can send.
+
+Sources: [API routes](routes/api.php), [API controllers](app/Http/Controllers/Api), [feed generation](app/Actions/CreateUserFeed.php), [rate limits](app/Providers/AppServiceProvider.php), [docs page](app/Http/Controllers/ApiDocsController.php), [guides](resources/js/pages/api-docs/guides).
### Signed API and devices
diff --git a/app/Enums/ApiDocsSection.php b/app/Enums/ApiDocsSection.php
new file mode 100644
index 0000000000..a9d45b5655
--- /dev/null
+++ b/app/Enums/ApiDocsSection.php
@@ -0,0 +1,37 @@
+name;
+ }
+
+ public function description(): string
+ {
+ return match ($this) {
+ self::Introduction => 'What the API is for, and where it lives',
+ };
+ }
+
+ /**
+ * @return array{slug: string, title: string, description: string}
+ */
+ public function toArray(): array
+ {
+ return [
+ 'slug' => $this->value,
+ 'title' => $this->title(),
+ 'description' => $this->description(),
+ ];
+ }
+}
diff --git a/app/Http/Controllers/ApiDocsController.php b/app/Http/Controllers/ApiDocsController.php
new file mode 100644
index 0000000000..58a5f8a841
--- /dev/null
+++ b/app/Http/Controllers/ApiDocsController.php
@@ -0,0 +1,30 @@
+ array_map(fn (ApiDocsSection $section): array => $section->toArray(), ApiDocsSection::cases()),
+ 'current' => $section->value,
+ 'snippets' => $snippets->for($section),
+ ])->withViewData(['preview' => $metadata->page(
+ $section->title().' - API docs - /dev/null',
+ $section->description().'. The JSON API the /dev/null apps use, open to anything you build.',
+ route('api-docs.show', $section),
+ )]);
+ }
+}
diff --git a/app/Services/ApiGuideSnippets.php b/app/Services/ApiGuideSnippets.php
new file mode 100644
index 0000000000..b59ec1d1a1
--- /dev/null
+++ b/app/Services/ApiGuideSnippets.php
@@ -0,0 +1,39 @@
+
+ */
+ public function for(ApiDocsSection $section): array
+ {
+ $snippets = match ($section) {
+ ApiDocsSection::Introduction => [
+ 'firstRequest' => ['bash', 'curl '.self::BaseUrl."/users/nunomaduro \\\n -H 'Accept: application/json'"],
+ ],
+ };
+
+ return array_map(fn (array $snippet): array => [
+ 'language' => $snippet[0],
+ 'html' => $this->highlighter->parse($snippet[1], $snippet[0]),
+ ], $snippets);
+ }
+}
diff --git a/resources/js/components/api-docs/guide.tsx b/resources/js/components/api-docs/guide.tsx
new file mode 100644
index 0000000000..39983231bd
--- /dev/null
+++ b/resources/js/components/api-docs/guide.tsx
@@ -0,0 +1,119 @@
+import type { ReactNode } from 'react';
+import { CodeBlock } from '@/components/code-block';
+import { cn } from '@/lib/utils';
+import type { ApiDocsSnippet } from '@/types';
+
+/**
+ * How wide the docs' content is, so moving between their pages never changes the page's width.
+ */
+export const DOCS_WIDTH = 'max-w-[1160px]';
+
+/**
+ * A guide of the API docs, read like the site's other long pages: one Feed White sheet on the console's shell, its
+ * sections one after the other with a hairline between them, never a card each.
+ */
+export function Guide({ children }: { children: ReactNode }) {
+ return (
+
+ {children}
+
+ );
+}
+
+function anchor(title: string): string {
+ return title
+ .toLowerCase()
+ .replace(/[^a-z0-9]+/g, '-')
+ .replace(/^-|-$/g, '');
+}
+
+/**
+ * A section of a guide, its title a link to itself, so a reader can point someone at it.
+ */
+export function GuideSection({
+ title,
+ children,
+}: {
+ title: string;
+ children: ReactNode;
+}) {
+ const id = anchor(title);
+
+ return (
+
+
+ The JSON API the /dev/null apps use, open to anything you
+ build: a bot, a bridge, a widget on your own site.
+
+
+ Reading public profiles and commits needs nothing. Acting
+ for someone needs their approval and a signature on every
+ request: there are no passwords and no API tokens.
+
+ {API_URL} },
+ {
+ name: 'format',
+ children:
+ 'JSON, or multipart when a request carries images or a voice note',
+ },
+ {
+ name: 'accept',
+ children: (
+ <>
+ Accept: application/json on
+ every request, so every error comes back as
+ JSON
+ >
+ ),
+ },
+ ]}
+ />
+
+
+
+
A profile, as anyone can read it:
+
+
+
+
+
+ A signed request sees what the web shows the person who
+ signed it, and goes through the same validation, moderation
+ and limits: a commit may come back pending, and a blocked
+ profile stays out of reach.
+
+
+
+ );
+}
diff --git a/resources/js/pages/api-docs/show.tsx b/resources/js/pages/api-docs/show.tsx
new file mode 100644
index 0000000000..05981c44c6
--- /dev/null
+++ b/resources/js/pages/api-docs/show.tsx
@@ -0,0 +1,19 @@
+import { Head, usePage } from '@inertiajs/react';
+import ApiDocsLayout from '@/layouts/api-docs/layout';
+import { Introduction } from '@/pages/api-docs/guides/introduction';
+import type { ApiDocsProps } from '@/types';
+
+export default function Show() {
+ const { sections, current, snippets } = usePage().props;
+ const section = sections.find((candidate) => candidate.slug === current);
+
+ return (
+ <>
+
+
+ {current === 'introduction' && }
+ >
+ );
+}
+
+Show.layout = ApiDocsLayout;
diff --git a/resources/js/types/api-docs.ts b/resources/js/types/api-docs.ts
new file mode 100644
index 0000000000..9e1191b80c
--- /dev/null
+++ b/resources/js/types/api-docs.ts
@@ -0,0 +1,16 @@
+export type ApiDocsSection = {
+ slug: string;
+ title: string;
+ description: string;
+};
+
+export type ApiDocsSnippet = {
+ language: string;
+ html: string;
+};
+
+export type ApiDocsProps = {
+ sections: ApiDocsSection[];
+ current: string;
+ snippets: Record;
+};
diff --git a/resources/js/types/index.ts b/resources/js/types/index.ts
index f7facc21a5..e585011f25 100644
--- a/resources/js/types/index.ts
+++ b/resources/js/types/index.ts
@@ -1,4 +1,5 @@
export type * from './achievement';
+export type * from './api-docs';
export type * from './activity';
export type * from './auth';
export type * from './commit';
diff --git a/routes/web.php b/routes/web.php
index c10b9580d9..618ff52962 100644
--- a/routes/web.php
+++ b/routes/web.php
@@ -2,9 +2,11 @@
declare(strict_types=1);
+use App\Enums\ApiDocsSection;
use App\Enums\Log;
use App\Enums\ProfileType;
use App\Http\Controllers\AboutController;
+use App\Http\Controllers\ApiDocsController;
use App\Http\Controllers\AppController;
use App\Http\Controllers\BanController;
use App\Http\Controllers\BannedController;
@@ -251,6 +253,10 @@
// What was merged into production, readable by everyone...
Route::get('changelog', [ChangelogController::class, 'index'])->name('changelog.index');
+// The API docs, readable by everyone...
+Route::redirect('docs/api', '/docs/api/'.ApiDocsSection::Introduction->value)->name('api-docs.index');
+Route::get('docs/api/{section}', [ApiDocsController::class, 'show'])->name('api-docs.show');
+
// Public pages, readable by guests and crawlers...
Route::middleware([RememberIntendedUrl::class, RedirectToHandleCase::class])->group(function (): void {
// A handle no user has may be an organization's, an unclaimed developer's, or one to look up on GitHub. Bindings
diff --git a/tests/Feature/Controllers/ApiDocsControllerTest.php b/tests/Feature/Controllers/ApiDocsControllerTest.php
new file mode 100644
index 0000000000..40c758b853
--- /dev/null
+++ b/tests/Feature/Controllers/ApiDocsControllerTest.php
@@ -0,0 +1,55 @@
+get('/docs/api')->assertRedirect(route('api-docs.show', ApiDocsSection::Introduction));
+});
+
+it('renders every section of the API docs for guests', function (ApiDocsSection $section): void {
+ $this->get(route('api-docs.show', $section))
+ ->assertOk()
+ ->assertInertia(fn ($page) => $page->component('api-docs/show')
+ ->where('current', $section->value));
+})->with(ApiDocsSection::cases());
+
+it('renders the API docs for signed in users', function (): void {
+ $this->actingAs(User::factory()->create())
+ ->get(route('api-docs.show', ApiDocsSection::Introduction))
+ ->assertOk()
+ ->assertInertia(fn ($page) => $page->component('api-docs/show'));
+});
+
+it('lists the guides in reading order', function (): void {
+ $this->get(route('api-docs.show', ApiDocsSection::Introduction))
+ ->assertInertia(fn ($page) => $page
+ ->has('sections', 1)
+ ->where('sections.0', [
+ 'slug' => 'introduction',
+ 'title' => 'Introduction',
+ 'description' => 'What the API is for, and where it lives',
+ ]));
+});
+
+it('gives a guide its code blocks', function (): void {
+ $this->get(route('api-docs.show', ApiDocsSection::Introduction))
+ ->assertInertia(fn ($page) => $page
+ ->has('snippets', 1)
+ ->has('snippets.firstRequest', fn ($snippet) => $snippet->where('language', 'bash')->has('html')));
+});
+
+it('answers a section the docs do not have with the not found page', function (): void {
+ $this->get('/docs/api/webhooks')
+ ->assertNotFound()
+ ->assertHeader('Content-Type', 'text/html; charset=UTF-8');
+});
+
+it('describes each section to search engines and link previews', function (): void {
+ $this->get(route('api-docs.show', ApiDocsSection::Introduction))
+ ->assertOk()
+ ->assertSee('Introduction - API docs - /dev/null', false)
+ ->assertSee('', false);
+});
diff --git a/tests/Unit/ApiDocsGuides.test.tsx b/tests/Unit/ApiDocsGuides.test.tsx
new file mode 100644
index 0000000000..919f305d0b
--- /dev/null
+++ b/tests/Unit/ApiDocsGuides.test.tsx
@@ -0,0 +1,60 @@
+///
+
+import assert from 'node:assert/strict';
+import { renderToString } from 'react-dom/server';
+import { test } from 'vite-plus/test';
+import {
+ DOCS_WIDTH,
+ Guide,
+ GuideSection,
+} from '../../resources/js/components/api-docs/guide';
+import { Introduction } from '../../resources/js/pages/api-docs/guides/introduction';
+
+test('lays a guide out as sections of one article, never as cards', () => {
+ const html = renderToString(
+
+
+