World-Building Platform

Appearance

API Endpoints ​

Conventions ​

  • Base URL: /api
  • All endpoints nested under project: /api/projects/{key}/...
  • {key} = project key (e.g., VNO)
  • {seq} = public sequence number (e.g., 42, making the full public ID VNO-42)
  • {id} = internal identifier (for child entities without public sequence numbers)

Phase 1: Core Timeline & Projects ​

Auth (pending team decision on provider) ​

POST   /api/auth/register
POST   /api/auth/login
POST   /api/auth/refresh
POST   /api/auth/forgot-password
POST   /api/auth/reset-password
GET    /api/auth/verify-email                                    # Verify email with token

Projects ​

GET    /api/projects                              # List user's projects
POST   /api/projects                              # Create project
GET    /api/projects/{key}                        # Get project details
PUT    /api/projects/{key}                        # Update project
DELETE /api/projects/{key}                        # Delete project
GET    /api/projects/{key}/dashboard              # Project statistics
POST   /api/projects/{key}/archive                # Archive project
POST   /api/projects/{key}/restore                # Restore archived project
POST   /api/projects/{key}/transfer-ownership     # Transfer project ownership

Members ​

GET    /api/projects/{key}/members                              # List members + pending invites
POST   /api/projects/{key}/members/invite                       # Send invitation
PATCH  /api/projects/{key}/members/{userId}                     # Change role
DELETE /api/projects/{key}/members/{userId}                     # Remove member
POST   /api/projects/{key}/members/leave                        # Leave project voluntarily
DELETE /api/projects/{key}/members/invitations/{invitationId}   # Revoke pending invitation

Invitations ​

POST   /api/invitations/{token}/accept                          # Accept invitation
POST   /api/invitations/{token}/decline                         # Decline invitation

Timelines ​

GET    /api/projects/{key}/timelines              # List all timeline updates
POST   /api/projects/{key}/timelines              # Create timeline update
GET    /api/projects/{key}/timelines/{seq}        # Get with sections + items included
PUT    /api/projects/{key}/timelines/{seq}        # Update
DELETE /api/projects/{key}/timelines/{seq}        # Delete
PUT    /api/projects/{key}/timelines/reorder      # Reorder timelines

Sections ​

POST   /api/projects/{key}/sections               # Create (timelineSeq in body)
PUT    /api/projects/{key}/sections/{id}          # Update
DELETE /api/projects/{key}/sections/{id}          # Delete
PUT    /api/projects/{key}/sections/reorder       # Reorder within a timeline

Items ​

POST   /api/projects/{key}/items                  # Create (sectionId in body)
PUT    /api/projects/{key}/items/{id}             # Update
DELETE /api/projects/{key}/items/{id}             # Delete
PUT    /api/projects/{key}/items/reorder          # Reorder within a section
GET    /api/projects/{key}/search?q=keyword       # Search within project

Bookmarks ​

GET    /api/bookmarks                              # List user's bookmarks
POST   /api/bookmarks                              # Create bookmark (projectId + entityId + entityType in body)
DELETE /api/bookmarks/{id}                          # Remove bookmark

Recently Viewed ​

GET    /api/recently-viewed                         # List recently viewed items

Phase 2: Relationship Mapping ​

Characters ​

GET    /api/projects/{key}/characters              # List (filtered by permissions)
POST   /api/projects/{key}/characters              # Create character
GET    /api/projects/{key}/characters/{seq}        # Get character details
PUT    /api/projects/{key}/characters/{seq}        # Update
DELETE /api/projects/{key}/characters/{seq}        # Delete

Character Relationships ​

GET    /api/projects/{key}/characters/relationships              # List all visible relationships
POST   /api/projects/{key}/characters/relationships              # Create
PUT    /api/projects/{key}/characters/relationships/{id}         # Update
DELETE /api/projects/{key}/characters/relationships/{id}         # Delete

Factions ​

GET    /api/projects/{key}/factions                              # List factions
POST   /api/projects/{key}/factions                              # Create faction
GET    /api/projects/{key}/factions/{seq}                        # Get faction details
PUT    /api/projects/{key}/factions/{seq}                        # Update
DELETE /api/projects/{key}/factions/{seq}                        # Delete

Faction Memberships ​

GET    /api/projects/{key}/factions/{seq}/memberships            # List members
POST   /api/projects/{key}/factions/{seq}/memberships            # Add character
PUT    /api/projects/{key}/factions/{seq}/memberships/{id}       # Update rank
DELETE /api/projects/{key}/factions/{seq}/memberships/{id}       # Remove

Faction Relationships ​

GET    /api/projects/{key}/factions/relationships                # List all
POST   /api/projects/{key}/factions/relationships                # Create
PUT    /api/projects/{key}/factions/relationships/{id}           # Update
DELETE /api/projects/{key}/factions/relationships/{id}           # Delete

Graph Endpoints (custom) ​

GET    /api/projects/{key}/graphs/characters       # Character relationship graph (nodes + edges, pre-assembled)
GET    /api/projects/{key}/graphs/factions          # Faction relationship graph

Phase 3: Advanced Collaboration ​

Comments ​

GET    /api/projects/{key}/comments?targetType=timeline&targetSeq=3    # List comments for a target
POST   /api/projects/{key}/comments                                    # Create (targetType + targetSeq in body)
PUT    /api/projects/{key}/comments/{id}                               # Update
DELETE /api/projects/{key}/comments/{id}                               # Delete
POST   /api/projects/{key}/comments/{id}/resolve                       # Resolve thread
POST   /api/projects/{key}/comments/{id}/unresolve                     # Unresolve thread
POST   /api/projects/{key}/comments/{id}/replies                       # Reply to comment

Activity Feed ​

GET    /api/projects/{key}/activity                                    # Project activity feed
GET    /api/projects/{key}/activity?userId={id}                        # Filter by user
GET    /api/projects/{key}/activity?type=character                     # Filter by content type

Notifications ​

GET    /api/notifications                                              # User's notifications (cross-project)
PUT    /api/notifications/{id}/read                                    # Mark as read
PUT    /api/notifications/read-all                                     # Mark all as read

Version History ​

GET    /api/projects/{key}/history?targetType=timeline&targetSeq=3     # Version history for a target
GET    /api/projects/{key}/history/{id}                                # Get specific version
GET    /api/projects/{key}/history/{id}/diff                           # Diff with previous version
POST   /api/projects/{key}/history/{id}/restore                        # Restore to this version

Phase 4: Enhanced Features ​

Changelog ​

GET    /api/projects/{key}/timelines/{seq}/changelog                   # Changelog for a timeline update
POST   /api/projects/{key}/timelines/{seq}/changelog                   # Add changelog entry
PUT    /api/projects/{key}/timelines/{seq}/changelog/{id}              # Update entry
DELETE /api/projects/{key}/timelines/{seq}/changelog/{id}              # Delete entry
GET    /api/projects/{key}/search?q=keyword&type=character&status=published&from=2026-01-01    # Filtered search
GET    /api/search?q=keyword                                           # Cross-project search (respects permissions)

Export ​

POST   /api/projects/{key}/export                                      # Request export (format in body: json/pdf)
GET    /api/projects/{key}/export/{id}                                 # Download export file

Bulk Operations ​

POST   /api/projects/{key}/timelines/bulk-status                       # Bulk status change

Templates ​

GET    /api/templates/characters                                       # List character templates
GET    /api/templates/factions                                         # List faction templates
POST   /api/projects/{key}/characters/from-template                    # Create character from template
POST   /api/projects/{key}/factions/from-template                      # Create faction from template