API Documentation

Complete guide to integrating with TellsTree's powerful storytelling API.

Quick Start

Get up and running with the TellsTree API in minutes

1
Get JWT Token
2
Make API Calls
3
Start Building

Required headers

Send Accept: application/json with every request. Validation failures come back as 422 with a readable message for callers that ask for JSON. Without the header the request is treated as a browser form post and is answered with a 302 redirect instead, and no message reaches the caller.

The application's own interface always sends the header. This note matters for scripts and third-party clients.

Features

✓
RESTful API
CRUD operations & consistent JSON responses
✓
No Complex Setup
Get JWT Token → Make API Calls → Start Building
✓
Copy & Paste Examples
Working code for JavaScript, Python, PHP, cURL
✓
Clear Error Messages
HTTP status codes and RFC 7807 compliant error messages
✓
Generous Limits
60 api calls per minute

Resources

Projects /api/projects
Nodes /api/nodes
Edges /api/edges
Media /api/media
Comments /api/comments
Themes /api/themes
Designs /api/designs

Rate Limits

API rate limiting prevents abuse and ensures fair usage. Limits are enforced per IP address and vary by endpoint type.

All API responses include rate limit information in the headers. When limits are exceeded, a 429 status is returned.

Header Fields

  • X-RateLimit-LimitMaximum requests allowed in the current window
  • X-RateLimit-RemainingRemaining requests in the current window
  • Retry-AfterSeconds to wait before retry (429 responses only)
API 300 requests/minute General API limit (optimized for graph editor)
AUTH 5 attempts/minute Login attempts
REFRESH 30 requests/minute Token refresh
REG 3 attempts/10 minutes User registration

Error Handling

The API uses conventional HTTP response codes to indicate success or failure. All error responses follow a consistent JSON format with RFC 7807 Problem Details.

Error responses include a `type` (URL to error documentation), `title` (human-readable summary), `detail` (explanation), and `status` (HTTP code).

2xx 200, 201, 204 Success responses
4xx 400, 401, 403, 404, 422, 429 Client errors
5xx 500, 503 Server errors

Authentication

The TellsTree API uses JWT (JSON Web Token) based authentication. You need to obtain a token by logging in with valid credentials.

POST /api/auth/login Login / Obtain token
GET /api/auth/me Get current user info
POST /api/auth/refresh Refresh token
POST /api/auth/logout Logout / Invalidate token
GET /api/.well-known/jwks.json Public keys (JWKS)

Login

Most API endpoints require authentication. Get your JWT token through the authentication endpoint.

Required Credentials

  • email - Your account email
  • password - Your account password

Response

200 Success / Login successful
401 Authentication failed / Invalid credentials
422 Validation failed / Missing fields
429 Too Many Requests / Rate limited

Refresh Token

Tokens expire after 1 hour. Use the refresh endpoint to get a new access token without re-authentication.

Token Refresh

  • • Refresh token is stored as HttpOnly cookie
  • • No request body required
  • • Returns new access token
  • • Include cookies with request

Response

200 Success / Token refreshed
401 Unauthorized / Invalid refresh token
403 Forbidden / Token expired

Get Current User

Get information about the currently authenticated user and token details.

Authentication Required

  • • Include JWT token in Authorization header
  • • Returns user profile and token information
  • • Useful for validating token status

Response

200 Success / User information
401 Unauthorized / Missing or invalid token

Logout

Logout and invalidate all tokens for the current user. This prevents further API access with existing tokens.

Token Invalidation

  • • Invalidates current access token
  • • Invalidates refresh token
  • • Increments user token version
  • • Clears authentication cookies

Response

204 No Content / Logout successful
401 Unauthorized / Invalid token

JSON Web Key Set (JWKS)

Public cryptographic keys for verifying JWT tokens issued by TellsTree. Required for external systems that need to validate TellsTree tokens independently.

Use Cases

  • • Microservices: Verify TellsTree tokens without API calls
  • • API Gateways: Validate tokens at gateway level
  • • Single Sign-On (SSO): Enable SSO integrations
  • • Third-party Apps: Verify token authenticity offline

Technical Details

  • • Standard RFC 7517 compliant endpoint
  • • RSA-256 public keys included
  • • Key rotation support via 'kid' field
  • • No authentication required (public endpoint)

Response

200 Success / Public keys

Using Tokens for API Access

Once you have an access token, include it in the Authorization header for all API requests.

Authorization Header

  • Authorization: Bearer YOUR_TOKEN
  • • Required for all protected endpoints
  • • Token expires after 1 hour
  • • Use refresh endpoint to get new tokens

Example API Call

GET /api/projects
Authorization: Bearer eyJ0eXAiOiJKV1Q...
Accept: application/json

?? Projects

Projects are the top-level containers for your storytelling content. Each project can contain multiple nodes (story elements) and edges (connections).

GET /api/projects List all projects
POST /api/projects Create project
Identifiers. The path segment takes the public_id of the project — a 26-character identifier (ULID, Crockford base32), not the internal counter value. Shape: 26 characters from 0-9A-Z, without I, L, O, U, in practice starting with 01M. An unknown value answers like somebody else's project, so the identifier does not become a lead.
GET /api/projects/{public_id} Get project
PUT /api/projects/{public_id} Update project
DELETE /api/projects/{public_id} Delete project
GET /api/projects/{public_id}/activity Poll for activity updates

