API documentation

vessel profile

Look up a vessel by its slug and get profile info including name, description, links, pages, and theme.

your vessels

List all vessels your account has access to, with your role, permissions, and via attribution for each.

vessel posts

Paginated JSON feed of published posts for a vessel. Returns structured post objects with media, tags, location, and type-specific data.

{
"type": "post",
"subType": "text|photoset|video|event|link",
"short": "aBc123dEfGh",
"ts": 1712000000000,
"created": "2026-04-01T12:00:00.000Z",
"edited": "2026-04-01T13:00:00.000Z",
"vslName": "My Vessel",
"vslUrl": "my-vessel",
"content": "<p>Post HTML content</p>",
"media": [{ "short", "fileShort", "url", "w", "h", "th", "caption", "ext" }],
"ps": [{ ... }],       // photoset images
"psl": "321",          // photoset layout
"video": { "status", "w", "h", "duration", "src", "th" },
"link": { "url", "title", "description", "image", "domain" },
"event": { ... },
"loc": { "name", "venue", "geo", "lat", "lon" },
"tags": [{ "display": "Art", "canon": "art", "type": 0 }],
"client": { "kind": "app", "name", "url", "icon" }  // only on API-created posts; {"kind":"api"} for a personal token
}

tag feed

Global tag feed as JSON. Returns posts from all vessels tagged with the given tag, newest first. Tag names are auto-canonicalized (lowercased, trimmed).

drafts

Unpublished draft posts for a vessel. Requires authentication and publish permission on the vessel.

queue

Posts in the publish queue for a vessel, waiting to be auto-published. Requires authentication and publish permission.

scheduled

Posts scheduled for future publication. Each item includes a scheduledDate field. Requires authentication and publish permission.

text

Create a text post with HTML content. Supports @mentions and #hashtags which are auto-detected and linked.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel": "{slug}",
"type": "text",
"content": "<p>Hello from the API!</p>",
"tags": ["api", "hello-world"]
}' \
'https://nyx.now/api/v1/pst/create'

photoset

Upload 1–10 images in a single request using multipart form data. Text content, a layout string, and captions are all optional.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'vessel={slug}' \
-F 'type=photoset' \
-F 'content=<p>Beach day</p>' \
-F '[email protected]' \
-F '[email protected]' \
-F '[email protected]' \
-F 'layout=21' \
-F 'image_caption=["Sunset","Sandy beach","Seashells"]' \
-F 'tags=["beach","summer"]' \
'https://nyx.now/api/v1/pst/create'

event

Create an event with cover images, date, location, and optional RSVP. Uses multipart form data. A description can be added with content.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'vessel={slug}' \
-F 'type=event' \
-F '[email protected]' \
-F 'event={
"title": "Summer Concert",
"summary": "Live music in the park",
"startDate": "2027-06-15T19:00:00Z",
"endDate": "2027-06-15T23:00:00Z",
"timezone": "America/New_York",
"locationType": "in_person",
"location": "Central Park, NYC",
"ticket": {"type": "rsvp"}
}' \
-F 'lat=77.1755' \
-F 'lon=-61.1311' \
-F 'location_name=Worm City' \
-F 'tags=["music","summer"]' \
'https://nyx.now/api/v1/pst/create'

event fields

link

Share a URL. The title, description, and preview image are automatically fetched from the page's Open Graph metadata. URLs from supported sites — including Spotify, SoundCloud, Apple Music, YouTube, Vimeo, and others — render as rich embeds using oEmbed. If the target site blocks our crawler, the link may render without a preview. Optionally add your own text with content.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel": "{slug}",
"type": "link",
"url": "https://example.com/article",
"content": "<p>Great read on this topic</p>",
"tags": ["reading"]
}' \
'https://nyx.now/api/v1/pst/create'

video

Create a video post from a publicly reachable URL. Pass video_source_url and we fetch, transcode, and host the file for you — there is no direct upload endpoint. The post is returned in "processing" state and auto-publishes when encoding finishes. Poll GET /api/v1/video/:short with the returned post_video_short to watch progress.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel": "{slug}",
"type": "video",
"video_source_url": "https://",
"content": "<p>Optional caption</p>",
"tags": ["clips"]
}' \
'https://nyx.now/api/v1/pst/create'

