Neocities.org

Neocities Developers API

Make changes to your site remotely with programming languages!

Ideas

Rules

Command Line Usage

If you're just looking for a command line interface to the API, go here.

Libraries

There are client libraries available for popular programming languages to make it easier to work with the API for certain languages.
Note that these most of these are from third parties so we can't provide support for them.

API Documentation

The Neocities API is a REST API, which uses query parameters for input, and returns data in the JSON format (except for file downloads). It uses client-side HTTP AUTH to authenticate, using your user/site name and password as the credentials. It is designed to play nicely with the most common HTTP libraries available in programming languages, and can be easily used with cURL (a command-line tool for making HTTP requests you can use by opening a terminal on your computer).

That's a lot of buzz words if you're new to programming. Don't worry, it's easier than it sounds! We'll walk you through some working examples you can get started with.

POST /api/upload

Uploads files to your site. You can upload as many files as you want with a single query, as long as the entire request stays within the disk space limit. The parameter name should be the name of the file, with the extension so we know what kind of file it is (index.html).

Examples

Using cURL

Upload a single local file (local.html), which will be named hello.html on your site:

$ curl -F "hello.html=@local.html" "https://USER:PASS@neocities.org/api/upload"
Using Node.js

This example uses the neocities module. You can install it by running npm install neocities --global in your terminal.

var neocities = require('neocities')
var api = new neocities('YOURUSERNAME', 'YOURPASSWORD')

api.upload([
  {name: 'hello.html', path: './local.html'}
], function(resp) {
  console.log(resp)
})

POST /api/delete

Deletes files from your site. Provide a filenames argument with an array of filenames you wish to delete. You can delete any files except index.html.

Be careful with this API call. There is no way to undo a delete!

Examples

Using cURL

Delete img1.jpg and img2.jpg from your site: 

curl -d "filenames[]=img1.jpg" -d "filenames[]=img2.jpg" \
"https://YOURUSER:YOURPASS@neocities.org/api/delete"
Using Node.js
var neocities = require('neocities')
var api = new neocities('YOURUSERNAME', 'YOURPASSWORD')

api.delete(['img1.jpg', 'img2.jpg'], function(resp) {
  console.log(resp)
})

GET /api/list

This call provides a list of files for your site. If you pass no arguments, it will return a list of all files. If you provide a path argument, it will return a list of files for the path. Dates conform to RFC2822.

Examples

Using cURL
$ curl "https://USER:PASS@neocities.org/api/list"
{
  "result": "success",
  "files": [
    {
      "path": "index.html",
      "is_directory": false,
      "size": 1023,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "c8aac06f343c962a24a7eb111aad739ff48b7fb1"
    },
    {
      "path": "not_found.html",
      "is_directory": false,
      "size": 271,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "cfdf0bda2557c322be78302da23c32fec72ffc0b"
    },
    {
      "path": "images",
      "is_directory": true,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000"
    },
    {
      "path": "images/cat.png",
      "is_directory": false,
      "size": 16793,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "41fe08fc0dd44e79f799d03ece903e62be25dc7d"
    }
  ]
}

$ curl "https://USER:PASS@neocities.org/api/list?path=images"
{
  "result": "success",
  "files": [
    {
      "path": "images/cat.png",
      "is_directory": false,
      "size": 16793,
      "updated_at": "Sat, 13 Feb 2016 03:04:00 -0000",
      "sha1_hash": "41fe08fc0dd44e79f799d03ece903e62be25dc7d"
    }
  ]
}

GET /api/info

This call lets you retreive information about a web site. This call does not require site authorization if you provide a sitename argument. Note that the sitename is the same as a username. If you provide auth credentials, you will receive the info for the auth user's site. Dates conform to RFC2822 format, and there are helpers for parsing it into a time object for most programming languages.

Examples

Using cURL
$ curl "https://neocities.org/api/info?sitename=youpi"
{
  "result": "success",
  "info": {
    "sitename": "youpi",
    "hits": 5072,
    "created_at": "Sat, 29 Jun 2013 10:11:38 +0000",
    "last_updated": "Tue, 23 Jul 2013 20:04:03 +0000",
    "domain": null,
    "tags": []
  }
}

Getting your own site's info:

$ curl "https://YOURUSER:YOURPASS@neocities.org/api/info"
Using Node.js

Your site:

var neocities = require('neocities')
var api = new neocities('YOURUSERNAME', 'YOURPASSWORD')

api.info(function(resp) {
  console.log(resp)
})

Getting data for a different site - such as the Madam FRP Manual: 

var neocities = require('neocities')
var api = new neocities('YOURUSERNAME', 'YOURPASSWORD')

api.info('madamfrp', function(resp) {
  console.log(resp)
})

GET /api/key

Returns an API key that you can use for the API instead of login credentials. It will automatically generate a new API key if one doesn't exist yet for your site.

Examples

Using cURL
$ curl "https://USER:PASS@neocities.org/api/key"
{
  "result": "success",
  "api_key": "da77c3530c30593663bf7b797323e48c"
}

Using the api key for requests:

$ curl -H "Authorization: Bearer da77c3530c30593663bf7b797323e48c" \
https://neocities.org/api/info

Need something the API doesn't provide?

If the API does not supply something you need, contact us and we will try to add it!