docs: move file list endpoint to dedicated api

[arpitgupta1214]

Summary

• document the file list endpoint under the dedicated GET /api/files route
• move the file-list spec into the split content OpenAPI document
• add the Files nav entry and include owner_email in the response schema

Verification

• confirmed the docs page is wired into navigation
• verified the spec references GET /api/files and no longer documents /api/files/list

---

Summary by cubic

Documented the File List endpoint under a dedicated Files API and added a new docs page. The OpenAPI now exposes GET /api/files with clear params, auth, error responses, and a nullable owner_email in the response.

• New Features
  • Added GET /api/files to api-reference/openapi/content.json with artist_account_id (required), path, recursive, and auth via apiKeyAuth or bearerAuth.
  • Defined FileListItem and FilesListResponse schemas; owner_email is always present and nullable when the owner has no email.
  • Created api-reference/files/list.mdx and added a "Files" nav group in docs.json.

^{Written for commit 09a92b6. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Introduced a new API endpoint to retrieve and list files and directories associated with artist accounts, supporting optional path filtering and recursive directory traversal.

• Documentation

  • Added API reference documentation for the file listing endpoint, including query parameters, response schemas, and error handling specifications.

[coderabbitai]

📝 Walkthrough

Walkthrough

A new API endpoint for listing files is being documented. The changes introduce OpenAPI specification for a GET /api/files endpoint with corresponding MDX documentation and navigation entries, defining query parameters, response schemas, and error handling.

Changes

Cohort / File(s)	Summary
API Documentation api-reference/files/list.mdx, docs.json	Added MDX documentation page for the List Files endpoint and registered it in the documentation navigation under a new "Files" group.
OpenAPI Specification api-reference/openapi/content.json	Defined the GET /api/files endpoint with required artist_account_id query parameter, optional path and recursive parameters, and introduced two new response schemas: FileListItem (file/folder metadata) and FilesListResponse (array wrapper).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

---

🐰 A listing endpoint hops into view,
With schemas so clean and parameters true,
Files organized in a structured tree,
From artist to folder, retrieval runs free!
Documentation blooms where features take flight, 🌿

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title mentions moving a file list endpoint to a dedicated API, but the changes actually add new documentation and API specification for the file list endpoint rather than moving it from an existing location.	Consider clarifying the title to reflect the actual action: either 'docs: add file list endpoint documentation' if this is a new addition, or provide context about where the endpoint was previously documented if it was indeed moved.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@api-reference/files/list.mdx`:
- Line 3: The frontmatter value for openapi is incorrectly set to a file path
plus method; update the openapi frontmatter in this file (and similar
api-reference pages) to the required format "METHOD /path" (e.g., change
openapi: "/api-reference/openapi/content.json GET /api/files" to openapi: "GET
/api/files"); ensure any other api-reference pages follow the same pattern and
perform a quick grep for the malformed pattern to fix them consistently.

In `@api-reference/openapi/content.json`:
- Around line 293-377: The GET operation for /api/files is missing a security
requirement despite mentioning authentication; add a security array to the get
operation that declares both auth methods referenced in the description (e.g.,
add two security requirement objects: one for the bearer token scheme name used
in components.securitySchemes (e.g., "bearerAuth": []) and one for the API key
scheme name used for x-api-key (e.g., "apiKeyAuth": [])) so generated docs and
SDKs mark the endpoint as requiring authentication.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b66eddee-80fa-4057-b639-02561af2f556

📥 Commits

Reviewing files that changed from the base of the PR and between 2ccfba1 and 822b7aa.

📒 Files selected for processing (3)

• api-reference/files/list.mdx
• api-reference/openapi/content.json
• docs.json

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
python - <<'PY'
import pathlib, re
for p in sorted(pathlib.Path("api-reference").rglob("*.mdx")):
    text = p.read_text()
    m = re.search(r'^\s*openapi:\s*(.+)$', text, re.MULTILINE)
    if m:
        print(f"{p}: {m.group(1).strip()}")
PY

Repository: recoupable/docs

Length of output: 12075

---

Update openapi frontmatter to match the required format

The frontmatter uses the format openapi: "/api-reference/openapi/content.json GET /api/files" but should follow the format openapi: 'METHOD /path' per the API reference standard, such as openapi: "GET /api/files". This pattern affects most api-reference pages in the repository and should be corrected systematically.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@api-reference/files/list.mdx` at line 3, The frontmatter value for openapi is
incorrectly set to a file path plus method; update the openapi frontmatter in
this file (and similar api-reference pages) to the required format "METHOD
/path" (e.g., change openapi: "/api-reference/openapi/content.json GET
/api/files" to openapi: "GET /api/files"); ensure any other api-reference pages
follow the same pattern and perform a quick grep for the malformed pattern to
fix them consistently.

[cubic-dev-ai]

1 issue found across 3 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/openapi/content.json">

<violation number="1" location="api-reference/openapi/content.json:2440">
P2: `FileListItem` is missing a `required` array, so the generated docs will mark every field — including `id`, `file_name`, and `is_directory` — as optional. Add a `required` list for the fields the API always returns.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/openapi/content.json">

<violation number="1" location="api-reference/openapi/content.json:2463">
P1: Custom agent: **Flag AI Slop and Fabricated Changes**

`owner_email` is marked `required` in the new array, but the endpoint description says it is included only "when the file owner's account has an email on record" and the property itself is `nullable: true`. If the field is truly conditional, remove it from `required` so clients and generated SDKs don't expect it on every response. If it is always present (as `null` when missing), update the description to say so.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}