response (HTTP 201)

{
"ok": true,
"data": {
"short": "aBc123dEfGh",
"type": "video",
"status": "processing",
"url": "/v/my-vessel/aBc123dEfGh",
"video": {
"post_video_short": "vId987xYzAb",
"status": "processing"
}
}
}

audio

Audio posts are a two-step flow: first upload each track via POST /api/v1/audio/upload to get back a short per track, then pass those shorts in audio_tracks here. Posts hold 1–25 tracks played as a playlist, with an optional shared album art image.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel": "{slug}",
"type": "audio",
"audio_tracks": [
{"short": "aUdC7x3bKpR", "title": "Intro"},
{"short": "aUdF9k2mNqZ", "title": "Ocean"}
],
"album_art_short": "iMgAbC123dE",
"content": "<p>Optional description</p>",
"tags": ["demo"]
}' \
'https://nyx.now/api/v1/pst/create'

response (HTTP 201)

{
"ok": true,
"data": {
"short": "aBc123dEfGh",
"type": "audio",
"status": "published",
"url": "/v/my-vessel/aBc123dEfGh",
"audio": {
"tracks": [
{ "short": "aUdC7x3bKpR", "title": "Intro", "duration": 27, "ext": "mp3" },
{ "short": "aUdF9k2mNqZ", "title": "Ocean", "duration": 183, "ext": "mp3" }
],
"album_art": { "short": "iMgXyZ789Ab", "ext": "jpg" }
}
}
}

poll

Polls hold 2–6 options and run for a set duration (5 minutes–14 days). poll_kind picks the layout: "text" renders a labeled list, "image" renders an image grid where each option carries a pre-uploaded image (use POST /api/images/post first, then pass each short as image_short). An optional content HTML body shows below the poll.

example — text poll

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel": "{slug}",
"type": "poll",
"poll_question": "Best beach day activity?",
"poll_kind": "text",
"poll_duration_seconds": 86400,
"poll_options": [
{"text": "Surf"},
{"text": "Read"},
{"text": "Nap"}
],
"tags": ["summer"]
}' \
'https://nyx.now/api/v1/pst/create'

example — image poll

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel": "{slug}",
"type": "poll",
"poll_question": "Which cover?",
"poll_kind": "image",
"poll_duration_seconds": 604800,
"poll_options": [
{"image_short": "iMgAbC123dE", "alt": "Sunrise"},
{"image_short": "iMgFgH456iJ", "alt": "Sunset"}
]
}' \
'https://nyx.now/api/v1/pst/create'

response (HTTP 201)

{
"ok": true,
"data": {
"short": "aBc123dEfGh",
"type": "poll",
"status": "published",
"url": "/v/my-vessel/aBc123dEfGh",
"poll": {
"question": "Best beach day activity?",
"kind": "text",
"close_at": "2026-04-26T17:32:00Z",
"options": [
{ "text": "Surf" },
{ "text": "Read" },
{ "text": "Nap" }
]
}
}
}

inline images

Put images anywhere inside a post’s content HTML. Upload each image to /api/images/post to get a short code and a copy-paste placeholder, then embed it in your content. Optionally attach alignment and a caption per image via image_settings. Works with any text-bearing post type (text, event, link, video, poll).

step 1 — upload

vessel_short is the vessel’s short code (same form used by the Likes endpoint), not the URL slug.

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F '[email protected]' \
-F 'vessel_short={vessel}' \
'https://nyx.now/api/images/post'

response

{
"ok": true,
"data": {
"short": "aBc123dEfGh",
"url": "https://i.nyx.now/ab/c1/nyx_aBc123dEfGh.jpg",
"placeholder": "{{[[img:aBc123dEfGh]]}}",
"thumbhash": "...",
"width": 1600,
"height": 1200,
// "gps": { "lat": .., "lon": .. } — only when the image carries EXIF geotags
}
}

