neocities-c/README.md

Neocities C API

Minimal, secure C wrapper for the Neocities API using API key authentication.

No login flow. No credential storage. Stateless by design.

Users must generate their own API key via the Neocities dashboard.

---

Features

• Site info retrieval
• File listing
• Upload files
• Delete files
• TLS verification enabled by default

Authentication is performed exclusively via:

Authorization: Bearer <API_KEY>

---

Requirements

• libcurl

Linux (example):

sudo apt install libcurl4-openssl-dev

---

Authentication

Generate your API key at:

Neocities > Settings > Manage Site Settings > API (or https://neocities.org/settings/YOUR-USERNAME#api_key)

If you're coding a CLI or application, you must provide the key at runtime (env var, config file, etc).

---

API Overview

Just an overview. For more detailed information, see: Function-Guide.md

Info (public)

int neocities_info(const char *sitename, neocities_info_t *out);

Fetch metadata about a site.

---

List files

int neocities_list(const char *api_key,
                   const char *path,
                   neocities_filelist_t *out);

List files at a path.

---

Upload

int neocities_upload(const char *api_key,
                     const char **local_files,
                     const char **remote_names,
                     size_t count,
                     char **response);

Uploads multiple files.

• local_files[i] → local path
• remote_names[i] → remote filename

---

Delete

int neocities_delete(const char *api_key,
                     const char **filenames,
                     size_t count,
                     char **response);

Deletes files from the site.

---

API Key

For security reasons, you should get the API key via Neocities settings. This function is not avaiable.

---

Memory Management

Always free parsed outputs:

void neocities_free_info(neocities_info_t *info);
void neocities_free_filelist(neocities_filelist_t *list);

response returned by upload/delete must also be freed by caller.

---

Example Usage

List files

neocities_filelist_t list;

if (neocities_list(api_key, "/", &list) == 0) {
    for (size_t i = 0; i < list.count; i++)
        printf("%s\n", list.paths[i]);

    neocities_free_filelist(&list);
}

---

Upload

const char *local[]  = {"index.html"};
const char *remote[] = {"index.html"};
char *resp;

neocities_upload(api_key, local, remote, 1, &resp);
free(resp);

---

Security Notes

• TLS verification is enforced
• Redirects are disabled intentionally
• API key is never persisted internally

Recommended:

• Store key in env vars
• Avoid hardcoding

---

Design Philosophy

• No login/password support
• API key only
• Explicit memory ownership
• Minimal abstraction

---

Future Extensions (Optional)

Possible areas to explore:

• Structured responses for upload/delete
• JSON passthrough mode
• Streaming uploads
• Error codes standardization

---

License

MIT