Overview

Unlike other forum software, Storyden is built around a (fairly) HTTP standards-compliant RESTful API. This enables endless possibilities for developers to build powerful frontends, automations, integrations and more.

Using the API

To start experimenting with the API, get a local instance running:

docker run -p 8000:8000 ghcr.io/southclaws/storyden

Once you've waited roughly 1 millisecond for Storyden to boot up, you can start interacting with it via your favourite HTTP client. The OpenAPI specification is available at:

/api/openapi.json

You can also access interactive API documentation, powered by Scalar, at:

/api/docs

Because Storyden uses simple browser cookies, you can use the docs to immediately start playing with the API.

Authentication

Storyden uses secure cookies for authentication. You can register for an account (or log in) either via the browser or via the API itself in order to obtain a session token. You'll find the session cookie under a cookie named:

storyden-session

Include this with all requests to the API. For example, using curl register for a new account on a fresh local instance:

curl -c cookies.txt http://localhost:8000/api/auth/password/signup \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "identifier": "storyden",
  "token": "password"
}'

curl -c cookies.txt http://localhost:8000/api/auth/password/signup --request POST --header 'Content-Type: application/json' --data '{"identifier":"storyden","token":"password"}'

(curl -c cookies.txt http://localhost:8000/api/auth/password/signup
  --request POST
  --header 'Content-Type: application/json'
  --data '{
  "identifier": "storyden",
  "token": "password"
}')

Note: we cannot use Nushell's http command here as it doesn't support cookies.

Now use the -b cookies.txt option for cURL to include the session cookie in all requests. For example, to get a list of all members, you will see yourself in the list:

curl -b cookies.txt http://localhost:8000/api/accounts

You'll see your account information in the response:

{
  // The first signup is admin by default.
  "admin": true,
  // Your bio can be written with rich text formatting.
  "bio": "<body></body>",
  // Accounts may have multiple email addresses if email features are enabled.
  "email_addresses": [],
  // The identifier you signed up with
  "handle": "storyden",
  "id": "d01oa6i37ros73bk14rg", // Your unique ID
  "joined": "2025-04-19T11:12:26.873686708Z",
  // Your display name is the same as your handle by default, you can change this to anything you want.
  "name": "storyden",
  // Roles provide permissions, since this would be the first account created, it receives both the Member role with default permissions and the Admin role with all permissions denoted by "ADMINISTRATOR".
  "roles": [
    {
      "badge": false,
      "colour": "green",
      "createdAt": "0001-01-01T00:00:00Z",
      "default": true,
      "id": "00000000000000000010",
      "name": "Member",
      "permissions": [
        "CREATE_POST",
        "READ_PUBLISHED_THREADS",
        "CREATE_REACTION",
        "READ_PUBLISHED_LIBRARY",
        "SUBMIT_LIBRARY_NODE",
        "UPLOAD_ASSET",
        "LIST_PROFILES",
        "READ_PROFILE",
        "CREATE_COLLECTION",
        "LIST_COLLECTIONS",
        "READ_COLLECTION",
        "COLLECTION_SUBMIT"
      ],
      "updatedAt": "0001-01-01T00:00:00Z"
    },
    {
      "badge": false,
      "colour": "red",
      "createdAt": "0001-01-01T00:00:00Z",
      "default": true,
      "id": "00000000000000000020",
      "name": "Admin",
      "permissions": ["ADMINISTRATOR"],
      "updatedAt": "0001-01-01T00:00:00Z"
    }
  ]
}

Access Keys

For programmatic access, scripts, and integrations, Storyden provides access keys as an alternative to session cookies. Access keys are bearer tokens that authenticate API requests and inherit the permissions of the account that created them.

Access keys are ideal for:

Building bots and automation workflows
Integrating with third-party services (Discord, n8n, Zapier, etc.)
Server-to-server communication

To create and manage access keys, see the Access Keys documentation. You'll need the USE_PERSONAL_ACCESS_KEYS permission to create keys for your account.

Example usage:

curl http://localhost:8000/api/threads \
  --header 'Authorization: Bearer your_access_key_here'

curl http://localhost:8000/api/threads --header 'Authorization: Bearer your_access_key_here'

http get http://localhost:8000/api/threads Authorization:'Bearer your_access_key_here'

Overview

Using the API

Authentication

Access Keys

On this page