// docs / public files api

The Public Files API

Query any published MyJay site's asset index directly from your application code. Zero setup, zero scraping, full CORS flexibility.

The Problem This Solves

Building custom dynamic interfaces (like portfolios, blogs, or anthologies) on top of traditional static hosts usually requires heavy build-steps or parsing HTML strings via fragile scraping tools.

The Public Files API treats your static directories as a live, queryable data layout. Pass a username, and MyJay returns a structural mapping of every file that site owns. This makes it effortless to turn your MyJay files into a headless content directory.

The Endpoint

GET https://myjay.net/api/sites/:username/files

Replace :username with the targeted site's subdomain (the segment preceding .myjay.net). Use lowercase strings only; omit sub-paths or protocols.

$ curl https://myjay.net/api/sites/noah/files { "username": "noah", "files": [ {"key": "index.html", "size": 1653, "modified": "2026-06-21T13:13:02.355Z"}, {"key": "styles.css", "size": 4448, "modified": "2026-06-21T13:13:02.641Z"}, {"key": "literature/story-one.md", "size": 6001, "modified": "2026-06-21T14:05:11.846Z"} ] }

Response Schema

Field	Type	Description
`username`	string	The requested user subdomain target.
`files`	array	An un-ordered collection of all public objects contained in the site directory.
`files[].key`	string	Relative path starting from the root directory (e.g., `literature/story-one.md`).
`files[].size`	number	Exact storage allocation in bytes.
`files[].modified`	string	ISO 8601 string documenting the file's last update timestamp.

Note on architecture: MyJay relies on a flat key-value architecture. Folders do not exist as independent systemic entries. A key featuring a forward slash is simply an individual file object explicitly tracking its directory pathway prefix. See the File Manager docs for more detail.

Integration Example (JavaScript Fetch)

Because this API is completely unauthenticated and cross-origin accessible, you can dynamically read, sort, and render contents inside client-side components:

// Fetching directory data and parsing custom source targets async function fetchMyJayContent(username) { const apiTarget = `https://myjay.net/api/sites/${username}/files`; const response = await fetch(apiTarget); if (!response.ok) throw new Error(`MyJay API error: ${response.status}`); const data = await response.json(); // Filter for specific markdown content categories const stories = data.files.filter(file => file.key.startsWith('literature/')); for (const story of stories) { const assetUrl = `https://${username}.myjay.net/${story.key}`; console.log(`Content URL for ${story.key}: ${assetUrl}`); } }

Route Matching & Accessibility

The endpoint strictly mimics the identical availability checks running on the production gateway at username.myjay.net. Review how routing works for comprehensive details:

Deployment State	HTTP Status	Payload String / Action
Subdomain is unregistered or expired	`404 Not Found`	`"No site is registered at this subdomain"`
Registered account, currently in draft state	`403 Forbidden`	`"This site exists but has not been published"`
Registered and explicitly live	`200 OK`	Returns structural JSON file array listing.

This mechanism presents no security surface exposure risks: it treats visibility exactly like standard web requests. Unauthenticated external requests will never read index mappings belonging to un-published or draft accounts.

Authentication & CORS Scope

While account actions or site writing requires specific cookies or explicit authorization headers, this route functions with no barriers:

No Keys Required: No bearer tokens, access parameters, or active user sessions are demanded.
Wildcard CORS (Access-Control-Allow-Origin: *): Explicitly unrestricted permissions allow direct queries from cross-origin contexts, including frontend browser engines, automation servers, workflows, or remote local hosts.

Limitations & Exclusions

No Inline Payload Data: This is an inventory summary mapping, not a content bundle tool. To ingest file bodies, perform distinct requests directly to the file distribution network targets (e.g., https://noah.myjay.net/literature/story-one.md).
Empty Virtual Pathways: Directory names containing zero active tracking files are not included in results since empty folders are structurally dropped by the system engine.