From 3fab343b6ee60dfa96d436df3c29ea8983ca0497 Mon Sep 17 00:00:00 2001
From: Deep Kumar Singh Kushwah <deepkumarsinghkushwah@Deeps-MacBook-Air.local>
Date: Thu, 11 Jun 2026 18:50:58 +0530
Subject: [PATCH] feat(gateway,admin-ui): corpus create/delete admin CRUD (Step
 3.10)

Corpus management in the admin console was local-only: the "New corpus"
button mutated React state and never called the gateway, and the gateway
had no write route (POST /v1/corpora returned 405). This wires it end to end.

- CorpusStore SPI: add tenant-scoped create / delete (NoopCorpusStore +
  PgCorpusStore), with the same cross-tenant invisibility rule as get.
- Gateway: POST /v1/corpora (201, server-minted id, tenant from ctx) and
  DELETE /v1/corpora/{id} (204/404). New CreateCorpusRequest wire type.
- Admin UI: createCorpus / deleteCorpus client + Corpora page calls them
  when live, keeps local behaviour in demo mode (mirrors the Webhooks page).
- Tests: gateway routes (test_corpora.py), SPI conformance, Pg integration.
- Docs + regenerated dist/openapi.{json,yaml}.

Verified locally (CI billing-blocked): full create -> list -> delete -> 404
lifecycle + tenant isolation + CORS preflight/POST from :3100; ruff,
mypy --strict, pytest, admin-ui tsc + vitest all green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 apps/admin-ui/src/app/corpora/page.tsx        |  57 +++++--
 apps/admin-ui/src/lib/api.ts                  |  19 +++
 apps/gateway/src/rag_gateway/corpora.py       | 102 ++++++++++--
 apps/gateway/tests/test_corpora.py            |  99 +++++++++++
 dist/openapi.json                             | 155 ++++++++++++++++++
 dist/openapi.yaml                             | 128 +++++++++++++++
 docs/architecture/gateway.md                  |   2 +-
 docs/reference/admin-ui.md                    |   2 +-
 docs/reference/gateway.md                     |  39 +++++
 .../rag_backends/corpus/pg_corpus_store.py    |  40 ++++-
 packages/core/src/rag_core/gateway_types.py   |  27 +++
 .../core/src/rag_core/spi/corpus_store.py     |  43 ++++-
 .../src/rag_core/spi/noop/corpus_store.py     |  18 +-
 tests/contract/test_corpus_store.py           |  27 +++
 tests/integration/test_pg_corpus_store.py     |  22 +++
 15 files changed, 736 insertions(+), 44 deletions(-)
 create mode 100644 apps/gateway/tests/test_corpora.py

diff --git a/apps/admin-ui/src/app/corpora/page.tsx b/apps/admin-ui/src/app/corpora/page.tsx
index 7b06f11..9616187 100644
--- a/apps/admin-ui/src/app/corpora/page.tsx
+++ b/apps/admin-ui/src/app/corpora/page.tsx
@@ -26,7 +26,8 @@ import {
   TableSkeleton,
   Textarea,
 } from "@/components/ui/primitives";
-import { fetchCorpora } from "@/lib/api";
+import { createCorpus, deleteCorpus, fetchCorpora } from "@/lib/api";
+import { GATEWAY_URL } from "@/lib/config";
 import { CORPORA } from "@/lib/mock";
 import { absTime, relTime } from "@/lib/time";
 import type { Corpus } from "@/lib/types";