Copy the placeholder string; that’s what you embed in your content. A gps object is included only when the uploaded image has EXIF geotags.

step 2 — embed in content

<p>Check this out {{[[img:aBc123dEfGh]]}} cool photo!</p>

Place the placeholder anywhere in your HTML. Multiple images are fine; repeating the same placeholder inserts the same image twice.

step 3 — publish with optional alignment & caption

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel": "{slug}",
"type": "text",
"content": "<p>Cool shot {{[[img:aBc123dEfGh]]}}.</p>",
"image_settings": {
"aBc123dEfGh": { "align": "center", "caption": "Sunset over the bay" }
}
}' \
'https://nyx.now/api/v1/pst/create'

alignment & caption

constraints

when the cap is reached

{
"ok": false,
"error": {
"code": "image_limit_reached",
"message": "Daily image limit reached.",
"details": {
"limit": <applicable cap>,
"current": <your count>,
"tier": "free" | "paid",
"cta": { "label": <label>, "url": "/settings/billing" }
}
}
}

See Rate Limits for the full error taxonomy.

follow or unfollow

Toggle a follow from one of your vessels.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel_short": "{vessel}",
"target_short": "xYz789wVuTs",
"target_type": "vessel",
"action": "follow"
}' \
'https://nyx.now/api/v1/follow'

response

{
"ok": true,
"data": { "following": true }
}

Bulk variant: POST /api/v1/follow/bulk takes a vessel_shorts array (max 25) against one target and returns a per-vessel result map.

like a post

Like a published post from one of your vessels.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel_short": "{vessel}",
"post_short": "aBc123dEfGh",
"post_vessel_short": "xYz789wVuTs"
}' \
'https://nyx.now/api/v1/like'

response

{
"ok": true,
"data": {
"liked": true,
"count": 12
}
}

unlike a post

Remove a like from a post. Same body as the like endpoint.

example

curl -X DELETE \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel_short": "{vessel}",
"post_short": "aBc123dEfGh",
"post_vessel_short": "xYz789wVuTs"
}' \
'https://nyx.now/api/v1/like'

response

{
"ok": true,
"data": {
"liked": false,
"count": 11
}
}

list comments

Paginated list of top-level comments on a post. Auth is optional; password-protected vessels still require the access cookie.

example

curl 'https://nyx.now/api/v1/cmt/xYz789wVuTs/aBc123dEfGh?sort=top&limit=50'

response

{
"ok": true,
"data": { "items": [ /* comment objects */ ] },
"meta": {
"page": { "nextCursor": "eyJ...", "hasMore": true },
"totalCount": 509,
"sort": "top"
}
}

list replies

Every descendant of a top-level comment (oldest first), flat. top_short is the short of the top-level comment whose thread you want.

example

curl 'https://nyx.now/api/v1/cmt/xYz789wVuTs/aBc123dEfGh/cMt456pQrSt/r'

response

{
"ok": true,
"data": { "items": [ /* comment objects */ ] },
"meta": {
"page": { "nextCursor": "eyJ...", "hasMore": false },
"totalCount": 12
}
}

list reposters

The quote posts carrying a comment (the who-reposted panel): rendered rows, oldest first, with count = the comment's quoteCnt. Hidden or unpublished quote posts and banned / muted reposters are omitted at read time. Post comments only. The sibling /likers and /collections panels share the path shape.

example

curl 'https://nyx.now/api/v1/cmt/xYz789wVuTs/aBc123dEfGh/cMt456pQrSt/reposters'

post a comment

Post a new comment on a published post. Body and/or a staged image are required (empty body is allowed only with an image). To reply to an existing comment, pass parent_short.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"post_vessel_short": "xYz789wVuTs",
"post_short": "aBc123dEfGh",
"vessel_short": "{vessel}",
"body": "great post"
}' \
'https://nyx.now/api/v1/cmt'

response

{
"ok": true,
"data": { "comment": { /* comment object */ } }
}

edit a comment

Edit body and/or attached image on an existing comment.

example

