hanzoai/docs
2
0
Fork 0
mirror of https://github.com/hanzo-docs/docs.git synced 2026-10-26 10:55:57 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity
Files
8ea4ad783e4378f644fa69f00909dbe238a0d156
docs/examples/openapi/openapi.yaml
T

6300 lines
216 KiB
YAML
Raw Blame History

openapi: 3.1.0
#
# ╓███,
# ▄██▀"███▄
# ╚█▀ `▀██▄
# ,, ╓███, ▀██▌_
# ╓███ ▄██▀"███▄ ╙███_
# ▐██" ▄██▀ `▀██▄ ╙██
# ▐██ ╙██▄ ╫██Γ ██─
# ▐██ ▀██▄ ,▓██▀ ██─
# ▐██ ╙█████▀ ██─
# ▐██ ╓█████_ ██─
# ▐██ ▄██▀` ╙███╥ ██─
# └███████▀ `▀██ ██
#
info:
contact:
name: Barnaby Keene
description: >
Storyden social API for building community driven platforms.
The Storyden API does not adhere to semantic versioning but instead applies
a rolling strategy with deprecations and minimal breaking changes. This has
been done mainly for a simpler development process and it may be changed to
a more fixed versioning strategy in the future. Ultimately, the primary way
Storyden tracks versions is dates, there are no set release tags currently.
title: storyden
version: 'v1.25.8-canary'
servers:
- url: '/api'
description: >
The HTTP interface that this document describes is mounted on the `/api/`
path and any requests outside of the base path will not be covered by the
API specification and will be used for experimental features and plugins.
# All endpoints are by default accessible via a browser session cookie or an API
# key for either human accounts or bot accounts unless explicitly specified.
security:
- browser: []
- access_key: []
x-types:
cache_response_headers: &cache_response_headers
Cache-Control: { $ref: '#/components/headers/Cache-Control' }
Last-Modified: { $ref: '#/components/headers/Last-Modified' }
ETag: { $ref: '#/components/headers/ETag' }
tags:
- name: misc
description: General metadata for the instance and uncategorised routes.
- name: admin
description: Administration and configuration settings.
- name: roles
description: Roles for permissions and aesthetics.
- name: auth
description: Authentication resources.
- name: accounts
description: User accounts.
- name: invitations
description: Account invitations.
- name: notifications
description: Event notifications.
- name: profiles
description: Public profiles.
- name: categories
description: Thread categories.
- name: tags
description: Organisational tags for discussion posts and library nodes.
- name: posts
description: Any operations for any kind of Post resource.
- name: threads
description: Forum threads.
- name: replies
description: Posts within a specific thread.
- name: assets
description: File uploads and downloads.
- name: likes
description: Likes/votes for posts and library nodes.
- name: collections
description: User curated collections of posts and library nodes.
- name: nodes
description: Structured knowledgebase content tree.
- name: links
description: Social bookmarks.
- name: datagraph
description: Content graph (posts, nodes, links) APIs.
- name: events
description: Event scheduling, invites and management.
#
# 8888888b. d8888 88888888888 888 888 .d8888b.
# 888 Y88b d88888 888 888 888 d88P Y88b
# 888 888 d88P888 888 888 888 Y88b.
# 888 d88P d88P 888 888 8888888888 "Y888b.
# 8888888P" d88P 888 888 888 888 "Y88b.
# 888 d88P 888 888 888 888 "888
# 888 d8888888888 888 888 888 Y88b d88P
# 888 d88P 888 888 888 888 "Y8888P"
#
paths:
#
# d8b
# Y8P
#
# 88888b.d88b. 888 .d8888b .d8888b
# 888 "888 "88b 888 88K d88P"
# 888 888 888 888 "Y8888b. 888
# 888 888 888 888 X88 Y88b.
# 888 888 888 888 88888P' "Y8888P
#
/version:
get:
operationId: GetVersion
summary: Get the software version string.
description: |
The version number includes the date and time of the release build as
well as a short representation of the Git commit hash.
security: [] # TODO: Maybe remove from public access?
tags: [misc]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'200':
description: OK
content:
text/plain:
schema:
type: string
/openapi.json:
get:
operationId: GetSpec
summary: OpenAPI specification
description: |
This endpoint returns the OpenAPI specification for the Storyden API in
JSON format. This is useful for clients that want to dynamically load
the API specification for documentation or code generation.
security: [] # TODO: Remove this from default public access, add a perm.
tags: [misc]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'200':
description: OK
content:
application/vnd.oai.openapi+json;version=3.1.0:
schema:
type: object
/docs:
get:
operationId: GetDocs
summary: API documentation
description: |
This endpoint returns the OpenAPI documentation for the Storyden API in
an interactive HTML format. This is useful for developers who want to
explore the API and test endpoints without writing code.
security: [] # TODO: Remove this from default public access, add a perm.
tags: [misc]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'200':
description: OK
content:
text/html:
schema:
type: string
/info:
get:
operationId: GetInfo
description: |
Get the basic forum installation info such as title, description, etc.
This is a fully public endpoint as it drives the ability to render stuff
like OpenGraph metadata, favicon, titles, descriptions, for crawlers.
security: []
tags: [misc]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'200': { $ref: '#/components/responses/GetInfoOK' }
/info/icon/{icon_size}:
get:
operationId: IconGet
description: Get the logo icon image.
security: []
tags: [misc]
parameters: [{ $ref: '#/components/parameters/IconSize' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'200': { $ref: '#/components/responses/AssetGetOK' }
/info/icon:
post:
operationId: IconUpload
description: Upload and process the installation's logo image.
tags: [misc]
requestBody: { $ref: '#/components/requestBodies/AssetUpload' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200':
description: OK
/info/banner:
get:
operationId: BannerGet
description: Get the banner image.
security: []
tags: [misc]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'200': { $ref: '#/components/responses/AssetGetOK' }
post:
operationId: BannerUpload
description: Upload and process the installation's banner image.
tags: [misc]
requestBody: { $ref: '#/components/requestBodies/AssetUpload' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200':
description: OK
/beacon:
post:
operationId: SendBeacon
description: |
A catch-all endpoint for tracking read states and other things that are
not critical to the functioning of the platform. This endpoint is fire
and forget and does not return any meaningful data. It is designed to
be used with the `navigator.sendBeacon` API in browsers to mark things
such as how far down a thread a member has read, or whether or not a
Library Page has been visited recently. It may queue the work for later
processing and is not guaranteed to be processed immediately or at all.
security: []
tags: [misc]
requestBody: { $ref: '#/components/requestBodies/Beacon' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'202':
description: Accepted
#
# 888 d8b
# 888 Y8P
# 888
# 8888b. .d88888 88888b.d88b. 888 88888b.
# "88b d88" 888 888 "888 "88b 888 888 "88b
# .d888888 888 888 888 888 888 888 888 888
# 888 888 Y88b 888 888 888 888 888 888 888
# "Y888888 "Y88888 888 888 888 888 888 888
#
/admin:
patch:
operationId: AdminSettingsUpdate
description: Update non-env configuration settings for installation.
tags: [admin]
requestBody: { $ref: '#/components/requestBodies/AdminSettingsUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AdminSettingsUpdateOK' }
/admin/bans/{account_handle}:
post:
operationId: AdminAccountBanCreate
description: |
Suspend an account - soft delete. This disables the ability for the
account owner to log in and use the platform. It keeps the account on
record for linkage to content so UI doesn't break. It does not change
anything else about the account such as the avatar, name, etc.
tags: [admin]
parameters: [$ref: '#/components/parameters/AccountHandleParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AccountGetOK' }
delete:
operationId: AdminAccountBanRemove
description: Given the account is suspended, remove the suspended state.
tags: [admin]
parameters: [$ref: '#/components/parameters/AccountHandleParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AccountGetOK' }
/admin/access-keys:
get:
operationId: AdminAccessKeyList
description: |
List all access keys for the entire instance. This is only available to
admin accounts and is used to manage access keys from other accounts.
tags: [admin]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'403': { $ref: '#/components/responses/Forbidden' }
'200': { $ref: '#/components/responses/AdminAccessKeyListOK' }
/admin/access-keys/{access_key_id}:
delete:
operationId: AdminAccessKeyDelete
description: |
Revoke an access key. This will immediately invalidate the key and it
will no longer be usable for authentication.
tags: [admin]
parameters: [{ $ref: '#/components/parameters/AccessKeyIDParam' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'403': { $ref: '#/components/responses/Forbidden' }
'204': { $ref: '#/components/responses/NoContent' }
#
# 888
# 888
# 888
# 888d888 .d88b. 888 .d88b. .d8888b
# 888P" d88""88b 888 d8P Y8b 88K
# 888 888 888 888 88888888 "Y8888b.
# 888 Y88..88P 888 Y8b. X88
# 888 "Y88P" 888 "Y8888 88888P'
#
/roles:
post:
operationId: RoleCreate
description: Creates a role with the specified permissions granted.
tags: [roles]
requestBody: { $ref: '#/components/requestBodies/RoleCreate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/RoleCreateOK' }
get:
operationId: RoleList
description: List all roles and their permissions.
tags: [roles]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'200': { $ref: '#/components/responses/RoleListOK' }
/roles/{role_id}:
get:
operationId: RoleGet
description: Retreives a role and all its permissions.
tags: [roles]
parameters: [{ $ref: '#/components/parameters/RoleIDParam' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/RoleGetOK' }
patch:
operationId: RoleUpdate
description: Updates a role's attributes.
tags: [roles]
parameters: [{ $ref: '#/components/parameters/RoleIDParam' }]
requestBody: { $ref: '#/components/requestBodies/RoleUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/RoleGetOK' }
delete:
operationId: RoleDelete
description: Deletes a role.
tags: [roles]
parameters: [{ $ref: '#/components/parameters/RoleIDParam' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
#
# 888 888
# 888 888
# 888 888
# 8888b. 888 888 888888 88888b.
# "88b 888 888 888 888 "88b
# .d888888 888 888 888 888 888
# 888 888 Y88b 888 Y88b. 888 888
# "Y888888 "Y88888 "Y888 888 888
#
/auth:
get:
operationId: AuthProviderList
description: |
Retrieve a list of authentication providers. Storyden supports a few
ways to authenticate, from simple passwords to OAuth and WebAuthn. This
endpoint tells a client which auth capabilities are enabled.
tags: [auth]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/AuthProviderListOK' }
/auth/password/signup:
post:
operationId: AuthPasswordSignup
description: Register a new account with a username and password.
tags: [auth]
parameters: [$ref: '#/components/parameters/InvitationIDQueryParam']
requestBody: { $ref: '#/components/requestBodies/AuthPassword' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/password/signin:
post:
operationId: AuthPasswordSignin
description: Sign in to an existing account with a username and password.
tags: [auth]
requestBody: { $ref: '#/components/requestBodies/AuthPassword' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/password:
post:
operationId: AuthPasswordCreate
description: |
Given the requesting account does not have a password authentication,
add a password authentication method to it with the given password.
tags: [auth]
security: [browser: []]
requestBody: { $ref: '#/components/requestBodies/AuthPasswordCreate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
patch:
operationId: AuthPasswordUpdate
description: |
Given the requesting account has a password authentication, update the
password on file.
tags: [auth]
security: [browser: []]
requestBody: { $ref: '#/components/requestBodies/AuthPasswordUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/password/reset:
post:
operationId: AuthPasswordReset
description: |
Complete a password-reset flow using a token that was provided to the
member via a reset request operation such as `AuthEmailPasswordReset`.
tags: [auth]
requestBody: { $ref: '#/components/requestBodies/AuthPasswordReset' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/email-password/signup:
post:
operationId: AuthEmailPasswordSignup
description: Register a new account with a email and password.
tags: [auth]
parameters: [$ref: '#/components/parameters/InvitationIDQueryParam']
requestBody: { $ref: '#/components/requestBodies/AuthEmailPassword' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/email-password/signin:
post:
operationId: AuthEmailPasswordSignin
description: Sign in to an existing account with a email and password.
tags: [auth]
requestBody: { $ref: '#/components/requestBodies/AuthEmailPassword' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/email-password/reset:
post:
operationId: AuthPasswordResetRequestEmail
description: |
Request password reset email to be sent to the specified email address.
tags: [auth]
requestBody: { $ref: '#/components/requestBodies/AuthEmailPasswordReset' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
/auth/email/signup:
post:
operationId: AuthEmailSignup
description: |
Register a new account with an email and optional password. The password
requirement is dependent on how the instance is configured for account
authentication with email addresses (password vs magic link.)
When the email address has not been registered, this endpoint will send
a verification email however it will also return a session cookie to
facilitate pre-verification usage of the platform. If the email address
already exists, no session cookie will be returned in order to prevent
arbitrary account control by a malicious actor. In this case, the email
will be sent again with the same OTP for the case where the user has
cleared their cookies or switched device but hasn't yet verified due to
missing the email or a delivery failure. In this sense, the endpoint can
act as a "resend verification email" operation as well as registration.
In the first case, a 200 response is provided with the session cookie,
in the second case, a 422 response is provided without a session cookie.
Given that this is an unauthenticated endpoint that triggers an email to
be sent to any public address, it MUST be heavily rate limited.
tags: [auth]
parameters: [$ref: '#/components/parameters/InvitationIDQueryParam']
requestBody: { $ref: '#/components/requestBodies/AuthEmail' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'422':
description: Verification email sent but no session will be provided.
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/email/signin:
post:
operationId: AuthEmailSignin
description: |
Sign in to an existing account with an email and optional password. The
behaviour of this endpoint depends on how the instance is configured. If
email+password is the preferred method, a cookie is returned on success
but if magic links are preferred, the endpoint will start the code flow.
tags: [auth]
requestBody: { $ref: '#/components/requestBodies/AuthEmail' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/email/verify:
post:
operationId: AuthEmailVerify
description: |
Verify an email address using a token that was emailed to one of the
account's email addresses either set via sign up or added later.
tags: [auth]
requestBody: { $ref: '#/components/requestBodies/AuthEmailVerify' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/oauth/{oauth_provider}/callback:
post:
operationId: OAuthProviderCallback
description: OAuth2 callback.
tags: [auth]
parameters: [$ref: '#/components/parameters/OAuthProvider']
requestBody: { $ref: '#/components/requestBodies/OAuthProviderCallback' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'401': { $ref: '#/components/responses/Unauthorised' }
'404': { $ref: '#/components/responses/NotFound' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/webauthn/make/{account_handle}:
get:
operationId: WebAuthnRequestCredential
description: |
Start the WebAuthn registration process by requesting a credential.
tags: [auth]
parameters: [$ref: '#/components/parameters/AccountHandleParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/WebAuthnRequestCredentialOK' }
/auth/webauthn/make:
post:
operationId: WebAuthnMakeCredential
description: Complete WebAuthn registration by creating a new credential.
tags: [auth]
security: [webauthn: []]
parameters: [$ref: '#/components/parameters/InvitationIDQueryParam']
requestBody: { $ref: '#/components/requestBodies/WebAuthnMakeCredential' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/webauthn/assert/{account_handle}:
get:
operationId: WebAuthnGetAssertion
description: Start the WebAuthn assertion for an existing account.
tags: [auth]
parameters: [$ref: '#/components/parameters/AccountHandleParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200':
$ref: '#/components/responses/WebAuthnGetAssertionOK'
/auth/webauthn/assert:
post:
operationId: WebAuthnMakeAssertion
description: Complete the credential assertion and sign in to an account.
tags: [auth]
security: [webauthn: []]
requestBody: { $ref: '#/components/requestBodies/WebAuthnMakeAssertion' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/phone:
post:
operationId: PhoneRequestCode
description: |
Start the authentication flow with a phone number. The handler will send
a one-time code to the provided phone number which must then be sent to
the other phone endpoint to verify the number and validate the account.
tags: [auth]
parameters: [$ref: '#/components/parameters/InvitationIDQueryParam']
requestBody: { $ref: '#/components/requestBodies/PhoneRequestCode' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/phone/{account_handle}:
put:
operationId: PhoneSubmitCode
description: |
Complete the phone number authentication flow by submitting the one-time
code that was sent to the user's phone.
tags: [auth]
parameters: [$ref: '#/components/parameters/AccountHandleParam']
requestBody: { $ref: '#/components/requestBodies/PhoneSubmitCode' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/AuthSuccessOK' }
/auth/access-keys:
get:
operationId: AccessKeyList
description: |
List all access keys for the authenticated account or all access keys
that have been issued for the entire instance if and only if the request
parameters specify all keys and the requesting account is an admin.
tags: [auth]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'403': { $ref: '#/components/responses/Forbidden' }
'200': { $ref: '#/components/responses/AccessKeyListOK' }
post:
operationId: AccessKeyCreate
description: |
Create a new access key for the authenticated account. Access keys are
used to authenticate API requests on behalf of the account in a more
granular and service-friendly way than a session cookie.
Access keys share the same roles and permissions as the owning account
and only provide a way to use an `Authorization` header as an way of
interacting with the Storyden API.
Access keys also allow an expiry date to be set to limit how long a key
can be used to authenticate against the API.
tags: [auth]
security: [browser: []]
requestBody: { $ref: '#/components/requestBodies/AccessKeyCreate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'403': { $ref: '#/components/responses/Forbidden' }
'200': { $ref: '#/components/responses/AccessKeyCreateOK' }
/auth/access-keys/{access_key_id}:
delete:
operationId: AccessKeyDelete
description: |
Revoke an access key. This will immediately invalidate the key and it
will no longer be usable for authentication.
tags: [auth]
parameters: [{ $ref: '#/components/parameters/AccessKeyIDParam' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'403': { $ref: '#/components/responses/Forbidden' }
'204': { $ref: '#/components/responses/NoContent' }
/auth/logout:
get:
operationId: AuthProviderLogout
description: |
Performs a HTTP logout by clearing the session cookie and redirecting to
to the requested path at the frontend's `WEB_ADDRESS`. Typically this
may be a secondary logout route on the frontend implementation that can
handle any frontend-specific logout tasks. This is necessary in cases
where the frontend is running on a different origin to the API service
such as api.site.com vs site.com because Clear-Site-Data and other
headers are same-origin compliant and won't work cross-origin.
tags: [auth]
security: [browser: []]
parameters:
- name: redirect
in: query
description: |
Path relative to the `WEB_ADDRESS` to redirect to. Note that this is
a path only and not a full URL to prevent cross-origin or cross-site
redirects. If not provided, redirects to `WEB_ADDRESS` index page.
required: false
schema:
type: string
responses:
'302':
description: Redirect to specified URL or home page
headers:
Set-Cookie: { schema: { type: string } }
Clear-Site-Data: { schema: { type: string } }
Cache-Control: { schema: { type: string } }
Location: { schema: { type: string } }
#
# 888
# 888
# 888
# 8888b. .d8888b .d8888b .d88b. 888 888 88888b. 888888 .d8888b
# "88b d88P" d88P" d88""88b 888 888 888 "88b 888 88K
# .d888888 888 888 888 888 888 888 888 888 888 "Y8888b.
# 888 888 Y88b. Y88b. Y88..88P Y88b 888 888 888 Y88b. X88
# "Y888888 "Y8888P "Y8888P "Y88P" "Y88888 888 888 "Y888 88888P'
#
/accounts:
get:
operationId: AccountGet
description: Get the information for the currently authenticated account.
tags: [accounts]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AccountGetOK' }
'304': { $ref: '#/components/responses/NotModified' }
patch:
operationId: AccountUpdate
description: Update the information for the currently authenticated account.
tags: [accounts]
requestBody: { $ref: '#/components/requestBodies/AccountUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AccountUpdateOK' }
/accounts/{account_id}:
get:
operationId: AccountView
description: |
Get detailed account information by ID. Requires either the permissions
VIEW_ACCOUNTS or ADMINISTRATOR. Users with VIEW_ACCOUNTS can view any
account that is not ADMINISTRATOR including those with VIEW_ACCOUNTS.
Only members with ADMINISTRATOR can view other ADMINISTRATOR accounts.
tags: [accounts]
parameters: [{ $ref: '#/components/parameters/AccountIDParam' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'403': { $ref: '#/components/responses/Forbidden' }
'200': { $ref: '#/components/responses/AccountGetOK' }
/accounts/self/auth-methods:
get:
operationId: AccountAuthProviderList
description: |
Retrieve a list of authentication providers with a flag indicating which
ones are active for the currently authenticated account.
tags: [accounts]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/AccountAuthProviderListOK' }
/accounts/self/auth-methods/{auth_method_id}:
delete:
operationId: AccountAuthMethodDelete
description: |
Deletes the specified authentication method from the account. This is
irreversible however if this authentication method is the only remaining
method for the account, this operation will fail with a 400 bad request.
tags: [accounts]
parameters:
- name: auth_method_id
required: true
in: path
schema:
type: string
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/AccountAuthProviderListOK' }
/accounts/self/emails:
post:
operationId: AccountEmailAdd
description: Add an email address to the authenticated account.
tags: [accounts]
requestBody: { $ref: '#/components/requestBodies/AccountEmailAdd' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AccountEmailUpdateOK' }
/accounts/self/emails/{email_address_id}:
delete:
operationId: AccountEmailRemove
description: Remove an email address from the authenticated account.
tags: [accounts]
parameters: [{ $ref: '#/components/parameters/EmailAddressIDParam' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
/accounts/self/avatar:
post:
operationId: AccountSetAvatar
description: Upload an avatar for the authenticated account.
tags: [accounts]
requestBody: { $ref: '#/components/requestBodies/AccountSetAvatar' }
parameters: [$ref: '#/components/parameters/ContentLength']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: 'OK' }
/accounts/{account_handle}/avatar:
get:
operationId: AccountGetAvatar
description: Get an avatar for the specified account.
tags: [accounts]
parameters: [$ref: '#/components/parameters/AccountHandleParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AccountGetAvatar' }
/accounts/{account_handle}/roles/{role_id}:
put:
operationId: AccountAddRole
description: |
Adds a role to an account. Members without the MANAGE_ROLES permission
cannot use this operation.
tags: [accounts]
parameters:
- $ref: '#/components/parameters/RoleIDParam'
- $ref: '#/components/parameters/AccountHandleParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AccountUpdateOK' }
delete:
operationId: AccountRemoveRole
description: |
Removes a role from an account. Members without the MANAGE_ROLES cannot
use this operation. Admins cannot remove the admin role from themselves.
tags: [accounts]
parameters:
- $ref: '#/components/parameters/RoleIDParam'
- $ref: '#/components/parameters/AccountHandleParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AccountUpdateOK' }
/accounts/{account_handle}/roles/{role_id}/badge:
put:
operationId: AccountRoleSetBadge
description: |
Desgiantes the specified role as a badge for the profile. Only one role
may be set as a badge for the profile. Setting a role as a badge is
entirely aesthetic and does not grant any additional permissions. Roles
may be created without any permissions in order to be used as badges.
tags: [accounts]
parameters:
- $ref: '#/components/parameters/RoleIDParam'
- $ref: '#/components/parameters/AccountHandleParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AccountUpdateOK' }
delete:
operationId: AccountRoleRemoveBadge
description: |
Removes the badge from the profile. This does not remove the role from
the account, only the visual badge-status representation of the role.
tags: [accounts]
parameters:
- $ref: '#/components/parameters/RoleIDParam'
- $ref: '#/components/parameters/AccountHandleParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AccountUpdateOK' }
#
# d8b d8b 888 888 d8b
# Y8P Y8P 888 888 Y8P
# 888 888
# 888 88888b. 888 888 888 888888 8888b. 888888 888 .d88b. 88888b. .d8888b
# 888 888 "88b 888 888 888 888 "88b 888 888 d88""88b 888 "88b 88K
# 888 888 888 Y88 88P 888 888 .d888888 888 888 888 888 888 888 "Y8888b.
# 888 888 888 Y8bd8P 888 Y88b. 888 888 Y88b. 888 Y88..88P 888 888 X88
# 888 888 888 Y88P 888 "Y888 "Y888888 "Y888 888 "Y88P" 888 888 88888P'
#
/invitations:
get:
operationId: InvitationList
description: |
Retrieve all invitations for the authenticated account. This endpoint
is useful for showing the user which invitations they have sent out and
which ones have been accepted.
If the requesting account is not an admin, the account_id query param
must be equal to the ID of the requesting session account's ID.
If the requesting account is an admin, the account_id query param may
be used to retrieve invitations for a specific account. Otherwise, the
endpoint will return all invitations for all accounts.
tags: [invitations]
parameters:
- { $ref: '#/components/parameters/AccountIDQueryParam' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/InvitationListOK' }
post:
operationId: InvitationCreate
description: |
Create an invitation for the authenticated account. Responds with the
invitation data which can be used to construct a public vendor-specific
registration URL using the invitation's identifier which can be used in
calls to registration operations to indicate the account was invited.
tags: [invitations]
requestBody: { $ref: '#/components/requestBodies/InvitationCreate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/InvitationCreateOK' }
/invitations/{invitation_id}:
get:
operationId: InvitationGet
description: |
Retrieve the details of an invitation by its identifier. This endpoint
is publicly accessible and can be used to show invitation details before
the client's registration flow.
tags: [invitations]
parameters: [{ $ref: '#/components/parameters/InvitationIDParam' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/InvitationGetOK' }
delete:
operationId: InvitationDelete
description: Delete an invitation. After deletion, it cannot be used.
tags: [invitations]
parameters: [{ $ref: '#/components/parameters/InvitationIDParam' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: 'OK' }
#
# 888 d8b .d888 d8b 888 d8b
# 888 Y8P d88P" Y8P 888 Y8P
# 888 888 888
# 88888b. .d88b. 888888 888 888888 888 .d8888b 8888b. 888888 888 .d88b. 88888b. .d8888b
# 888 "88b d88""88b 888 888 888 888 d88P" "88b 888 888 d88""88b 888 "88b 88K
# 888 888 888 888 888 888 888 888 888 .d888888 888 888 888 888 888 888 "Y8888b.
# 888 888 Y88..88P Y88b. 888 888 888 Y88b. 888 888 Y88b. 888 Y88..88P 888 888 X88
# 888 888 "Y88P" "Y888 888 888 888 "Y8888P "Y888888 "Y888 888 "Y88P" 888 888 88888P'
#
/notifications:
get:
operationId: NotificationList
description: Retreive all notifications.
tags: [notifications]
parameters:
- $ref: '#/components/parameters/PaginationQuery'
- $ref: '#/components/parameters/NotificationStatusQuery'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NotificationListOK' }
/notifications/{notification_id}:
patch:
operationId: NotificationUpdate
description: Change the read status for a notification.
tags: [notifications]
parameters: [$ref: '#/components/parameters/NotificationIDParam']
requestBody: { $ref: '#/components/requestBodies/NotificationUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NotificationUpdateOK' }
#
# .d888 d8b 888
# d88P" Y8P 888
# 888 888
# 88888b. 888d888 .d88b. 888888 888 888 .d88b. .d8888b
# 888 "88b 888P" d88""88b 888 888 888 d8P Y8b 88K
# 888 888 888 888 888 888 888 888 88888888 "Y8888b.
# 888 d88P 888 Y88..88P 888 888 888 Y8b. X88
# 88888P" 888 "Y88P" 888 888 888 "Y8888 88888P'
# 888
# 888
# 888
#
/profiles:
get:
operationId: ProfileList
description: Query and search profiles.
tags: [profiles]
parameters:
- $ref: '#/components/parameters/SearchQuery'
- $ref: '#/components/parameters/PaginationQuery'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/ProfileListOK' }
/profiles/{account_handle}:
get:
operationId: ProfileGet
description: Get a public profile by ID.
tags: [profiles]
parameters: [$ref: '#/components/parameters/AccountHandleParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/ProfileGetOK' }
'304': { $ref: '#/components/responses/NotModified' }
/profiles/{account_handle}/followers:
get:
operationId: ProfileFollowersGet
description: Get the followers and following details for a profile.
tags: [profiles]
parameters:
- $ref: '#/components/parameters/PaginationQuery'
- $ref: '#/components/parameters/AccountHandleParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/ProfileFollowersGetOK' }
put:
operationId: ProfileFollowersAdd
description: Follow the specified profile as the authenticated account.
tags: [profiles]
parameters: [$ref: '#/components/parameters/AccountHandleParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
delete:
operationId: ProfileFollowersRemove
description: Unfollow the specified profile as the authenticated account.
tags: [profiles]
parameters: [$ref: '#/components/parameters/AccountHandleParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
/profiles/{account_handle}/following:
get:
operationId: ProfileFollowingGet
description: Get the profiles that this account is following.
tags: [profiles]
parameters:
- $ref: '#/components/parameters/PaginationQuery'
- $ref: '#/components/parameters/AccountHandleParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/ProfileFollowingGetOK' }
'304': { $ref: '#/components/responses/NotModified' }
#
# 888 d8b
# 888 Y8P
# 888
# .d8888b 8888b. 888888 .d88b. .d88b. .d88b. 888d888 888 .d88b. .d8888b
# d88P" "88b 888 d8P Y8b d88P"88b d88""88b 888P" 888 d8P Y8b 88K
# 888 .d888888 888 88888888 888 888 888 888 888 888 88888888 "Y8888b.
# Y88b. 888 888 Y88b. Y8b. Y88b 888 Y88..88P 888 888 Y8b. X88
# "Y8888P "Y888888 "Y888 "Y8888 "Y88888 "Y88P" 888 888 "Y8888 88888P'
# 888
# Y8b d88P
# "Y88P"
#
/categories:
post:
operationId: CategoryCreate
description: Create a category for organising posts.
tags: [categories]
requestBody: { $ref: '#/components/requestBodies/CategoryCreate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/CategoryCreateOK' }
get:
operationId: CategoryList
description: Get a list of all categories on the site.
tags: [categories]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'200': { $ref: '#/components/responses/CategoryListOK' }
/categories/{category_slug}:
get:
operationId: CategoryGet
description: Get information about a category.
tags: [categories]
parameters: [{ $ref: '#/components/parameters/CategorySlugParam' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'200': { $ref: '#/components/responses/CategoryGetOK' }
patch:
operationId: CategoryUpdate
description: Update a category's information.
tags: [categories]
parameters: [$ref: '#/components/parameters/CategorySlugParam']
requestBody: { $ref: '#/components/requestBodies/CategoryUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/CategoryUpdateOK' }
delete:
operationId: CategoryDelete
description: Delete a category. All posts in this category will be moved to the specified target category.
tags: [categories]
parameters: [$ref: '#/components/parameters/CategorySlugParam']
requestBody: { $ref: '#/components/requestBodies/CategoryDelete' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorised' }
'404': { $ref: '#/components/responses/NotFound' }
'200': { $ref: '#/components/responses/CategoryDeleteOK' }
/categories/{category_slug}/position:
patch:
operationId: CategoryUpdatePosition
description: |
Update the category's position in the tree. You may change the parent
using `parent`, and/or reposition the category among its siblings using
either `before` or `after`. Use this operation for drag-and-drop
interfaces.
tags: [categories]
parameters: [$ref: '#/components/parameters/CategorySlugParam']
requestBody: { $ref: '#/components/requestBodies/CategoryUpdatePosition' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorised' }
'404': { $ref: '#/components/responses/NotFound' }
'200': { $ref: '#/components/responses/CategoryListOK' }
#
# 888
# 888
# 888
# 888888 8888b. .d88b. .d8888b
# 888 "88b d88P"88b 88K
# 888 .d888888 888 888 "Y8888b.
# Y88b. 888 888 Y88b 888 X88
# "Y888 "Y888888 "Y88888 88888P'
# 888
# Y8b d88P
# "Y88P"
#
/tags:
get:
operationId: TagList
description: Get a list of all tags on the site.
tags: [tags]
parameters: [$ref: '#/components/parameters/SearchQuery']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'200': { $ref: '#/components/responses/TagListOK' }
/tags/{tag_name}:
get:
operationId: TagGet
description: Get information about a tag.
tags: [tags]
parameters: [{ $ref: '#/components/parameters/TagNameParam' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'200': { $ref: '#/components/responses/TagGetOK' }
#
# 888 888 888
# 888 888 888
# 888 888 888
# 888888 88888b. 888d888 .d88b. 8888b. .d88888 .d8888b
# 888 888 "88b 888P" d8P Y8b "88b d88" 888 88K
# 888 888 888 888 88888888 .d888888 888 888 "Y8888b.
# Y88b. 888 888 888 Y8b. 888 888 Y88b 888 X88
# "Y888 888 888 888 "Y8888 "Y888888 "Y88888 88888P'
#
/threads:
post:
operationId: ThreadCreate
description: Create a new thread within the specified category.
tags: [threads]
requestBody: { $ref: '#/components/requestBodies/ThreadCreate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/ThreadCreateOK' }
get:
operationId: ThreadList
description: Get a list of all threads.
tags: [threads]
parameters:
- $ref: '#/components/parameters/SearchQuery'
- $ref: '#/components/parameters/PaginationQuery'
- name: author
description: Show only results creeated by this user.
required: false
in: query
schema: { $ref: '#/components/schemas/AccountHandle' }
- $ref: '#/components/parameters/VisibilityParam'
- name: tags
description: Show only results with these tags
required: false
in: query
schema: { $ref: '#/components/schemas/TagListIDs' }
- $ref: '#/components/parameters/CategorySlugListQuery'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/ThreadListOK' }
/threads/{thread_mark}:
get:
operationId: ThreadGet
summary: Get information about a thread and the posts within the thread.
description: |
Get information about a thread such as its title, author, when it was
created as well as a list of the posts within the thread.
tags: [threads]
parameters:
- $ref: '#/components/parameters/ThreadMarkParam'
- $ref: '#/components/parameters/PaginationQuery'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/ThreadGet' }
'304': { $ref: '#/components/responses/NotModified' }
patch:
operationId: ThreadUpdate
description: Publish changes to a thread.
tags: [threads]
parameters: [$ref: '#/components/parameters/ThreadMarkParam']
requestBody: { $ref: '#/components/requestBodies/ThreadUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/ThreadUpdateOK' }
delete:
operationId: ThreadDelete
description: Archive a thread using soft-delete.
tags: [threads]
parameters: [$ref: '#/components/parameters/ThreadMarkParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
#
# 888 d8b
# 888 Y8P
# 888
# 888d888 .d88b. 88888b. 888 888 .d88b. .d8888b
# 888P" d8P Y8b 888 "88b 888 888 d8P Y8b 88K
# 888 88888888 888 888 888 888 88888888 "Y8888b.
# 888 Y8b. 888 d88P 888 888 Y8b. X88
# 888 "Y8888 88888P" 888 888 "Y8888 88888P'
# 888
# 888
# 888
#
/threads/{thread_mark}/replies:
post:
operationId: ReplyCreate
description: Create a new post within a thread.
tags: [replies]
parameters: [$ref: '#/components/parameters/ThreadMarkParam']
requestBody: { $ref: '#/components/requestBodies/ReplyCreate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/ReplyCreateOK' }
#
# 888
# 888
# 888
# 88888b. .d88b. .d8888b 888888 .d8888b
# 888 "88b d88""88b 88K 888 88K
# 888 888 888 888 "Y8888b. 888 "Y8888b.
# 888 d88P Y88..88P X88 Y88b. X88
# 88888P" "Y88P" 88888P' "Y888 88888P'
# 888
# 888
# 888
#
/posts/{post_id}:
patch:
operationId: PostUpdate
description: Publish changes to a single post.
tags: [posts]
parameters: [$ref: '#/components/parameters/PostIDParam']
requestBody: { $ref: '#/components/requestBodies/PostUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/PostUpdateOK' }
delete:
operationId: PostDelete
description: Archive a post using soft-delete.
tags: [posts]
parameters: [$ref: '#/components/parameters/PostIDParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
/posts/{post_id}/reacts:
put:
operationId: PostReactAdd
description: Add a reaction to a post.
tags: [posts]
parameters: [$ref: '#/components/parameters/PostIDParam']
requestBody: { $ref: '#/components/requestBodies/PostReactAdd' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/PostReactAddOK' }
/posts/{post_id}/reacts/{react_id}:
delete:
operationId: PostReactRemove
description: Remove a reaction from a post.
tags: [posts]
parameters:
- $ref: '#/components/parameters/PostIDParam'
- $ref: '#/components/parameters/ReactIDParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
#
# 888
# 888
# 888
# 8888b. .d8888b .d8888b .d88b. 888888 .d8888b
# "88b 88K 88K d8P Y8b 888 88K
# .d888888 "Y8888b. "Y8888b. 88888888 888 "Y8888b.
# 888 888 X88 X88 Y8b. Y88b. X88
# "Y888888 88888P' 88888P' "Y8888 "Y888 88888P'
#
/assets:
post:
operationId: AssetUpload
description: Upload and process a media file.
tags: [assets]
requestBody: { $ref: '#/components/requestBodies/AssetUpload' }
parameters:
- $ref: '#/components/parameters/ContentLength'
- $ref: '#/components/parameters/AssetNameQuery'
- $ref: '#/components/parameters/ParentAssetIDQuery'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AssetUploadOK' }
/assets/{asset_filename}:
get:
operationId: AssetGet
description: Download an asset by its ID.
tags: [assets]
parameters: [$ref: '#/components/parameters/AssetPathParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/AssetGetOK' }
#
# 888 d8b 888
# 888 Y8P 888
# 888 888
# 888 888 888 888 .d88b. .d8888b
# 888 888 888 .88P d8P Y8b 88K
# 888 888 888888K 88888888 "Y8888b.
# 888 888 888 "88b Y8b. X88
# 888 888 888 888 "Y8888 88888P'
#
/likes/posts/{post_id}:
get:
operationId: LikePostGet
description: Retreives all likes for the given post. Not paginated (yet.)
tags: [likes]
parameters:
- $ref: '#/components/parameters/PostIDParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/LikePostGetOK' }
put:
operationId: LikePostAdd
description: |
Add a like/vote to a post. A "like" is pretty much what you'd expect for
any modern social platform, it will inform the feed algorithm and the
account's recommendations as well as listing the post on their profile.
Idempotent operation where repeated use will do nothing.
tags: [likes]
parameters:
- $ref: '#/components/parameters/PostIDParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
delete:
operationId: LikePostRemove
description: |
Removes a like/vote from the authenticated account for the post. It will
perform the inverse of any changes to the account's algorithm. Also is
idempotent, so repeated use will do nothing after being actioned once.
tags: [likes]
parameters:
- $ref: '#/components/parameters/PostIDParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
/likes/profiles/{account_handle}:
get:
operationId: LikeProfileGet
description: Retreives all the likes that the given profile has given.
tags: [likes]
parameters:
- $ref: '#/components/parameters/AccountHandleParam'
- $ref: '#/components/parameters/PaginationQuery'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/LikeProfileGetOK' }
#
# 888 888 888 d8b
# 888 888 888 Y8P
# 888 888 888
# .d8888b .d88b. 888 888 .d88b. .d8888b 888888 888 .d88b. 88888b. .d8888b
# d88P" d88""88b 888 888 d8P Y8b d88P" 888 888 d88""88b 888 "88b 88K
# 888 888 888 888 888 88888888 888 888 888 888 888 888 888 "Y8888b.
# Y88b. Y88..88P 888 888 Y8b. Y88b. Y88b. 888 Y88..88P 888 888 X88
# "Y8888P "Y88P" 888 888 "Y8888 "Y8888P "Y888 888 "Y88P" 888 888 88888P'
#
/collections:
post:
operationId: CollectionCreate
description: |
Create a collection for curating posts under the authenticated account.
tags: [collections]
requestBody: { $ref: '#/components/requestBodies/CollectionCreate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/CollectionCreateOK' }
get:
operationId: CollectionList
description: List all collections using the filtering options.
tags: [collections]
parameters:
- { $ref: '#/components/parameters/AccountHandleQueryParam' }
- { $ref: '#/components/parameters/CollectionHasItemQueryParam' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'200': { $ref: '#/components/responses/CollectionListOK' }
/collections/{collection_mark}:
get:
operationId: CollectionGet
description: |
Get a collection by its ID. Collections can be public or private so the
response will depend on which account is making the request and if the
target collection is public, private, owned or not owned by the account.
tags: [collections]
parameters: [$ref: '#/components/parameters/CollectionMarkParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/CollectionGetOK' }
patch:
operationId: CollectionUpdate
description: Update a collection owned by the authenticated account.
tags: [collections]
parameters: [$ref: '#/components/parameters/CollectionMarkParam']
requestBody: { $ref: '#/components/requestBodies/CollectionUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/CollectionUpdateOK' }
delete:
operationId: CollectionDelete
description: Delete a collection owned by the authenticated account.
tags: [collections]
parameters: [$ref: '#/components/parameters/CollectionMarkParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
/collections/{collection_mark}/posts/{post_id}:
put:
operationId: CollectionAddPost
description: |
Add a post to a collection. The collection must be owned by the account
making the request. The post can be any published post of any kind.
tags: [collections]
parameters:
- $ref: '#/components/parameters/CollectionMarkParam'
- $ref: '#/components/parameters/PostIDParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/CollectionAddPostOK' }
delete:
operationId: CollectionRemovePost
description: |
Remove a post from a collection. The collection must be owned by the
account making the request.
tags: [collections]
parameters:
- $ref: '#/components/parameters/CollectionMarkParam'
- $ref: '#/components/parameters/PostIDParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/CollectionRemovePostOK' }
/collections/{collection_mark}/nodes/{node_id}:
put:
operationId: CollectionAddNode
description: |
Add a node to a collection. The collection must be owned by the account
making the request. The node can be any published node or any node
not published but owned by the collection owner.
tags: [collections]
parameters:
- $ref: '#/components/parameters/CollectionMarkParam'
- $ref: '#/components/parameters/NodeIDParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/CollectionAddNodeOK' }
delete:
operationId: CollectionRemoveNode
description: |
Remove a node from a collection. The collection must be owned by the
account making the request.
tags: [collections]
parameters:
- $ref: '#/components/parameters/CollectionMarkParam'
- $ref: '#/components/parameters/NodeIDParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/CollectionRemoveNodeOK' }
#
# 888
# 888
# 888
# 88888b. .d88b. .d88888 .d88b. .d8888b
# 888 "88b d88""88b d88" 888 d8P Y8b 88K
# 888 888 888 888 888 888 88888888 "Y8888b.
# 888 888 Y88..88P Y88b 888 Y8b. X88
# 888 888 "Y88P" "Y88888 "Y8888 88888P'
#
/nodes:
post:
operationId: NodeCreate
description: |
Create a node for curating structured knowledge together.
tags: [nodes]
requestBody: { $ref: '#/components/requestBodies/NodeCreate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NodeCreateOK' }
get:
operationId: NodeList
description: |
List nodes using the given filters. Can be used to get a full tree.
tags: [nodes]
parameters:
- $ref: '#/components/parameters/SearchQuery'
- $ref: '#/components/parameters/PaginationQuery'
- name: node_id
description: List this node and all child nodes.
required: false
in: query
schema: { $ref: '#/components/schemas/Identifier' }
- name: author
description: Show only results owned by this account.
required: false
in: query
schema: { $ref: '#/components/schemas/AccountHandle' }
- $ref: '#/components/parameters/VisibilityParam'
- $ref: '#/components/parameters/TreeDepthParam'
- $ref: '#/components/parameters/NodeListFormatParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'200': { $ref: '#/components/responses/NodeListOK' }
/nodes/{node_slug}:
get:
operationId: NodeGet
description: Get a node by its URL slug.
tags: [nodes]
parameters:
- $ref: '#/components/parameters/NodeSlugParam'
- $ref: '#/components/parameters/NodeChildrenSortParam'
- $ref: '#/components/parameters/PaginationQuery'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NodeGetOK' }
patch:
operationId: NodeUpdate
description: Update a node.
tags: [nodes]
parameters:
- $ref: '#/components/parameters/NodeSlugParam'
requestBody: { $ref: '#/components/requestBodies/NodeUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NodeUpdateOK' }
delete:
operationId: NodeDelete
description: Delete a node and move all children to its parent or root.
tags: [nodes]
parameters:
- $ref: '#/components/parameters/NodeSlugParam'
- $ref: '#/components/parameters/TargetNodeSlugQuery'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NodeDeleteOK' }
/nodes/{node_slug}/title:
post:
operationId: NodeGenerateTitle
description: |
Generate a proposed title for the specified node. Will not actually
mutate the specified node, instead will return a proposal based on the
output from a language model call.
tags: [nodes]
parameters: [$ref: '#/components/parameters/NodeSlugParam']
requestBody: { $ref: '#/components/requestBodies/NodeGenerateTitle' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'501': { $ref: '#/components/responses/NotImplemented' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/NodeGenerateTitleOK' }
/nodes/{node_slug}/tags:
post:
operationId: NodeGenerateTags
description: |
Generate proposed tags for the specified node. Will not actually mutate
the specified node, instead will return a proposal based on the output
from a language model call.
tags: [nodes]
parameters: [$ref: '#/components/parameters/NodeSlugParam']
requestBody: { $ref: '#/components/requestBodies/NodeGenerateTags' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'501': { $ref: '#/components/responses/NotImplemented' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/NodeGenerateTagsOK' }
/nodes/{node_slug}/content:
post:
operationId: NodeGenerateContent
description: |
Generate proposed content for the specified node. Will not actually
mutate the specified node, instead will return a proposal based on the
output from a language model call.
tags: [nodes]
parameters: [$ref: '#/components/parameters/NodeSlugParam']
requestBody: { $ref: '#/components/requestBodies/NodeGenerateContent' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'501': { $ref: '#/components/responses/NotImplemented' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/NodeGenerateContentOK' }
/nodes/{node_slug}/children:
get:
operationId: NodeListChildren
description: |
Get all the children of a given node using the provided filters and page
parameters. This can be used for rendering the child nodes of the given
node as an interactive table where properties can be used as columns.
tags: [nodes]
parameters:
- $ref: '#/components/parameters/NodeSlugParam'
- $ref: '#/components/parameters/NodeChildrenSortParam'
- $ref: '#/components/parameters/PaginationQuery'
- $ref: '#/components/parameters/SearchQuery'
- $ref: '#/components/parameters/TagNameListQueryParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NodeListOK' }
/nodes/{node_slug}/children/property-schema:
patch:
operationId: NodeUpdateChildrenPropertySchema
description: |
Updates the property schema of the children of this node. All children
of a node use the same schema for properties resulting in a table-like
structure and behaviour. See also: NodeUpdatePropertySchema
tags: [nodes]
parameters: [$ref: '#/components/parameters/NodeSlugParam']
requestBody:
{ $ref: '#/components/requestBodies/NodeUpdatePropertySchema' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200':
$ref: '#/components/responses/NodeUpdatePropertySchemaOK'
/nodes/{node_slug}/property-schema:
patch:
operationId: NodeUpdatePropertySchema
description: |
Updates the property schema of this node and its siblings. All children
of a node use the same schema for properties resulting in a table-like
structure and behaviour. Property schemas are loosely structured and can
automatically cast their values sometimes. A failed cast will not change
data and instead just yield an empty value when reading however changing
the schema back to the original type (or a type compatible with what the
type was before changing) will retain the original data upon next read.
This permits clients to undo changes to the schema easily while allowing
quick schema changes without the need to remove or update values before.
tags: [nodes]
parameters: [$ref: '#/components/parameters/NodeSlugParam']
requestBody:
{ $ref: '#/components/requestBodies/NodeUpdatePropertySchema' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200':
$ref: '#/components/responses/NodeUpdatePropertySchemaOK'
/nodes/{node_slug}/properties:
patch:
operationId: NodeUpdateProperties
description: |
Update the properties of a node. New schema fields will result in the
schema of the node being updated before values are assigned. This will
also propagate to all sibling nodes as they all share the same schema.
tags: [nodes]
parameters: [$ref: '#/components/parameters/NodeSlugParam']
requestBody: { $ref: '#/components/requestBodies/NodeUpdateProperties' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/NodeUpdatePropertiesOK' }
/nodes/{node_slug}/visibility:
patch:
operationId: NodeUpdateVisibility
description: |
Update the visibility of a node. When changed, this may trigger other
operations such as notifications/newsletters. Changing the visibility of
anything to "published" is often accompanied by some other side effects.
tags: [nodes]
parameters: [$ref: '#/components/parameters/NodeSlugParam']
requestBody: { $ref: '#/components/requestBodies/VisibilityUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NodeUpdateOK' }
/nodes/{node_slug}/assets/{asset_id}:
put:
operationId: NodeAddAsset
description: Add an asset to a node.
tags: [nodes]
parameters:
- $ref: '#/components/parameters/NodeSlugParam'
- $ref: '#/components/parameters/AssetIDParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NodeUpdateOK' }
delete:
operationId: NodeRemoveAsset
description: Remove an asset from a node.
tags: [nodes]
parameters:
- $ref: '#/components/parameters/NodeSlugParam'
- $ref: '#/components/parameters/AssetIDParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NodeUpdateOK' }
/nodes/{node_slug}/nodes/{node_slug_child}:
put:
operationId: NodeAddNode
description: Set a node's parent to the specified node
tags: [nodes]
parameters:
- $ref: '#/components/parameters/NodeSlugParam'
- $ref: '#/components/parameters/NodeSlugChildParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NodeAddChildOK' }
delete:
operationId: NodeRemoveNode
description: |
Remove a node from its parent node and back to the top level.
tags: [nodes]
parameters:
- $ref: '#/components/parameters/NodeSlugParam'
- $ref: '#/components/parameters/NodeSlugChildParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/NodeRemoveChildOK' }
/nodes/{node_slug}/position:
patch:
operationId: NodeUpdatePosition
description: |
Update the node's position in the tree, which optionally allows for
changing the node's parent either to another node or to `null` which
severs the parent and moves the node to the root. This endpoint also
allows for moving the node's sort position within either its current
parent, or when moving it to a new parent. Use this operation for a
draggable tree interface or a table interface.
tags: [nodes]
parameters: [$ref: '#/components/parameters/NodeSlugParam']
requestBody: { $ref: '#/components/requestBodies/NodeUpdatePosition' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'400': { $ref: '#/components/responses/BadRequest' }
'200': { $ref: '#/components/responses/NodeUpdateOK' }
#
# 888 d8b 888
# 888 Y8P 888
# 888 888
# 888 888 88888b. 888 888 .d8888b
# 888 888 888 "88b 888 .88P 88K
# 888 888 888 888 888888K "Y8888b.
# 888 888 888 888 888 "88b X88
# 888 888 888 888 888 888 88888P'
#
/links:
post:
operationId: LinkCreate
description: |
Add a link to the community bookmarks. This will also scrape the content
at the site the link points to, if possible. If the submitted link is an
invalid link for whatever reason (invalid URL structure or page is dead)
then the API will fail. The metadata for the link is indexed on success.
If the submitted link already exists it will be an idempotent operation,
unless the body contains additional metadata. In these cases, the link's
metadata will be updated with the new metadata and the URL is unchanged.
When a link is submitted, it is first "cleaned" to remove any fragments.
tags: [links]
requestBody: { $ref: '#/components/requestBodies/LinkCreate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/LinkCreateOK' }
get:
operationId: LinkList
description: List all links using the filtering options.
tags: [links]
parameters:
- $ref: '#/components/parameters/SearchQuery'
- $ref: '#/components/parameters/PaginationQuery'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'200': { $ref: '#/components/responses/LinkListOK' }
/links/{link_slug}:
get:
operationId: LinkGet
description: |
Get the details for a specific link. Such as where it's been posted,
which resources it's linked to and how many times it's been opened.
tags: [links]
parameters: [{ $ref: '#/components/parameters/LinkSlugParam' }]
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'200': { $ref: '#/components/responses/LinkGetOK' }
#
# 888 888 888
# 888 888 888
# 888 888 888
# .d88888 8888b. 888888 8888b. .d88b. 888d888 8888b. 88888b. 88888b.
# d88" 888 "88b 888 "88b d88P"88b 888P" "88b 888 "88b 888 "88b
# 888 888 .d888888 888 .d888888 888 888 888 .d888888 888 888 888 888
# Y88b 888 888 888 Y88b. 888 888 Y88b 888 888 888 888 888 d88P 888 888
# "Y88888 "Y888888 "Y888 "Y888888 "Y88888 888 "Y888888 88888P" 888 888
# 888 888
# Y8b d88P 888
# "Y88P" 888
#
/datagraph:
get:
operationId: DatagraphSearch
description: Query and search content.
tags: [datagraph]
parameters:
- $ref: '#/components/parameters/RequiredSearchQuery'
- $ref: '#/components/parameters/DatagraphKindQuery'
- $ref: '#/components/parameters/PaginationQuery'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/DatagraphSearchOK' }
/datagraph/ask:
get:
operationId: DatagraphAsk
description: Ask questions about the community's content.
tags: [datagraph]
parameters:
- $ref: '#/components/parameters/RequiredSearchQuery'
- $ref: '#/components/parameters/ParentQuestionID'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/DatagraphAskOK' }
#
# 888
# 888
# 888
# .d88b. 888 888 .d88b. 88888b. 888888 .d8888b
# d8P Y8b 888 888 d8P Y8b 888 "88b 888 88K
# 88888888 Y88 88P 88888888 888 888 888 "Y8888b.
# Y8b. Y8bd8P Y8b. 888 888 Y88b. X88
# "Y8888 Y88P "Y8888 888 888 "Y888 88888P'
#
/events:
get:
operationId: EventList
description: List all events using the filtering options.
tags: [events]
parameters:
- $ref: '#/components/parameters/SearchQuery'
- $ref: '#/components/parameters/PaginationQuery'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'200': { $ref: '#/components/responses/EventListOK' }
post:
operationId: EventCreate
description: |
Create a new event. When an event is created, a thread is also created
which provides the means for discussion via the thread and reply APIs.
tags: [events]
requestBody: { $ref: '#/components/requestBodies/EventCreate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/EventCreateOK' }
/events/{event_mark}:
get:
operationId: EventGet
description: Get an event by its ID.
tags: [events]
parameters: [$ref: '#/components/parameters/EventMarkParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/EventGetOK' }
patch:
operationId: EventUpdate
description: |
Update an event. If the content field is updated, this is stored on the
thread associated with the event, rather than the event itself. It's
possible to update that thread directly using `threads` operations.
tags: [events]
parameters: [$ref: '#/components/parameters/EventMarkParam']
requestBody: { $ref: '#/components/requestBodies/EventUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { $ref: '#/components/responses/EventUpdateOK' }
delete:
operationId: EventDelete
description: Delete an event.
tags: [events]
parameters: [$ref: '#/components/parameters/EventMarkParam']
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
/events/{event_mark}/participants/{account_id}:
put:
operationId: EventParticipantUpdate
description: |
Add a participant to an event or change an existing participant's state.
If the requesting account is an admin or holds MANAGE_EVENTS permission,
they can change the participation properties of any account. Otherwise,
they can only change their own participation properties.
For non-managing members (i.e. not an admin and not a host) this will
follow a stricter state machine for the participation status. If the
participation status is not set (no participation record is present) or
set to "declined", the member may only set their status to "requested"
if the event policy is set to "invite_only". Otherwise, they may set it
to "attending". If the member is already set to one of these states,
they may change it to "declined".
A non-managing member cannot change their role and the default is
"attendee", only managing members can change participant roles.
If the event participation policy is set to "invite_only" then members
can only set their status to "requested" or delete their participation.
If the event participation policy is set to "closed", it's a no-op.
Requests to this resource are idempotent given identical request bodies.
It acts as a create-or-update action as participation is account-unique.
tags: [events]
parameters:
- $ref: '#/components/parameters/EventMarkParam'
- $ref: '#/components/parameters/AccountIDParam'
requestBody: { $ref: '#/components/requestBodies/EventParticipantUpdate' }
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
delete:
operationId: EventParticipantRemove
description: |
Remove a participant from an event. Same rules as EventParticipantUpdate
where non-managing members may only remove themselves. Not soft-delete.
tags: [events]
parameters:
- $ref: '#/components/parameters/EventMarkParam'
- $ref: '#/components/parameters/AccountIDParam'
responses:
default: { $ref: '#/components/responses/InternalServerError' }
'404': { $ref: '#/components/responses/NotFound' }
'401': { $ref: '#/components/responses/Unauthorised' }
'200': { description: OK }
components:
#
# 8888888b. d8888 8888888b. d8888 888b d888 8888888888 88888888888 8888888888 8888888b. .d8888b.
# 888 Y88b d88888 888 Y88b d88888 8888b d8888 888 888 888 888 Y88b d88P Y88b
# 888 888 d88P888 888 888 d88P888 88888b.d88888 888 888 888 888 888 Y88b.
# 888 d88P d88P 888 888 d88P d88P 888 888Y88888P888 8888888 888 8888888 888 d88P "Y888b.
# 8888888P" d88P 888 8888888P" d88P 888 888 Y888P 888 888 888 888 8888888P" "Y88b.
# 888 d88P 888 888 T88b d88P 888 888 Y8P 888 888 888 888 888 T88b "888
# 888 d8888888888 888 T88b d8888888888 888 " 888 888 888 888 888 T88b Y88b d88P
# 888 d88P 888 888 T88b d88P 888 888 888 8888888888 888 8888888888 888 T88b "Y8888P"
#
parameters:
IconSize:
description: Icon sizes.
example: '512x512'
name: icon_size
in: path
required: true
schema:
type: string
enum:
- 512x512 # Generic big icon
- 32x32 # Generic small icon
- 180x180 # iOS high DPI
- 120x120 # iOS low DPI
- 167x167 # iPad OS
- 152x152 # iPad Mini
ContentLength:
description: Body content length in bytes.
name: Content-Length
in: header
required: true
schema:
type: integer
x-go-type: int64
RoleIDParam:
description: Role ID
in: path
name: role_id
required: true
schema:
$ref: '#/components/schemas/Identifier'
AccessKeyIDParam:
description: Access key ID.
in: path
name: access_key_id
required: true
schema:
$ref: '#/components/schemas/Identifier'
AccountIDParam:
description: Account ID.
name: account_id
in: path
required: true
schema:
$ref: '#/components/schemas/Identifier'
AccountHandleParam:
description: Account handle.
example: southclaws
name: account_handle
in: path
required: true
schema:
$ref: '#/components/schemas/AccountHandle'
AccountHandleQueryParam:
description: Account handle.
example: southclaws
name: account_handle
in: query
required: false
schema:
$ref: '#/components/schemas/AccountHandle'
AccountIDQueryParam:
description: Account ID.
name: account_id
in: query
required: false
schema:
$ref: '#/components/schemas/Identifier'
EmailAddressIDParam:
description: An email address ID associated with the requesting account.
name: email_address_id
in: path
required: true
schema:
$ref: '#/components/schemas/Identifier'
InvitationIDParam:
description: Unique invitation ID.
name: invitation_id
in: path
required: true
schema:
$ref: '#/components/schemas/Identifier'
InvitationIDQueryParam:
description: Unique invitation ID.
name: invitation_id
in: query
required: false
schema:
$ref: '#/components/schemas/Identifier'
NotificationStatusQuery:
description: Notification status.
name: status
in: query
required: false
schema:
$ref: '#/components/schemas/NotificationStatusList'
NotificationIDParam:
description: Unique notification ID.
name: notification_id
in: path
required: true
schema:
$ref: '#/components/schemas/Identifier'
ThreadMarkParam:
description: Thread unique and permanent identifier.
name: thread_mark
in: path
required: true
schema:
$ref: '#/components/schemas/ThreadMark'
PostIDParam:
description: Unique post ID.
name: post_id
in: path
required: true
schema:
$ref: '#/components/schemas/Identifier'
ReactIDParam:
description: Unique react ID.
name: react_id
in: path
required: true
schema:
$ref: '#/components/schemas/Identifier'
NodeIDParam:
description: Unique node ID.
name: node_id
in: path
required: true
schema:
$ref: '#/components/schemas/Identifier'
OAuthProvider:
description: The identifier for an OAuth2 provider such as "twitter".
name: oauth_provider
in: path
required: true
example: twitter
schema:
type: string
SearchQuery:
description: Search query string.
name: q
in: query
required: false
allowEmptyValue: true
schema:
type: string
minLength: 0
RequiredSearchQuery:
description: Search query string.
name: q
in: query
required: true
allowEmptyValue: true
schema:
type: string
minLength: 0
ParentQuestionID:
description: If a follow-up question, the parent question ID.
name: parent_question_id
in: query
required: false
allowEmptyValue: true
schema:
type: string
DatagraphKindQuery:
description: Datagraph item kind query.
name: kind
in: query
required: false
allowEmptyValue: true
explode: true
schema:
type: array
items: { $ref: '#/components/schemas/DatagraphItemKind' }
PaginationQuery:
description: Pagination query parameters.
name: page
in: query
required: false
schema:
type: string
AssetPathParam:
description: Asset ID.
name: asset_filename
in: path
required: true
schema:
type: string
AssetIDParam:
description: Asset ID.
name: asset_id
in: path
required: true
schema:
type: string
ParentAssetIDQuery:
description: |
For uploading new versions of an existing asset, set this parameter to
the asset ID of the parent asset. This must be an ID and not a filename.
This feature is used for situations where you want to replace an asset
in its usage context, but retain the original with a way to reference it
for features such as editable/croppable images or file version history.
name: parent_asset_id
in: query
required: false
schema:
type: string
AssetNameQuery:
description: The client-provided file name for the asset.
name: filename
in: query
required: false
schema:
type: string
CategorySlugParam:
description: Unique category URL slug.
name: category_slug
in: path
required: true
schema:
type: string
CategorySlugListQuery:
name: categories
description: |
Category slugs to filter by. Multiple instances of this parameter can be
used to filter by many categories. If not provided, no filtering will be
applied and all threads will be returned. If ANY of the provided values
is set to the exact value of "null" then only uncategorised threads will
be returned. When filtering for uncategorised threads, all other values
will be ignored, only the value containing "null" will be considered.
required: false
in: query
schema:
$ref: '#/components/schemas/CategorySlugList'
TagNameParam:
description: Tag name.
name: tag_name
in: path
required: true
schema:
type: string
TagNameListQueryParam:
description: Tags to filter by.
name: tags
in: query
required: false
schema: { $ref: '#/components/schemas/TagNameList' }
CollectionMarkParam:
description: |
Either:
- The unique collection ID.
- A string of the form <id>-<slug>
name: collection_mark
in: path
required: true
schema:
$ref: '#/components/schemas/Mark'
CollectionHasItemQueryParam:
description: |
When specified, will include a field in the response indicating whether
or not the specified item is present in the collection. This saves you
needing to make two queries to check if an item is in a collection.
name: has_item
in: query
required: false
schema:
$ref: '#/components/schemas/Identifier'
NodeSlugParam:
description: Unique node Slug.
name: node_slug
in: path
required: true
schema:
$ref: '#/components/schemas/Identifier'
NodeSlugChildParam:
description: Unique node Slug.
name: node_slug_child
in: path
required: true
schema:
$ref: '#/components/schemas/Identifier'
NodeChildrenSortParam:
description: |
The field (either in schema or in property schema) to sort by.
name: children_sort
in: query
required: false
schema:
type: string
TargetNodeSlugQuery:
description: |
If set, child nodes will be moved to the target node. If not set, child
nodes will be moved to the root.
name: target_node
in: query
required: false
schema:
type: string
LinkSlugParam:
description: Unique link Slug.
name: link_slug
in: path
required: true
schema:
type: string
VisibilityParam:
name: visibility
description: |
Filter content with specific visibility values. Note that by default,
only published items are returned. When 'draft' is specified, only
drafts owned by the requesting account are included. When 'review' is
specified, the request will fail if the requesting account does not have
the necessary permission to view in-review items.
required: false
in: query
explode: true
schema:
type: array
items: { $ref: '#/components/schemas/Visibility' }
TreeDepthParam:
name: depth
description: |
When set to a positive value, the nodes in the response will include all
child nodes up to the specified depth. When set to zero, then if the
request includes a node ID only that node will be returned, otherwise
only top-level (root) nodes will be returned.
required: false
in: query
schema:
type: string
NodeListFormatParam:
name: format
description: |
List format, either a tree where each item contains a children array or
flat where children items contain an ID that references their parent.
required: false
in: query
schema:
default: tree
type: string
enum: [tree, flat]
EventMarkParam:
description: |
Either:
- The unique event ID.
- The unique event slug.
- A string of the form <id>-<slug>
name: event_mark
in: path
required: true
schema:
$ref: '#/components/schemas/Mark'
#
# 8888888b. 8888888888 .d88888b. 888 888 8888888888 .d8888b. 88888888888 .d8888b.
# 888 Y88b 888 d88P" "Y88b 888 888 888 d88P Y88b 888 d88P Y88b
# 888 888 888 888 888 888 888 888 Y88b. 888 Y88b.
# 888 d88P 8888888 888 888 888 888 8888888 "Y888b. 888 "Y888b.
# 8888888P" 888 888 888 888 888 888 "Y88b. 888 "Y88b.
# 888 T88b 888 888 Y8b 888 888 888 888 "888 888 "888
# 888 T88b 888 Y88b.Y8b88P Y88b. .d88P 888 Y88b d88P 888 Y88b d88P
# 888 T88b 8888888888 "Y888888" "Y88888P" 8888888888 "Y8888P" 888 "Y8888P"
# Y8b
#
requestBodies:
Beacon:
content:
text/plain:
schema: { $ref: '#/components/schemas/BeaconProps' }
AdminSettingsUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/AdminSettingsMutableProps' }
RoleCreate:
content:
application/json:
schema: { $ref: '#/components/schemas/RoleInitialProps' }
RoleUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/RoleMutableProps' }
AuthPassword:
content:
application/json:
schema: { $ref: '#/components/schemas/AuthPair' }
AuthEmailPassword:
content:
application/json:
schema: { $ref: '#/components/schemas/AuthEmailPasswordInitialProps' }
AuthEmailPasswordReset:
content:
application/json:
schema: { $ref: '#/components/schemas/AuthEmailPasswordReset' }
AuthEmail:
content:
application/json:
schema: { $ref: '#/components/schemas/AuthEmailInitialProps' }
AuthEmailVerify:
content:
application/json:
schema: { $ref: '#/components/schemas/AuthEmailVerifyProps' }
AuthPasswordCreate:
content:
application/json:
schema: { $ref: '#/components/schemas/AuthPasswordInitialProps' }
AuthPasswordUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/AuthPasswordMutableProps' }
AuthPasswordReset:
content:
application/json:
schema: { $ref: '#/components/schemas/AuthPasswordResetProps' }
OAuthProviderCallback:
content:
application/json:
schema: { $ref: '#/components/schemas/OAuthCallback' }
WebAuthnMakeCredential:
content:
application/json:
schema: { $ref: '#/components/schemas/PublicKeyCredential' }
WebAuthnMakeAssertion:
content:
application/json:
schema: { $ref: '#/components/schemas/PublicKeyCredential' }
PhoneRequestCode:
content:
application/json:
schema: { $ref: '#/components/schemas/PhoneRequestCodeProps' }
PhoneSubmitCode:
content:
application/json:
schema: { $ref: '#/components/schemas/PhoneSubmitCodeProps' }
AccessKeyCreate:
content:
application/json:
schema: { $ref: '#/components/schemas/AccessKeyInitialProps' }
AccountUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/AccountMutableProps' }
AccountEmailAdd:
content:
application/json:
schema: { $ref: '#/components/schemas/AccountEmailInitialProps' }
AccountSetAvatar:
content:
application/octet-stream:
schema:
type: string
format: binary
InvitationCreate:
content:
application/json:
schema: { $ref: '#/components/schemas/InvitationInitialProps' }
NotificationUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/NotificationMutableProps' }
CategoryCreate:
content:
application/json:
schema: { $ref: '#/components/schemas/CategoryInitialProps' }
CategoryUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/CategoryMutableProps' }
CategoryUpdatePosition:
content:
application/json:
schema: { $ref: '#/components/schemas/CategoryPositionMutableProps' }
CategoryDelete:
content:
application/json:
schema: { $ref: '#/components/schemas/CategoryDeleteProps' }
ThreadCreate:
content:
application/json:
schema: { $ref: '#/components/schemas/ThreadInitialProps' }
ThreadUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/ThreadMutableProps' }
ReplyCreate:
description: Create a reply, which is a post within a thread.
content:
application/json:
schema: { $ref: '#/components/schemas/ReplyInitialProps' }
PostUpdate:
description: Create a post within a thread.
content:
application/json:
schema: { $ref: '#/components/schemas/PostMutableProps' }
PostReactAdd:
description: Add a reaction to a post.
content:
application/json:
schema: { $ref: '#/components/schemas/ReactInitialProps' }
AssetUpload:
description: Upload a file.
content:
application/octet-stream:
schema:
type: string
format: binary
CollectionCreate:
content:
application/json:
schema: { $ref: '#/components/schemas/CollectionInitialProps' }
CollectionUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/CollectionMutableProps' }
NodeCreate:
content:
application/json:
schema: { $ref: '#/components/schemas/NodeInitialProps' }
NodeUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/NodeMutableProps' }
NodeGenerateTitle:
content:
application/json:
schema: { $ref: '#/components/schemas/NodeGenerateTitleRequest' }
NodeGenerateTags:
content:
application/json:
schema: { $ref: '#/components/schemas/NodeGenerateTagsRequest' }
NodeGenerateContent:
content:
application/json:
schema: { $ref: '#/components/schemas/NodeGenerateContentRequest' }
NodeUpdateProperties:
content:
application/json:
schema: { $ref: '#/components/schemas/PropertyMutableProps' }
NodeUpdatePropertySchema:
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/PropertySchemaMutableProps' }
NodeUpdatePosition:
content:
application/json:
schema: { $ref: '#/components/schemas/NodePositionMutableProps' }
LinkCreate:
content:
application/json:
schema: { $ref: '#/components/schemas/LinkInitialProps' }
VisibilityUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/VisibilityMutationProps' }
EventCreate:
content:
application/json:
schema: { $ref: '#/components/schemas/EventInitialProps' }
EventUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/EventMutableProps' }
EventParticipantUpdate:
content:
application/json:
schema: { $ref: '#/components/schemas/EventParticipantMutableProps' }
#
# 8888888b. 8888888888 .d8888b. 8888888b. .d88888b. 888b 888 .d8888b. 8888888888 .d8888b.
# 888 Y88b 888 d88P Y88b 888 Y88b d88P" "Y88b 8888b 888 d88P Y88b 888 d88P Y88b
# 888 888 888 Y88b. 888 888 888 888 88888b 888 Y88b. 888 Y88b.
# 888 d88P 8888888 "Y888b. 888 d88P 888 888 888Y88b 888 "Y888b. 8888888 "Y888b.
# 8888888P" 888 "Y88b. 8888888P" 888 888 888 Y88b888 "Y88b. 888 "Y88b.
# 888 T88b 888 "888 888 888 888 888 Y88888 "888 888 "888
# 888 T88b 888 Y88b d88P 888 Y88b. .d88P 888 Y8888 Y88b d88P 888 Y88b d88P
# 888 T88b 8888888888 "Y8888P" 888 "Y88888P" 888 Y888 "Y8888P" 8888888888 "Y8888P"
#
responses:
NotImplemented:
description: Not implemented
NotModified:
description: Not modified
headers: { <<: *cache_response_headers }
BadRequest:
description: Bad request
NotFound:
description: Not found
Unauthorised:
description: Unauthorized
Forbidden:
description: Forbidden
NoContent:
description: No content
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/APIError'
GetInfoOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Info'
AdminSettingsUpdateOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AdminSettingsProps'
RoleCreateOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
RoleListOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/RoleListResult'
RoleGetOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
AuthSuccessOK:
description: OK
headers:
'Set-Cookie':
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/AuthSuccess'
AuthProviderListOK:
description: OK
content:
application/json:
schema:
type: object
required: [providers, mode]
properties:
providers: { $ref: '#/components/schemas/AuthProviderList' }
mode: { $ref: '#/components/schemas/AuthMode' }
WebAuthnRequestCredentialOK:
description: OK
headers:
'Set-Cookie':
schema:
type: string
content:
application/json:
schema:
{ $ref: '#/components/schemas/WebAuthnPublicKeyCreationOptions' }
WebAuthnGetAssertionOK:
description: OK
headers:
'Set-Cookie':
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/CredentialRequestOptions'
AccessKeyCreateOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKeyIssued'
AdminAccessKeyListOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OwnedAccessKeyListResult'
AccessKeyListOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccessKeyListResult'
AccountGetOK:
description: OK
headers: { <<: *cache_response_headers }
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
AccountUpdateOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
AccountEmailUpdateOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountEmailAddress'
AccountAuthProviderListOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountAuthMethods'
AccountGetAvatar:
description: OK
headers: { <<: *cache_response_headers }
content:
image/png:
schema:
type: string
format: binary
InvitationListOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/InvitationListResult'
InvitationCreateOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Invitation'
InvitationGetOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Invitation'
NotificationListOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationListResult'
NotificationUpdateOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Notification'
ProfileListOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PublicProfileListResult'
ProfileGetOK:
description: OK
headers: { <<: *cache_response_headers }
content:
application/json:
schema:
$ref: '#/components/schemas/PublicProfile'
ProfileFollowersGetOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PublicProfileFollowersResult'
ProfileFollowingGetOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PublicProfileFollowingResult'
CategoryCreateOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Category'
CategoryGetOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Category'
CategoryUpdateOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Category'
CategoryDeleteOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Category'
CategoryListOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryListResult'
TagListOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/TagListResult'
TagGetOK:
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Tag'
ThreadCreateOK:
description: Thread created.
content:
application/json:
schema:
$ref: '#/components/schemas/Thread'
ThreadUpdateOK:
description: Thread updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Thread'
ThreadListOK:
description: List of all threads.
headers: { <<: *cache_response_headers }
content:
application/json:
schema: { $ref: '#/components/schemas/ThreadListResult' }
ThreadGet:
description: The information about a thread and its posts.
headers: { <<: *cache_response_headers }
content:
application/json:
schema: { $ref: '#/components/schemas/Thread' }
ReplyCreateOK:
description: Thread reply created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Reply'
PostUpdateOK:
description: Post updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Post'
PostReactAddOK:
description: Post reaction added.
content:
application/json:
schema:
$ref: '#/components/schemas/React'
AssetUploadOK:
description: The new URL of an uploaded file.
content:
application/json:
schema:
$ref: '#/components/schemas/Asset'
AssetGetOK:
description: The new URL of an uploaded file.
headers: { <<: *cache_response_headers }
content:
'*/*':
schema:
type: string
format: binary
LikePostGetOK:
description: All likes for a post.
content:
application/json:
schema:
type: object
required: [likes]
properties:
likes: { $ref: '#/components/schemas/ItemLikeList' }
LikeProfileGetOK:
description: Likes that an account has given.
content:
application/json:
schema:
$ref: '#/components/schemas/ProfileLikeListResult'
CollectionCreateOK:
description: Collection created.
content:
application/json:
schema:
$ref: '#/components/schemas/Collection'
CollectionListOK:
description: Collection list.
content:
application/json:
schema:
type: object
required: [collections]
properties:
collections: { $ref: '#/components/schemas/CollectionList' }
CollectionGetOK:
description: Collection information and content.
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionWithItems'
CollectionUpdateOK:
description: Collection updated.
content:
application/json:
schema:
$ref: '#/components/schemas/Collection'
CollectionAddPostOK:
description: Collection content added.
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionWithItems'
CollectionRemovePostOK:
description: Collection content added.
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionWithItems'
CollectionAddNodeOK:
description: Collection content added.
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionWithItems'
CollectionRemoveNodeOK:
description: Collection content added.
content:
application/json:
schema:
$ref: '#/components/schemas/CollectionWithItems'
NodeCreateOK:
description: Node created.
content:
application/json:
schema:
$ref: '#/components/schemas/Node'
NodeListOK:
description: Node list.
content:
application/json:
schema: { $ref: '#/components/schemas/NodeListResult' }
NodeGetOK:
description: Node information and content.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeWithChildren'
NodeUpdateOK:
description: Node updated.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeWithChildren'
NodeGenerateTitleOK:
description: Node title generated.
content:
application/json:
schema: { $ref: '#/components/schemas/NodeGenerateTitleResult' }
NodeGenerateTagsOK:
description: Node tags generated.
content:
application/json:
schema: { $ref: '#/components/schemas/NodeGenerateTagsResult' }
NodeGenerateContentOK:
description: Node content generated.
content:
application/json:
schema: { $ref: '#/components/schemas/NodeGenerateContentResult' }
NodeUpdatePropertiesOK:
description: Node properties updated.
content:
application/json:
schema:
type: object
required: [properties]
properties:
properties:
$ref: '#/components/schemas/PropertyList'
NodeUpdatePropertySchemaOK:
description: Node children schema updated.
content:
application/json:
schema:
type: object
required: [properties]
properties:
properties:
$ref: '#/components/schemas/PropertySchemaList'
NodeDeleteOK:
description: Node deleted.
content:
application/json:
schema:
type: object
properties:
destination:
$ref: '#/components/schemas/Node'
NodeAddChildOK:
description: Node child added. Returns parent node.
content:
application/json:
schema:
$ref: '#/components/schemas/Node'
NodeRemoveChildOK:
description: Node child removed. Returns parent node.
content:
application/json:
schema:
$ref: '#/components/schemas/Node'
LinkCreateOK:
description: Link indexed
content:
application/json:
schema:
$ref: '#/components/schemas/LinkReference'
LinkListOK:
description: Link list.
content:
application/json:
schema: { $ref: '#/components/schemas/LinkListResult' }
LinkGetOK:
description: Link data.
content:
application/json:
schema:
$ref: '#/components/schemas/Link'
DatagraphSearchOK:
description: Search results.
content:
application/json:
schema: { $ref: '#/components/schemas/DatagraphSearchResult' }
DatagraphAskOK:
description: Search results.
content:
text/event-stream:
schema:
type: string
EventListOK:
description: Event list.
content:
application/json:
schema: { $ref: '#/components/schemas/EventListResult' }
EventCreateOK:
description: Event create.
content:
application/json:
schema: { $ref: '#/components/schemas/Event' }
EventGetOK:
description: Event get.
content:
application/json:
schema: { $ref: '#/components/schemas/Event' }
EventUpdateOK:
description: Event update.
content:
application/json:
schema: { $ref: '#/components/schemas/Event' }
#
# .d8888b. .d8888b. 888 888 8888888888 888b d888 d8888 .d8888b.
# d88P Y88b d88P Y88b 888 888 888 8888b d8888 d88888 d88P Y88b
# Y88b. 888 888 888 888 888 88888b.d88888 d88P888 Y88b.
# "Y888b. 888 8888888888 8888888 888Y88888P888 d88P 888 "Y888b.
# "Y88b. 888 888 888 888 888 Y888P 888 d88P 888 "Y88b.
# "888 888 888 888 888 888 888 Y8P 888 d88P 888 "888
# Y88b d88P Y88b d88P 888 888 888 888 " 888 d8888888888 Y88b d88P
# "Y8888P" "Y8888P" 888 888 8888888888 888 888 d88P 888 "Y8888P"
#
headers:
Cache-Control:
schema:
type: string
Last-Modified:
schema:
type: string
format: RFC1123
ETag:
schema:
type: string
schemas:
#
# .d8888b.
# d88P Y88b
# 888 888
# 888 .d88b. 88888b.d88b. 88888b.d88b. .d88b. 88888b.
# 888 d88""88b 888 "888 "88b 888 "888 "88b d88""88b 888 "88b
# 888 888 888 888 888 888 888 888 888 888 888 888 888 888
# Y88b d88P Y88..88P 888 888 888 888 888 888 Y88..88P 888 888
# "Y8888P" "Y88P" 888 888 888 888 888 888 "Y88P" 888 888
#
Identifier:
type: string
format: xid
# NOTE: Does not work currently with oapi-codegen because it generates a
# new type declaration instead of a type alias so the unmarshalling fails.
# To work around this, there are special conversion APIs in the oapi pkg.
x-go-type: string
# x-go-type-import:
# name: xid
# path: github.com/rs/xid
example: 'cc5lnd2s1s4652adtu50'
description: A unique identifier for this resource.
NullableIdentifier:
type: string
format: xid
nullable: true
example: 'cc5lnd2s1s4652adtu50'
description: A unique identifier for this resource.
Mark:
description: |
A polymorphic identifier which is either a raw ID, a slug or both values
combined and separated by a hyphen. This allows endpoints to respond to
varying forms of a resource's ID which may be present in different app
contexts. For example, a slug may be used in a URL but raw IDs are often
exposed as part of API responses or in certain endpoint parameters. This
type allows flexibility in user experience as well as the API surface
while ensuring performance during database queries and other operations.
For example, given a thread with the ID `cc5lnd2s1s4652adtu50` and the
slug `top-10-movies-thread`, Storyden will understand both the forms:
`cc5lnd2s1s4652adtu50-top-10-movies-thread` or `cc5lnd2s1s4652adtu50` or
`top-10-movies-thread` as the identifier for that thread.
Marks are only ever used on the read path as they are a derivative data
type and are not stored in the database as-is, while IDs and slugs are.
The write path typically exposes slugs as writable and IDs as immutable.
x-go-type: string
type: string
format: xid-prefixed-kebab-case-string
example: 'cc5lnd2s1s4652adtu50-top-10-movies-thread'
Info:
description: Basic public information about the Storyden installation.
type: object
required:
- title
- description
- content
- accent_colour
- authentication_mode
- capabilities
- onboarding_status
properties:
title:
type: string
description:
type: string
content:
$ref: '#/components/schemas/PostContent'
accent_colour:
type: string
onboarding_status:
$ref: '#/components/schemas/OnboardingStatus'
authentication_mode:
$ref: '#/components/schemas/AuthMode'
capabilities:
$ref: '#/components/schemas/InstanceCapabilityList'
metadata:
$ref: '#/components/schemas/Metadata'
OnboardingStatus:
description: |
Derived from data state, indicates what stage in the onboarding process
the Storyden installation is in for directing first-time setup steps.
type: string
enum:
- requires_first_account
- requires_category
- requires_more_accounts
- requires_first_post
- complete
InstanceCapability:
type: string
enum:
- gen_ai
- semdex
- email_client
- sms_client
InstanceCapabilityList:
type: array
items: { $ref: '#/components/schemas/InstanceCapability' }
Visibility:
type: string
enum:
- draft
- unlisted
- review
- published
VisibilityMutationProps:
type: object
required: [visibility]
properties:
visibility: { $ref: '#/components/schemas/Visibility' }
Slug:
description: A URL-safe slug for uniquely identifying resources.
type: string
ThreadMark:
description: |
A thread's ID and optional slug separated by a dash = it's unique mark.
This allows endpoints to respond to varying forms of a thread's ID.
For example, given a thread with the ID `cc5lnd2s1s4652adtu50` and the
slug `top-10-movies-thread`, Storyden will understand both the forms:
`cc5lnd2s1s4652adtu50-top-10-movies-thread` and `cc5lnd2s1s4652adtu50`
as the identifier for that thread.
x-go-type: string
type: string
format: xid-prefixed-kebab-case-string
example: 'cc5lnd2s1s4652adtu50-top-10-movies-thread'
CommonProperties:
type: object
required:
- id
- createdAt
- updatedAt
properties:
id: { $ref: '#/components/schemas/Identifier' }
createdAt:
type: string
format: date-time
description: The time the resource was created.
updatedAt:
type: string
format: date-time
description: The time the resource was updated.
deletedAt:
type: string
format: date-time
description: The time the resource was soft-deleted.
misc:
type: object
description: Arbitrary extra data stored with the resource.
APIError:
type: object
description: |
A description of an error including a human readable message and any
related metadata from the request and associated services.
required: [error]
properties:
error:
description: The internal error, not intended for end-user display.
type: string
message:
description: A human-readable message intended for end-user display.
type: string
suggested:
description: A suggested action for the user.
type: string
metadata:
description: Any additional metadata related to the error.
type: object
additionalProperties: true
Metadata:
type: object
additionalProperties: true
description: Arbitrary metadata for the resource.
PaginatedResult:
description: To be composed with paginated resource responses.
type: object
required: [page_size, results, total_pages, current_page]
properties:
page_size:
type: integer
results:
type: integer
total_pages:
type: integer
current_page:
type: integer
next_page:
type: integer
URL:
description: A web address
type: string
format: url
AccountName:
type: string
description: The account owners display name.
example: Barnaby Keene
AccountHandle:
type: string
x-go-type: string
description: The unique @ handle of an account.
example: Southclaws
AccountBio:
type: string
description: The rich-text bio for an account's public profile.
example: <body><p>hi, my name is</p><p>southclaws</p></body>
EmailAddress:
description: A valid email address.
type: string
example: '[email protected]'
ProfileReference:
type: object
description: A minimal reference to an account.
required: [id, joined, handle, name, roles]
properties:
id: { $ref: '#/components/schemas/Identifier' }
joined: { $ref: '#/components/schemas/MemberJoinedDate' }
suspended: { $ref: '#/components/schemas/MemberSuspendedDate' }
handle: { $ref: '#/components/schemas/AccountHandle' }
name: { $ref: '#/components/schemas/AccountName' }
ThreadTitle:
type: string
description: The title of a thread.
example: Hello world!
PostContent:
description: |
The body text of a post within a thread. The type is either a string or
an object, depending on what was used during creation. Strings can be
used for basic plain text or markdown content and objects are used for
more complex types such as Slate.js editor documents.
type: string
RelevanceScore:
description: |
For recommendations and other uses, only available when a Semdex is
configured for content indexing and contextual relativity scoring.
type: number
BeaconProps:
x-go-type: string
description: |
A beacon is a lightweight reference to an object used for tracking
purposes. It contains only the kind and ID of the object. This is mostly
used for tracking read states of threads. But may be used for more.
I should clarify, not the morally questionable kind of "tracking".
type: object
required: [k, id]
properties:
k: { $ref: '#/components/schemas/DatagraphItemKind' }
id:
type: string
description: The identifier for the object related to tracking.
#
# d8888 888 d8b
# d88888 888 Y8P
# d88P888 888
# d88P 888 .d88888 88888b.d88b. 888 88888b.
# d88P 888 d88" 888 888 "888 "88b 888 888 "88b
# d88P 888 888 888 888 888 888 888 888 888
# d8888888888 Y88b 888 888 888 888 888 888 888
# d88P 888 "Y88888 888 888 888 888 888 888
#
AdminSettingsProps:
description: Storyden installation and administration settings.
type: object
required:
- title
- description
- content
- accent_colour
- authentication_mode
properties:
title:
type: string
description:
type: string
content:
$ref: '#/components/schemas/PostContent'
accent_colour:
type: string
authentication_mode:
$ref: '#/components/schemas/AuthMode'
metadata:
$ref: '#/components/schemas/Metadata'
AdminSettingsMutableProps:
type: object
properties:
title:
type: string
description:
type: string
content:
$ref: '#/components/schemas/PostContent'
accent_colour:
type: string
authentication_mode:
$ref: '#/components/schemas/AuthMode'
metadata:
description: |
The settings metadata may be used by frontends to store arbitrary
vendor-specific configuration data specific to the frontend itself.
$ref: '#/components/schemas/Metadata'
#
# 8888888b. 888
# 888 Y88b 888
# 888 888 888
# 888 d88P .d88b. 888 .d88b.
# 8888888P" d88""88b 888 d8P Y8b
# 888 T88b 888 888 888 88888888
# 888 T88b Y88..88P 888 Y8b.
# 888 T88b "Y88P" 888 "Y8888
#
Role:
type: object
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/RoleProps'
RoleListResult:
type: object
required: [roles]
properties:
roles: { $ref: '#/components/schemas/RoleList' }
RoleList:
type: array
items:
$ref: '#/components/schemas/Role'
AccountRole:
type: object
allOf:
- $ref: '#/components/schemas/Role'
- $ref: '#/components/schemas/AccountRoleProps'
AccountRoleList:
type: array
items:
$ref: '#/components/schemas/AccountRole'
AccountRoleProps:
type: object
required: [badge, default]
properties:
badge:
description: |
One role may be designated as a badge for the account. If ture, it
should be displayed prominently on the profile or in other contexts.
type: boolean
default:
description: |
There are two built-in roles: everyone and admin, this boolean flag
is set if this role is one of the default built-in roles.
type: boolean
RoleProps:
type: object
required: [name, colour, permissions]
properties:
name:
type: string
colour:
type: string
permissions:
$ref: '#/components/schemas/PermissionList'
RoleInitialProps:
type: object
required: [name, colour, permissions]
properties:
name:
type: string
colour:
type: string
permissions:
$ref: '#/components/schemas/PermissionList'
RoleMutableProps:
type: object
properties:
name:
type: string
colour:
type: string
permissions:
$ref: '#/components/schemas/PermissionList'
Permission:
type: string
enum:
# Posts (Threads, replies and posts)
- 'CREATE_POST'
- 'READ_PUBLISHED_THREADS'
- 'CREATE_REACTION'
- 'MANAGE_POSTS'
- 'MANAGE_CATEGORIES'
- 'CREATE_INVITATION'
# Library (Page tree nodes)
- 'READ_PUBLISHED_LIBRARY'
- 'MANAGE_LIBRARY'
- 'SUBMIT_LIBRARY_NODE'
# Assets
- 'UPLOAD_ASSET'
# Events
- 'MANAGE_EVENTS'
# Profiles (listing and viewing member profiles)
- 'LIST_PROFILES'
- 'READ_PROFILE'
# Collections
- 'CREATE_COLLECTION'
- 'LIST_COLLECTIONS'
- 'READ_COLLECTION'
- 'MANAGE_COLLECTIONS'
- 'COLLECTION_SUBMIT'
# Personal access keys for automation/MCP
- 'USE_PERSONAL_ACCESS_KEYS'
# Administrative (Settings, bans, etc)
- 'MANAGE_SETTINGS'
- 'MANAGE_SUSPENSIONS'
- 'MANAGE_ROLES'
- 'VIEW_ACCOUNTS'
# Administrator implicitly has all permissions.
- 'ADMINISTRATOR'
PermissionList:
type: array
items:
$ref: '#/components/schemas/Permission'
#
# d8888 888 888
# d88888 888 888
# d88P888 888 888
# d88P 888 888 888 888888 88888b.
# d88P 888 888 888 888 888 "88b
# d88P 888 888 888 888 888 888
# d8888888888 Y88b 888 Y88b. 888 888
# d88P 888 "Y88888 "Y888 888 888
#
AuthProviderList:
type: array
items:
$ref: '#/components/schemas/AuthProvider'
AuthMode:
type: string
enum:
- handle
- email
- phone
AuthProvider:
type: object
required: [provider, name]
properties:
provider:
description: The slug name of the provider.
type: string
name:
description: The human-readable name of the provider.
type: string
link:
description: The hyperlink to render for the user.
type: string
AuthPair:
type: object
required: [identifier, token]
properties:
identifier:
example: 'odin'
type: string
token:
example: 'password'
type: string
AuthEmailPasswordInitialProps:
type: object
required: [email, password]
properties:
email: { $ref: '#/components/schemas/EmailAddress' }
password:
type: string
handle:
$ref: '#/components/schemas/AccountHandle'
AuthEmailPasswordReset:
type: object
required: [email, token_url]
properties:
email: { $ref: '#/components/schemas/EmailAddress' }
token_url:
type: object
required: [url, query]
properties:
url:
description: |
The URL to include in the password reset email. This URL's host
must match the configured Storyden instance's web address value.
type: string
query:
description: |
The query parameters to store the reset token in. This is a
frontend client specific value.
type: string
AuthEmailInitialProps:
type: object
required: [email]
properties:
email: { $ref: '#/components/schemas/EmailAddress' }
handle:
$ref: '#/components/schemas/AccountHandle'
AuthEmailVerifyProps:
type: object
required: [email, code]
properties:
email:
description: |
The email address to be verified, only necessary for when submitting
a verification without a session cookie present.
$ref: '#/components/schemas/EmailAddress'
code:
example: '728562'
type: string
AuthPasswordInitialProps:
type: object
required: [password]
properties:
password:
example: 'password123'
type: string
AuthPasswordMutableProps:
type: object
required: [old, new]
properties:
old:
example: 'password123'
type: string
new:
example: 'password456'
type: string
AuthPasswordResetProps:
type: object
required: [token, new]
properties:
token:
type: string
new:
example: 'password456'
type: string
AuthSuccess:
type: object
required: [id]
properties:
id:
type: string
OAuthCallback:
type: object
required:
- state
- code
properties:
state:
type: string
code:
type: string
WebAuthnPublicKeyCreationOptions:
description: |
https://www.w3.org/TR/webauthn-2/#sctn-credentialcreationoptions-extension
type: object
required: [publicKey]
properties:
publicKey:
$ref: '#/components/schemas/PublicKeyCredentialCreationOptions'
PublicKeyCredentialCreationOptions:
description: |
https://www.w3.org/TR/webautehn-2/#dictdef-publickeycredentialcreationoptions
type: object
required:
- rp
- user
- challenge
- excludeCredentials
- pubKeyCredParams
properties:
rp: { $ref: '#/components/schemas/PublicKeyCredentialRpEntity' }
user: { $ref: '#/components/schemas/PublicKeyCredentialUserEntity' }
challenge:
type: string
pubKeyCredParams:
type: array
items: { $ref: '#/components/schemas/PublicKeyCredentialParameters' }
timeout:
type: integer
excludeCredentials:
type: array
items: { $ref: '#/components/schemas/PublicKeyCredentialDescriptor' }
authenticatorSelection:
{ $ref: '#/components/schemas/AuthenticatorSelectionCriteria' }
attestation:
{ $ref: '#/components/schemas/AttestationConveyancePreference' }
extensions:
{ $ref: '#/components/schemas/AuthenticationExtensionsClientInputs' }
PublicKeyCredentialRpEntity:
description: |
https://www.w3.org/TR/webauthn-2/#dictdef-publickeycredentialrpentity
type: object
required: [name, id]
properties:
id:
type: string
name:
type: string
PublicKeyCredentialUserEntity:
description: |
https://www.w3.org/TR/webauthn-2/#dictdef-publickeycredentialuserentity
type: object
required: [id, name, displayName]
properties:
id:
type: string
name:
type: string
displayName:
type: string
PublicKeyCredentialParameters:
description: |
https://www.w3.org/TR/webauthn-2/#dictdef-publickeycredentialparameters
type: object
required: [type, alg]
properties:
type:
$ref: '#/components/schemas/PublicKeyCredentialType'
alg:
type: number
PublicKeyCredentialType:
description: |
https://www.w3.org/TR/webauthn-2/#enumdef-publickeycredentialtype
type: string
enum: [public-key]
PublicKeyCredentialDescriptor:
description: |
https://www.w3.org/TR/webauthn-2/#dictdef-publickeycredentialdescriptor
type: object
required: [type, id]
properties:
type:
$ref: '#/components/schemas/PublicKeyCredentialType'
id:
type: string
transports:
type: array
items:
type: string
enum: ['ble', 'internal', 'nfc', 'usb', 'cable', 'hybrid']
AuthenticatorSelectionCriteria:
description: |
https://www.w3.org/TR/webauthn-2/#dictdef-authenticatorselectioncriteria
type: object
required:
- authenticatorAttachment
- residentKey
properties:
authenticatorAttachment:
$ref: '#/components/schemas/AuthenticatorAttachment'
residentKey:
$ref: '#/components/schemas/ResidentKeyRequirement'
requireResidentKey:
type: boolean
userVerification:
$ref: '#/components/schemas/UserVerificationRequirement'
AuthenticatorAttachment:
description: |
https://www.w3.org/TR/webauthn-2/#enumdef-authenticatorattachment
type: string
enum: [platform, cross-platform]
ResidentKeyRequirement:
description: |
https://www.w3.org/TR/webauthn-2/#enumdef-residentkeyrequirement
type: string
enum:
- discouraged
- preferred
- required
UserVerificationRequirement:
description: |
https://www.w3.org/TR/webauthn-2/#enumdef-userverificationrequirement
type: string
default: preferred
enum:
- discouraged
- preferred
- required
AttestationConveyancePreference:
description: |
https://www.w3.org/TR/webauthn-2/#enum-attestation-convey
type: string
enum:
- direct
- enterprise
- indirect
- none
AuthenticationExtensionsClientInputs:
description: |
https://www.w3.org/TR/webauthn-2/#dictdef-authenticationextensionsclientinputs
type: object
additionalProperties: true
PublicKeyCredential:
description: |
https://www.w3.org/TR/webauthn-2/#iface-pkcredential
type: object
required:
- id
- rawId
- response
- type
properties:
id:
type: string
rawId:
type: string
response: { $ref: '#/components/schemas/AuthenticatorResponse' }
type:
type: string
clientExtensionResults:
type: object
authenticatorAttachment:
type: string
AuthenticatorResponse:
description: |
https://www.w3.org/TR/webauthn-2/#authenticatorresponse
type: object
required: [clientDataJSON]
properties:
clientDataJSON:
type: string
attestationObject:
type: string
transports:
type: array
items:
type: string
authenticatorData:
type: string
signature:
type: string
userHandle:
type: string
CredentialRequestOptions:
description: |
https://www.w3.org/TR/webauthn-2/#sctn-credentialrequestoptions-extension
type: object
required: [publicKey]
properties:
publicKey:
$ref: '#/components/schemas/PublicKeyCredentialRequestOptions'
PublicKeyCredentialRequestOptions:
description: |
https://www.w3.org/TR/webauthn-2/#dictdef-publickeycredentialrequestoptions
type: object
required: [challenge]
properties:
challenge:
type: string
timeout:
type: integer
rpId:
type: string
allowCredentials:
type: array
items:
$ref: '#/components/schemas/PublicKeyCredentialDescriptor'
userVerification:
type: string
enum: ['discouraged', 'preferred', 'required']
PhoneRequestCodeProps:
description: The phone number request payload.
type: object
required: [identifier, phone_number]
properties:
identifier:
description: The desired username to link to the phone number.
example: 'southclaws'
type: string
phone_number:
description: The phone number to receive the one-time code on.
type: string
PhoneSubmitCodeProps:
description: The Phone submit code payload.
type: object
required: [code]
properties:
code:
type: string
AccessKey:
type: object
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/AccessKeyProps'
OwnedAccessKey:
description: |
An owned access key is a key that has been already issued to an account,
it is used specifically for administrator listing of all access keys
where it's necessary to include the account that created the key.
type: object
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/AccessKeyProps'
- required: [created_by]
properties:
created_by: { $ref: '#/components/schemas/ProfileReference' }
AccessKeyIssued:
description: |
An access key issued to an account, this is the full access key object
including the secret. This is only exposed upon creation of the key and
the secret value is never stored. The caller that receives this object
is responsible for securely storing the secret value for later use.
type: object
allOf:
- $ref: '#/components/schemas/AccessKey'
- $ref: '#/components/schemas/AccessKeySecret'
AccessKeyProps:
type: object
required: [name, enabled]
properties:
name:
description: The name of the access key.
type: string
enabled:
type: boolean
expires_at:
type: string
format: date-time
description: When the access key expires, if null, it never expires.
AccessKeyInitialProps:
type: object
required: [name]
properties:
name:
description: The name of the access key.
type: string
expires_at:
type: string
format: date-time
description: When the access key expires, if null, it never expires.
AccessKeySecret:
type: object
required: [secret]
properties:
secret:
description: |
The secret key used to authenticate with the API.
Keys are prefixed with a kind identifier, "sdpak" refers to a
Storyden Personal Access Key and "sdbak" refers to a Storyden
Bot Access Key. The two kinds are not interchangeable however they
do not have behavioural differences and is merely a visual cue.
type: string
example: 'sdpak_a1b2c3d4cfc00d429ba841f9425c62f82341381b'
AccessKeyList:
type: array
items: { $ref: '#/components/schemas/AccessKey' }
AccessKeyListResult:
type: object
required: [keys]
properties:
keys: { $ref: '#/components/schemas/AccessKeyList' }
OwnedAccessKeyList:
type: array
items: { $ref: '#/components/schemas/OwnedAccessKey' }
OwnedAccessKeyListResult:
type: object
required: [keys]
properties:
keys: { $ref: '#/components/schemas/OwnedAccessKeyList' }
#
# d8888 888
# d88888 888
# d88P888 888
# d88P 888 .d8888b .d8888b .d88b. 888 888 88888b. 888888
# d88P 888 d88P" d88P" d88""88b 888 888 888 "88b 888
# d88P 888 888 888 888 888 888 888 888 888 888
# d8888888888 Y88b. Y88b. Y88..88P Y88b 888 888 888 Y88b.
# d88P 888 "Y8888P "Y8888P "Y88P" "Y88888 888 888 "Y888
#
Account:
type: object
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/AccountCommonProps'
AccountCommonProps:
required:
[
joined,
handle,
name,
roles,
bio,
links,
meta,
verified_status,
email_addresses,
admin,
]
properties:
joined: { $ref: '#/components/schemas/MemberJoinedDate' }
suspended: { $ref: '#/components/schemas/MemberSuspendedDate' }
handle:
$ref: '#/components/schemas/AccountHandle'
name:
$ref: '#/components/schemas/AccountName'
roles:
$ref: '#/components/schemas/AccountRoleList'
bio:
$ref: '#/components/schemas/AccountBio'
links:
$ref: '#/components/schemas/ProfileExternalLinkList'
meta:
$ref: '#/components/schemas/Metadata'
verified_status:
$ref: '#/components/schemas/AccountVerifiedStatus'
email_addresses:
$ref: '#/components/schemas/AccountEmailAddressList'
notifications:
$ref: '#/components/schemas/NotificationCount'
admin:
type: boolean
invited_by:
$ref: '#/components/schemas/ProfileReference'
AccountMutableProps:
type: object
properties:
handle:
$ref: '#/components/schemas/AccountHandle'
name:
$ref: '#/components/schemas/AccountName'
bio:
$ref: '#/components/schemas/AccountBio'
interests:
$ref: '#/components/schemas/TagNameList'
links:
$ref: '#/components/schemas/ProfileExternalLinkList'
meta:
$ref: '#/components/schemas/Metadata'
AccountAuthMethods:
type: object
required: [active, available]
properties:
active: { $ref: '#/components/schemas/AccountAuthMethodList' }
available: { $ref: '#/components/schemas/AuthProviderList' }
AccountAuthMethodList:
type: array
items: { $ref: '#/components/schemas/AccountAuthMethod' }
AccountAuthMethod:
description: |
An authentication method is an active instance of an authentication
provider associated with an account. Use this to display a user's active
authentication methods so they can edit or remove it.
type: object
required: [id, created_at, name, identifier, provider]
properties:
id:
description: The internal unique ID this method has.
type: string
created_at:
type: string
format: date-time
description: When this auth method was registered to the account.
name:
description: The personal name given to the method.
type: string
identifier:
description: The external identifier (third party ID or device ID)
type: string
provider: { $ref: '#/components/schemas/AuthProvider' }
AccountVerifiedStatus:
type: string
enum: [none, verified_email]
AccountEmailAddressList:
description: |
If the instance is configured to not use any email features for auth or
transactional/content communications, this will always be empty.
type: array
items: { $ref: '#/components/schemas/AccountEmailAddress' }
AccountEmailAddress:
type: object
required: [id, email_address, verified]
properties:
id: { $ref: '#/components/schemas/Identifier' }
email_address: { $ref: '#/components/schemas/EmailAddress' }
verified:
description: Is the email address verified to be owned by the account?
type: boolean
AccountEmailInitialProps:
type: object
required: [email_address]
properties:
email_address: { $ref: '#/components/schemas/EmailAddress' }
#
# 8888888 d8b 888 888 d8b
# 888 Y8P 888 888 Y8P
# 888 888 888
# 888 88888b. 888 888 888 888888 8888b. 888888 888 .d88b. 88888b.
# 888 888 "88b 888 888 888 888 "88b 888 888 d88""88b 888 "88b
# 888 888 888 Y88 88P 888 888 .d888888 888 888 888 888 888 888
# 888 888 888 Y8bd8P 888 Y88b. 888 888 Y88b. 888 Y88..88P 888 888
# 8888888 888 888 Y88P 888 "Y888 "Y888888 "Y888 888 "Y88P" 888 888
#
Invitation:
type: object
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/InvitationProps'
InvitationList:
type: array
items: { $ref: '#/components/schemas/Invitation' }
InvitationListResult:
type: object
allOf:
- { $ref: '#/components/schemas/PaginatedResult' }
- type: object
required: [invitations]
properties:
invitations: { $ref: '#/components/schemas/InvitationList' }
InvitationProps:
type: object
required: [creator]
properties:
creator: { $ref: '#/components/schemas/ProfileReference' }
message:
type: string
InvitationInitialProps:
type: object
properties:
message:
type: string
#
# 888b 888 888 d8b .d888 d8b 888 d8b
# 8888b 888 888 Y8P d88P" Y8P 888 Y8P
# 88888b 888 888 888 888
# 888Y88b 888 .d88b. 888888 888 888888 888 .d8888b 8888b. 888888 888 .d88b. 88888b.
# 888 Y88b888 d88""88b 888 888 888 888 d88P" "88b 888 888 d88""88b 888 "88b
# 888 Y88888 888 888 888 888 888 888 888 .d888888 888 888 888 888 888 888
# 888 Y8888 Y88..88P Y88b. 888 888 888 Y88b. 888 888 Y88b. 888 Y88..88P 888 888
# 888 Y888 "Y88P" "Y888 888 888 888 "Y8888P "Y888888 "Y888 888 "Y88P" 888 888
#
Notification:
type: object
required: [id, created_at, event, status]
properties:
id: { $ref: '#/components/schemas/Identifier' }
created_at:
type: string
format: date-time
description: The time the resource was created.
event: { $ref: '#/components/schemas/NotificationEvent' }
item: { $ref: '#/components/schemas/DatagraphItem' }
source: { $ref: '#/components/schemas/ProfileReference' }
status: { $ref: '#/components/schemas/NotificationStatus' }
NotificationMutableProps:
type: object
properties:
status: { $ref: '#/components/schemas/NotificationStatus' }
NotificationList:
type: array
items: { $ref: '#/components/schemas/Notification' }
NotificationListResult:
type: object
allOf:
- { $ref: '#/components/schemas/PaginatedResult' }
- type: object
required: [notifications]
properties:
notifications: { $ref: '#/components/schemas/NotificationList' }
NotificationEvent:
description: |
The kind of event that triggered the notification.
Identical to the `notification.Event` enumerated type.
type: string
enum: [thread_reply, post_like, follow, profile_mention]
NotificationStatus:
type: string
enum: [unread, read]
NotificationStatusList:
type: array
items: { $ref: '#/components/schemas/NotificationStatus' }
NotificationCount:
type: integer
#
# 8888888b. .d888 d8b 888
# 888 Y88b d88P" Y8P 888
# 888 888 888 888
# 888 d88P 888d888 .d88b. 888888 888 888 .d88b.
# 8888888P" 888P" d88""88b 888 888 888 d8P Y8b
# 888 888 888 888 888 888 888 88888888
# 888 888 Y88..88P 888 888 888 Y8b.
# 888 888 "Y88P" 888 888 888 "Y8888
#
PublicProfile:
type: object
allOf:
- $ref: '#/components/schemas/CommonProperties'
- required:
- createdAt
- joined
- handle
- name
- roles
- bio
- followers
- following
- like_score
- interests
- links
- meta
properties:
createdAt:
deprecated: true
type: string
joined: { $ref: '#/components/schemas/MemberJoinedDate' }
suspended: { $ref: '#/components/schemas/MemberSuspendedDate' }
handle:
$ref: '#/components/schemas/AccountHandle'
name:
$ref: '#/components/schemas/AccountName'
roles:
$ref: '#/components/schemas/AccountRoleList'
bio:
$ref: '#/components/schemas/AccountBio'
image:
type: string
followers:
$ref: '#/components/schemas/ProfileFollowersCount'
following:
$ref: '#/components/schemas/ProfileFollowingCount'
like_score:
$ref: '#/components/schemas/LikeScore'
interests:
$ref: '#/components/schemas/TagReferenceList'
links:
$ref: '#/components/schemas/ProfileExternalLinkList'
invited_by:
$ref: '#/components/schemas/ProfileReference'
meta:
$ref: '#/components/schemas/Metadata'
PublicProfileFollowersResult:
allOf:
- { $ref: '#/components/schemas/PaginatedResult' }
- type: object
required: [followers]
properties:
followers: { $ref: '#/components/schemas/ProfileFollowersList' }
PublicProfileFollowingResult:
allOf:
- { $ref: '#/components/schemas/PaginatedResult' }
- type: object
required: [following]
properties:
following: { $ref: '#/components/schemas/ProfileFollowingList' }
ProfileExternalLinkList:
type: array
items:
$ref: '#/components/schemas/ProfileExternalLink'
ProfileExternalLink:
type: object
required: [text, url]
properties:
text:
type: string
url:
type: string
PublicProfileListResult:
allOf:
- { $ref: '#/components/schemas/PaginatedResult' }
- type: object
required: [profiles]
properties:
profiles: { $ref: '#/components/schemas/PublicProfileList' }
PublicProfileList:
type: array
items: { $ref: '#/components/schemas/PublicProfile' }
ProfileFollowersList:
type: array
items: { $ref: '#/components/schemas/ProfileReference' }
ProfileFollowingList:
type: array
items: { $ref: '#/components/schemas/ProfileReference' }
ProfileFollowersCount:
type: integer
ProfileFollowingCount:
type: integer
MemberJoinedDate:
type: string
format: date-time
description: The time the resource was created.
MemberSuspendedDate:
type: string
format: date-time
description: The time the resource was created.
#
# .d8888b. 888
# d88P Y88b 888
# 888 888 888
# 888 8888b. 888888 .d88b. .d88b. .d88b. 888d888 888 888
# 888 "88b 888 d8P Y8b d88P"88b d88""88b 888P" 888 888
# 888 888 .d888888 888 88888888 888 888 888 888 888 888 888
# Y88b d88P 888 888 Y88b. Y8b. Y88b 888 Y88..88P 888 Y88b 888
# "Y8888P" "Y888888 "Y888 "Y8888 "Y88888 "Y88P" 888 "Y88888
# 888 888
# Y8b d88P Y8b d88P
# "Y88P" "Y88P"
#
Category:
type: object
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/CategoryCommonProps'
- $ref: '#/components/schemas/CategoryAdditional'
CategoryReference:
type: object
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/CategoryCommonProps'
CategoryCommonProps:
type: object
required: [name, slug, description, colour, sort, children]
properties:
name:
$ref: '#/components/schemas/CategoryName'
slug:
$ref: '#/components/schemas/CategorySlug'
description:
type: string
colour:
type: string
sort:
type: integer
parent:
$ref: '#/components/schemas/Identifier'
description: Parent category identifier. Unset indicates a root-level category.
cover_image:
$ref: '#/components/schemas/Asset'
children: { $ref: '#/components/schemas/CategoryList' }
meta: { $ref: '#/components/schemas/Metadata' }
CategoryInitialProps:
type: object
required: [name, description, colour]
properties:
name:
$ref: '#/components/schemas/CategoryName'
slug:
$ref: '#/components/schemas/CategorySlug'
description:
type: string
colour:
type: string
parent:
$ref: '#/components/schemas/Identifier'
description: Parent category identifier. Unset indicates a root-level category.
cover_image_asset_id: { $ref: '#/components/schemas/Identifier' }
meta: { $ref: '#/components/schemas/Metadata' }
CategoryMutableProps:
type: object
properties:
name:
$ref: '#/components/schemas/CategoryName'
slug:
$ref: '#/components/schemas/CategorySlug'
description:
type: string
colour:
type: string
cover_image_asset_id:
allOf:
- $ref: '#/components/schemas/NullableIdentifier'
nullable: true
description: Optional cover image asset identifier for the category.
meta: { $ref: '#/components/schemas/Metadata' }
CategoryDeleteProps:
type: object
required: [move_to]
properties:
move_to:
$ref: '#/components/schemas/Identifier'
description: Category ID to move all posts to before deleting this category.
CategoryName:
description: A category's user-facing name.
type: string
CategorySlug:
description: A category's URL-safe slug.
type: string
CategorySlugList:
description: A list of category names.
type: array
items:
$ref: '#/components/schemas/CategorySlug'
CategoryAdditional:
type: object
required: [postCount]
properties:
postCount:
type: integer
CategoryList:
type: array
items: { $ref: '#/components/schemas/Category' }
CategoryListResult:
type: object
required: [categories]
properties:
categories:
$ref: '#/components/schemas/CategoryList'
CategoryPositionMutableProps:
type: object
description: |
Parameters for repositioning a category in the hierarchy. Update the
parent using `parent`, and/or reposition among siblings using `before`
or `after`. Using both `before` and `after` is not allowed.
properties:
parent:
$ref: '#/components/schemas/NullableIdentifier'
description: Optional new parent category identifier. Set to null to move to the root level.
before:
$ref: '#/components/schemas/Identifier'
description: Move this category before the sibling with this identifier.
after:
$ref: '#/components/schemas/Identifier'
description: Move this category after the sibling with this identifier.
#
# 88888888888
# 888
# 888
# 888 8888b. .d88b.
# 888 "88b d88P"88b
# 888 .d888888 888 888
# 888 888 888 Y88b 888
# 888 "Y888888 "Y88888
# 888
# Y8b d88P
# "Y88P"
#
Tag:
type: object
description: |
A tag is a label that can be applied to posts or pages to organise
related content. They can be used to filter and search for content.
The Tag schema provides all the data for a tag including its items, so
it's quite a heavy object if referencing a lot of items. For a lighter
weight version, use a TagReference for use-cases such as tag searches.
allOf:
- $ref: '#/components/schemas/TagReferenceProps'
- $ref: '#/components/schemas/TagProps'
TagReference:
description: |
A minimal representation of a tag for use in most contexts where you
don't need the full list of items associated with the tag.
type: object
allOf:
- $ref: '#/components/schemas/TagReferenceProps'
TagProps:
type: object
required: [id, items]
properties:
id: { $ref: '#/components/schemas/Identifier' }
items: { $ref: '#/components/schemas/DatagraphItemList' }
TagReferenceProps:
type: object
required: [name, colour, item_count]
properties:
name: { $ref: '#/components/schemas/TagName' }
colour: { $ref: '#/components/schemas/TagColour' }
item_count: { $ref: '#/components/schemas/TagItemCount' }
TagName:
type: string
description: The name of a tag.
TagColour:
type: string
description: The colour of a tag.
TagItemCount:
type: integer
description: The number of items tagged with this tag.
TagReferenceList:
type: array
description: A list of tags.
items: { $ref: '#/components/schemas/TagReference' }
TagNameList:
type: array
items: { $ref: '#/components/schemas/TagName' }
TagListIDs:
type: array
description: A list of tags IDs.
items: { $ref: '#/components/schemas/Identifier' }
TagListResult:
type: object
required: [tags]
properties:
tags: { $ref: '#/components/schemas/TagReferenceList' }
#
# 8888888b. 888
# 888 Y88b 888
# 888 888 888
# 888 d88P .d88b. .d8888b 888888
# 8888888P" d88""88b 88K 888
# 888 888 888 "Y8888b. 888
# 888 Y88..88P X88 Y88b.
# 888 "Y88P" 88888P' "Y888
#
Post:
type: object
description: |
A post represents a temporal piece of content, it can be a thread, or a
reply to a thread or something else such as a blog, announcement, etc.
Post is used in generic use-cases where it may not matter whether you
want a thread or a reply, such as search results or recommendations.
allOf:
- { $ref: '#/components/schemas/CommonProperties' }
- { $ref: '#/components/schemas/PostReferenceProps' }
- { $ref: '#/components/schemas/PostProps' }
PostReference:
description: |
A minimal object used to refer to a post without providing a lot of
unnecessary data such as the full content or child items.
type: object
allOf:
- { $ref: '#/components/schemas/CommonProperties' }
- { $ref: '#/components/schemas/PostReferenceProps' }
PostProps:
description: |
The general properties required for any post-like resource. Is composed
with Threads or Replies to provide the basic common properties.
type: object
required: [body, body_links]
properties:
body: { $ref: '#/components/schemas/PostContent' }
body_links: { $ref: '#/components/schemas/LinkReferenceList' }
PostReferenceProps:
type: object
required: [title, slug, author, assets, reacts, collections, likes]
properties:
title: { $ref: '#/components/schemas/ThreadTitle' }
description: { $ref: '#/components/schemas/PostDescription' }
slug: { $ref: '#/components/schemas/ThreadMark' }
author: { $ref: '#/components/schemas/ProfileReference' }
assets: { $ref: '#/components/schemas/AssetList' }
reacts: { $ref: '#/components/schemas/ReactList' }
collections: { $ref: '#/components/schemas/CollectionStatus' }
likes: { $ref: '#/components/schemas/LikeData' }
meta: { $ref: '#/components/schemas/Metadata' }
PostReferenceList:
type: array
items: { $ref: '#/components/schemas/PostReference' }
PostMutableProps:
type: object
properties:
body: { $ref: '#/components/schemas/PostContent' }
meta: { $ref: '#/components/schemas/Metadata' }
url: { $ref: '#/components/schemas/URL' }
PostDescription:
type: string
description: A short version of the post's body text for use in previews.
#
# 88888888888 888 888
# 888 888 888
# 888 888 888
# 888 88888b. 888d888 .d88b. 8888b. .d88888
# 888 888 "88b 888P" d8P Y8b "88b d88" 888
# 888 888 888 888 88888888 .d888888 888 888
# 888 888 888 888 Y8b. 888 888 Y88b 888
# 888 888 888 888 "Y8888 "Y888888 "Y88888
#
Thread:
allOf:
- $ref: '#/components/schemas/ThreadReference'
- $ref: '#/components/schemas/DatagraphRecommendations'
- type: object
required: [replies]
properties:
replies: { $ref: '#/components/schemas/PaginatedReplyList' }
ThreadInitialProps:
type: object
required: [title]
properties:
title: { $ref: '#/components/schemas/ThreadTitle' }
body: { $ref: '#/components/schemas/PostContent' }
tags: { $ref: '#/components/schemas/TagNameList' }
meta: { $ref: '#/components/schemas/Metadata' }
category: { $ref: '#/components/schemas/Identifier' }
visibility: { $ref: '#/components/schemas/Visibility' }
url: { $ref: '#/components/schemas/URL' }
ThreadMutableProps:
type: object
properties:
title: { $ref: '#/components/schemas/ThreadTitle' }
body: { $ref: '#/components/schemas/PostContent' }
tags: { $ref: '#/components/schemas/TagNameList' }
meta: { $ref: '#/components/schemas/Metadata' }
category: { $ref: '#/components/schemas/Identifier' }
visibility: { $ref: '#/components/schemas/Visibility' }
url: { $ref: '#/components/schemas/URL' }
ThreadReference:
type: object
description: |
A thread reference includes most of the information about a thread but
does not include the posts within the thread. Useful for rendering large
lists of threads or other situations when you don't need the full data.
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/PostReferenceProps'
- $ref: '#/components/schemas/PostProps'
- $ref: '#/components/schemas/ThreadReferenceProps'
ThreadReferenceProps:
type: object
required:
- pinned
- visibility
- tags
- reply_status
- collections
properties:
pinned:
type: boolean
description: Whether the thread is pinned in this category.
visibility: { $ref: '#/components/schemas/Visibility' }
read_status: { $ref: '#/components/schemas/ReadStatus' }
reply_status: { $ref: '#/components/schemas/ReplyStatus' }
category: { $ref: '#/components/schemas/CategoryReference' }
link: { $ref: '#/components/schemas/LinkReference' }
tags: { $ref: '#/components/schemas/TagReferenceList' }
last_reply_at:
type: string
format: date-time
description: The time of the last reply to the thread.
ReadStatus:
description: |
Information about the read status of a thread for the requesting
authenticated user. If the user is not authenticated or they have not
read the thread before, this will not be included in the Thread object.
type: object
required: [last_read_at, replies_since]
properties:
last_read_at:
type: string
format: date-time
description: |
When requested by an authenticated account, shows the last time they
last read the thread at.
replies_since:
type: integer
description: |
When requested by an authenticated account, shows the number of new
replies since they last read the thread.
ReplyStatus:
type: object
required: [replies, replied]
properties:
replies:
description: The total number of replies to the thread.
type: integer
replied:
description: |
If requested by an authenticated account, the number of replies that
were made by that account to the thread.
type: integer
ThreadList:
type: array
items:
$ref: '#/components/schemas/ThreadReference'
ThreadListResult:
allOf:
- { $ref: '#/components/schemas/PaginatedResult' }
- type: object
required: [threads]
properties:
threads: { $ref: '#/components/schemas/ThreadList' }
#
# 8888888b. 888
# 888 Y88b 888
# 888 888 888
# 888 d88P .d88b. 88888b. 888 888 888
# 8888888P" d8P Y8b 888 "88b 888 888 888
# 888 T88b 88888888 888 888 888 888 888
# 888 T88b Y8b. 888 d88P 888 Y88b 888
# 888 T88b "Y8888 88888P" 888 "Y88888
# 888 888
# 888 Y8b d88P
# 888 "Y88P"
#
Reply:
type: object
description: |
A new post within a thread of posts. A post may reply to another post in
the thread by specifying the `reply_to` property. The identifier in the
`reply_to` value must be post within the same thread.
allOf:
- { $ref: '#/components/schemas/CommonProperties' }
- { $ref: '#/components/schemas/PostReferenceProps' }
- { $ref: '#/components/schemas/PostProps' }
- { $ref: '#/components/schemas/ReplyProps' }
PaginatedReplyList:
allOf:
- $ref: '#/components/schemas/PaginatedResult'
- type: object
required: [replies]
properties:
replies: { $ref: '#/components/schemas/ReplyList' }
ReplyList:
type: array
items: { $ref: '#/components/schemas/Reply' }
ReplyProps:
type: object
required: [root_id, root_slug]
properties:
root_id: { $ref: '#/components/schemas/Identifier' }
root_slug: { $ref: '#/components/schemas/ThreadMark' }
reply_to: { $ref: '#/components/schemas/Identifier' }
ReplyInitialProps:
type: object
required: [body]
properties:
body: { $ref: '#/components/schemas/PostContent' }
meta: { $ref: '#/components/schemas/Metadata' }
reply_to: { $ref: '#/components/schemas/Identifier' }
url: { $ref: '#/components/schemas/URL' }
#
# 8888888b. 888
# 888 Y88b 888
# 888 888 888
# 888 d88P .d88b. 8888b. .d8888b 888888
# 8888888P" d8P Y8b "88b d88P" 888
# 888 T88b 88888888 .d888888 888 888
# 888 T88b Y8b. 888 888 Y88b. Y88b.
# 888 T88b "Y8888 "Y888888 "Y8888P "Y888
#
React:
type: object
required: [id, emoji, author]
properties:
id: { $ref: '#/components/schemas/Identifier' }
emoji: { $ref: '#/components/schemas/ReactEmoji' }
author: { $ref: '#/components/schemas/ProfileReference' }
ReactInitialProps:
description: Reactions are currently just simple emoji characters.
type: object
required: [emoji]
properties:
emoji: { $ref: '#/components/schemas/ReactEmoji' }
ReactList:
description: A list of reactions this post has had from people.
type: array
items: { $ref: '#/components/schemas/React' }
ReactEmoji:
description: |
A single emoji character representing a reaction. In future, this will
be augmented with a more fully fledged custom emoji system.
type: string
#
# 888b d888 888 d8b
# 8888b d8888 888 Y8P
# 88888b.d88888 888
# 888Y88888P888 .d88b. .d88888 888 8888b.
# 888 Y888P 888 d8P Y8b d88" 888 888 "88b
# 888 Y8P 888 88888888 888 888 888 .d888888
# 888 " 888 Y8b. Y88b 888 888 888 888
# 888 888 "Y8888 "Y88888 888 "Y888888
#
AssetID:
$ref: '#/components/schemas/Identifier'
AssetIDs:
type: array
items: { $ref: '#/components/schemas/AssetID' }
AssetList:
type: array
items: { $ref: '#/components/schemas/Asset' }
Asset:
type: object
required: [id, filename, path, mime_type, width, height]
properties:
id:
$ref: '#/components/schemas/AssetID'
filename:
type: string
path:
description: |
The API path of the asset, conforms to the schema's GET `/assets`.
type: string
mime_type:
type: string
width:
type: number
height:
type: number
# NOTE: Presence is dictated by the callee, not the API (currently.)
parent: { $ref: '#/components/schemas/Asset' }
AssetSourceURL:
description:
An asset source URL holds the address of an off-platform media asset
which is not hosted on a Storyden instance. It may represent a source
URL for an intended download or an asset which is stored elsewhere.
type: string
AssetSourceList:
type: array
items: { $ref: '#/components/schemas/AssetSourceURL' }
#
# 888 d8b 888
# 888 Y8P 888
# 888 888
# 888 888 888 888 .d88b.
# 888 888 888 .88P d8P Y8b
# 888 888 888888K 88888888
# 888 888 888 "88b Y8b.
# 88888888 888 888 888 "Y8888
#
ItemLike:
description: A like on an item, contains the owner only.
type: object
allOf:
- $ref: '#/components/schemas/LikeProps'
- required: [owner]
properties:
owner: { $ref: '#/components/schemas/ProfileReference' }
ItemLikeList:
type: array
items: { $ref: '#/components/schemas/ItemLike' }
ProfileLike:
description: A like on an item, contains the item only.
type: object
allOf:
- $ref: '#/components/schemas/LikeProps'
- required: [item]
properties:
item: { $ref: '#/components/schemas/DatagraphItem' }
ProfileLikeList:
type: array
items: { $ref: '#/components/schemas/ProfileLike' }
LikeProps:
type: object
required: [id, created_at]
properties:
id: { $ref: '#/components/schemas/Identifier' }
created_at:
type: string
format: date-time
ProfileLikeListResult:
allOf:
- $ref: '#/components/schemas/PaginatedResult'
- type: object
required: [likes]
properties:
likes: { $ref: '#/components/schemas/ProfileLikeList' }
LikeData:
type: object
required: [likes, liked]
properties:
likes: { $ref: '#/components/schemas/LikeCount' }
liked: { $ref: '#/components/schemas/LikeStatus' }
LikeCount:
description: |
A simple count of likes for contexts where pulling the full list would
be overkill. For use on minimal item reference schemas.
type: integer
LikeScore:
description: The total number of likes received by a member.
type: integer
LikeStatus:
description: |
A boolean indicating if the account in context has liked this item.
type: boolean
#
# .d8888b. 888 888 888 d8b
# d88P Y88b 888 888 888 Y8P
# 888 888 888 888 888
# 888 .d88b. 888 888 .d88b. .d8888b 888888 888 .d88b. 88888b.
# 888 d88""88b 888 888 d8P Y8b d88P" 888 888 d88""88b 888 "88b
# 888 888 888 888 888 888 88888888 888 888 888 888 888 888 888
# Y88b d88P Y88..88P 888 888 Y8b. Y88b. Y88b. 888 Y88..88P 888 888
# "Y8888P" "Y88P" 888 888 "Y8888 "Y8888P "Y888 888 "Y88P" 888 888
#
Collection:
description: |
A collection is a group of threads owned by a user. It allows users to
curate their own lists of content from the site. Collections can only
contain root level posts (threads) with titles and slugs to link to.
type: object
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/CollectionCommonProps'
- $ref: '#/components/schemas/CollectionAdditionalProps'
CollectionWithItems:
description: |
The full properties of a collection, for rendering a single collection
somewhere where you can afford to show all the items in the collection.
type: object
required: [items]
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/CollectionCommonProps'
- required: [items]
properties:
items: { $ref: '#/components/schemas/CollectionItemList' }
CollectionCommonProps:
description: A reference to the collection
type: object
required: [name, slug, owner]
properties:
name: { $ref: '#/components/schemas/CollectionName' }
slug: { $ref: '#/components/schemas/CollectionSlug' }
description: { $ref: '#/components/schemas/CollectionDescription' }
owner: { $ref: '#/components/schemas/ProfileReference' }
CollectionAdditionalProps:
type: object
required: [item_count, has_queried_item]
properties:
item_count:
type: integer
has_queried_item:
type: boolean
CollectionList:
type: array
items: { $ref: '#/components/schemas/Collection' }
CollectionInitialProps:
type: object
required: [name]
properties:
name: { $ref: '#/components/schemas/CollectionName' }
slug: { $ref: '#/components/schemas/CollectionSlug' }
description: { $ref: '#/components/schemas/CollectionDescription' }
CollectionMutableProps:
type: object
properties:
name: { $ref: '#/components/schemas/CollectionName' }
slug: { $ref: '#/components/schemas/CollectionSlug' }
description: { $ref: '#/components/schemas/CollectionDescription' }
CollectionItemList:
type: array
items: { $ref: '#/components/schemas/CollectionItem' }
CollectionItem:
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/CollectionItemMetadata'
- required: [item]
properties:
item: { $ref: '#/components/schemas/DatagraphItem' }
CollectionItemMetadata:
type: object
required: [owner, added_at, membership_type]
properties:
owner:
$ref: '#/components/schemas/ProfileReference'
added_at:
type: string
format: date-time
description: The time that the item was added to the collection.
membership_type:
$ref: '#/components/schemas/CollectionItemMembershipType'
relevance_score:
$ref: '#/components/schemas/RelevanceScore'
CollectionItemMembershipType:
type: string
enum: [normal, submission_review, submission_accepted]
CollectionStatus:
type: object
required: [in_collections, has_collected]
properties:
in_collections: { $ref: '#/components/schemas/CollectionCount' }
has_collected: { $ref: '#/components/schemas/HasCollected' }
CollectionCount:
description: How many collections has this item been added to?
type: integer
HasCollected:
description: |
A boolean indicating if the account in context has collected this item.
type: boolean
CollectionName:
type: string
CollectionSlug:
$ref: '#/components/schemas/Mark'
CollectionDescription:
type: string
#
# 888b 888 888
# 8888b 888 888
# 88888b 888 888
# 888Y88b 888 .d88b. .d88888 .d88b.
# 888 Y88b888 d88""88b d88" 888 d8P Y8b
# 888 Y88888 888 888 888 888 88888888
# 888 Y8888 Y88..88P Y88b 888 Y8b.
# 888 Y888 "Y88P" "Y88888 "Y8888
#
Node:
description: |
A node is a text document with children and assets. It serves as an
abstraction for grouping structured data objects. It can represent
things such as brands, manufacturers, authors, directors, etc. Nodes
can be referenced in content posts and they also have their own content.
type: object
allOf:
- $ref: '#/components/schemas/CommonProperties'
- $ref: '#/components/schemas/NodeCommonProps'
NodeWithChildren:
description: |
The full properties of a node including all child nodes.
type: object
required: [children]
allOf:
- $ref: '#/components/schemas/Node'
- $ref: '#/components/schemas/DatagraphRecommendations'
- required: [properties, child_property_schema, children]
properties:
properties: { $ref: '#/components/schemas/PropertyList' }
child_property_schema:
$ref: '#/components/schemas/PropertySchemaList'
children:
type: array
items: { $ref: '#/components/schemas/NodeWithChildren' }
NodeName:
type: string
NodeSlug:
$ref: '#/components/schemas/Slug'
NodeDescription:
type: string
NodeCommonProps:
description: The main properties of a node.
type: object
required:
- name
- slug
- assets
- description
- owner
- hide_child_tree
- tags
- visibility
- meta
properties:
name: { $ref: '#/components/schemas/NodeName' }
slug: { $ref: '#/components/schemas/NodeSlug' }
assets: { $ref: '#/components/schemas/AssetList' }
link: { $ref: '#/components/schemas/LinkReference' }
description: { $ref: '#/components/schemas/NodeDescription' }
primary_image: { $ref: '#/components/schemas/Asset' }
content: { $ref: '#/components/schemas/PostContent' }
owner: { $ref: '#/components/schemas/ProfileReference' }
parent: { $ref: '#/components/schemas/Node' }
hide_child_tree:
description: |
A boolean indicating if the children of this node tree are hidden
when querying the full tree. This is useful for nodes that contain
a large amount of children and do not need to be rendered in a tree
view (such as a sidebar navigation). These children can still be
accessed via the node or node children GET operations for rendering.
type: boolean
tags: { $ref: '#/components/schemas/TagReferenceList' }
visibility: { $ref: '#/components/schemas/Visibility' }
relevance_score: { $ref: '#/components/schemas/RelevanceScore' }
meta: { $ref: '#/components/schemas/Metadata' }
NodeTree:
type: array
items: { $ref: '#/components/schemas/NodeWithChildren' }
NodeList:
type: array
items: { $ref: '#/components/schemas/Node' }
NodeListResult:
allOf:
- { $ref: '#/components/schemas/PaginatedResult' }
- type: object
required: [nodes]
properties:
nodes: { $ref: '#/components/schemas/NodeTree' }
NodeInitialProps:
type: object
required: [name]
properties:
name: { $ref: '#/components/schemas/NodeName' }
slug: { $ref: '#/components/schemas/NodeSlug' }
asset_ids: { $ref: '#/components/schemas/AssetIDs' }
asset_sources: { $ref: '#/components/schemas/AssetSourceList' }
url: { $ref: '#/components/schemas/URL' }
description: { $ref: '#/components/schemas/NodeDescription' }
primary_image_asset_id: { $ref: '#/components/schemas/AssetID' }
content: { $ref: '#/components/schemas/PostContent' }
parent: { $ref: '#/components/schemas/NodeSlug' }
hide_child_tree:
type: boolean
properties: { $ref: '#/components/schemas/PropertyMutationList' }
tags: { $ref: '#/components/schemas/TagNameList' }
visibility: { $ref: '#/components/schemas/Visibility' }
meta: { $ref: '#/components/schemas/Metadata' }
NodeMutableProps:
description: |
Note: Properties are replace-all and are not merged with existing.
type: object
properties:
name: { $ref: '#/components/schemas/NodeName' }
slug: { $ref: '#/components/schemas/NodeSlug' }
asset_ids: { $ref: '#/components/schemas/AssetIDs' }
asset_sources: { $ref: '#/components/schemas/AssetSourceList' }
url:
type: string
format: url
nullable: true
description: { $ref: '#/components/schemas/NodeDescription' }
primary_image_asset_id:
{ $ref: '#/components/schemas/NullableIdentifier' }
content: { $ref: '#/components/schemas/PostContent' }
parent: { $ref: '#/components/schemas/NodeSlug' }
hide_child_tree:
type: boolean
properties: { $ref: '#/components/schemas/PropertyMutationList' }
tags: { $ref: '#/components/schemas/TagNameList' }
meta: { $ref: '#/components/schemas/Metadata' }
NodeGenerateTitleRequest:
description: |
A request for a generated title for a node. A request for a generated
title does not use the existing content on a node but takes the current
client's content state (from an "edit mode" text box for example) and
sends that in order to generate a potential title using an LLM.
type: object
required: [content]
properties:
content:
type: string
NodeGenerateTitleResult:
description: The result of a title generation request from an LLM.
type: object
required: [title]
properties:
title:
type: string
NodeGenerateTagsRequest:
description: |
A request for generated tags for a node. A request for generated tags
does not use the existing content on a node but takes the current
client's content state (from an "edit mode" text box for example) and
sends that in order to generate potential tags using an LLM.
type: object
required: [content]
properties:
content:
type: string
NodeGenerateTagsResult:
description: The result of a tag generation request from an LLM.
type: object
required: [tags]
properties:
tags: { $ref: '#/components/schemas/TagNameList' }
NodeGenerateContentRequest:
description: |
A request for generated content for a node. A request for generated content
does not use the existing content on a node but takes the current
client's content state (from an "edit mode" text box for example) and
sends that in order to generate potential content using an LLM.
type: object
required: [content]
properties:
content:
type: string
NodeGenerateContentResult:
description: The result of a content generation request from an LLM.
type: object
required: [content]
properties:
content:
type: string
PropertyMutableProps:
description: |
Note: Properties are replace-all and are not merged with existing.
type: object
required: [properties]
properties:
properties: { $ref: '#/components/schemas/PropertyMutationList' }
Property:
type: object
required: [fid, name, type, sort, value]
properties:
fid: { $ref: '#/components/schemas/Identifier' }
name: { $ref: '#/components/schemas/PropertyName' }
type: { $ref: '#/components/schemas/PropertyType' }
value: { $ref: '#/components/schemas/PropertyValue' }
sort:
type: string
PropertyList:
type: array
items: { $ref: '#/components/schemas/Property' }
PropertyName:
type: string
PropertyType:
type: string
enum:
- text
- number
- timestamp
- boolean
PropertyValue:
type: string
PropertySortKey:
type: string
PropertyMutation:
description: |
A property mutation is a change to a property on a node. It can be used
to update existing properties or add new properties to a node. When a
property already exists by name/fid, type and sort columns are optional.
type: object
required: [name, value]
properties:
fid: { $ref: '#/components/schemas/Identifier' }
name: { $ref: '#/components/schemas/PropertyName' }
value: { $ref: '#/components/schemas/PropertyValue' }
type: { $ref: '#/components/schemas/PropertyType' }
sort: { $ref: '#/components/schemas/PropertySortKey' }
PropertyMutationList:
type: array
items: { $ref: '#/components/schemas/PropertyMutation' }
PropertySchema:
type: object
required: [fid, name, type, sort]
properties:
fid: { $ref: '#/components/schemas/Identifier' }
name: { $ref: '#/components/schemas/PropertyName' }
type: { $ref: '#/components/schemas/PropertyType' }
sort:
type: string
PropertySchemaList:
type: array
items: { $ref: '#/components/schemas/PropertySchema' }
PropertySchemaMutableProps:
description: |
Mutating property schemas permits updating existing fields as well as
adding new fields. The discinction is determined by the presence of the
`id` field. When an `id` field is provided, the operation is treated as
an update operation where any of the other fields will be used to write
new values. If an `id` field is omitted, the schema is considered a new
field and is subject to a uniqueness constraint on the `name` field.
type: object
required: [name, type, sort]
properties:
fid: { $ref: '#/components/schemas/Identifier' }
name: { $ref: '#/components/schemas/PropertyName' }
type: { $ref: '#/components/schemas/PropertyType' }
sort:
type: string
NodePositionMutableProps:
type: object
description: |
Parameters for repositioning a node in the hierarchy. You may change the
node's parent using `parent`, and/or reposition it among its siblings
using one of: `before`, `after`, or `index`. Using multiple reordering
properties is not allowed.
properties:
parent:
type: string
nullable: true
description: |
Optional new parent node slug. Set to null to move node to the root.
before:
type: string
description: Move this node before the sibling with this ID.
after:
type: string
description: Move this node after the sibling with this ID.
example:
parent: 'd031a8do2dtqtahe9nl0'
before: 'cc5lnd2s1s4652adtu50'
#
# 888 d8b 888
# 888 Y8P 888
# 888 888
# 888 888 88888b. 888 888
# 888 888 888 "88b 888 .88P
# 888 888 888 888 888888K
# 888 888 888 888 888 "88b
# 88888888 888 888 888 888 888
#
Link:
description: |
A web address with content information such as title, description, etc.
type: object
required: [url, assets, slug, domain]
allOf:
- { $ref: '#/components/schemas/CommonProperties' }
- { $ref: '#/components/schemas/LinkReferenceProps' }
- { $ref: '#/components/schemas/LinkProps' }
- { $ref: '#/components/schemas/DatagraphRecommendations' }
LinkReference:
description: |
A minimal object used to refer to a link without sending too much data.
type: object
allOf:
- { $ref: '#/components/schemas/CommonProperties' }
- { $ref: '#/components/schemas/LinkReferenceProps' }
LinkProps:
description: |
All the resources that a link has been referenced in. May be large.
required: [assets, posts, nodes, collections]
properties:
assets: { $ref: '#/components/schemas/AssetList' }
posts: { $ref: '#/components/schemas/PostReferenceList' }
nodes: { $ref: '#/components/schemas/NodeList' }
LinkReferenceProps:
type: object
required: [url, slug, domain]
properties:
url: { $ref: '#/components/schemas/URL' }
slug: { $ref: '#/components/schemas/LinkSlug' }
domain: { $ref: '#/components/schemas/LinkDomain' }
title: { $ref: '#/components/schemas/LinkTitle' }
description: { $ref: '#/components/schemas/LinkDescription' }
favicon_image: { $ref: '#/components/schemas/Asset' }
primary_image: { $ref: '#/components/schemas/Asset' }
LinkTitle:
type: string
example: 'The Open Graph Protocol'
LinkDescription:
type: string
example: 'The Open Graph protocol enables any web page to become a rich object in a social graph.'
LinkSlug:
type: string
example: github-com-southclaws-storyden
LinkDomain:
type: string
example: github.com
LinkReferenceList:
type: array
items: { $ref: '#/components/schemas/LinkReference' }
LinkListResult:
allOf:
- { $ref: '#/components/schemas/PaginatedResult' }
- type: object
required: [links]
properties:
links: { $ref: '#/components/schemas/LinkReferenceList' }
LinkInitialProps:
type: object
required: [url]
properties:
url: { $ref: '#/components/schemas/URL' }
title: { $ref: '#/components/schemas/LinkTitle' }
description: { $ref: '#/components/schemas/LinkDescription' }
#
# 8888888b. 888 888
# 888 "Y88b 888 888
# 888 888 888 888
# 888 888 8888b. 888888 8888b. .d88b. 888d888 8888b. 88888b. 88888b.
# 888 888 "88b 888 "88b d88P"88b 888P" "88b 888 "88b 888 "88b
# 888 888 .d888888 888 .d888888 888 888 888 .d888888 888 888 888 888
# 888 .d88P 888 888 Y88b. 888 888 Y88b 888 888 888 888 888 d88P 888 888
# 8888888P" "Y888888 "Y888 "Y888888 "Y88888 888 "Y888888 88888P" 888 888
# 888 888
# Y8b d88P 888
# "Y88P" 888
#
DatagraphSearchResult:
type: object
allOf:
- { $ref: '#/components/schemas/PaginatedResult' }
- type: object
required: [items]
properties:
items: { $ref: '#/components/schemas/DatagraphItemList' }
DatagraphItemList:
type: array
items: { $ref: '#/components/schemas/DatagraphItem' }
DatagraphItem:
type: object
discriminator:
propertyName: kind
mapping:
post: '#/components/schemas/DatagraphItemPost'
thread: '#/components/schemas/DatagraphItemThread'
reply: '#/components/schemas/DatagraphItemReply'
node: '#/components/schemas/DatagraphItemNode'
profile: '#/components/schemas/DatagraphItemProfile'
oneOf:
- $ref: '#/components/schemas/DatagraphItemPost'
- $ref: '#/components/schemas/DatagraphItemThread'
- $ref: '#/components/schemas/DatagraphItemReply'
- $ref: '#/components/schemas/DatagraphItemNode'
- $ref: '#/components/schemas/DatagraphItemProfile'
DatagraphItemPost:
type: object
required: [kind, ref]
properties:
kind: { $ref: '#/components/schemas/DatagraphItemKind' }
ref: { $ref: '#/components/schemas/Post' }
DatagraphItemThread:
type: object
required: [kind, ref]
properties:
kind: { $ref: '#/components/schemas/DatagraphItemKind' }
ref: { $ref: '#/components/schemas/Thread' }
DatagraphItemReply:
type: object
required: [kind, ref]
properties:
kind: { $ref: '#/components/schemas/DatagraphItemKind' }
ref: { $ref: '#/components/schemas/Reply' }
DatagraphItemNode:
type: object
required: [kind, ref]
properties:
kind: { $ref: '#/components/schemas/DatagraphItemKind' }
ref: { $ref: '#/components/schemas/Node' }
DatagraphItemProfile:
type: object
required: [kind, ref]
properties:
kind: { $ref: '#/components/schemas/DatagraphItemKind' }
ref: { $ref: '#/components/schemas/PublicProfile' }
DatagraphItemKind:
type: string
enum: [post, thread, reply, node, collection, profile, event]
DatagraphRecommendations:
required: [recomentations]
properties:
recomentations: { $ref: '#/components/schemas/DatagraphItemList' }
#
# 8888888888 888
# 888 888
# 888 888
# 8888888 888 888 .d88b. 88888b. 888888
# 888 888 888 d8P Y8b 888 "88b 888
# 888 Y88 88P 88888888 888 888 888
# 888 Y8bd8P Y8b. 888 888 Y88b.
# 8888888888 Y88P "Y8888 888 888 "Y888
#
Event:
description: |
An event represents any kind of event, such as an online or in-person
gathering, a conference, a workshop, a webinar, etc. Events will contain
a start and end timestamp and may have a location and other metadata.
Each event also gets its own thread for discussion and planning. This is
automatically created for every new event and is linked to the event.
type: object
allOf:
- { $ref: '#/components/schemas/CommonProperties' }
- { $ref: '#/components/schemas/EventReferenceProps' }
- { $ref: '#/components/schemas/EventProps' }
EventReference:
description: |
A minimal object used to refer to an event without providing all data.
type: object
allOf:
- { $ref: '#/components/schemas/CommonProperties' }
- { $ref: '#/components/schemas/EventReferenceProps' }
EventList:
type: array
items: { $ref: '#/components/schemas/EventReference' }
EventListResult:
allOf:
- { $ref: '#/components/schemas/PaginatedResult' }
- type: object
required: [events]
properties:
events: { $ref: '#/components/schemas/EventList' }
EventProps:
type: object
required: [thread]
properties:
thread: { $ref: '#/components/schemas/Thread' }
EventReferenceProps:
type: object
required:
- name
- slug
- description
- time_range
- participants
- participation_policy
- visibility
- location
properties:
name: { $ref: '#/components/schemas/EventName' }
slug: { $ref: '#/components/schemas/EventSlug' }
description: { $ref: '#/components/schemas/EventDescription' }
time_range: { $ref: '#/components/schemas/EventTimeRange' }
primary_image: { $ref: '#/components/schemas/Asset' }
participants: { $ref: '#/components/schemas/EventParticipantList' }
participation_policy:
{ $ref: '#/components/schemas/EventParticipationPolicy' }
visibility: { $ref: '#/components/schemas/Visibility' }
location: { $ref: '#/components/schemas/EventLocation' }
capacity: { $ref: '#/components/schemas/EventCapacity' }
meta: { $ref: '#/components/schemas/Metadata' }
EventInitialProps:
type: object
required:
- name
- content
- time_range
- participation_policy
- visibility
- thread_category_id
properties:
name: { $ref: '#/components/schemas/EventName' }
slug: { $ref: '#/components/schemas/EventSlug' }
description: { $ref: '#/components/schemas/EventDescription' }
content: { $ref: '#/components/schemas/PostContent' }
time_range: { $ref: '#/components/schemas/EventTimeRange' }
primary_image_asset_id: { $ref: '#/components/schemas/AssetID' }
participation_policy:
{ $ref: '#/components/schemas/EventParticipationPolicy' }
visibility: { $ref: '#/components/schemas/Visibility' }
location: { $ref: '#/components/schemas/EventLocation' }
capacity: { $ref: '#/components/schemas/EventCapacity' }
thread_category_id: { $ref: '#/components/schemas/Identifier' }
meta: { $ref: '#/components/schemas/Metadata' }
EventMutableProps:
type: object
properties:
name: { $ref: '#/components/schemas/EventName' }
slug: { $ref: '#/components/schemas/EventSlug' }
description: { $ref: '#/components/schemas/EventDescription' }
content: { $ref: '#/components/schemas/PostContent' }
time_range: { $ref: '#/components/schemas/EventTimeRange' }
primary_image_asset_id: { $ref: '#/components/schemas/AssetID' }
participation_policy:
{ $ref: '#/components/schemas/EventParticipationPolicy' }
visibility: { $ref: '#/components/schemas/Visibility' }
location: { $ref: '#/components/schemas/EventLocation' }
capacity: { $ref: '#/components/schemas/EventCapacity' }
meta: { $ref: '#/components/schemas/Metadata' }
EventName:
type: string
example: 'Friday beers, coding and design hack night'
EventSlug:
type: string
example: friday-beers-coding-design-hack-night
EventDescription:
type: string
example: 'Join us for a night of coding, design and beers!'
EventTimeRange:
description: |
A time range for an event, which may span multiple days or times of day.
type: object
required: [start, end]
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
EventParticipantList:
description: A list of attendees, hosts and invites for an event.
type: array
items: { $ref: '#/components/schemas/EventParticipant' }
EventParticipant:
type: object
required: [profile, role, status]
properties:
profile: { $ref: '#/components/schemas/ProfileReference' }
role: { $ref: '#/components/schemas/EventParticipantRole' }
status: { $ref: '#/components/schemas/EventParticipationStatus' }
EventParticipantMutableProps:
type: object
default: { status: 'requested', role: 'attendee' }
properties:
role: { $ref: '#/components/schemas/EventParticipantRole' }
status: { $ref: '#/components/schemas/EventParticipationStatus' }
EventParticipantRole:
type: string
enum: [attendee, host]
EventParticipationStatus:
type: string
enum: [requested, invited, attending, declined]
EventParticipationPolicy:
type: string
enum: [open, closed, invite_only]
EventLocation:
description: |
An event location can be either physical or virtual. A physical location
may have an address or coordinates. A virtual location may have a link.
type: object
discriminator:
propertyName: location_type
mapping:
physical: '#/components/schemas/EventLocationPhysical'
virtual: '#/components/schemas/EventLocationVirtual'
oneOf:
- $ref: '#/components/schemas/EventLocationPhysical'
- $ref: '#/components/schemas/EventLocationVirtual'
EventLocationType:
type: string
enum: [physical, virtual]
EventLocationPhysical:
description: |
A physical location for an event, such as a venue, a park, a street
address, etc. This location may have a name, address, and coordinates.
A URL may also be added for a Google maps link etc.
type: object
required: [location_type, name]
properties:
location_type:
$ref: '#/components/schemas/EventLocationType'
name:
type: string
address:
type: string
latitude:
type: number
longitude:
type: number
url:
type: string
EventLocationVirtual:
description: |
A virtual location for an event, such as a URL, a video conference
link, a Discord server, etc. This location may have a URL.
type: object
required: [location_type, name]
properties:
location_type:
$ref: '#/components/schemas/EventLocationType'
name:
type: string
url:
type: string
EventCapacity:
description: The maximum number of attendees that can attend the event.
type: integer
securitySchemes:
browser:
type: apiKey
in: cookie
name: storyden-session
access_key:
type: http
scheme: bearer
webauthn:
type: apiKey
in: cookie
name: 'storyden-webauthn-session'
#
# ..:. .***=
# .+#%%%%%#+ ... :%%%+
# #%%%+==+#. =%%%. :%%%+
# :%%%%: -*%%%=-. :==+==: ---: :== ---- .---- .-===-:%%%+ :==+=-: .---..-==-.
# +%%%%%#*=. #%%%%%%-.+%%%%#%%%%+ .%%%##%%% -%%%#. .#%%#=*%%%%%%%%%%+ =%%#+=+#%#- -%%%#%#%%%%*
# .-+#%%%%%- +%%%:..#%%%= +%%%*.%%%#-. . :#%%#..#%%#:#%%%= .+%%%+-%%%*===+%%%:-%%%+ .#%%%.
# +%%%# =%%%. .%%%# .%%%%.%%%+ .#%%##%%#:.%%%# :%%%+=%%%*+++++++:-%%%: +%%%.
# .##*===#%%%= =%%%. +%%%#=-=#%%%-.%%%+ .#%%%%*. +%%%#=-=#%%%+.#%%+:..=++= -%%%: +%%%.
# -*%%%%%%%*- =%%%. :*%%%%%%#+: .%%%+ -%%%#. -*%%%%%*%%%+ .+#%%%%%%+. -%%%: +%%%.
# .:::. .:::. -%%%*. .:. .:::.
# -%%%*
# -***+
#
Reference in New Issue View Git Blame Copy Permalink