@@ -188,9 +189,35 @@ export default function CorporaPage() {
 
       {creating && (
         <NewCorpusDialog
-          tenantId={tenant.id}
           onClose={() => setCreating(false)}
-          onCreate={(corpus) => {
+          onCreate={async ({ display_name, description, embedding_model, embedding_dimension }) => {
+            let corpus: Corpus;
+            if (GATEWAY_URL && source === "live") {
+              try {
+                corpus = await createCorpus(tenant.id, {
+                  display_name,
+                  description,
+                  embedding_model,
+                  embedding_dimension,
+                });
+              } catch {
+                toast({ title: "Failed to create corpus", variant: "error" });
+                return;
+              }
+            } else {
+              corpus = {
+                id: "corpus_" + Math.random().toString(16).slice(2, 14),
+                tenant_id: tenant.id,
+                display_name,
+                description,
+                embedding_model,
+                embedding_dimension,
+                document_count: 0,
+                created_at: new Date().toISOString(),
+                updated_at: new Date().toISOString(),
+                metadata: {},
+              };
+            }
             setRows((prev) => [corpus, ...prev]);
             setCreating(false);
             toast({ title: "Corpus created", description: corpus.display_name, variant: "success" });
@@ -214,8 +241,15 @@ export default function CorporaPage() {
           </Button>
           <Button
             variant="destructive"
-            onClick={() => {
+            onClick={async () => {
               if (deleting) {
+                if (GATEWAY_URL && source === "live") {
+                  try {
+                    await deleteCorpus(tenant.id, deleting.id);
+                  } catch {
+                    /* fall through to local removal */
+                  }
+                }
                 setRows((prev) => prev.filter((c) => c.id !== deleting.id));
                 toast({ title: "Corpus deleted", description: deleting.display_name, variant: "error" });
               }
@@ -231,13 +265,16 @@ export default function CorporaPage() {
 }
 
 function NewCorpusDialog({
-  tenantId,
   onClose,
   onCreate,
 }: {
-  tenantId: string;
   onClose: () => void;
-  onCreate: (c: Corpus) => void;
+  onCreate: (v: {
+    display_name: string;
+    description: string;
+    embedding_model: string;
+    embedding_dimension: number;
+  }) => void;
 }) {
   const [name, setName] = useState("");
   const [description, setDescription] = useState("");
@@ -276,16 +313,10 @@ function NewCorpusDialog({
           disabled={!name.trim()}
           onClick={() =>
             onCreate({
-              id: "corpus_" + Math.random().toString(16).slice(2, 14),
-              tenant_id: tenantId,
               display_name: name.trim(),
               description: description.trim(),
               embedding_model: model,
               embedding_dimension: dim,
-              document_count: 0,
-              created_at: new Date().toISOString(),
-              updated_at: new Date().toISOString(),
-              metadata: {},
             })
           }
         >
diff --git a/apps/admin-ui/src/lib/api.ts b/apps/admin-ui/src/lib/api.ts
index 1d292e7..121c71e 100644
--- a/apps/admin-ui/src/lib/api.ts
+++ b/apps/admin-ui/src/lib/api.ts
@@ -83,6 +83,25 @@ export async function fetchCorpora(tenantId: string): Promise<Corpus[]> {
   return data.corpora;
 }
 
+export async function createCorpus(
+  tenantId: string,
+  body: {
+    display_name: string;
+    description: string;
+    embedding_model: string;
+    embedding_dimension: number;
+  },
+): Promise<Corpus> {
+  return request<Corpus>(tenantId, "/v1/corpora", {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+}
+
+export async function deleteCorpus(tenantId: string, id: string): Promise<void> {
+  await request<void>(tenantId, `/v1/corpora/${id}`, { method: "DELETE" });
+}
+
 export async function fetchWebhooks(tenantId: string): Promise<WebhookSubscription[]> {
   const data = await request<{ subscriptions: WebhookSubscription[]; total: number }>(
     tenantId,
diff --git a/apps/gateway/src/rag_gateway/corpora.py b/apps/gateway/src/rag_gateway/corpora.py
index 57f7447..3942bce 100644
--- a/apps/gateway/src/rag_gateway/corpora.py
+++ b/apps/gateway/src/rag_gateway/corpora.py
@@ -1,4 +1,4 @@
-"""``/v1/corpora`` read-only CRUD (Step 3.1).
+"""``/v1/corpora`` CRUD (read in Step 3.1, admin writes in Step 3.10).
 
 The gateway exposes corpus metadata as a discoverability surface for
 SDK consumers + admin UIs: clients hitting ``/v1/query`` need a way
@@ -6,24 +6,27 @@
 verify a given ``corpus_id`` is real (and visible) before making a
 query.
 
-v0 is **read-only** — list + get.  Create / update / delete belong
-with the admin UI surface in Step 3.10 (and the Postgres-backed
-:class:`CorpusStore` impl that lands with the corpus router in
-Step 3.5).  Read-only here keeps the SPI small while giving SDKs
-something to discover against.
+Read (``GET`` list + get) is the discovery surface; ``POST /v1/corpora``
+and ``DELETE /v1/corpora/{id}`` (Step 3.10) are the admin write surface
+behind the console's corpus-management UI.  The id is minted server-side
+and the tenant is taken from ``ctx``, so a caller can neither choose a
+corpus id nor write into (or delete from) another tenant.
 
 Tenant isolation is enforced at the SPI boundary:
-:meth:`CorpusStore.get` returns ``None`` for cross-tenant lookups
-rather than raising, so callers can't probe for other tenants'
-corpora.  This route surfaces ``None`` as ``404 Not Found``.
+:meth:`CorpusStore.get` / :meth:`CorpusStore.delete` treat a
+cross-tenant id as not-visible rather than raising, so callers can't
+probe for other tenants' corpora.  These routes surface that as
+``404 Not Found``.
 """
 
 from __future__ import annotations
 
-from fastapi import APIRouter, Request
+import uuid
+
+from fastapi import APIRouter, Request, Response
 from fastapi.responses import JSONResponse
 from rag_core import get_logger
-from rag_core.gateway_types import Corpus, CorpusList, GatewayError
+from rag_core.gateway_types import Corpus, CorpusList, CreateCorpusRequest, GatewayError
 from rag_core.types import CorpusId, RequestContext
 
 from rag_gateway.query import _require_ctx_for_handler
@@ -31,6 +34,11 @@
 _log = get_logger(__name__)
 
 
+def _new_corpus_id() -> str:
+    """Mint a unique corpus id — server-assigned so callers can't choose one."""
+    return f"corpus_{uuid.uuid4().hex}"
+
+
 def make_corpora_router() -> APIRouter:
     """Build the APIRouter for ``GET /v1/corpora`` + ``GET /v1/corpora/{id}``."""
     router = APIRouter(tags=["corpora"])
@@ -55,6 +63,45 @@ async def list_corpora(request: Request) -> CorpusList:
         corpora = await store.list(ctx)
         return CorpusList(corpora=corpora, total=len(corpora))
 
+    @router.post(
+        "/v1/corpora",
+        response_model=Corpus,
+        status_code=201,
+        responses={
+            401: {"model": GatewayError, "description": "Missing or invalid auth"},
+        },
+        summary="Create a corpus for the calling tenant",
+    )
+    async def create_corpus(request: Request, body: CreateCorpusRequest) -> Corpus:
+        """Create a corpus owned by the calling tenant.
+
+        The id is minted server-side (``corpus_…``) and the tenant comes
+        from ``ctx`` — the body carries only display fields + embedding
+        metadata, so a caller can neither pick an id nor create into
+        another tenant.  ``document_count`` starts at 0 and is maintained
+        by the ingest path.
+        """
+        ctx = _require_ctx_for_handler(request)
+        store = request.app.state.corpus_store
+        corpus = Corpus(
+            id=CorpusId(_new_corpus_id()),
+            tenant_id=ctx.tenant_id,
+            display_name=body.display_name,
+            description=body.description,
+            embedding_model=body.embedding_model,
+            embedding_dimension=body.embedding_dimension,
+            metadata=body.metadata,
+        )
+        created: Corpus = await store.create(ctx, corpus)
+        _log.info(
+            "corpus.created",
+            extra={
+                "rag_tenant_id": str(ctx.tenant_id),
+                "rag_corpus_id": str(created.id),
+            },
+        )
+        return created
+
     @router.get(
         "/v1/corpora/{corpus_id}",
         response_model=Corpus,
@@ -85,6 +132,39 @@ async def get_corpus(
             )
         return corpus
 
+    @router.delete(
+        "/v1/corpora/{corpus_id}",
+        status_code=204,
+        responses={
+            401: {"model": GatewayError, "description": "Missing or invalid auth"},
+            404: {"model": GatewayError, "description": "Corpus not found / not visible"},
+        },
+        summary="Delete a corpus",
+    )
+    async def delete_corpus(request: Request, corpus_id: str) -> Response:
+        """Delete a corpus owned by the calling tenant.
+
+        Cross-tenant / unknown ids return 404 — the same invisibility
+        rule as ``GET`` — so a caller can't probe for or delete another
+        tenant's corpora.
+        """
+        ctx = _require_ctx_for_handler(request)
+        store = request.app.state.corpus_store
+        deleted = await store.delete(ctx, CorpusId(corpus_id))
+        if not deleted:
+            return JSONResponse(
+                status_code=404,
+                content=_not_found_body(corpus_id, ctx),
+            )
+        _log.info(
+            "corpus.deleted",
+            extra={
+                "rag_tenant_id": str(ctx.tenant_id),
+                "rag_corpus_id": corpus_id,
+            },
+        )
+        return Response(status_code=204)
+
     return router
 
 
diff --git a/apps/gateway/tests/test_corpora.py b/apps/gateway/tests/test_corpora.py
new file mode 100644
index 0000000..6a20924
--- /dev/null
+++ b/apps/gateway/tests/test_corpora.py
@@ -0,0 +1,99 @@
+"""Gateway corpus surface — list / get (read) + create / delete (admin writes).
+
+The read side landed in Step 3.1; ``POST /v1/corpora`` + ``DELETE
+/v1/corpora/{id}`` are the Step 3.10 admin write surface.  These tests pin the
+contract the admin console relies on: server-minted ids, tenant scoping (a
+tenant can neither see nor delete another tenant's corpus), and the
+create→list→delete→404 lifecycle.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi.testclient import TestClient
+from rag_gateway import build_app
+
+HEADERS = {"x-tenant-id": "acme", "x-principal-id": "svc"}
+OTHER = {"x-tenant-id": "globex", "x-principal-id": "svc"}
+
+
+def _client() -> TestClient:
+    return TestClient(build_app())
+
+
+def _create(
+    client: TestClient, headers: dict[str, str] = HEADERS, **body: Any
+) -> dict[str, Any]:
+    payload = {"display_name": "Support KB", **body}
+    resp = client.post("/v1/corpora", json=payload, headers=headers)
+    assert resp.status_code == 201, resp.text
+    return resp.json()
+
+
+def test_create_mints_id_and_scopes_tenant() -> None:
+    client = _client()
+    created = _create(
+        client,
+        description="Tickets",
+        embedding_model="text-embedding-3-small",
+        embedding_dimension=1536,
+    )
+    assert created["id"].startswith("corpus_")
+    assert created["tenant_id"] == "acme"  # taken from ctx, not the body
+    assert created["display_name"] == "Support KB"
+    assert created["description"] == "Tickets"
+    assert created["embedding_dimension"] == 1536
+    assert created["document_count"] == 0  # ingest maintains this, not create
+
+
+def test_created_corpus_is_listed_and_gettable() -> None:
+    client = _client()
+    created = _create(client)
+    listed = client.get("/v1/corpora", headers=HEADERS).json()
+    assert listed["total"] == 1
+    assert listed["corpora"][0]["id"] == created["id"]
+    got = client.get(f"/v1/corpora/{created['id']}", headers=HEADERS).json()
+    assert got["id"] == created["id"]
+
+
+def test_create_rejects_blank_display_name() -> None:
+    client = _client()
+    resp = client.post("/v1/corpora", json={"display_name": ""}, headers=HEADERS)
+    assert resp.status_code == 422  # pydantic min_length
+
+
+def test_create_requires_auth() -> None:
+    client = _client()
+    resp = client.post("/v1/corpora", json={"display_name": "x"})
+    assert resp.status_code == 401
+
+
+def test_delete_removes_then_404s() -> None:
+    client = _client()
+    created = _create(client)
+    assert (
+        client.delete(f"/v1/corpora/{created['id']}", headers=HEADERS).status_code == 204
+    )
+    # gone from the list...
+    assert client.get("/v1/corpora", headers=HEADERS).json()["total"] == 0
+    # ...and a second delete is a 404 with the canonical error code.
+    resp = client.delete(f"/v1/corpora/{created['id']}", headers=HEADERS)
+    assert resp.status_code == 404
+    assert resp.json()["error"]["code"] == "corpus_not_found"
+
+
+def test_delete_unknown_returns_404() -> None:
+    client = _client()
+    assert client.delete("/v1/corpora/corpus_nope", headers=HEADERS).status_code == 404
+
+
+def test_tenant_isolation_on_get_and_delete() -> None:
+    client = _client()
+    created = _create(client)  # owned by acme
+    # globex can neither read it...
+    assert client.get(f"/v1/corpora/{created['id']}", headers=OTHER).status_code == 404
+    # ...nor delete it...
+    assert client.delete(f"/v1/corpora/{created['id']}", headers=OTHER).status_code == 404
+    # ...and acme still has it.
+    assert client.get(f"/v1/corpora/{created['id']}", headers=HEADERS).status_code == 200
diff --git a/dist/openapi.json b/dist/openapi.json
index e9b9437..c32db2b 100644
--- a/dist/openapi.json
+++ b/dist/openapi.json
@@ -1624,6 +1624,57 @@
         "title": "CounterView",
         "type": "object"
       },
+      "CreateCorpusRequest": {
+        "description": "``POST /v1/corpora`` body (admin write surface — Step 3.10).\n\n``id`` and ``tenant_id`` are assigned server-side — the id is minted\nas a unique ``corpus_…`` token and the tenant is taken from the\nauthenticated request — so a caller can neither choose a corpus id nor\ncreate into another tenant.  ``document_count`` starts at 0; it is\nmaintained by the ingest path, never set on create.",
+        "properties": {
+          "description": {
+            "default": "",
+            "title": "Description",
+            "type": "string"
+          },
+          "display_name": {
+            "description": "Human-readable corpus name shown in the console.",
+            "minLength": 1,
+            "title": "Display Name",
+            "type": "string"
+          },
+          "embedding_dimension": {
+            "anyOf": [
+              {
+                "minimum": 1.0,
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Embedding vector dimension.",
+            "title": "Embedding Dimension"
+          },
+          "embedding_model": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Model the corpus is embedded with (informational — documents dimension).",
+            "title": "Embedding Model"
+          },
+          "metadata": {
+            "additionalProperties": true,
+            "title": "Metadata",
+            "type": "object"
+          }
+        },
+        "required": [
+          "display_name"
+        ],
+        "title": "CreateCorpusRequest",
+        "type": "object"
+      },
       "CreateSubscriptionRequest": {
         "description": "``POST /v1/webhooks/subscriptions`` body.",
         "properties": {
@@ -5951,9 +6002,113 @@
         "tags": [
           "corpora"
         ]
+      },
+      "post": {
+        "description": "Create a corpus owned by the calling tenant.\n\nThe id is minted server-side (``corpus_…``) and the tenant comes\nfrom ``ctx`` — the body carries only display fields + embedding\nmetadata, so a caller can neither pick an id nor create into\nanother tenant.  ``document_count`` starts at 0 and is maintained\nby the ingest path.",
+        "operationId": "create_corpus_v1_corpora_post",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateCorpusRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "201": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Corpus"
+                }
+              }
+            },
+            "description": "Successful Response"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GatewayError"
+                }
+              }
+            },
+            "description": "Missing or invalid auth"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Create a corpus for the calling tenant",
+        "tags": [
+          "corpora"
+        ]
       }
     },
     "/v1/corpora/{corpus_id}": {
+      "delete": {
+        "description": "Delete a corpus owned by the calling tenant.\n\nCross-tenant / unknown ids return 404 — the same invisibility\nrule as ``GET`` — so a caller can't probe for or delete another\ntenant's corpora.",
+        "operationId": "delete_corpus_v1_corpora__corpus_id__delete",
+        "parameters": [
+          {
+            "in": "path",
+            "name": "corpus_id",
+            "required": true,
+            "schema": {
+              "title": "Corpus Id",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Successful Response"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GatewayError"
+                }
+              }
+            },
+            "description": "Missing or invalid auth"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GatewayError"
+                }
+              }
+            },
+            "description": "Corpus not found / not visible"
+          },
+          "422": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            },
+            "description": "Validation Error"
+          }
+        },
+        "summary": "Delete a corpus",
+        "tags": [
+          "corpora"
+        ]
+      },
       "get": {
         "description": "Return metadata for one corpus, or 404 if not visible.\n\nCross-tenant lookups (the corpus exists in a different tenant)\nreturn 404 deliberately — the response shape doesn't\ndistinguish \"not found\" from \"not visible\" so attackers\ncan't probe for other tenants' corpora.",
         "operationId": "get_corpus_v1_corpora__corpus_id__get",
diff --git a/dist/openapi.yaml b/dist/openapi.yaml
index 9e152cc..9ade1b5 100644
--- a/dist/openapi.yaml
+++ b/dist/openapi.yaml
@@ -1459,6 +1459,51 @@ components:
       - value
       title: CounterView
       type: object
+    CreateCorpusRequest:
+      description: '``POST /v1/corpora`` body (admin write surface — Step 3.10).
+
+
+        ``id`` and ``tenant_id`` are assigned server-side — the id is minted
+
+        as a unique ``corpus_…`` token and the tenant is taken from the
+
+        authenticated request — so a caller can neither choose a corpus id nor
+
+        create into another tenant.  ``document_count`` starts at 0; it is
+
+        maintained by the ingest path, never set on create.'
+      properties:
+        description:
+          default: ''
+          title: Description
+          type: string
+        display_name:
+          description: Human-readable corpus name shown in the console.
+          minLength: 1
+          title: Display Name
+          type: string
+        embedding_dimension:
+          anyOf:
+          - minimum: 1.0
+            type: integer
+          - type: 'null'
+          description: Embedding vector dimension.
+          title: Embedding Dimension
+        embedding_model:
+          anyOf:
+          - type: string
+          - type: 'null'
+          description: Model the corpus is embedded with (informational — documents
+            dimension).
+          title: Embedding Model
+        metadata:
+          additionalProperties: true
+          title: Metadata
+          type: object
+      required:
+      - display_name
+      title: CreateCorpusRequest
+      type: object
     CreateSubscriptionRequest:
       description: '``POST /v1/webhooks/subscriptions`` body.'
       properties:
@@ -4963,7 +5008,90 @@ paths:
       summary: List corpora visible to the calling tenant
       tags:
       - corpora
+    post:
+      description: 'Create a corpus owned by the calling tenant.
+
+
+        The id is minted server-side (``corpus_…``) and the tenant comes
+
+        from ``ctx`` — the body carries only display fields + embedding
+
+        metadata, so a caller can neither pick an id nor create into
+
+        another tenant.  ``document_count`` starts at 0 and is maintained
+
+        by the ingest path.'
+      operationId: create_corpus_v1_corpora_post
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateCorpusRequest'
+        required: true
+      responses:
+        '201':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Corpus'
+          description: Successful Response
+        '401':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GatewayError'
+          description: Missing or invalid auth
+        '422':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPValidationError'
+          description: Validation Error
+      summary: Create a corpus for the calling tenant
+      tags:
+      - corpora
   /v1/corpora/{corpus_id}:
+    delete:
+      description: 'Delete a corpus owned by the calling tenant.
+
+
+        Cross-tenant / unknown ids return 404 — the same invisibility
+
+        rule as ``GET`` — so a caller can''t probe for or delete another
+
+        tenant''s corpora.'
+      operationId: delete_corpus_v1_corpora__corpus_id__delete
+      parameters:
+      - in: path
+        name: corpus_id
+        required: true
+        schema:
+          title: Corpus Id
+          type: string
+      responses:
+        '204':
+          description: Successful Response
+        '401':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GatewayError'
+          description: Missing or invalid auth
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GatewayError'
+          description: Corpus not found / not visible
+        '422':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPValidationError'
+          description: Validation Error
+      summary: Delete a corpus
+      tags:
+      - corpora
     get:
       description: 'Return metadata for one corpus, or 404 if not visible.
 
diff --git a/docs/architecture/gateway.md b/docs/architecture/gateway.md
index f493c5c..b505900 100644
--- a/docs/architecture/gateway.md
+++ b/docs/architecture/gateway.md
@@ -127,7 +127,7 @@ Production wires real backends via `build_app(understanding=..., retrieval_route
 ## What's deliberately deferred
 
 - **SSE streaming.**  TRACKER.md lists it under 3.1 but the 🥈 milestone is `curl returns JSON`.  SSE adds event framing + partial-result emission + abort semantics; it lands with gRPC streaming in Step 3.2 where the framing decisions naturally belong.
-- **`/v1/corpora` CRUD.**  v0 is read-only.  Create / update / delete belong with the admin UI surface in Step 3.10.
+- **`/v1/corpora` CRUD.**  Read (list / get) shipped in v0; `POST` (create) and `DELETE` shipped with the admin UI surface in Step 3.10.  Update (`PUT`/`PATCH`) is still deferred — the console edits no corpus fields yet.
 - **Real `Auth` impl.**  `NoopAuth` accepts anything.  Production `Auth` (OIDC / JWT / API-key) lands with Phase 6 governance.
 - **`rag.yaml` config-driven wiring.**  Step 3.5 — every backend is constructable from config so deployments don't need to re-write `build_app(...)`.
 - **`POST /v1/ingest/document` improvements**: bulk ingest, async polling, audit-log query.  Step 3.x as needed.
diff --git a/docs/reference/admin-ui.md b/docs/reference/admin-ui.md
index 0fbfdf4..02cb222 100644
--- a/docs/reference/admin-ui.md
+++ b/docs/reference/admin-ui.md
@@ -19,7 +19,7 @@ state control):
 | Metrics | `/metrics` | **live** `WS /v1/status/ws` → seed fallback (Step 3.11) |
 | Logs | `/logs` | **live** SSE `/v1/status/logs/stream` → seed fallback (Step 3.11) |
 | Query Trace | `/trace` | **live** `GET /v1/query/{id}/trace` → seed fallback (Step 5.1/5.6b) |
-| Corpora | `/corpora` | **live** `GET /v1/corpora` → seed fallback |
+| Corpora | `/corpora` | **live** `GET /v1/corpora` (list) + `POST` (create) + `DELETE` → seed fallback (writes are local-only in demo mode, Step 3.10) |
 | Connectors | `/connectors` | seed |
 | Ingest | `/ingest` | **live** multipart `POST /v1/ingest/document` → seed simulation (Step 7.9b) |
 | Glossary | `/glossary` | seed |
diff --git a/docs/reference/gateway.md b/docs/reference/gateway.md
index eed3281..92fc1a0 100644
--- a/docs/reference/gateway.md
+++ b/docs/reference/gateway.md
@@ -14,6 +14,8 @@
 | `POST /v1/retrieve` | Retrieval-only subset (no rerank / pack / generate). |
 | `GET  /v1/corpora` | List corpora visible to the calling tenant. |
 | `GET  /v1/corpora/{id}` | Describe one corpus. |
+| `POST /v1/corpora` | Create a corpus for the calling tenant (admin surface, Step 3.10). |
+| `DELETE /v1/corpora/{id}` | Delete a corpus owned by the calling tenant (admin surface, Step 3.10). |
 | `GET  /openapi.json` | Auto-generated OpenAPI 3.1 spec. |
 | `GET  /docs` | Swagger UI. |
 | `GET  /redoc` | ReDoc UI. |
@@ -141,6 +143,43 @@ Response:
 
 Describe one corpus.  **Cross-tenant lookups return 404, not 403** — this is deliberate.  The response shape doesn't distinguish "not found" from "not visible" so callers can't probe for other tenants' corpora.
 
+## `POST /v1/corpora`
+
+Create a corpus owned by the calling tenant (the admin write surface behind the console's Corpora page, Step 3.10).  The body carries only display fields and embedding metadata — **`id` is minted server-side** (`corpus_…`) and **`tenant_id` is taken from the authenticated request**, so a caller can neither choose an id nor create into another tenant.  `document_count` starts at `0` and is maintained by the ingest path.  Returns `201` with the created `Corpus`.
+
+```bash
+curl -s -X POST http://localhost:8000/v1/corpora \
+  -H 'content-type: application/json' \
+  -H 'x-tenant-id: demo' \
+  -H 'x-principal-id: curl' \
+  -d '{
+    "display_name": "Support KB",
+    "description": "Customer support tickets",
+    "embedding_model": "text-embedding-3-small",
+    "embedding_dimension": 1536
+  }' | jq
+```
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `display_name` | string | ✓ | Human-readable name (min length 1). |
+| `description` | string | | Defaults to `""`. |
+| `embedding_model` | string \| null | | Informational — documents the model the corpus is embedded with. |
+| `embedding_dimension` | int \| null | | Embedding vector dimension (`≥ 1`). |
+| `metadata` | object | | Free-form tenant metadata. |
+
+A blank `display_name` is rejected with `422`; a request without tenant / principal credentials is rejected with `401`.
+
+## `DELETE /v1/corpora/{corpus_id}`
+
+Delete a corpus owned by the calling tenant.  Returns `204` on success.  **Cross-tenant or unknown ids return `404`** — the same invisibility rule as `GET`, so a caller can neither delete nor probe for another tenant's corpora.
+
+```bash
+curl -s -X DELETE http://localhost:8000/v1/corpora/corpus_8f… \
+  -H 'x-tenant-id: demo' \
+  -H 'x-principal-id: curl' -i
+```
+
 ## OpenAPI 3.1
 
 The spec is auto-generated by FastAPI at `/openapi.json`.  Routes carry `tags`, `summary`, `description` (from the route docstring), and `responses` tables for the documented error codes.
diff --git a/packages/backends/src/rag_backends/corpus/pg_corpus_store.py b/packages/backends/src/rag_backends/corpus/pg_corpus_store.py
index 4ba8d8d..523af0f 100644
--- a/packages/backends/src/rag_backends/corpus/pg_corpus_store.py
+++ b/packages/backends/src/rag_backends/corpus/pg_corpus_store.py
@@ -1,19 +1,19 @@
 """PostgreSQL-backed implementation of the ``CorpusStore`` SPI (Step 3.5).
 
-The ``CorpusStore`` contract is read-only (``list`` / ``get``) — corpus
-*creation* is an operator action that lands with the admin surface in
-Step 3.10.  This backend therefore exposes the SPI read side plus an
-out-of-band :meth:`upsert` helper used by ``ragctl corpus seed`` and the
-integration tests to populate the registry.  ``upsert`` is deliberately
-*not* part of the SPI so service-facing callers can't mutate corpora
-through the read path.
+The ``CorpusStore`` SPI is ``list`` / ``get`` (read) plus ``create`` /
+``delete`` (the Step 3.10 admin surface) — all four tenant-scoped in SQL.
+:meth:`upsert` stays as an out-of-band operator/seed helper used by
+``ragctl corpus seed`` and the integration tests; unlike the ``create``
+SPI it also *updates* an existing row, so it is kept off the SPI to keep
+"create" honest.
 
 Usage::
 
     store = PgCorpusStore(dsn="postgresql://rag:rag@localhost:5432/rag")
     await store.initialize()          # creates table once (idempotent)
-    await store.upsert(corpus)        # operator / seed path
+    await store.create(ctx, corpus)   # admin write (or upsert() to seed)
     corpora = await store.list(ctx)   # tenant-scoped read
+    await store.delete(ctx, corpus.id)
     await store.close()
 
 Tenant isolation is enforced in SQL: every read is scoped by
@@ -95,6 +95,12 @@
 _SQL_LIST = _SQL_SELECT_COLS + "WHERE tenant_id = $1"
 _SQL_GET = _SQL_SELECT_COLS + "WHERE tenant_id = $1 AND corpus_id = $2"
 
+# ``RETURNING`` lets us report existed/not-existed without a prior SELECT,
+# while the ``tenant_id = $1`` predicate keeps the delete tenant-scoped.
+_SQL_DELETE = (
+    "DELETE FROM {table} WHERE tenant_id = $1 AND corpus_id = $2 RETURNING corpus_id"
+)
+
 
 def _as_dict(value: Any) -> dict[str, Any]:
     """Normalise a JSONB column to a dict.
@@ -198,6 +204,24 @@ async def get(self, ctx: RequestContext, corpus_id: CorpusId) -> Corpus | None:
             )
         return self._row_to_corpus(row) if row is not None else None
 
+    async def create(self, ctx: RequestContext, corpus: Corpus) -> Corpus:
+        # Reuse the upsert path: the gateway mints a fresh unique id, so in
+        # practice there is no conflict; the ON CONFLICT clause only ever
+        # fires for the seed/operator path that intentionally re-runs.
+        # ``corpus.tenant_id`` is set from ``ctx`` at the boundary.
+        await self.upsert(corpus)
+        return corpus
+
+    async def delete(self, ctx: RequestContext, corpus_id: CorpusId) -> bool:
+        pool = await self._get_pool()
+        async with pool.acquire() as conn:
+            row = await conn.fetchrow(
+                _SQL_DELETE.format(table=self._table),
+                str(ctx.tenant_id),
+                str(corpus_id),
+            )
+        return row is not None
+
     async def health(self) -> bool:
         try:
             pool = await self._get_pool()
diff --git a/packages/core/src/rag_core/gateway_types.py b/packages/core/src/rag_core/gateway_types.py
index efaa1ca..06e245c 100644
--- a/packages/core/src/rag_core/gateway_types.py
+++ b/packages/core/src/rag_core/gateway_types.py
@@ -98,6 +98,32 @@ class Corpus(BaseModel):
     metadata: dict[str, Any] = Field(default_factory=dict)
 
 
+class CreateCorpusRequest(BaseModel):
+    """``POST /v1/corpora`` body (admin write surface — Step 3.10).
+
+    ``id`` and ``tenant_id`` are assigned server-side — the id is minted
+    as a unique ``corpus_…`` token and the tenant is taken from the
+    authenticated request — so a caller can neither choose a corpus id nor
+    create into another tenant.  ``document_count`` starts at 0; it is
+    maintained by the ingest path, never set on create.
+    """
+
+    model_config = {"frozen": True}
+
+    display_name: str = Field(
+        min_length=1, description="Human-readable corpus name shown in the console."
+    )
+    description: str = ""
+    embedding_model: str | None = Field(
+        default=None,
+        description="Model the corpus is embedded with (informational — documents dimension).",
+    )
+    embedding_dimension: int | None = Field(
+        default=None, ge=1, description="Embedding vector dimension."
+    )
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
 # ---------------------------------------------------------------------------
 # Request shapes
 # ---------------------------------------------------------------------------
@@ -596,6 +622,7 @@ class GatewayError(BaseModel):
     "ComplianceEraseRequest",
     "Corpus",
     "CorpusList",
+    "CreateCorpusRequest",
     "ExperimentAssignment",
     "FeedbackAck",
     "FeedbackRequest",
diff --git a/packages/core/src/rag_core/spi/corpus_store.py b/packages/core/src/rag_core/spi/corpus_store.py
index de9c42a..22595cc 100644
--- a/packages/core/src/rag_core/spi/corpus_store.py
+++ b/packages/core/src/rag_core/spi/corpus_store.py
@@ -1,4 +1,4 @@
-"""CorpusStore SPI — read-only tenant-scoped corpus registry (Step 3.1).
+"""CorpusStore SPI — tenant-scoped corpus registry (Step 3.1, writes in 3.10).
 
 The gateway's ``GET /v1/corpora`` + ``GET /v1/corpora/{id}`` routes
 read from this SPI.  Production backends (Postgres-backed corpus
@@ -6,14 +6,18 @@
 the read side + the in-memory noop reference impl so the gateway
 demo runs creds-free.
 
-The contract is deliberately read-only.  Create / delete are
-operator actions tied to the admin surface (Step 3.10); they don't
-belong on a service-facing SPI.
+Read (``list`` / ``get``) is the service-facing surface every query
+path depends on.  ``create`` / ``delete`` (Step 3.10) back the admin
+console's corpus-management UI — tenant-scoped writes guarded by the
+same isolation rule, kept off the hot query path.  They are not
+consulted by retrieval, so they carry no ``PolicyEngine`` obligation
+(see the policy-coverage rule set); the write authority is the
+caller's authenticated tenant on ``ctx``.
 
 Tenant isolation is the same rule as every other SPI: a corpus
-created under tenant A must never resolve when ``ctx.tenant_id`` is
-tenant B, regardless of backend.  The reference noop impl enforces
-this with a tenant-scoped key.
+created under tenant A must never resolve — nor be deletable — when
+``ctx.tenant_id`` is tenant B, regardless of backend.  The reference
+noop impl enforces this with a tenant-scoped key.
 """
 
 from __future__ import annotations
@@ -66,5 +70,30 @@ async def get(
         tenants' corpora.
         """
 
+    @abc.abstractmethod
+    async def create(self, ctx: RequestContext, corpus: Corpus) -> Corpus:
+        """Persist a new corpus owned by ``ctx.tenant_id`` and return it.
+
+        The returned instance reflects what was stored (with any
+        store-assigned fields populated).  ``corpus.tenant_id`` is set by
+        the caller from ``ctx`` at the gateway boundary, so implementations
+        store it as given — they MUST NOT let a caller write into another
+        tenant by smuggling a mismatched ``corpus.tenant_id``.
+
+        The ``id`` is assigned by the caller (the gateway mints a unique
+        ``corpus_…`` id); implementations persist it verbatim.
+        """
+
+    @abc.abstractmethod
+    async def delete(self, ctx: RequestContext, corpus_id: CorpusId) -> bool:
+        """Delete the corpus from ``ctx.tenant_id``; return whether it existed.
+
+        Returns ``True`` if a corpus was removed, ``False`` if no corpus
+        with that id was visible to ``ctx.tenant_id`` (missing, or owned by
+        a different tenant — the same cross-tenant invisibility rule as
+        :meth:`get`, so a caller can't delete or probe another tenant's
+        corpora).  Implementations MUST NOT raise on a missing id.
+        """
+
 
 __all__ = ["CorpusStore"]
diff --git a/packages/core/src/rag_core/spi/noop/corpus_store.py b/packages/core/src/rag_core/spi/noop/corpus_store.py
index bcb3b35..81d4bfa 100644
--- a/packages/core/src/rag_core/spi/noop/corpus_store.py
+++ b/packages/core/src/rag_core/spi/noop/corpus_store.py
@@ -16,9 +16,10 @@ class NoopCorpusStore(CorpusStore):
     """In-memory dict, tenant-scoped.
 
     Construct with an optional ``seed`` list to pre-populate
-    deterministic corpora for tests + smoke flows.  ``register`` /
-    ``unregister`` are test-only helpers — production callers
-    should not mutate corpora through the read-side SPI.
+    deterministic corpora for tests + smoke flows.  ``create`` /
+    ``delete`` are the tenant-scoped SPI writes (admin surface,
+    Step 3.10); ``register`` / ``unregister`` remain as synchronous
+    test-only helpers that bypass ``ctx``.
     """
 
     def __init__(self, seed: list[Corpus] | None = None) -> None:
@@ -40,6 +41,17 @@ async def get(
     ) -> Corpus | None:
         return self._by_key.get((str(ctx.tenant_id), str(corpus_id)))
 
+    async def create(self, ctx: RequestContext, corpus: Corpus) -> Corpus:
+        # ``corpus.tenant_id`` is set from ``ctx`` at the gateway boundary;
+        # key on it so a corpus only ever lands in its owner's tenant.
+        self._by_key[(str(corpus.tenant_id), str(corpus.id))] = corpus
+        return corpus
+
+    async def delete(self, ctx: RequestContext, corpus_id: CorpusId) -> bool:
+        # Scope the delete to the caller's tenant so tenant A can't remove
+        # (or probe for) tenant B's corpus by id.
+        return self._by_key.pop((str(ctx.tenant_id), str(corpus_id)), None) is not None
+
     async def health(self) -> bool:
         return True
 
diff --git a/tests/contract/test_corpus_store.py b/tests/contract/test_corpus_store.py
index 1506a44..a20bfd5 100644
--- a/tests/contract/test_corpus_store.py
+++ b/tests/contract/test_corpus_store.py
@@ -93,3 +93,30 @@ async def test_unregister_helper_removes_corpus() -> None:
     store = NoopCorpusStore(seed=[_corpus("docs")])
     store.unregister("tenant-a", "docs")
     assert await store.get(_ctx(), CorpusId("docs")) is None
+
+
+# ---- create / delete (admin write surface, Step 3.10) ---------------------
+async def test_create_persists_and_is_tenant_scoped() -> None:
+    store = NoopCorpusStore()
+    created = await store.create(_ctx("tenant-a"), _corpus("docs", tenant="tenant-a"))
+    assert str(created.id) == "docs"
+    # visible to its owner...
+    assert [str(c.id) for c in await store.list(_ctx("tenant-a"))] == ["docs"]
+    # ...and to nobody else.
+    assert await store.list(_ctx("tenant-b")) == []
+
+
+async def test_delete_removes_and_reports_existence() -> None:
+    store = NoopCorpusStore(seed=[_corpus("docs")])
+    assert await store.delete(_ctx(), CorpusId("docs")) is True
+    assert await store.get(_ctx(), CorpusId("docs")) is None
+    # second delete: nothing left → False, never raises.
+    assert await store.delete(_ctx(), CorpusId("docs")) is False
+
+
+async def test_delete_cross_tenant_is_a_noop() -> None:
+    """Tenant A must NOT be able to delete tenant B's corpus by id."""
+    store = NoopCorpusStore(seed=[_corpus("wiki", tenant="tenant-b")])
+    assert await store.delete(_ctx("tenant-a"), CorpusId("wiki")) is False
+    # still present for its real owner.
+    assert await store.get(_ctx("tenant-b"), CorpusId("wiki")) is not None
diff --git a/tests/integration/test_pg_corpus_store.py b/tests/integration/test_pg_corpus_store.py
index e2d8fda..9b0fcff 100644
--- a/tests/integration/test_pg_corpus_store.py
+++ b/tests/integration/test_pg_corpus_store.py
@@ -86,3 +86,25 @@ async def test_upsert_updates_in_place(store: PgCorpusStore) -> None:
     assert got is not None
     assert got.document_count == 42
     assert len(await store.list(ctx)) == 1
+
+
+async def test_create_and_delete(store: PgCorpusStore) -> None:
+    ctx = make_ctx(tenant_id="t-corp-8")
+    await store.create(ctx, _corpus("kb", "t-corp-8", description="Knowledge base"))
+    got = await store.get(ctx, CorpusId("kb"))
+    assert got is not None
+    assert got.description == "Knowledge base"
+    assert await store.delete(ctx, CorpusId("kb")) is True
+    assert await store.get(ctx, CorpusId("kb")) is None
+    # idempotent: deleting again reports False, never raises.
+    assert await store.delete(ctx, CorpusId("kb")) is False
+
+
+async def test_delete_is_tenant_scoped(store: PgCorpusStore) -> None:
+    owner = make_ctx(tenant_id="t-corp-9")
+    other = make_ctx(tenant_id="t-corp-10")
+    await store.create(owner, _corpus("private", "t-corp-9"))
+    # a different tenant can't delete it...
+    assert await store.delete(other, CorpusId("private")) is False
+    # ...and it survives for its owner.
+    assert await store.get(owner, CorpusId("private")) is not None