List Public Projects

Retrieve all publicly available projects. No authentication required.

Query Parameters

query[is_public] Set to true to get public projects
query[page] Page number (default: 1)
query[per_page] Items per page (default: 15)

Response

200 Success, Returns paginated list of public projects

List Private Projects

Retrieve all projects that the authenticated user has access to. Authentication required.

Headers

Authorization Bearer {your_jwt_token}

Query Parameters

query[page] Page number (optional)
query[per_page] Items per page (optional)

Response

200 Success, Returns paginated list of user's projects
401 Unauthorized, Invalid or missing token

Create New Project

Create a new storytelling project with a theme and design.

Response

201 Created, data.project{} (Complete Project object with theme, design, nodes, edges, members, capabilities, comments)
422 Invalid data, Validation errors in data.errors{}
401 Unauthorized, Invalid token

Get Single Project

Retrieve detailed information about a specific project.

Response

200 Success, Returns complete project details
404 Project not found
403 Forbidden, No access

Update Project

Update an existing project's properties, theme, or design.

🔒 Lock Management

Lock/unlock functionality is integrated into the update endpoint:

  • • is_locked: true - Lock project for current user
  • • is_locked: false - Unlock project (only by lock owner)
  • • Response includes is_locked: true/false
  • • Auto-unlock: Locks expire automatically after 300 seconds when project is accessed

Response

200 Success, Project updated successfully
422 Invalid data, Validation errors
404 Project not found
403 Forbidden, No permission

Delete Project

Permanently delete a project and all its content.

Response

204 No Content, Project deleted successfully
404 Project not found
403 Forbidden, No permission

Poll for Activity Updates

Retrieve IDs of resources that have been modified since a given timestamp. Enables real-time collaborative editing. Authentication required.

Headers

Authorization Bearer {your_jwt_token}

Query Parameters

since Unix timestamp - only return activities after this time (optional)

Response

200 Success, Returns activity updates since timestamp
401 Unauthorized, Invalid or missing token
403 Forbidden, User is not a project member

📋 Nodes

Nodes are the building blocks of your story. Each node represents a narrative element like a scene, chapter or character. A Node can contain text, media, and interactive elements.

GET /api/nodes List all nodes
POST /api/nodes Create new node
GET /api/nodes?query[include]=ids Get specific nodes (lazy loading)
GET /api/nodes/{node} Get node details
PUT /api/nodes/{node} Update node
DELETE /api/nodes/{node} Delete node

List Nodes

Retrieve all nodes or filter by project, including their content, position, and metadata.

Query Parameters

  • query[project_id] - Filter by project ID (required)
  • query[page] - Page number (optional, default: 1)
  • query[per_page] - Items per page (optional, default: 20)

Response

200 Success / Nodes list
400 Missing project_id parameter
401 Unauthorized / Invalid token

Load Specific Nodes

Get specific nodes by IDs for lazy loading in the TellsTreeGraph editor. Used for performance optimization when working with large projects.

Query Parameters

  • query[project_id] - Required project ID
  • query[include] - Comma-separated node IDs
  • • Returns canvas-ready node data
  • • Optimized for editor performance

Response

200 Success / Nodes loaded
400 Missing project_id

Create Node

Create a new node. Nodes can exist independently or be associated with a project via project_id.

Required Fields

  • title - Node title

Optional Fields

  • project_id - Associate with project
  • content - Node content/text
  • type - Node type
  • position_x - X coordinate
  • position_y - Y coordinate
  • properties - Custom properties

Response

201 Created / Node created
422 Invalid data / Validation failed
401 Unauthorized / Invalid token

Get Node

Retrieve detailed information about a specific node, including all its properties and metadata.

URL Parameters

  • project - Project ID
  • node - Node ID

Response

200 Success / Node details
404 Node not found
403 Forbidden / No access

Update Node

Update an existing node's content, position, properties, or other attributes.

🔒 Lock Management

Lock/unlock functionality is integrated into the update endpoint:

  • • is_locked: true - Lock node for current user
  • • is_locked: false - Unlock node (only by lock owner)
  • • Response includes is_locked: true/false
  • • Auto-unlock: Locks expire automatically after 300 seconds when node is accessed

Updatable Fields

  • title - Node title
  • content - Node content
  • type - Node type
  • position_x - X coordinate
  • position_y - Y coordinate
  • properties - Custom properties
  • locked_by - Lock status (user_id or null)

Response

200 Success / Node updated
422 Invalid data / Validation failed
404 Node not found
403 Forbidden / No permission

Delete Node

Permanently delete a node from the project. This will also remove all connected edges.

Response

204 Success / No Content
404 Node not found
403 Forbidden / No permission

?? Edges

Edges create connections between nodes, defining the flow and relationships in your interactive stories. They represent transitions, choices, and narrative pathways.

