canonical: https://jentic.com/apis/neocities/neocities # Neocities API The Neocities API is the programmatic interface for Neocities, the indie web host that publishes static personal sites. The five endpoints cover uploading files, deleting files, listing the site tree, fetching site metadata, and minting an API key in exchange for username and password credentials. It is designed for static-site generators, deploy scripts, and CI pipelines that publish a folder of HTML, CSS, and assets to a Neocities site. ## For AI agents Upload, list, and delete files on a Neocities static site, fetch site info, and exchange basic auth credentials for an API key. ## Scope Does not handle DNS, build steps, or serverless functions - use for static file upload, list, and delete on a Neocities site only. ## Capabilities - Upload one or more files to a Neocities site, replacing existing files at the same path - Delete files from a Neocities site by path - List every file on the site with its path, size, and last update timestamp - Fetch site metadata including views, hits, last update, and tags - Mint an API key by calling `/api/key` with basic auth credentials, then switch to bearer auth for subsequent calls ## Use cases ### Static Site Deploy from CI Indie developers wire the Neocities API into a CI job so a git push rebuilds and uploads the static output. `/api/upload` accepts multipart files, `/api/delete` removes stale assets, and `/api/list` reports the published tree. The deploy step takes seconds for a small site and replaces hand-uploading through the web UI. Example prompt: Upload the contents of the dist/ folder to a Neocities site, then list the site to confirm every file is present. ### Site Cleanup and Audit Site owners run an audit that compares their local content against `/api/list`, deletes orphaned assets via `/api/delete`, and reports the resulting site size. This pattern keeps a Neocities site under the free-tier storage cap and removes leftover files from old builds. Example prompt: List all files on the Neocities site, delete any file under /old/ that has not been updated in 90 days, and return the count of files removed. ### Site Metrics Dashboard Hobby developers pull `/api/info` on a schedule to chart views, hits, and update activity for their Neocities site. The endpoint returns the same fields the public profile page shows, so the agent can build a small dashboard or a Slack bot that posts daily totals. Example prompt: Fetch the Neocities site info and return the views, hits, and last_updated timestamp. ### AI Agent Integration via Jentic An AI agent uses Jentic to publish HTML directly to Neocities without hand-rolling the multipart upload code. Jentic exposes `/api/upload` by intent, the agent supplies the file payload, and the request is executed with the API key kept in the vault. This makes Neocities a viable build target for an LLM-driven site generator. Example prompt: Use Jentic to search for upload to neocities, load the schema for `/api/upload`, and publish a generated index.html. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/api/upload` | Upload one or more files to a site | | POST | `/api/delete` | Delete files from a site | | GET | `/api/list` | List all files on a site | | GET | `/api/info` | Get site info and metrics | | GET | `/api/key` | Mint an API key from basic auth credentials | ## Key resources - **Upload** — Upload one or more files to the site - **Delete** — Remove files from the site by path - **List** — List all files on the site - **Info** — Get site metadata including views and last update - **Key** — Mint an API key from username and password ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 61 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 100 / 100 - Developer Experience & Jentic Compatibility: 63 / 100 - AI-Readiness & Agent Experience: 49 / 100 - Agent Usability: 94 / 100 - Security: 35 / 100 - AI Discoverability: 75 / 100 - **View full report:** https://jentic.com/apis/neocities/neocities/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the Neocities API by hand means choosing between basic auth and a bearer key, exchanging your login for an API key, and packing static files into multipart uploads against the site host yourself. Through Jentic you install once, import Neocities from the API Directory, store the API key once, and your agent calls it. - **Permission scoping:** The Neocities operations carry the file names to upload or delete inside the request body rather than as a resource id in the URL path, so you limit the agent to the operations it needs, such as upload, list, or info. You choose that operation set, so delete is not included unless you add it. - **Credential handling:** Your Neocities API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'upload files to a Neocities site' or 'list site files', and Jentic returns the matching operation with its multipart schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Netlify API** — Static site host with build pipelines and edge functions - **Vercel API** — Frontend cloud with framework-aware deploys and edge runtime - **GitHub API** — Source control system that triggers a Neocities deploy on push ## FAQ ### What authentication does the Neocities API use? Neocities supports two schemes: HTTP basic auth with username and password, and bearer token using an API key. Use GET `/api/key` with basic auth to mint a key once, then switch to bearer for all subsequent calls. Jentic stores the key encrypted in the vault and injects it at execution time. ### Can I delete files from a Neocities site through the API? Yes. POST to `/api/delete` with the file paths in the filenames[] form parameter. The endpoint removes the listed files; the rest of the site is untouched. ### How do I deploy a folder of files to Neocities through Jentic? Search Jentic for upload to neocities, load the schema for POST `/api/upload`, then execute with each file as a multipart part. The full flow is pip install jentic, search, load, execute. ### What are the rate limits for the Neocities API? Neocities does not document explicit rate limits in the spec. The free tier caps total storage and bandwidth instead, so a deploy job should batch uploads in a single `/api/upload` call where possible rather than firing one request per file. ### Is the Neocities API free? Yes - the API is free for any Neocities account, including the free tier. Supporters and paying members get higher storage and bandwidth caps but use the same endpoints. ### Can I get the view count for my site through the API? Yes. GET `/api/info` returns the site metadata including views, hits, last_updated, and tags. This is the same data that appears on the public profile page. ### Can I limit what my agent is allowed to do with the Neocities API? Yes. Because your Jentic One instance is self-hosted, you set the rules that decide which Neocities operations and credentials the agent may use. The Neocities operations pass the file names to upload or delete in the request body rather than as an id in the URL path, so you scope the agent to just the operations it needs, such as upload, list, or info. Destructive calls like delete stay out of that set unless you add them, and your API key is injected only for the operations you allow.