curl -X PATCH \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"post_vessel_short": "xYz789wVuTs",
"post_short": "aBc123dEfGh",
"vessel_short": "{vessel}",
"body": "edited!"
}' \
'https://nyx.now/api/v1/cmt/cMt456pQrSt'

response

{
"ok": true,
"data": { "comment": { /* updated comment object */ } }
}

delete a comment

Soft-delete a comment. The row stays so the thread reads in order, but the body and any attached image are dropped. Idempotent on already-deleted comments.

example

curl -X DELETE \
-H 'Authorization: Bearer YOUR_API_KEY' \
'https://nyx.now/api/v1/cmt/cMt456pQrSt?post_vessel_short=xYz789wVuTs&post_short=aBc123dEfGh'

response

{
"ok": true,
"data": { "deleted": true, "html": "<article ...>" }
}

like a comment

Like a comment from one of your vessels. One like per account and one per vessel: re-posting with a different vessel_short moves your like there and returns switched: true plus switchedFrom (the like count does not change); a vessel another member already liked from answers 409 like_taken.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel_short": "{vessel}",
"comment_short": "cMt456pQrSt",
"post_short": "aBc123dEfGh",
"post_vessel_short": "xYz789wVuTs"
}' \
'https://nyx.now/api/v1/cmt/like'

response

{
"ok": true,
"data": {
"liked": true,
"switched": false,
"vesselShort": "vsLAbc12345",
"count": 5
}
}

unlike a comment

Remove a like from a comment. Without vessel_short your own like goes wherever it sits. With it, the like that vessel holds goes: yours, or another member’s when you own or administer the vessel (403 like_locked otherwise).

example

curl -X DELETE \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"comment_short": "cMt456pQrSt",
"post_short": "aBc123dEfGh",
"post_vessel_short": "xYz789wVuTs"
}' \
'https://nyx.now/api/v1/cmt/like'

response

{
"ok": true,
"data": {
"liked": false,
"count": 4
}
}

GET /api/v1/forum/list?vessel_short=VESSEL_SHORT

Returns the forums you can reach on the vessel with their short codes (the coordinates every other forum call wants), names, kind, and the sections you can reach (sections[]: short, name, url, parentShort). Authentication is optional; the vessel's access rules apply, and forums or sections you cannot see are left out.

GET /api/v1/forum/{vessel_short}/{forum_short}/threads?c=<cursor>

Standard cursor pagination. Ranked forums also accept sort=hot|top|new|activity (invalid sorts fall back to the default).

GET /api/v1/forum/{vessel_short}/t/{thread_short}/posts?c=<cursor>

Posts carry short, HTML body, author (or the anonymous tag), and reply linkage. Threaded forums nest via parent_short; ranked replies accept a sort= param.

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"forum_vessel_short": "FORUM_VESSEL_SHORT",
"vessel_short": "YOUR_VESSEL_SHORT",
"forum_short": "FORUM_SHORT",
"title": "tape trading thread",
"body": "<p>post your lists</p>"
}' \
'https://nyx.now/api/v1/forum/thread'

response (HTTP 200)

{
"ok": true,
"data": {
"thread": { "short": "aBc123dEfGh", "url": "/v/.../f/.../tape-trading-thread/aBc123dEfGh" },
"redirect": "..."
}
}

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"forum_vessel_short": "VESSEL_SHORT",
"vessel_short": "YOUR_VESSEL_SHORT",
"body": "<p>list incoming</p>"
}' \
'https://nyx.now/api/v1/forum/thread/THREAD_SHORT/posts'

Returns the created post as data.post (plus rendered data.html). Locked threads refuse with a 400.

upload track

Upload one audio file. Returns a short you can pass in audio_tracks when creating the post. Unused tracks are garbage-collected after 3 days.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'vessel_short={slug}' \
-F '[email protected]' \
'https://nyx.now/api/v1/audio/upload'

response (HTTP 200)