GET /api/edges List all edges
POST /api/edges Create new edge
GET /api/edges/{edge} Get edge details
PUT /api/edges/{edge} Update edge
DELETE /api/edges/{edge} Delete edge

Create Edge

Create a new edge connection between two nodes in a project.

Required Fields

  • source_node_id - ID of source node
  • target_node_id - ID of target node

Optional Fields

  • label - Display text for edge
  • condition - Edge activation condition

Response

201 Created / Edge created
422 Invalid data / Validation failed
404 Source/target node not found

Get Edge

Retrieve detailed information about a specific edge, including source and target node details.

URL Parameters

  • project - Project ID
  • edge - Edge ID

Response

200 Success / Edge details
404 Edge not found
403 Forbidden / No access

Update Edge

Update properties of an existing edge. You can modify the label, condition, and connection endpoints.

🔒 Lock Management

Lock/unlock functionality is integrated into the update endpoint:

  • • is_locked: true - Lock edge for current user
  • • is_locked: false - Unlock edge (only by lock owner)
  • • Response includes is_locked: true/false
  • • Auto-unlock: Locks expire automatically after 300 seconds when edge is accessed

Request Body

  • source_node_id - Source node ID
  • target_node_id - Target node ID
  • label - Edge display label
  • condition - Edge condition
  • locked_by - Lock status (internal use only)

Response

200 Success / Edge updated
422 Invalid data / Validation failed
404 Edge not found
403 Forbidden / No permission

Delete Edge

Permanently delete an edge connection. This action cannot be undone and will break the connection between nodes.

Response

204 Success / No Content
404 Edge not found
403 Forbidden / No permission

🎬 Media

Media files can be attached to projects, nodes, or edges. Support for images, videos, audio, and documents to enrich your interactive stories with multimedia content.

GET /api/media List all media
POST /api/media Upload new media
GET /api/media/{media} Get media details
PUT /api/media/{media} Update media metadata
PATCH /api/media/{media}/visibility Update visibility
DELETE /api/media/{media} Delete media

List Media

Retrieve all media files or filter by project, node, or edge.

Query Parameters

  • project_id - Filter by project ID (optional)
  • node_id - Filter by node ID (optional)
  • edge_id - Filter by edge ID (optional)
  • type - Filter by media type (optional)
  • page - Page number (optional)
  • per_page - Items per page (optional)

Response

200 Success / Media list
401 Unauthorized / Invalid token
403 Forbidden / No access

Upload Media

Upload a new media file and attach it to a project, node, or edge.

Required Fields

  • file - Media file to upload

Optional Fields

  • project_id - Attach to project
  • node_id - Attach to node
  • edge_id - Attach to edge
  • alt_text - Alternative text
  • description - Media description
  • visibility - public/private

Response

201 Created / Media uploaded
422 Invalid file / Validation failed
413 Payload Too Large / File too big
415 Unsupported Media Type

💬 Comments

Comments enable collaborative feedback and discussion within projects. Team members can leave notes, suggestions, and feedback to improve the narrative experience.

GET /api/comments List all comments
POST /api/comments Create new comment
GET /api/comments/{comment} Get comment details
PUT /api/comments/{comment} Update comment
DELETE /api/comments/{comment} Delete comment

List Comments

Retrieve all comments or filter by project to see discussions and feedback.

Query Parameters

  • project_id - Filter by project ID (optional)
  • user_id - Filter by author (optional)
  • status - Filter by status (optional)
  • page - Page number (optional)
  • per_page - Items per page (optional)

Response

200 Success / Comments list
401 Unauthorized / Invalid token
403 Forbidden / No access

Create Comment

Add a new comment or feedback to a project for collaborative discussion.

Required Fields

  • content - Comment text
  • project_id - Project to attach comment to

Optional Fields

  • priority - low/medium/high
  • node_id - Related node ID
  • position - UI position data
  • tags - Array of tags

Response

201 Created / Comment created
422 Invalid data / Validation failed
404 Project not found
403 Forbidden / No access

Themes

Themes define the visual styling and appearance of your storytelling projects. Each theme contains color schemes, fonts, and layout configurations.

GET /api/themes List all themes
GET /api/themes/{theme} Get theme by domain

List All Themes

Retrieve a paginated list of all available themes. This is a public endpoint and does not require authentication.

Query Parameters

  • page - Page number (optional, default: 1)
  • per_page - Items per page (optional, default: 15)

Response

200 Success / Themes list

Get Specific Theme

Retrieve detailed information about a specific theme by its domain. This is a public endpoint and does not require authentication.

URL Parameters

  • theme - The unique domain identifier of the theme (e.g., "dialog")

Response

200 Success / Theme details
404 Theme not found

✨ Designs

Designs provide specific styling configurations within themes, allowing fine-grained control over the visual presentation of story elements.

GET /api/designs List all designs
GET /api/designs/{design} Get design by domain

List All Designs

Retrieve a list of all available designs. This is a public endpoint and does not require authentication.

Response

200 Success / Designs list

Get Specific Design

Retrieve detailed configuration for a specific design by its domain identifier.

URL Parameters

  • design - The domain identifier of the design

Response

200 Success / Design details
404 Design not found