docs(api): API reference docs umbrella (AGE-3734)

api/oss/src/apis/fastapi/folders/models.py

@@ -1,7 +1,7 @@
 from typing import Optional, List
 from uuid import UUID
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 from fastapi import HTTPException
 
 from oss.src.utils.exceptions import Support
@@ -15,30 +15,57 @@
 
 
 class FolderCreateRequest(BaseModel):
-    folder: FolderCreate
+    folder: FolderCreate = Field(
+        ...,
+        description="Folder to create. `slug` is required; `parent_id` nests the new folder under an existing one.",
+    )
 
 
 class FolderEditRequest(BaseModel):
-    folder: FolderEdit
+    folder: FolderEdit = Field(
+        ...,
+        description="Folder edit payload. `id` must match the path parameter. Only fields present in the payload are changed.",
+    )
 
 
 class FolderQueryRequest(BaseModel):
-    folder: FolderQuery
+    folder: FolderQuery = Field(
+        ...,
+        description="Filter object. Any combination of `id`/`ids`, `slug`/`slugs`, `kind`/`kinds`, `parent_id`/`parent_ids`, `path`/`paths`, and `prefix`/`prefixes` narrows the result.",
+    )
 
 
 class FolderResponse(Support):
-    count: int = 0
-    folder: Optional[Folder] = None
+    count: int = Field(
+        default=0,
+        description="Number of folders returned (`0` or `1`).",
+    )
+    folder: Optional[Folder] = Field(
+        default=None,
+        description="The folder, when found. Omitted when `count` is `0`.",
+    )
 
 
 class FoldersResponse(Support):
-    count: int = 0
-    folders: List[Folder] = []
+    count: int = Field(
+        default=0,
+        description="Number of folders in `folders`.",
+    )
+    folders: List[Folder] = Field(
+        default_factory=list,
+        description="Matching folders for the query. Ordering is not guaranteed.",
+    )
 
 
 class FolderIdResponse(Support):
-    count: int = 0
-    id: Optional[UUID] = None
+    count: int = Field(
+        default=0,
+        description="`1` if a folder was deleted, `0` if no folder matched.",
+    )
+    id: Optional[UUID] = Field(
+        default=None,
+        description="Id of the deleted folder. Omitted when nothing was deleted.",
+    )
 
 
 class FolderNameInvalidException(HTTPException):

api/oss/src/apis/fastapi/folders/router.py

@@ -141,6 +141,16 @@ async def create_folder(
         #
         folder_create_request: FolderCreateRequest,
     ) -> FolderResponse:
+        """
+        Create a folder.
+
+        The folder name must match `[\\w -]+` (letters, digits, underscore,
+        space, hyphen); other characters return `400`. The resulting path
+        (the slug joined to the parent's path with a dot) must be unique
+        within the project, otherwise the call returns `409`. Passing a
+        `parent_id` that does not exist returns `404`. Paths are capped at
+        10 levels of nesting and slugs at 64 characters.
+        """
         if is_ee():
             if not await check_action_access(  # type: ignore
                 user_uid=request.state.user_id,
@@ -171,6 +181,12 @@ async def fetch_folder(
         #
         folder_id: UUID,
     ) -> FolderResponse:
+        """
+        Fetch one folder by id.
+
+        Returns a single `folder` envelope. If the folder does not exist in
+        the caller's project, `count` is `0` and `folder` is omitted.
+        """
         if is_ee():
             if not await check_action_access(  # type: ignore
                 user_uid=request.state.user_id,
@@ -201,6 +217,15 @@ async def edit_folder(
         folder_id: UUID,
         folder_edit_request: FolderEditRequest,
     ) -> FolderResponse:
+        """
+        Rename or move a folder.
+
+        Use this endpoint to change a folder's `slug`, `name`, or
+        `parent_id`. The `id` in the request body must match the path
+        parameter or the call returns `400`. Name and path-uniqueness rules
+        from create apply: invalid names return `400`, a path collision
+        returns `409`, and a missing `parent_id` returns `404`.
+        """
         if is_ee():
             if not await check_action_access(  # type: ignore
                 user_uid=request.state.user_id,
@@ -236,6 +261,15 @@ async def delete_folder(
         #
         folder_id: UUID,
     ) -> FolderIdResponse:
+        """
+        Delete a folder and every descendant.
+
+        Removes the folder identified by `folder_id` together with every
+        folder beneath it, in a single transaction. Deletion is
+        unconditional; there is no archive or unarchive step. Resources
+        that were assigned to any of the removed folders continue to
+        exist and are no longer reachable through the deleted folder.
+        """
         if is_ee():
             if not await check_action_access(  # type: ignore
                 user_uid=request.state.user_id,
@@ -266,6 +300,17 @@ async def query_folders(
         #
         folder_query_request: FolderQueryRequest,
     ) -> FoldersResponse:
+        """
+        Filter folders inside the caller's project.
+
+        Follows the general response envelope described in the
+        [Query Pattern](/reference/api-guide/query-pattern) guide, but
+        does not accept `windowing` or `include_archived` — folders are
+        hard-deleted and the response always returns the full filtered
+        set. Filters include `id`/`ids`, `slug`/`slugs`, `kind`/`kinds`,
+        `parent_id`/`parent_ids` (use `parent_id: null` for root folders),
+        `path`/`paths`, and `prefix`/`prefixes` for subtree lookup.
+        """
         if is_ee():
             if not await check_action_access(  # type: ignore
                 user_uid=request.state.user_id,

api/oss/src/apis/fastapi/otlp/models.py

@@ -1,9 +1,8 @@
 from typing import List, Optional
 from datetime import datetime
 
-from pydantic import BaseModel, ConfigDict
-
 from oss.src.utils.exceptions import Support
+from pydantic import BaseModel, ConfigDict, Field
 
 from oss.src.core.otel.dtos import (
     OTelSpanDTO,
@@ -15,7 +14,14 @@
 
 
 class CollectStatusResponse(Support):
-    status: str
+    """OTLP endpoint readiness response."""
+
+    status: str = Field(
+        description=(
+            "Readiness string. `ready` means the router is mounted and "
+            "accepts OTLP ingest."
+        ),
+    )
 
 
 class OTelTracingResponse(Support):

api/oss/src/apis/fastapi/otlp/router.py

@@ -66,13 +66,48 @@ def __init__(
 
     @intercept_exceptions()
     async def otlp_status(self):
+        """Return the OTLP endpoint liveness status.
+
+        Lightweight readiness probe. Returns `{"status": "ready"}` when
+        the router is mounted. Intended for health checks from OTel
+        collectors before they start exporting traces.
+        """
         return CollectStatusResponse(status="ready")
 
     @intercept_exceptions()
     async def otlp_ingest(
         self,
         request: Request,
     ):
+        """Ingest traces via the OTLP/HTTP protobuf protocol.
+
+        This endpoint accepts a serialized
+        `ExportTraceServiceRequest` protobuf. Point any OTLP/HTTP
+        collector or SDK at `POST /otlp/v1/traces` and spans will flow
+        into the same ingest stream as the Agenta-native endpoints.
+
+        Use this when you already have OTel instrumentation emitting
+        OTLP. For new integrations that don't need raw OTLP, prefer
+        `POST /tracing/spans/ingest` — it takes JSON, accepts Agenta's
+        nested shape directly, and surfaces parse failures immediately.
+
+        ## Content-Type and size limit
+
+        Binary protobuf only (`Content-Type: application/x-protobuf`).
+        JSON OTLP is not accepted. Requests larger than the configured
+        batch limit (default 4 MB, see `OTLP_MAX_BATCH_BYTES`) return
+        `413 Request Entity Too Large`.
+
+        ## Response
+
+        Successful ingest returns `200 OK` with a serialized
+        `ExportTraceServiceResponse` protobuf. Parse failures on the
+        request body return `400`; malformed spans return `500`; quota
+        exhaustion returns `403`. Like the native ingest paths, spans
+        are queued on a Redis stream and persisted asynchronously — see
+        [Tracing — Async write
+        contract](/reference/api-guide/tracing#async-write-contract-202).
+        """
         # -------------------------------------------------------------------- #
         # Permission check
         # -------------------------------------------------------------------- #

api/oss/src/apis/fastapi/testcases/models.py

@@ -1,7 +1,7 @@
 from typing import Optional, List
 from uuid import UUID
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from oss.src.utils.exceptions import Support
 
@@ -18,23 +18,56 @@
 
 
 class TestcasesQueryRequest(BaseModel):
-    testcase_ids: Optional[List[UUID]] = None
+    testcase_ids: Optional[List[UUID]] = Field(
+        default=None,
+        description="Explicit list of testcase IDs to fetch. Combine with `testset_id` or testset references to scope the lookup.",
+    )
     #
-    testset_id: Optional[UUID] = None
+    testset_id: Optional[UUID] = Field(
+        default=None,
+        description="Return all testcases stored in this testset. The testset owns its testcases as a content-addressed bag; a revision references a subset of these.",
+    )
     #
-    testset_ref: Optional[Reference] = None
-    testset_variant_ref: Optional[Reference] = None
-    testset_revision_ref: Optional[Reference] = None
+    testset_ref: Optional[Reference] = Field(
+        default=None,
+        description="Testset reference used to resolve the latest revision on the default variant. The revision's ordered testcase IDs are used for the lookup and pagination.",
+    )
+    testset_variant_ref: Optional[Reference] = Field(
+        default=None,
+        description="Testset variant reference used to resolve the latest revision on that variant.",
+    )
+    testset_revision_ref: Optional[Reference] = Field(
+        default=None,
+        description="Specific testset revision reference. The revision's ordered testcase IDs drive the lookup and cursor pagination.",
+    )
     #
-    windowing: Optional[Windowing] = None
+    windowing: Optional[Windowing] = Field(
+        default=None,
+        description="Cursor-based pagination. When a revision reference is used, the cursor walks the revision's deterministic testcase ID list.",
+    )
 
 
 class TestcaseResponse(Support):
-    count: int = 0
-    testcase: Optional[Testcase] = None
+    count: int = Field(
+        default=0,
+        description="1 if a testcase was returned, 0 otherwise.",
+    )
+    testcase: Optional[Testcase] = Field(
+        default=None,
+        description="The testcase blob. `data` carries the user-defined columns; `testcase_dedup_id` (inside `data`) is the caller-supplied dedup key when present.",
+    )
 
 
 class TestcasesResponse(Support):
-    count: int = 0
-    testcases: List[Testcase] = []
-    windowing: Optional[Windowing] = None
+    count: int = Field(
+        default=0,
+        description="Number of testcases returned on this page.",
+    )
+    testcases: List[Testcase] = Field(
+        default_factory=list,
+        description="Testcase blobs matching the query, in revision-order when scoped by a revision reference.",
+    )
+    windowing: Optional[Windowing] = Field(
+        default=None,
+        description="Cursor for the next page, if more results exist.",
+    )