{
"ok": true,
"data": {
"short": "aUdC7x3bKpR",
"tracking_id": "abc123def456ghi789jkl012",
"title": "track",
"duration": 183,
"channels": 2,
"sample_rate": 44100,
"ext": "mp3",
"container": "mp3",
"codec": "mp3",
"url": "https://a.nyx.now/aud/ab/cd/nyx_abCdEfGh12345678.mp3?v=my-vessel"
}
}

title is derived from the uploaded filename (stem, no extension) — override it per-track in audio_tracks at publish time. url is live immediately; no processing wait.

rejection reasons

A rejected upload returns HTTP 400 with audio_rejected. The details.reason field gives a stable subcode:

track metadata

Fetch metadata for a track the caller controls. Useful to re-hydrate client state after a page reload when you have a short but not the rest.

example

curl -H 'Authorization: Bearer YOUR_API_KEY' \
'https://nyx.now/api/v1/audio/aUdC7x3bKpR'

response

{
"ok": true,
"data": {
"short": "aUdC7x3bKpR",
"vessel_short": "my-vessel",
"title": "Ocean",
"position": null,
"bound": false,
"duration": 183,
"channels": 2,
"sample_rate": 44100,
"ext": "mp3",
"container": "mp3",
"codec": "mp3",
"url": "https://a.nyx.now/aud/ab/cd/nyx_abCdEfGh12345678.mp3?v=my-vessel"
}
}

bound is true once the track has been attached to a post; position is its 0-indexed slot in the post's playlist.

delete track

Delete a temp (unbound) track. Tracks already attached to a post must be removed by deleting or editing the post — deleting them here would race the post's track ordering.

example

curl -X DELETE \
-H 'Authorization: Bearer YOUR_API_KEY' \
'https://nyx.now/api/v1/audio/aUdC7x3bKpR'

response

{
"ok": true,
"data": { "short": "aUdC7x3bKpR", "deleted": true }
}

Calling on a bound track returns invalid_request with a message pointing to post edit instead.

delete post

Hard delete. Attached images, videos, tags, location, RSVPs, likes, and feed index entries are all cleaned up automatically. Not idempotent — a second delete returns 404.

example

curl -X DELETE \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel": "{slug}"
}' \
'https://nyx.now/api/v1/pst/POST_SHORT'

response

{
"ok": true,
"data": { "deleted": true, "short": "aBc123dEfGh" }
}

Collaborators can only delete posts they authored. Owners and admins with perm_edit_posts can delete anything on the vessel.

pin post

Pin a published post to the top of its vessel's posts tab, or take it down. A vessel pins at most 3 posts, most recently pinned first (unpin and pin again to move one to the top). Pinned posts lead page 1 of the profile feed with pinned: true and pinnedAt, and meta.pinnedCount says how many; the chronological stream never repeats them. Both verbs are idempotent.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel": "{slug}"
}' \
'https://nyx.now/api/v1/pst/POST_SHORT/pin'

response

{
"ok": true,
"data": { "pinned": true }
}

The owner and admins with perm_change_settings can pin; collaborators cannot. A repost is a 400 (pin the original), an unpublished post a 409 invalid_state, a full block a 409 pin_limit_reached with details.limit and details.current.

publish draft

Transition a post from draft to published. Nothing else changes — no content edits, no other status transitions. Video posts must have a "ready" video before publishing.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel": "{slug}"
}' \
'https://nyx.now/api/v1/pst/POST_SHORT/publish'

response

{
"ok": true,
"data": {
"short": "aBc123dEfGh",
"status": "published",
"url": "/v/my-vessel/aBc123dEfGh"
}
}

errors

reschedule post

Change the publish time on a post that’s already in scheduled state. Content and status are untouched; only schedule_date moves.

example

curl -X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"vessel": "{slug}",
"schedule_date": "2026-11-03T18:00:00Z"
}' \
'https://nyx.now/api/v1/pst/POST_SHORT/reschedule'

response

{
"ok": true,
"data": {
"short": "aBc123dEfGh",
"status": "schedule",
"schedule_date": "2026-11-03T18:00:00Z",
"url": "/v/my-vessel/aBc123dEfGh"
}
}

notes