# Storylinez API Documentation (complete)

Source: https://storylinezads.com/docs
Last generated: 2026-07-20

# Storylinez API Reference

Source: https://storylinezads.com/docs
Last generated: 2026-07-20

A comprehensive API for AI video editing, motion graphics, and VFX automation - manage organizations, projects, files, sequences, and renders end to end.

> **Enterprise-Grade Solution:** Our comprehensive Stateful API delivers robust functionality, secure authentication, and seamless integration capabilities for your production environment.

## Overview

Storylinez automates video editing, motion graphics, and VFX with AI-driven workflows. The API orchestrates file storage, organization management, project handling, prompt generation, stock media access, storyboard creation, voiceover services, sequence management, rendering tasks, and user settings with enterprise-grade reliability and performance.

By seamlessly integrating with specialized internal services for preprocessing, building, and rendering, Storylinez provides an end-to-end content creation pipeline that maximizes efficiency while maintaining the highest standards of quality and security.

## Advanced Capabilities

Built on a modern technology stack with a sophisticated microservices architecture, Storylinez delivers exceptional performance and flexibility. Key advantages include:

- High-Performance Database Architecture: Leverages MongoDB for fast, scalable data storage with continuous connection monitoring and automatic recovery mechanisms.
- Intelligent Service Orchestration: Coordinates specialized internal services for preprocessing, building, and rendering, optimizing resource allocation for maximum efficiency.
- Advanced Rate Management: Implements intelligent rate limiting to ensure consistent performance and equitable resource distribution across all users.
- Enterprise-Grade Security: Protects your valuable data with robust token-based authentication and comprehensive access controls throughout the system.

## Base URL

All API endpoints are relative to the base URL:

```text
https://api.storylinezads.com
```


---

# Authentication

Source: https://storylinezads.com/docs/authentication
Last generated: 2026-07-20

Authenticate with the video generation and video editing API using API keys, headers, and secure best practices.

> **Security Notice:** All API requests must be made over HTTPS. Calls made over plain HTTP will fail. Never share your API keys in public repositories or client-side code.

The Storylinez API uses API key authentication. To access protected endpoints, you must include both your API key and API secret in the headers of your requests.

## Obtaining API Keys

To obtain API keys for the Storylinez platform, you need to:

1. Log in to your Storylinez account dashboard
2. Navigate to the Developer section
3. Click on "API Keys" and then "Generate New API Key"
4. Store both your API key and API secret securely - the secret will only be shown once

## Using Your API Keys

Include both your API key and API secret in the headers of your requests as follows:

```http
X-API-Key: api_your_generated_key
X-API-Secret: your_generated_secret
```

## API Key Management

Your API keys grant direct access to your Storylinez account and resources, so they should be treated with care:

- You can generate multiple API keys for different applications or environments
- We recommend rotating your API keys periodically for enhanced security
- You can set permissions and access levels for each API key

## Example Requests

**cURL**

```bash
curl -X GET \
  'https://api.storylinezads.com/orgs/get_all' \
  -H 'X-API-Key: api_your_generated_key' \
  -H 'X-API-Secret: your_generated_secret'
```

**JavaScript**

```javascript
fetch('https://api.storylinezads.com/orgs/get_all', {
  method: 'GET',
  headers: {
    'X-API-Key': 'api_your_generated_key',
    'X-API-Secret': 'your_generated_secret',
    'Content-Type': 'application/json'
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

**Python**

```python
import requests

url = "https://api.storylinezads.com/orgs/get_all"
headers = {
    "X-API-Key": "api_your_generated_key",
    "X-API-Secret": "your_generated_secret"
}

response = requests.get(url, headers=headers)
data = response.json()
print(data)
```

## Error Responses

If authentication fails, you'll receive one of the following error responses:

### Missing API Key

```json
{
  "error": "X-API-Key header is missing"
}
```

### Missing API Secret

```json
{
  "error": "X-API-Secret header is missing"
}
```

### Invalid API Key

```json
{
  "error": "Invalid API key or API key not found"
}
```

### Invalid API Secret

```json
{
  "error": "Invalid API secret"
}
```

### Unauthorized API Key

```json
{
  "error": "This API key is not authorized to access this resource"
}
```

## Best Practices

- Store keys securely: Never store API keys in client-side code, public repositories, or environment files that might be committed to source control.
- Use environment variables: Store your API keys as environment variables or in a secure vault service.
- Implement least privilege: Create API keys with only the permissions they need for their specific purpose.
- Rotate keys regularly: Create new API keys and deprecate old ones on a regular schedule.
- Monitor usage: Keep track of API key usage and investigate any unexpected patterns.
- Use HTTPS: Always use HTTPS to prevent key interception during transmission.


---

# API Limits & Configuration

Source: https://storylinezads.com/docs/rate-limiting
Last generated: 2026-07-20

Understand rate limits, headers, and throughput guidance for the video generation and video editing API.

> **Rate Limits Apply:** All API endpoints are subject to rate limiting to ensure fair usage and system stability.

## About Rate Limiting

The Storylinez API implements rate limiting to protect our infrastructure and ensure a consistent experience for all users. Rate limits are applied on a per-endpoint basis.

There are two types of rate limits:

- User Limits: Applied when interacting with the API through the web application or SDKs using user authentication. These limits are based on typical human interaction patterns.
- API Key Limits: Applied when using an API key for programmatic access. By default, API keys have a higher rate limit, calculated by multiplying the base user limit by a default multiplier (currently 8x).

The specific limits for each endpoint group are detailed below. Users requiring higher limits for their API keys can contact support to request an increase in their multiplier.

## Rate Limit Headers

Each API response includes headers that provide information about your current rate limit status:

| Header | Description |
| --- | --- |
| X-RateLimit-Limit | The maximum number of requests you can make per minute |
| X-RateLimit-Remaining | The number of requests remaining in the current rate limit window |
| X-RateLimit-Reset | The time at which the current rate limit window resets (Unix timestamp) |

## Rate Limit By Endpoint

Each endpoint group has a specific rate limit based on its resource intensity. Limits are shown per minute.

| Endpoint Group | User Limit | Default API Key Limit (8x) |
| --- | --- | --- |
| Server | 15 / min | 120 / min |
| Storyboard | 10 / min | 80 / min |
| Stock | 20 / min | 160 / min |
| Files | 15 / min | 120 / min |
| Organizations | 10 / min | 80 / min |
| Brands | 10 / min | 80 / min |
| Projects | 15 / min | 120 / min |
| Prompts | 15 / min | 120 / min |
| Voiceover | 10 / min | 80 / min |
| Sequence | 10 / min | 80 / min |
| Render | 8 / min | 64 / min |
| Settings | 20 / min | 160 / min |
| Utils | 15 / min | 120 / min |
| User | 30 / min | 240 / min |
| Tools | 10 / min | 80 / min |
| Search | 10 / min | 80 / min |
| Subscription | 15 / min | 120 / min |
| API Keys | 15 / min | 120 / min |

> **API Key Multiplier:** The "Default API Key Limit" shown uses the standard 8x multiplier. If your application requires higher throughput, please contact support to discuss increasing the multiplier for your specific API key.

> **Rate Limit Exceeded:** If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

## Rate Limit Exceeded Response

When you exceed the rate limit, you'll receive a 429 Too Many Requests response with the following body:

```json
{
  "error": "Rate limit exceeded",
  "message": "Too many requests, please try again later.",
  "retry_after": 60
}
```

## Storage Configuration

The following storage limits are applied:

| Setting | Value |
| --- | --- |
| Maximum Job History | 30 records |
| Maximum Storyboard History for Context | 10 items |
| Maximum Sequence History for Context | 10 items |
| Maximum Upload Size | 1 GB |

## File Processing Configuration

For uploaded files, the system automatically generates lower quality streamable versions with the following specifications:

### Video Compression

| Setting | Value |
| --- | --- |
| Width | 1280 pixels |
| Height | 720 pixels |
| Framerate | 30 FPS |
| Bitrate | 2000k |
| Processing Timeout | 300 seconds (5 minutes) |

### Image Compression

| Setting | Value |
| --- | --- |
| Width | 1280 pixels |
| Height | 720 pixels |
| Quality | 80% |

## Allowed File Formats

| File Type | Supported Formats |
| --- | --- |
| Video | mp4 |
| Audio | mp3, wav |
| Image | jpg, jpeg, png |


---

# Quickstart Guide

Source: https://storylinezads.com/docs/guides/quickstart
Last generated: 2026-07-20

Quickstart the Storylinez video generation and video editing API - authenticate, create projects, and build AI videos fast.

> **Getting Started:** This guide provides a comprehensive, step-by-step explanation of how to use the Storylinez API to create AI-generated videos. We'll cover the essential setup, core concepts, and the video creation pipeline.

## Prerequisites: What You Need First

Before you begin interacting with the Storylinez API, ensure you have the following essentials:

- A Storylinez Account: Your account is your gateway to the platform. It's where you manage your profile, billing, and generate the API credentials (key and secret) to authenticate your requests.
- Basic Knowledge of REST APIs: Understanding HTTP methods (POST, GET, PUT/PATCH, DELETE), request headers, and JSON is crucial for interacting with the API effectively.
- A Tool to Make API Requests: Postman for graphical testing, cURL for command-line scripting, or a programming language with an HTTP library (e.g. Python requests).

## Step 1: Authentication

Goal: Securely identify yourself or your application to the Storylinez API, proving you have permission to perform actions.

- API Key: Your unique username for the API - identifies which application or user is making the request.
- API Secret: Your password for the API - a confidential token used to verify the authenticity of the request.
- How to Obtain: Both are generated within your Storylinez account settings, typically in a dedicated API or Developer section.

For every call, include the X-API-Key and X-API-Secret headers. Treat your secret with the utmost care - never expose it in client-side code or public repositories.

## Step 2: Obtain Your Organization ID

Goal: Identify the specific workspace (Organization) within Storylinez where you want to create your video projects.

Organizations provide structure - a dedicated workspace for a client, department, or purpose. All API actions happen within the context of a specific organization. Create and manage organizations through the Storylinez UI, then find the org_id in settings and save it for the next step.

## Step 3: Create a Project

Goal: Initiate a new, specific video creation effort within a designated organization.

A project is a container for everything related to one video: the prompt, generated storyboard, uploaded media, voiceover choices, sequence arrangements, and final rendered output. Make a POST request to the project creation endpoint with the org_id, then save the returned project_id - you'll use it in almost all subsequent calls.

## Step 4: Retrieve Your Projects

Goal: Get a list of existing video projects associated with a specific organization.

Useful to verify a project exists, recover a project_id, build dashboards, or manage projects programmatically. Make a GET request to the projects endpoint with your organization ID; the API returns JSON describing each project.

## Step 5: Understanding the Video Building Pipeline

This is the core process where your ideas are transformed into a video using Storylinez's AI capabilities. The stages are generally sequential and depend on each other:

1. Project (and Files): The container for your effort - holds settings, associated media files, and links all subsequent components. Files are the raw visual/audio ingredients.
2. Prompt: Your natural-language instruction to the AI describing the video you want. The most critical input - it sets topic, tone, style, audience, and length.
3. Storyboard: An AI-generated plan/blueprint based on your prompt and media, following a specific JSON schema. Review and modify via API or UI.
4. Voiceover: The narration track. Upload your own file or use Text-to-Speech to generate a synthetic voiceover.
5. Sequence: Arranging and refining order, timing, transitions, and precise media usage based on storyboard and voiceover. Follows the Sequence Schema.
6. Render: The final step - Storylinez compiles all inputs into a single video file. Often asynchronous, with status checks available.

Note: Files (media assets) are associated with the Project (Step 1) and used throughout the process, especially during Storyboard generation and Sequencing.

## Next Steps & Where to Go from Here

- Project Management: Explore endpoints to rename, duplicate, or delete projects in the Projects API.
- Best Practices Guide: Consult the Best Practices guide for tips on effective prompts and getting the most out of the AI.
- Explore the wider API reference for more operations.


---

# API Best Practices

Source: https://storylinezads.com/docs/guides/best-practices
Last generated: 2026-07-20

Best practices for integrating the Storylinez video generation and video editing API - reliability, security, and performance tips.

> **Optimize Your Integration:** Follow these best practices to ensure optimal performance, reliability, and security when using the Storylinez API.

### Rate Limiting

- Monitor rate limit headers: Keep track of your remaining requests to avoid hitting the rate limit. Adjust your request rate accordingly.
- Implement exponential backoff: When you receive a 429 response, wait before retrying and increase the wait time for consecutive failures.

### Caching

- Cache responses when possible: To reduce API calls, cache responses that don't change frequently.
- Use ETags and conditional requests: Leverage HTTP caching mechanisms to avoid transferring unchanged resources.

### Performance Optimization

- Batch operations: Where applicable, use batch operations to reduce the number of API calls.
- Optimize file sizes: Compress and optimize files before uploading to reduce processing time.
- Use pagination: When retrieving large datasets, use pagination to improve response times.

### Security

- Secure your API keys: Never expose API keys in client-side code or public repositories.
- Use HTTPS: Always use HTTPS for all API requests.
- Implement proper authentication: Set up proper authentication flows for your application.

### Error Handling

- Graceful error handling: Always handle API errors gracefully to provide a good user experience.
- Log errors: Keep detailed logs of API errors for troubleshooting.
- Implement timeout handling: Set appropriate timeouts for API requests and handle timeout errors.

### Documentation

- Stay current: Regularly check the documentation for updates, deprecations, and new features.
- Use client libraries: When available, use our official client libraries to simplify integration.
- Test in sandbox: Test your integration in a sandbox environment before going to production.

## Advanced Best Practices

When building a production application with the Storylinez API, consider these additional best practices:

### Implement Proper Retry Logic

When you encounter transient errors (like rate limits or temporary server issues), implement a retry strategy:

- Start with a small delay (e.g. 1 second)
- Use exponential backoff to increase the delay for consecutive failures
- Add a small random jitter to prevent thundering herd problems
- Set a maximum number of retries to avoid infinite loops

### Optimize Uploads and Downloads

For file operations, consider these optimizations:

- Use chunked uploads for large files
- Implement resumable uploads for better reliability
- Compress files before upload when appropriate
- Consider using background tasks for large file operations

### Implement Webhooks

For long-running operations, consider using webhooks instead of polling:

- Set up a secure endpoint to receive webhook notifications
- Implement proper verification of webhook payloads
- Process webhook events asynchronously
- Implement idempotent handling for webhook events (to handle duplicates)


---

# User API

Source: https://storylinezads.com/docs/api/user
Last generated: 2026-07-20

Manage user profiles, subscriptions, storage usage, and developer access within organizations.

Base route: `/user` (relative to `https://api.storylinezads.com`)

## User Profile

Retrieve user profile information from the authentication provider (Clerk).

### Get Current User Profile

`GET https://api.storylinezads.com/me`

Retrieves the authenticated user's own profile data, filtered for frontend safety. Data is sourced directly from the Clerk API.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | no | Your API key. |
| X-API-Secret | no | Your API secret. |

**Response 200** — OK - User profile data retrieved successfully.

```json
{
  "success": true,
  "data": {
    "id": "user_2ax...",
    "username": "testuser",
    "first_name": "Test",
    "last_name": "User",
    "image_url": "https://img.clerk.com/...",
    "has_image": true,
    "email_addresses": [
      {
        "email_address": "test@example.com",
        "id": "idn_2ax...",
        "verification_status": "verified"
      }
    ],
    "phone_numbers": [
      {
        "phone_number": "+1234567890",
        "id": "idn_2ay..."
      }
    ],
    "public_metadata": {},
    "created_at": 1678886400000,
    "updated_at": 1678886400000,
    "last_sign_in_at": 1678886400000,
    "profile_image_url": "https://www.gravatar.com/avatar/..."
  }
}
```

**Response 401** — Unauthorized - Authentication failed or user ID missing.

```json
{ "error": "User ID not found in token" }
```

**Response 500** — Internal Server Error - Failed to fetch data or unexpected error.

```json
{ "error": "Internal server error" }
```

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| success | boolean | Indicates if the request was successful (always true on 200 OK). |
| data | object | Object containing the user's profile information. |
| data.id | string | Unique identifier for the user (from Clerk). |
| data.username | string | User's username (can be null). |
| data.first_name | string | User's first name. |
| data.last_name | string | User's last name. |
| data.image_url | string | URL to the user's profile image provided by Clerk. |
| data.has_image | boolean | Indicates if the user has uploaded a profile image via Clerk. |
| data.email_addresses | array | Array of email objects associated with the user. |
| data.email_addresses[].email_address | string | The email address string. |
| data.email_addresses[].id | string | Unique identifier for this email record in Clerk. |
| data.email_addresses[].verification_status | string | Status of email verification (e.g., 'verified'). |
| data.phone_numbers | array | Array of phone number objects associated with the user. |
| data.phone_numbers[].phone_number | string | The phone number string. |
| data.phone_numbers[].id | string | Unique identifier for this phone record in Clerk. |
| data.public_metadata | object | Custom public metadata object set for the user in Clerk. |
| data.created_at | number | Timestamp (milliseconds since epoch) when the user was created in Clerk. |
| data.updated_at | number | Timestamp (milliseconds since epoch) when the user was last updated in Clerk. |
| data.last_sign_in_at | number | Timestamp (milliseconds since epoch) when the user last signed in via Clerk. |
| data.profile_image_url | string | URL to the user's profile image (often the same as image_url or a Gravatar URL). |

**Usage notes**

- Use X-API-Key and X-API-Secret headers for authentication.
- Returns comprehensive profile information for the *currently authenticated* user.
- Use this endpoint when you need to access the current user's private information for display in their profile settings, dashboard, etc.
- The returned data includes potentially sensitive details like email addresses and phone numbers, which are *only* available for the authenticated user's own profile.
- To display user information in your UI, you can use the `username`, `first_name`, `last_name`, and `profile_image_url` fields.
- This endpoint serves as the foundation for personalizing your application's experience based on user attributes.
- For security reasons, some sensitive user data might be filtered out from the raw Clerk response, but this endpoint provides the most detail available for the current user.
- You can use this endpoint in combination with `/subscription` (passing the relevant `org_id`) to show user-specific subscription details alongside their profile.
- Rate limits for this endpoint are determined by your subscription tier; cache this data when appropriate to reduce API calls, but refresh it periodically (e.g., on page load or user action) to ensure up-to-date information.
- The `email_addresses[].verification_status` can be used to prompt users to verify their email addresses if needed.
- The `public_metadata` field can contain additional user attributes that are safe to expose to the frontend, configured within Clerk.
- This endpoint is meant *only* for fetching the current user's data - use `/user/{user_id}` for retrieving public information about *other* users.
- When building user profiles, ensure you handle cases where optional fields like `username`, `first_name`, or `last_name` might be null or empty.
- Consider using the `last_sign_in_at` timestamp (converted from milliseconds) to display 'last seen' information in your UI.
- The `id` field is the user's unique Clerk ID (`user_...`) and is crucial for linking data across different endpoints and collections (like `/storage` or `/subscription`).
- Use the `has_image` flag to decide whether to show the `profile_image_url` or a default avatar.
- This endpoint directly reflects data from Clerk; changes made in Clerk's user management will be reflected here after a short delay or upon refresh.

### Get Other User Profile

`GET https://api.storylinezads.com/user/{user_id}`

Retrieves limited public information about another user identified by their Clerk User ID. Data is sourced directly from the Clerk API.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | no | Your API key. |
| X-API-Secret | no | Your API secret. |

**Response 200** — OK - Public user data retrieved successfully.

```json
{
  "success": true,
  "data": {
    "id": "user_0123456789abcdef",
    "username": "otheruser",
    "first_name": "Other",
    "last_name": "User",
    "image_url": "https://img.clerk.com/...",
    "public_metadata": {}
  }
}
```

**Response 404** — Not Found - The specified user_id does not exist.

```json
{ "success": false, "error": "Error 404: {\"errors\":[{\"code\":\"resource_not_found\",\"long_message\":\"Could not find the resource you are looking for.\",\"message\":\"Resource not found\"}]}" }
```

**Response 500** — Internal Server Error - Failed to fetch data or unexpected error.

```json
{ "error": "Internal server error" }
```

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| success | boolean | Indicates if the request was successful. |
| data | object | Object containing the public user information. |
| data.id | string | Unique identifier for the user (from Clerk). |
| data.username | string | User's username (can be null). |
| data.first_name | string | User's first name. |
| data.last_name | string | User's last name. |
| data.image_url | string | URL to the user's profile image provided by Clerk. |
| data.public_metadata | object | Custom public metadata object set for the user in Clerk (only includes publicly viewable data). |

**Usage notes**

- This endpoint returns only a *limited subset* of public information about other users.
- It *does not* expose private data such as email addresses or phone numbers.
- Use this endpoint when displaying information about collaborators, team members, content authors, or other users within your application where only public details are needed.
- The `user_id` path parameter must be a valid Clerk user ID starting with 'user_'.
- Unlike the `/me` endpoint, this only returns fields considered safe for public consumption.
- This endpoint is useful for building user directories, team member lists, attribution features (e.g., 'created by'), or displaying user avatars and names in comments/feeds.
- You can use the returned `image_url` to display user avatars in your interface.
- `public_metadata` can contain additional user attributes that the user or system administrator has chosen to make public via Clerk settings.
- If you need to display information for multiple users (e.g., a list of organization members), consider using the `/users/batch` endpoint instead for better performance.
- For users not found in the system, you'll receive a 404 error from the Clerk API, which is propagated by this endpoint.
- When implementing user mentions or tagging features, this endpoint can be used to validate the `user_id` and retrieve the display name (`first_name`, `last_name`, or `username`).
- Use this endpoint for showing authorship of content or collaborative work contributions.
- The data returned is intentionally limited to protect user privacy while providing enough information for common collaboration and display scenarios.
- When building user profiles for display *to others*, always use this endpoint rather than `/me` to ensure privacy.
- Consider implementing client-side caching of frequently accessed public user profiles (e.g., team members) to minimize API calls and improve performance.
- Authentication is still required to use this endpoint, ensuring only logged-in users can look up other users.
- The structure of `public_metadata` depends on how it's configured in your Clerk instance.

### Get Multiple Users (Batch)

`POST https://api.storylinezads.com/users/batch`

Retrieves limited public information about multiple users in a single request. This is more efficient than making individual calls to `/user/{user_id}` when you need to fetch data for multiple users. Data is sourced directly from the Clerk API.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | no | Your API key. |
| X-API-Secret | no | Your API secret. |
| Content-Type | yes | Must be set to application/json for the request body |

**Request body**

```json
[object Object]
```

**Response 200** — OK - Batch user data retrieved successfully. Returns data for all requested users, including errors for individual users if they don't exist.

```json
{
  "success": true,
  "data": {
    "user_0123456789abcdef": {
      "id": "user_0123456789abcdef",
      "username": "user1",
      "first_name": "John",
      "last_name": "Doe",
      "image_url": "https://img.clerk.com/...",
      "public_metadata": {}
    },
    "user_fedcba9876543210": {
      "id": "user_fedcba9876543210",
      "username": "user2",
      "first_name": "Jane",
      "last_name": "Smith",
      "image_url": "https://img.clerk.com/...",
      "public_metadata": {}
    },
    "user_abcdef0123456789": {
      "error": "Error 404",
      "success": false
    }
  }
}
```

**Response 400** — Bad Request - Invalid request body or too many user IDs.

```json
{ "error": "Request must include user_ids array" }
```

**Response 400** — Bad Request - Too many user IDs in request.

```json
{ "error": "Maximum of 50 users can be fetched in a single request" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "Authentication required" }
```

**Response 500** — Internal Server Error - Failed to fetch data or unexpected error.

```json
{ "error": "Internal server error" }
```

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| success | boolean | Indicates if the overall request was successful (always true on 200 OK). |
| data | object | Object mapping user IDs to their respective user data or error information. |
| data.{user_id} | object | User data object keyed by the requested user ID, or error object if the user was not found. |
| data.{user_id}.id | string | Unique identifier for the user (from Clerk), present for successful responses. |
| data.{user_id}.username | string | User's username (can be null), present for successful responses. |
| data.{user_id}.first_name | string | User's first name, present for successful responses. |
| data.{user_id}.last_name | string | User's last name, present for successful responses. |
| data.{user_id}.image_url | string | URL to the user's profile image provided by Clerk, present for successful responses. |
| data.{user_id}.public_metadata | object | Custom public metadata object set for the user in Clerk, present for successful responses. |
| data.{user_id}.error | string | Error message if the user could not be retrieved (e.g., user not found). |
| data.{user_id}.success | boolean | Indicates if this specific user's data was retrieved successfully. Present only for error cases and set to false. |

**Usage notes**

- This endpoint is designed for efficiently fetching public information about multiple users in a single request.
- Use this instead of multiple individual `/user/{user_id}` calls when you need to display information for multiple users (e.g., team member lists, organization rosters, comment authors).
- The maximum number of user IDs that can be requested in a single call is 50. For larger sets, split into multiple requests.
- Like the `/user/{user_id}` endpoint, this only returns *limited public information* and does not expose private data such as email addresses or phone numbers.
- Each user in the response is keyed by their user ID, making it easy to map results back to your original request.
- If a user ID doesn't exist in Clerk, an error object will be returned for that specific user, but the overall request will still succeed (200 OK).
- This endpoint is particularly useful for displaying user avatars, names, and metadata in lists, grids, or collaborative interfaces.
- Consider implementing client-side caching of the results to avoid repeated API calls for the same users.
- The response maintains the same privacy protections as the individual user endpoint - only public-safe fields are returned.
- Rate limits apply to this endpoint, so consider the batch size and frequency of your requests based on your subscription tier.
- When building features like user mentions, team member displays, or content attribution, this endpoint provides an efficient way to resolve multiple user IDs to displayable information.
- Empty arrays or arrays with no valid user IDs will still return a successful response with an empty or minimal data object.
- Authentication is required to use this endpoint, ensuring only logged-in users can perform batch user lookups.
- The structure of `public_metadata` for each user depends on how it's configured in your Clerk instance.
- Consider the rate limiting implications when using this endpoint frequently - batch requests count as a single API call but may have internal rate limits based on the number of users requested.
- This endpoint is ideal for initial data loading when rendering user interfaces that need to display multiple users simultaneously.

## Storage Management

Monitor storage usage for individual users and entire organizations.

### Get User Storage Usage

`GET https://api.storylinezads.com/storage`

Retrieves storage usage information (in bytes) for the *authenticated user* within a specific organization. Requires the user to be a member or owner of the organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | no | Your API key. |
| X-API-Secret | no | Your API secret. |

**Response 200** — OK - Storage usage retrieved successfully.

```json
{
  "storage_used": 15728640,
  "user_id": "user_abcdef123456",
  "org_id": "org_0123456789abcdef"
}
```

**Response 400** — Bad Request - Organization ID parameter is missing.

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User does not have permission for the specified organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Failed to query database or unexpected error.

```json
{ "error": "An unexpected error occurred" }
```

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| storage_used | number | Storage space used by the authenticated user within the specified organization, measured in bytes. Data is retrieved from the `profile.orgs` collection. |
| user_id | string | Identifier of the authenticated user making the request. |
| org_id | string | Identifier of the organization for which storage was queried. |

**Usage notes**

- The `org_id` query parameter is mandatory and must be a valid organization ID (e.g., `org_...`) to which the authenticated user belongs.
- Storage usage is reported in raw bytes.
- If a storage profile document doesn't exist for the user in the specified organization within the backend database (`profile.orgs`), one will be created automatically with `storage_used` set to 0, and this zero value will be returned.
- Use this endpoint to track *individual* storage usage against subscription limits for the *current user*.
- Combine this endpoint's `storage_used` value with the `storage.limit_bytes` from the `/subscription` endpoint (using the same `org_id`) to show users how much of their personal or organizational storage allocation they've used.
- Storage usage is typically updated after operations like file uploads, deletions, or content processing that affect stored data size.
- Consider displaying storage usage to the user in more friendly units (KB, MB, GB) by dividing the `storage_used` value appropriately (e.g., GB = bytes / (1024 * 1024 * 1024)).
- For multi-member organizations, users can *only* retrieve their *own* storage usage with this endpoint. They cannot see other members' usage via this route.
- Organization administrators or users needing an overview of the entire organization's storage should use the `/org/storage` endpoint instead.
- Storage measurements reflect the exact byte counts recorded in the database.
- This endpoint is useful for displaying personal storage usage indicators or progress bars in user dashboards or settings pages.
- Regular polling of this endpoint (e.g., after file operations) can keep the UI updated, but be mindful of rate limits.
- When implementing file upload features, you could potentially check this endpoint (along with `/subscription`) first to estimate if sufficient storage remains, although checks during the upload process itself are more robust.
- This endpoint focuses solely on the user's storage footprint within one specific organization context.
- The `user_id` and `org_id` in the response confirm the context of the returned `storage_used` value.

### Get Organization Storage Usage

`GET https://api.storylinezads.com/org/storage`

Retrieves total storage usage information for an entire organization. Optionally includes a breakdown by user. Requires the user to be a member or owner of the organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | no | Your API key. |
| X-API-Secret | no | Your API secret. |

**Response 200** — OK (Without Breakdown) - Total organization storage usage retrieved.

```json
{
  "org_id": "org_0123456789abcdef",
  "total_storage_used": 52428800,
  "user_count": 3
}
```

**Response 200** — OK (With Breakdown) - Total usage and per-user breakdown retrieved.

```json
{
  "org_id": "org_0123456789abcdef",
  "total_storage_used": 52428800,
  "user_count": 3,
  "breakdown": [
    {
      "user_id": "user_member1",
      "org_id": "org_0123456789abcdef",
      "storage_used": 15728640
    },
    {
      "user_id": "user_owner",
      "org_id": "org_0123456789abcdef",
      "storage_used": 31457280
    },
    {
      "user_id": "user_member2",
      "org_id": "org_0123456789abcdef",
      "storage_used": 5242880
    }
  ]
}
```

**Response 400** — Bad Request - Organization ID parameter is missing.

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User does not have permission for the specified organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Failed to query database or unexpected error.

```json
{ "error": "An unexpected error occurred" }
```

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| org_id | string | Identifier of the organization queried. |
| total_storage_used | number | Total storage space used (in bytes) by all users combined within the organization. Calculated by summing `storage_used` from all relevant documents in `profile.orgs`. |
| user_count | number | The number of user profile documents found in `profile.orgs` for this organization that contribute to the total storage. |
| breakdown | array | Array of user storage objects, included *only* if `include_breakdown=true` was passed in the query. |
| breakdown[].user_id | string | Identifier of a specific user within the organization. |
| breakdown[].org_id | string | Identifier of the organization (same as the top-level `org_id`). |
| breakdown[].storage_used | number | Storage space used (in bytes) by this specific user in this organization. |

**Usage notes**

- The `org_id` query parameter is mandatory and must correspond to an organization the user belongs to.
- Total storage (`total_storage_used`) is reported in bytes.
- Set `include_breakdown=true` in the query string to receive the `breakdown` array containing individual user storage details.
- This endpoint is particularly useful for organization administrators or owners to monitor overall storage consumption and manage resources.
- The `breakdown` option allows identification of which users are consuming the most storage, helping with resource allocation or identifying potential cleanup needs.
- When building organization dashboards or administrative panels, use this endpoint to display aggregate storage metrics and, optionally, the user distribution.
- For large organizations, the response size may become significant when `include_breakdown` is true. Consider implementing pagination or summarization in your UI if displaying the full breakdown.
- Use this information to identify opportunities for storage optimization, make decisions about subscription upgrades, or enforce internal quotas.
- Compare `total_storage_used` against the organization's tier limits (potentially inferred from the owner's `/subscription` details or a separate org-level subscription endpoint if available) to monitor overall capacity.
- The storage breakdown can help identify inactive users who are still consuming storage resources.
- For regular monitoring, consider scheduling periodic checks (respecting rate limits) and setting up alerts when `total_storage_used` approaches the organization's limit.
- Storage usage visualization (like pie charts or bar graphs) can be effectively built using the `breakdown` data to show relative usage per user.
- This endpoint provides a holistic view of organizational storage use, crucial for capacity planning and cost management.
- The `user_count` indicates how many members have recorded storage usage within the organization.
- Use the breakdown data to implement fair usage policies or chargeback models within your organization if applicable.
- Consider automated notifications to organization admins when total storage reaches predefined thresholds (e.g., 80%, 90%) of the limit.

## Subscription Management

Monitor subscription details, usage limits (projects, storage, content processing), and billing periods for the user within an organization.

### Get Subscription Details

`GET https://api.storylinezads.com/subscription`

Retrieves detailed subscription status and usage information for the *authenticated user* within a specific organization. Requires organization membership or ownership.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | no | Your API key. |
| X-API-Secret | no | Your API secret. |

**Response 200** — OK - Comprehensive subscription and usage details retrieved.

```json
{
  "subscription_id": "60c7c8d...",
  "org_id": "org_0123456789abcdef",
  "user_id": "user_abcdef123456",
  "tier": 2,
  "plan_name": "Pro",
  "period": {
    "current_period_start": "2023-01-01T00:00:00Z",
    "current_period_end": "2023-02-01T00:00:00Z",
    "auto_renew": true
  },
  "projects": {
    "monthly_limit": 50,
    "monthly_used": 25,
    "monthly_remaining": 25,
    "daily_limit": 10,
    "daily_used": 5,
    "daily_remaining": 5,
    "extra_projects": 0,
    "last_project_date": "2023-01-15T12:30:45Z"
  },
  "storage": {
    "used_bytes": 5368709120,
    "used_gb": 5.0,
    "limit_bytes": 10737418240,
    "limit_gb": 10.0,
    "percentage_used": 50.0
  },
  "content_processing": {
    "total_processed_bytes": 2147483648,
    "total_processed_gb": 2.0,
    "period_processed_bytes": 1073741824,
    "period_processed_gb": 1.0,
    "period_limit_bytes": 5368709120,
    "period_limit_gb": 5.0,
    "percentage_used": 20.0
  },
  "reset_schedules": {
    "daily_project_count_resets": "Daily at midnight UTC",
    "monthly_project_count_resets": "At the end of billing period",
    "content_processing_resets": "At the end of billing period"
  }
}
```

**Response 400** — Bad Request - Organization ID parameter is missing.

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User does not have permission for the specified organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Failed to retrieve data or unexpected error.

```json
{ "error": "An unexpected error occurred" }
```

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| subscription_id | string | The MongoDB `_id` of the subscription document (as a string). |
| org_id | string | Organization identifier associated with this subscription context. |
| user_id | string | User identifier associated with this subscription context. |
| tier | number | Numeric identifier for the subscription tier (e.g., 1: Free, 2: Pro, 3: Team). Determined by `subscription_manager`. |
| plan_name | string | Human-readable name of the subscription plan (e.g., 'Free', 'Pro', 'Team'). Determined by `subscription_manager`. |
| period | object | Information about the current billing period. |
| period.current_period_start | string | ISO 8601 timestamp string indicating the start of the current billing period. From the subscription document. |
| period.current_period_end | string | ISO 8601 timestamp string indicating the end of the current billing period. From the subscription document. |
| period.auto_renew | boolean | Indicates if the subscription is set to automatically renew at the period end. From the subscription document. |
| projects | object | Details on project creation usage and limits. |
| projects.monthly_limit | number | Maximum number of projects allowed per billing period for this tier. Determined by `subscription_manager`. |
| projects.monthly_used | number | Number of projects created by the user in the current billing period (`period_project_count` from subscription document). |
| projects.monthly_remaining | number | Calculated projects remaining in the current billing period (`monthly_limit` - `monthly_used`). |
| projects.daily_limit | number | Maximum number of projects allowed per day (UTC) for this tier. Determined by `subscription_manager`. |
| projects.daily_used | number | Number of projects created by the user today (UTC) (`daily_project_count` from subscription document, reset daily). |
| projects.daily_remaining | number | Calculated projects remaining for today (UTC) (`daily_limit` - `daily_used`). |
| projects.extra_projects | number | Number of projects created beyond the monthly limit (applicable primarily to Team tier). From the subscription document. |
| projects.last_project_date | string | ISO 8601 timestamp string of the last project creation time by this user in this org. From the subscription document. |
| storage | object | Details on storage usage and limits. |
| storage.used_bytes | number | Current storage used by the user in this organization (in bytes). From `profile.orgs` via `subscription_manager`. |
| storage.used_gb | number | Storage used converted to gigabytes (bytes / 1024^3). |
| storage.limit_bytes | number | Storage limit for this tier (in bytes). Determined by `subscription_manager`. |
| storage.limit_gb | number | Storage limit converted to gigabytes (bytes / 1024^3). |
| storage.percentage_used | number | Calculated percentage of the storage limit currently used ((`used_bytes` / `limit_bytes`) * 100). Returns 0 if limit is 0. |
| content_processing | object | Details on content processing usage and limits. |
| content_processing.total_processed_bytes | number | Total content processed by the user across all time (lifetime) in this org (in bytes). From the subscription document (`content_processed_bytes`). |
| content_processing.total_processed_gb | number | Total content processed (lifetime) converted to gigabytes. |
| content_processing.period_processed_bytes | number | Content processed by the user in the current billing period in this org (in bytes). From the subscription document (`period_content_processed_bytes`). |
| content_processing.period_processed_gb | number | Period content processed converted to gigabytes. |
| content_processing.period_limit_bytes | number | Content processing limit for the current billing period for this tier (in bytes). Determined by `subscription_manager`. |
| content_processing.period_limit_gb | number | Period content processing limit converted to gigabytes. |
| content_processing.percentage_used | number | Calculated percentage of the period's content processing limit currently used ((`period_processed_bytes` / `period_limit_bytes`) * 100). Returns 0 if limit is 0. |
| reset_schedules | object | Human-readable information on when usage counters reset. |
| reset_schedules.daily_project_count_resets | string | Indicates daily project counts reset at midnight UTC. |
| reset_schedules.monthly_project_count_resets | string | Indicates monthly project counts and extra projects reset at the end of the billing period (based on `period.current_period_end`). |
| reset_schedules.content_processing_resets | string | Indicates period content processing usage resets at the end of the billing period (based on `period.current_period_end`). |

**Usage notes**

- The `org_id` query parameter is mandatory and must be an organization the user belongs to.
- This is the most comprehensive endpoint for understanding a user's current subscription status and usage within a specific organization.
- It provides details on the plan (`tier`, `plan_name`), billing cycle (`period`), project limits/usage (`projects`), storage limits/usage (`storage`), and content processing limits/usage (`content_processing`).
- Use this endpoint as the primary data source for building subscription dashboards or usage overview pages for users.
- The `tier` value maps to subscription levels (e.g., 1=Free, 2=Pro, 3=Team), which dictates the various limits.
- Storage and content processing values are provided in both bytes and gigabytes (GB, using 1024^3 conversion) for display flexibility.
- The `percentage_used` fields (for storage and content processing) are convenient for creating progress bars or visual indicators.
- `reset_schedules` provides user-friendly text explaining when daily and monthly/period-based limits reset, helping users manage their usage.
- Project limits (`projects`) include both daily and monthly restrictions. Display `daily_remaining` and `monthly_remaining` clearly to users.
- For Business plan subscribers (`tier: 3`), check `projects.extra_projects`. If it's greater than 0, use the `/projects/extras` endpoint to show the associated cost.
- Use `period.auto_renew` to inform users if their subscription will continue automatically.
- When approaching limits (e.g., `storage.percentage_used` > 80%), consider implementing UI warnings or notifications.
- The `projects.last_project_date` helps users recall their recent activity.
- This endpoint combines data from the user's subscription record and their storage profile (`profile.orgs`) via the `subscription_manager` utility.
- Display the `period.current_period_end` date prominently so users know when their current cycle ends and limits reset.
- Consider showing countdown timers to the daily reset time (midnight UTC) for users nearing their `projects.daily_limit`.
- Monitor `content_processing.percentage_used` for users with high processing needs.
- Create visual alerts (e.g., color changes) when any usage metric exceeds certain thresholds (e.g., 80%, 95%).
- Ensure your UI adapts to show appropriate limits based on the `tier` value, as limits vary significantly between plans.
- The `subscription_id` can be useful for support purposes or linking to external billing systems if needed.

### Get Project Usage

`GET https://api.storylinezads.com/projects/usage`

Retrieves project-specific usage information for the *authenticated user* within an organization, focusing on daily and monthly limits and current counts. Requires organization membership or ownership.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | no | Your API key. |
| X-API-Secret | no | Your API secret. |

**Response 200** — OK - Project usage details retrieved successfully.

```json
{
  "org_id": "org_0123456789abcdef",
  "user_id": "user_abcdef123456",
  "tier": 2,
  "plan_name": "Pro",
  "monthly_limit": 50,
  "monthly_used": 25,
  "monthly_remaining": 25,
  "daily_limit": 10,
  "daily_used": 5,
  "daily_remaining": 5,
  "last_project_date": "2023-01-15T12:30:45Z",
  "period_start": "2023-01-01T00:00:00Z",
  "period_end": "2023-02-01T00:00:00Z",
  "reset_schedules": {
    "daily_count_resets": "Daily at midnight UTC",
    "monthly_count_resets": "At the end of billing period"
  }
}
```

**Response 400** — Bad Request - Organization ID parameter is missing.

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User does not have permission for the specified organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Failed to retrieve data or unexpected error.

```json
{ "error": "An unexpected error occurred" }
```

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| org_id | string | Organization identifier for context. |
| user_id | string | User identifier for context. |
| tier | number | Numeric value representing subscription tier (e.g., 1: Free, 2: Pro, 3: Team). |
| plan_name | string | Human-readable name of the subscription plan. |
| monthly_limit | number | Maximum number of projects allowed per billing period for this tier. |
| monthly_used | number | Number of projects created by the user in the current billing period. |
| monthly_remaining | number | Calculated remaining projects allowed in the current billing period. |
| daily_limit | number | Maximum number of projects allowed per day (UTC) for this tier. |
| daily_used | number | Number of projects created by the user today (UTC). |
| daily_remaining | number | Calculated remaining projects allowed today (UTC). |
| last_project_date | string | ISO 8601 timestamp string of when the last project was created by this user in this org. |
| period_start | string | ISO 8601 timestamp string for the start of the current billing period. |
| period_end | string | ISO 8601 timestamp string for the end of the current billing period. |
| reset_schedules | object | Information about when project count limits reset. |
| reset_schedules.daily_count_resets | string | Indicates when daily project limits reset (typically 'Daily at midnight UTC'). |
| reset_schedules.monthly_count_resets | string | Indicates when monthly project limits reset (typically 'At the end of billing period' based on `period_end`). |

**Usage notes**

- The `org_id` query parameter is mandatory and must be an organization the user belongs to.
- Provides a focused view of project usage metrics, including daily and monthly limits and current counts. It's a subset of the data available from `/subscription`.
- This endpoint is more lightweight than `/subscription` if you *only* need project-related limit and usage information.
- Use this endpoint specifically when you need to display project limits or remaining counts, for example, right before a user attempts to create a new project.
- The `daily_remaining` and `monthly_remaining` values are key for showing users how many more projects they can create within the respective timeframes.
- Display clear warnings or disable creation buttons when `daily_remaining` or `monthly_remaining` is zero or low.
- The `last_project_date` helps track user activity related to project creation.
- Different subscription tiers (`tier`) have different project limits, which are reflected in the `monthly_limit` and `daily_limit` values.
- `period_start` and `period_end` define the billing cycle during which the `monthly_limit` applies.
- `reset_schedules` information helps users understand when their daily and monthly project creation allowances will refresh.
- For users who frequently create projects, consider implementing a countdown timer in the UI showing time remaining until the next daily reset (midnight UTC).
- Use this data to build a project creation scheduling feature if users often hit their limits.
- Combined with `/projects/extras`, you can inform Business plan users (`tier: 3`) about their ability to exceed the `monthly_limit` (at cost) if `monthly_remaining` is zero.
- Implement UI color-coding for `daily_remaining` and `monthly_remaining` values (e.g., green/yellow/red) to provide quick visual feedback.
- Consider calculating and displaying the user's average daily or weekly project creation rate based on historical usage (if tracked elsewhere) to help them manage their monthly allocation.
- Use the `period_start` and `period_end` values to create a visual timeline or calendar representation of the current billing period.
- For Free tier users, emphasize the upgrade path when they are frequently approaching their project limits.
- Implement automatic notifications (UI or email) when users reach a certain percentage (e.g., 80%) of their daily or monthly limits.
- This endpoint relies on the same underlying data as `/subscription`, accessed via `subscription_manager`.

### Get Extra Projects Information

`GET https://api.storylinezads.com/projects/extras`

Retrieves information about extra projects created beyond the monthly subscription limit, including the count and estimated cost. Primarily relevant for Team tier users. Requires organization membership or ownership.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | no | Your API key. |
| X-API-Secret | no | Your API secret. |

**Response 200** — OK - Extra projects information retrieved.

```json
{
  "org_id": "org_0123456789abcdef",
  "user_id": "user_abcdef123456",
  "tier": 3,
  "plan_name": "Team",
  "monthly_limit": 100,
  "monthly_used": 105,
  "extra_projects": 5,
  "extra_projects_cost": "$5.00",
  "billing_period": {
    "start": "2023-01-01T00:00:00Z",
    "end": "2023-02-01T00:00:00Z"
  },
  "is_team_plan": true,
  "can_create_extra_projects": true
}
```

**Response 400** — Bad Request - Organization ID parameter is missing.

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User does not have permission for the specified organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Failed to retrieve data or unexpected error.

```json
{ "error": "An unexpected error occurred" }
```

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| org_id | string | Organization identifier for context. |
| user_id | string | User identifier for context. |
| tier | number | Numeric value representing subscription tier (e.g., 1: Free, 2: Pro, 3: Team). |
| plan_name | string | Human-readable name of the subscription plan. |
| monthly_limit | number | Maximum number of projects included in the plan per billing period. |
| monthly_used | number | Total number of projects created by the user in the current billing period. |
| extra_projects | number | Number of projects created exceeding the `monthly_limit`. Sourced from the subscription document. |
| extra_projects_cost | string | Calculated cost for the extra projects (currently hardcoded at $1.00 per extra project). Formatted as a currency string (e.g., '$5.00'). |
| billing_period | object | Object containing the start and end dates of the current billing period. |
| billing_period.start | string | ISO 8601 timestamp string for the start of the current billing period. |
| billing_period.end | string | ISO 8601 timestamp string for the end of the current billing period. |
| is_team_plan | boolean | Boolean flag, true if the user's tier is 3 (Business). |
| can_create_extra_projects | boolean | Boolean flag, true if the user's tier is 3 (Business), indicating the ability to exceed the monthly limit (at cost). |

**Usage notes**

- The `org_id` query parameter is mandatory and must be an organization the user belongs to.
- This endpoint is primarily relevant for users on the Business plan (`tier: 3`), as only they can typically create projects beyond the standard monthly limit.
- It shows the number of `extra_projects` created and calculates the associated `extra_projects_cost` (based on a fixed rate, currently $1.00 per project).
- Use this endpoint to provide billing transparency for Business plan users or organization administrators.
- Display the `extra_projects_cost` clearly in billing sections or subscription dashboards for Business plans.
- The `is_team_plan` and `can_create_extra_projects` flags explicitly confirm if the user's plan supports this overage capability.
- For non-Business plans (`tier` 1 or 2), this endpoint will typically show `extra_projects` as 0 and `can_create_extra_projects` as false.
- When a Team user is about to exceed their `monthly_limit` (check using `/projects/usage`), you can use the information from this endpoint (`can_create_extra_projects` and the cost implication) to inform them in a confirmation dialog before they proceed.
- For budget-conscious organizations on the Business plan, use this endpoint to create spending alerts when `extra_projects_cost` reaches certain thresholds.
- The `billing_period` information helps users understand the timeframe during which these extra charges are accumulating and when they will likely be billed.
- Combine with `/projects/usage` to give Team users a complete picture: their limit, current usage, remaining standard projects, and any extra projects already created.
- This endpoint provides crucial financial information for organizations needing to monitor variable costs associated with high project creation volume.
- Implement UI warnings or notifications when `extra_projects` starts incrementing to keep users aware of potential costs.
- Use this endpoint's data for financial forecasting related to project usage on Business plans.
- Create visual representations comparing the number of standard included projects (`monthly_limit`) with the number of extra billable projects (`extra_projects`).
- Explain the value proposition to Team users: the flexibility to exceed limits when necessary, balanced with the associated cost.
- The cost calculation is currently based on a simple multiplication; ensure the documentation reflects the current price per extra project if it changes.

## Developer Access

Check the developer API access status for the authenticated user.

### Get Developer Access Status

`GET https://api.storylinezads.com/developer-status`

Retrieves the developer API access status for the *authenticated user*. Checks both the user's profile setting (`developer_api_clearance`) and any pending access requests.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | no | Your API key. |
| X-API-Secret | no | Your API secret. |

**Response 200** — OK - Developer status retrieved successfully.

```json
{
  "user_id": "user_abcdef123456",
  "has_developer_access": true,
  "pending_request": false,
  "request_date": null
}
```

**Response 200** — OK - Developer status retrieved successfully.

```json
{
  "user_id": "user_abcdef123456",
  "has_developer_access": false,
  "pending_request": true,
  "request_date": "2023-01-10T10:00:00Z"
}
```

**Response 401** — Unauthorized - Authentication failed or user ID missing.

```json
{ "error": "User ID not found in token" }
```

**Response 500** — Internal Server Error - Failed to query database or unexpected error.

```json
{ "error": "Internal server error" }
```

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| user_id | string | Identifier of the authenticated user making the request. |
| has_developer_access | boolean | Indicates whether the `developer_api_clearance` field is `true` in the user's document (`profile.users`). True means the user has general API access. |
| pending_request | boolean | Indicates if a document exists for this `user_id` with `status: 'pending'` in the API clearance requests collection (`requests.api_clearance_requests`). True means an access request is awaiting review. |
| request_date | string | ISO 8601 timestamp string indicating when the pending request was submitted (`requested_at` field from the request document). Null if `pending_request` is false. |

**Usage notes**

- Developer access (`has_developer_access: true`) is generally required to create, manage, and use personal API keys for programmatic access to the platform's API.
- Use this endpoint to determine if the current user should be shown UI elements related to API key management or developer documentation.
- If `has_developer_access` is `true`, the user can proceed to manage their API keys.
- If `has_developer_access` is `false`:
-   - If `pending_request` is `true`, inform the user that their request (submitted on `request_date`) is pending review. Disable any 'Request Access' buttons.
-   - If `pending_request` is `false`, the user does not have access and has no pending request. You can show them an option or instructions on how to request developer access.
- This endpoint checks a user-level flag (`profile.users` collection) and the status of requests (`requests.api_clearance_requests` collection).
- This status is specific to the *authenticated user* making the request.
- You might poll this endpoint periodically (e.g., on visiting a developer section) to update the UI if a pending request gets approved.
- The `request_date` helps users understand how long their request has been waiting.
- Combine this endpoint with API key management endpoints (if available) to provide a complete developer onboarding and management workflow.
- Use the status to conditionally render developer-specific features, documentation links, or API key generation forms.
- Ensure the process for requesting developer access (if `has_developer_access` and `pending_request` are both false) is clearly communicated to the user.
- This endpoint provides a quick check before allowing potentially sensitive operations like API key generation.


---

# Company API

Source: https://storylinezads.com/docs/api/company
Last generated: 2026-07-20

Manage company details within organizations

Base route: `/company` (relative to `https://api.storylinezads.com`)

## Company Details Management

Create, retrieve, update, and manage company details

### Create Company Details

`POST https://api.storylinezads.com/create`

Creates new company details for an organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |
| Content-Type | yes |  |

**Request body**

```json
[object Object]
```

**Response 201** — Created

```json
{
  "company_details_id": "cd_12345",
  "org_id": "org_12345",
  "company_name": "Acme Corporation",
  "type": "main",
  "tag_line": "Innovation for tomorrow",
  "cta_text": "Learn More",
  "cta_subtext": "About our solutions",
  "link": "https://example.com",
  "company_type": "Technology",
  "vision": "To transform businesses with cutting-edge technology",
  "products": "Software solutions, Cloud services",
  "others": {},
  "description": "Leading provider of innovative solutions",
  "is_default": true,
  "created_by": "user_12345",
  "created_at": "2023-06-01T12:00:00Z",
  "updated_at": "2023-06-01T12:00:00Z"
}
```

**Response 400** — Bad Request

```json
{ "error": "No JSON data provided" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 415** — Unsupported Media Type

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- The org_id must be a valid organization ID to which the user has access.
- Send the payload as JSON with Content-Type: application/json.
- If is_default is omitted and no other profiles exist for the org, this record is created as the default automatically.
- Setting is_default to true will first unset any existing default profile for the same organization.
- The created_by, created_at, and updated_at fields are automatically generated.

### Get All Company Details

`GET https://api.storylinezads.com/get_all`

Retrieves all company details for a specific organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |
| Content-Type | yes |  |

**Response 200** — OK

```json
{
  "company_details": [
    {
      "company_details_id": "cd_12345",
      "org_id": "org_12345",
      "company_name": "Acme Corporation",
      "type": "main",
      "tag_line": "Innovation for tomorrow",
      "cta_text": "Learn More",
      "cta_subtext": "About our solutions",
      "link": "https://example.com",
      "company_type": "Technology",
      "vision": "To transform businesses with cutting-edge technology",
      "products": "Software solutions, Cloud services",
      "others": {},
      "description": "Leading provider of innovative solutions",
      "is_default": true,
      "created_by": "user_12345",
      "created_at": "2023-06-01T12:00:00Z",
      "updated_at": "2023-06-01T12:00:00Z"
    },
    {
      "company_details_id": "cd_67890",
      "org_id": "org_12345",
      "company_name": "Acme Corporation - Branch Office",
      "type": "branch",
      "tag_line": "Local Innovation",
      "cta_text": "Contact Us",
      "cta_subtext": "For local support",
      "link": "https://branch.example.com",
      "company_type": "Technology",
      "vision": "To serve local businesses with cutting-edge technology",
      "products": "Regional support, Local solutions",
      "others": {},
      "description": "Local branch of Acme Corporation",
      "is_default": false,
      "created_by": "user_12345",
      "created_at": "2023-07-01T12:00:00Z",
      "updated_at": "2023-07-01T12:00:00Z"
    }
  ],
  "count": 2,
  "pagination": {
    "total_count": 10,
    "total_pages": 5,
    "current_page": 1,
    "page_size": 2,
    "has_next": true,
    "has_prev": false
  },
  "sorting": {
    "sort_by": "created_at",
    "order": "desc"
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "Organization ID is required as a query parameter" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "You do not have permission to access this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- The org_id must be a valid organization ID to which the user has access.
- This endpoint returns all company details regardless of their default status.
- If page is less than 1 the server automatically treats it as 1.
- If limit is less than 1 or greater than 100 the server resets it to 10 before executing the query.
- Only specific sort_by values are accepted (company_name, type, created_at, updated_at, tag_line, company_type, is_default); invalid values fall back to created_at with descending order by default.
- Sort results using sort_by and order parameters for better organization.

### Get One Company Detail

`GET https://api.storylinezads.com/get_one`

Retrieves a single company detail by ID or the default one for an organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |
| Content-Type | yes |  |

**Response 200** — OK

```json
{
  "company_details_id": "cd_12345",
  "org_id": "org_12345",
  "company_name": "Acme Corporation",
  "type": "main",
  "tag_line": "Innovation for tomorrow",
  "cta_text": "Learn More",
  "cta_subtext": "About our solutions",
  "link": "https://example.com",
  "company_type": "Technology",
  "vision": "To transform businesses with cutting-edge technology",
  "products": "Software solutions, Cloud services",
  "others": {},
  "description": "Leading provider of innovative solutions",
  "is_default": true,
  "created_by": "user_12345",
  "created_at": "2023-06-01T12:00:00Z",
  "updated_at": "2023-06-01T12:00:00Z"
}
```

**Response 400** — Bad Request

```json
{ "error": "Either company_details_id or org_id is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "You do not have permission to access this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Company details not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Provide either company_details_id to get a specific company details object or org_id to get the default company details for an organization.
- When only org_id is provided, the endpoint will return the company details with is_default set to true.
- If no default company details exist for the organization, a 404 error will be returned.
- Access is restricted to organization members; unauthorized callers receive a 403 response.

### Update Company Details

`PUT https://api.storylinezads.com/update`

Updates existing company details.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — OK

```json
{
  "company_details_id": "cd_12345",
  "org_id": "org_12345",
  "company_name": "Acme Corporation Updated",
  "type": "main",
  "tag_line": "New Innovation for tomorrow",
  "cta_text": "Learn More",
  "cta_subtext": "About our solutions",
  "link": "https://example.com",
  "company_type": "Technology",
  "vision": "To transform businesses with cutting-edge technology",
  "products": "Software solutions, Cloud services",
  "others": {},
  "description": "Leading provider of innovative solutions",
  "is_default": true,
  "created_by": "user_12345",
  "created_at": "2023-06-01T12:00:00Z",
  "updated_at": "2023-08-01T15:30:00Z"
}
```

**Response 400** — Bad Request

```json
{ "error": "Company details ID is required as a query parameter" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Company details not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Send the payload as JSON with Content-Type: application/json.
- Only provide the fields that need to be updated; unspecified fields remain unchanged.
- When setting is_default to true, all other company details for this organization are automatically marked non-default before the update is saved.
- Provide others as a JSON object; existing keys are fully replaced by the payload.
- The updated_at field is automatically refreshed to the current UTC time.

### Delete Company Details

`DELETE https://api.storylinezads.com/delete`

Deletes company details by ID.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{ "message": "Company details deleted successfully" }
```

**Response 400** — Bad Request

```json
{ "error": "Company details ID is required as a query parameter" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Company details not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- If the deleted company details were the default for the organization, another company details (if any exist) will be automatically set as the new default.

### Set Default Company Details

`PUT https://api.storylinezads.com/set_default`

Sets specific company details as the default for an organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{ "message": "Default company details set successfully" }
```

**Response 400** — Bad Request

```json
{ "error": "Company details ID is required as a query parameter" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Company details not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- When setting a company details as default, all other company details for the same organization will have their is_default flag set to false.
- Each organization should have exactly one default company details at any time.
- The selected profile's updated_at timestamp is refreshed to the current UTC time when it becomes the default.

### Duplicate Company Details

`POST https://api.storylinezads.com/duplicate`

Creates a copy of existing company details.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 201** — Created

```json
{
  "message": "Company details duplicated successfully",
  "company_details": {
    "company_details_id": "cd_67890",
    "org_id": "org_12345",
    "company_name": "Acme Corporation - Branch Office",
    "type": "main",
    "tag_line": "Innovation for tomorrow",
    "cta_text": "Learn More",
    "cta_subtext": "About our solutions",
    "link": "https://example.com",
    "company_type": "Technology",
    "vision": "To transform businesses with cutting-edge technology",
    "products": "Software solutions, Cloud services",
    "others": {},
    "description": "Leading provider of innovative solutions",
    "is_default": false,
    "created_by": "user_12345",
    "created_at": "2023-08-01T12:00:00Z",
    "updated_at": "2023-08-01T12:00:00Z"
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "No JSON data provided" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Company details not found or you do not have permission to duplicate it" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Send the payload as JSON with Content-Type: application/json.
- Duplicated company details are created with is_default set to false regardless of the source record.
- All attributes from the original company details are copied except for the identifiers, timestamps, created_by, and default status.
- The target org_id must match an organization the caller can manage, and the source profile must also belong to that organization.
- Provide a custom company_name to override the default '(Copy)' suffix applied to duplicates.

### Search Company Details

`GET https://api.storylinezads.com/search`

Searches for company details within an organization based on specific criteria.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "results": [
    {
      "company_details_id": "cd_12345",
      "org_id": "org_12345",
      "company_name": "Acme Corporation",
      "type": "main",
      "tag_line": "Innovation for tomorrow",
      "cta_text": "Learn More",
      "cta_subtext": "About our solutions",
      "link": "https://example.com",
      "company_type": "Technology",
      "vision": "To transform businesses with cutting-edge technology",
      "products": "Software solutions, Cloud services",
      "others": {},
      "description": "Leading provider of innovative solutions",
      "is_default": true,
      "created_by": "user_12345",
      "created_at": "2023-06-01T12:00:00Z",
      "updated_at": "2023-06-01T12:00:00Z"
    }
  ],
  "count": 1,
  "pagination": {
    "total_count": 5,
    "total_pages": 5,
    "current_page": 1,
    "page_size": 1,
    "has_next": true,
    "has_prev": false
  },
  "search_params": {
    "term": "Acme",
    "field": "company_name"
  },
  "sorting": {
    "sort_by": "created_at",
    "order": "desc"
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "Organization ID is required as a query parameter" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "You do not have permission to access this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- The org_id must be a valid organization ID to which the user has access.
- If no search term (q) is provided, the endpoint returns all company details for the organization (similar to get_all but with different response format).
- Search is case-insensitive and uses partial matching.
- Only specific fields can be searched: company_name, type, tag_line, company_type, vision, products, description.
- If page is less than 1 the server automatically treats it as 1.
- If limit is less than 1 or greater than 100 the server resets it to 10 before executing the query.
- Results are paginated and can be sorted using the same parameters as the get_all endpoint.

### Get Default Company Details

`GET https://api.storylinezads.com/get_default`

Retrieves the default company details for a specific organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "company_details_id": "cd_12345",
  "org_id": "org_12345",
  "company_name": "Acme Corporation",
  "type": "main",
  "tag_line": "Innovation for tomorrow",
  "cta_text": "Learn More",
  "cta_subtext": "About our solutions",
  "link": "https://example.com",
  "company_type": "Technology",
  "vision": "To transform businesses with cutting-edge technology",
  "products": "Software solutions, Cloud services",
  "others": {},
  "description": "Leading provider of innovative solutions",
  "is_default": true,
  "created_by": "user_12345",
  "created_at": "2023-06-01T12:00:00Z",
  "updated_at": "2023-06-01T12:00:00Z"
}
```

**Response 400** — Bad Request

```json
{ "error": "Organization ID is required as a query parameter" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "You do not have permission to access this organization" }
```

**Response 404** — Not Found

```json
{ "error": "No default company details found for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- This endpoint provides a direct way to retrieve the default company details for an organization.
- If no company details have been set as default for the organization, a 404 error will be returned.
- This is a simpler alternative to using /get_one with just org_id when you specifically need the default company details.


---

# Brands API

Source: https://storylinezads.com/docs/api/brands
Last generated: 2026-07-20

Endpoints for managing brand settings within an organization, including creating, retrieving, updating, deleting, duplicating brands as well as managing logos and fonts.

Base route: `/brands` (relative to `https://api.storylinezads.com`)

## Brand Management

Endpoints to create, retrieve, update, delete, duplicate, and set default brand profiles. Use these in combination to fully manage brand settings across your organization.

### Create Brand Settings

`POST https://api.storylinezads.com/create`

Creates a new brand profile with detailed styling and configuration parameters. Colors (provided as lists) are internally converted to tuples and fonts are validated.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 201** — Brand created successfully with complete settings; defaults are applied if optional parameters are omitted.

```json
{ /* Complete brand object with generated brand_id and timestamps */ }
```

**Response 400** — Missing required parameters or invalid data types. Examples include missing org_id, empty name, invalid logo_key, or unrecognized font names.

```json
{ "error": "Brand name is required" }
```

**Response 401** — Unauthorized access due to missing or invalid API credentials.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden – the user does not have permission to modify the specified organization.

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 409** — Conflict due to logo key already being associated with another brand.

```json
{ "error": "A brand with this logo key already exists. Please use a different logo." }
```

**Response 500** — Internal server error while processing the request.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Tip: Always verify your available fonts by calling GET /fonts before specifying font names in this endpoint.
- Remember: Color values must be provided as arrays of three integers (RGB); they will be converted to tuples internally.
- Workflow Guide: Generate an upload_id via GET /logo-upload-url (or POST /logo-from-url) and pass it here to attach a validated logo during creation.
- Advanced: Setting is_default to true will automatically unset any existing default brands within the organization.
- Usage: This endpoint is best used when establishing a new brand identity, with a full array of styling parameters; all optional fields have sensible defaults.

### Get All Brands

`GET https://api.storylinezads.com/get_all`

Retrieves a paginated list of brand profiles for a given organization. Optionally returns temporary download URLs for logos.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Brands retrieved successfully; includes pagination information.

```json
{ "brands": [ { ...brand object... } ], "count": 2, "pagination": { "total": 5, "page": 1, "limit": 20, "total_pages": 1 } }
```

**Response 400** — Bad Request - Missing required query parameter (org_id).

```json
{ "error": "Organization ID is required as a query parameter" }
```

**Response 401** — Unauthorized - API credentials missing or invalid.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - User does not have permission to access the organization.

```json
{ "error": "You do not have permission to access this organization" }
```

**Response 500** — Internal server error while retrieving brands.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Tip: Use this endpoint to display a brand selector when users manage or edit projects.
- Note: If you require logo previews, set include_urls=true to receive temporary download URLs.
- Guideline: Pagination details help manage large datasets; always check the pagination object to fetch additional pages.

### Get Brand Settings

`GET https://api.storylinezads.com/get`

Fetches the full details of a specific brand by brand_id, or retrieves the default brand for an organization if org_id is provided.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Brand settings retrieved successfully; includes a temporary logo URL if applicable.

```json
{ /* Complete brand object with logo_url if logo exists */ }
```

**Response 400** — Bad Request - Neither brand_id nor org_id provided.

```json
{ "error": "Either brand_id or org_id is required as a query parameter" }
```

**Response 401** — Unauthorized - Missing or invalid API credentials.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - User does not have access to this organization.

```json
{ "error": "You do not have permission to access this organization" }
```

**Response 404** — Not Found - Specified brand or default brand does not exist.

```json
{ "error": "Brand not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Guidance: Use this endpoint to load a brand's full configuration when editing or applying brand settings.
- Hint: Pass brand_id explicitly to retrieve a specific brand; if omitted, org_id will fetch the default brand for that organization.
- Note: When the brand is public, the response also includes likes, dislikes, net_score, user_interaction, and comment_count metadata for the requesting user.

### Update Brand Settings

`PUT https://api.storylinezads.com/update`

Updates specific fields of an existing brand. Only fields included in the request body are modified.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Brand updated successfully; returns the full updated brand object.

```json
{ /* Full updated brand object */ }
```

**Response 400** — Bad Request - Missing brand_id, empty name, invalid logo key, invalid font name, incorrect data type, or no valid fields provided.

```json
{ "error": "Brand name cannot be empty" }
```

**Response 401** — Unauthorized due to invalid API credentials.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - Insufficient permissions to update the brand.

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 404** — Brand not found.

```json
{ "error": "Brand not found" }
```

**Response 409** — Conflict if the new logo key is already used by another brand.

```json
{ "error": "A brand with this logo key already exists." }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Guidelines: Only include the fields that require updating; omitted fields will remain unchanged.
- Tip: For logo uploads, use the logo_upload_id parameter (preferred) or the legacy upload_id parameter.
- Note: When updating logos, logo_upload_id takes precedence over upload_id, which is maintained for backward compatibility.
- Tip: Validate font names with GET /fonts before updating any font-related fields.
- Reminder: If setting is_default to true, the system will unset the previous default automatically.
- Workflow: For changing the logo, it's recommended to use the /logo-upload-url and /add_logo endpoints instead of directly updating logo_key here.

### Delete Brand Settings

`DELETE https://api.storylinezads.com/delete`

Deletes a brand profile and its associated logo from S3. If the deleted brand was default, a replacement default will be selected.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Brand deleted successfully.

```json
{ "message": "Brand deleted successfully" }
```

**Response 400** — Missing brand_id.

```json
{ "error": "Brand ID is required as a query parameter" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden – no permission to delete the brand.

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 404** — Brand not found.

```json
{ "error": "Brand not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Important: Deletion is irreversible. Confirm deletion before calling this endpoint.
- Note: If the deleted brand is default, the system automatically selects a new default from existing brands.
- Tip: Always verify the brand details using GET /get_all before deletion.

### Set Default Brand

`PUT https://api.storylinezads.com/set_default`

Sets a specified brand as the organization's default. This causes any other default brand to be unset automatically.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Default brand updated successfully.

```json
{ "message": "Default brand set successfully" }
```

**Response 400** — Missing brand_id.

```json
{ "error": "Brand ID is required as a query parameter" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - insufficient permissions.

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 404** — Brand not found.

```json
{ "error": "Brand not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Tip: Use this endpoint when a user wants to change the default brand displayed or applied to new projects.
- Reminder: The system automatically unsets any previous default when a new default is selected.

### Duplicate Brand

`POST https://api.storylinezads.com/duplicate`

Creates a copy of an existing brand, with a new brand_id. Styling, fonts, and most configuration values are cloned. The service also attempts to duplicate the logo asset; if S3 copy fails, the new brand is created without a logo.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 201** — Brand duplicated successfully; returns the full duplicated brand object.

```json
{ "message": "Brand duplicated successfully", "brand": { /* New brand object with new brand_id and default settings */ } }
```

**Response 400** — Missing required parameters.

```json
{ "error": "Brand ID is required" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - no permission to create brand for the target organization.

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 404** — Source brand not found or inaccessible.

```json
{ "error": "Brand not found, or you do not have permission to duplicate it" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Usage Tip: Use this endpoint to quickly replicate a brand's style for use in another project or organization.
- Important: Logo assets are copied to a new key where possible. Inspect the response to confirm logo_key was set; if not, upload a fresh logo.
- Guideline: Duplicated brands are automatically set to non-default and private; update these settings with the update endpoint if needed.

### Get Default Brand

`GET https://api.storylinezads.com/get_default`

Retrieves the default brand for a specific organization with a simpler interface than the general-purpose `/get` endpoint.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Default brand retrieved successfully.

```json
{ /* Complete brand object with logo_url if applicable */ }
```

**Response 400** — Missing required organization ID.

```json
{ "error": "Organization ID is required as a query parameter" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden if user lacks permission on the organization.

```json
{ "error": "You do not have permission to access this organization" }
```

**Response 404** — No default brand exists for the organization.

```json
{ "error": "No default brand found for this organization" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- This endpoint provides a direct way to retrieve the default brand for an organization, simplifying the API call when you only need the default brand.
- A temporary presigned URL for the logo is included in the response if the brand has a logo.

## Logo Management

Endpoints for managing brand logos, including generating upload URLs and linking uploaded logos to brands.

### Get Logo Upload URL

`GET https://api.storylinezads.com/logo-upload-url`

Generates a pre-signed URL for secure uploading of a logo directly to S3. Use the provided upload_id in the subsequent update logo endpoint.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Pre-signed URL generated successfully.

```json
{ "upload_id": "upload-12345", "upload_link": { "url": "https://s3.example.com/...", "fields": { "key": "userdata/unique_logo_filename", ... } }, "key": "userdata/unique_logo_filename", "expires_in": 3600 }
```

**Response 400** — Either org_id or filename missing or file extension invalid.

```json
{ "error": "Filename is required as a query parameter" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden if user lacks permission on the organization.

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Tip: This endpoint is the first step of the logo upload workflow. It returns an upload_id and a pre-signed URL.
- Recommendation: After obtaining the upload_link, perform a PUT operation to upload the binary logo file directly to S3.
- Reminder: Save the returned upload_id because it must be passed to the update logo endpoint to finalize logo association.

### Download Logo From URL

`POST https://api.storylinezads.com/logo-from-url`

Downloads an external logo asset over HTTPS, validates it, and uploads it into the secure Storylinez storage in a single step. Returns the same upload_id flow used by the upload URL endpoint.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Logo downloaded and uploaded successfully. The returned upload_id can be passed to POST /create or PUT /add_logo.

```json
{ "upload_id": "d382...", "s3_key": "userdata/org123/logo_from_url_1700000000.png", "message": "Logo downloaded and uploaded successfully" }
```

**Response 400** — Bad request – missing fields, non-HTTP(S) URL, invalid content type, or empty file.

```json
{ "error": "Logo URL is required" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden when the caller lacks access to the organization.

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 413** — Payload too large – the downloaded asset exceeded the 5 MB limit.

```json
{ "error": "Logo file is too large (max 5MB)" }
```

**Response 422** — Unsupported image format after validation of MIME type and filename.

```json
{ "error": "Unsupported image format: webp. Allowed formats: jpg, jpeg, png, webp, bmp, tiff" }
```

**Response 500** — Internal server error during download or upload.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Workflow: Use this endpoint when the logo is already hosted online. The service fetches the asset, validates secure content-type, size (≤5 MB), and allowed extensions (jpg, jpeg, png, webp, bmp, tiff).
- Reminder: The response mirrors GET /logo-upload-url. Pass the upload_id to POST /create or PUT /add_logo so the processed logo is registered with the brand.
- Tip: Add metadata such as file name or source branding by inspecting the returned s3_key before final association.

### Add Logo to Brand

`PUT https://api.storylinezads.com/add_logo`

Associates a previously uploaded logo (using upload_id or direct logo_key) with an existing brand. Also removes any pre-existing logo if necessary.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Logo added or replaced successfully; returns the updated brand including a presigned logo_url valid for ~1 hour.

```json
{ "message": "Logo added successfully", "brand": { "brand_id": "...", "logo_key": "userdata/...", "logo_url": "https://signed-url", ... } }
```

**Response 400** — Bad Request - Missing brand_id or upload_id/logo_key, or invalid/expired upload.

```json
{ "error": "upload_id is required" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden if user is not permitted to modify the organization.

```json
{ "error": "You do not have permission to modify this organization" }
```

**Response 404** — Brand not found.

```json
{ "error": "Brand not found" }
```

**Response 409** — Conflict if the new logo_key is already in use by another brand.

```json
{ "error": "A brand with this logo key already exists." }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Usage Guide: This endpoint finalizes the logo upload process. Provide the upload_id obtained from the upload workflow whenever possible for full validation.
- Tip: If the brand already has a logo, the system safely removes the previous asset from S3 before linking the new one.
- Reminder: The response contains a temporary logo_url that expires; cache only the logo_key for persistence.
- Validation: Calls fail with HTTP 409 if another brand already uses the provided logo_key, preventing unintended sharing.

## Font Management

Endpoint to retrieve the list of available fonts that can be used in brand settings.

### Get Available Fonts

`GET https://api.storylinezads.com/fonts`

Retrieves a cached list of available font names from the renderer service. Use this list to ensure all font names used in brand creation or update are valid.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Available fonts retrieved successfully.

```json
{ "fonts": ["Montserrat-Bold", "Montserrat-Regular", "Arial-Bold", "Arial-Regular", "Lato-Regular", ...] }
```

**Response 401** — Unauthorized - Invalid API credentials.

```json
{ "error": "Invalid API Key or Secret" }
```

**Response 500** — Internal server error retrieving fonts.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Guide: Use this endpoint to populate font dropdowns in your UI.
- Tip: Ensure you use the exact case and spelling from the returned list when specifying fonts in brand settings.

## Brand Discovery

Endpoints for searching and discovering brand profiles. These endpoints facilitate cross-organization brand discovery and duplication.

### Search Brands

`GET https://api.storylinezads.com/search`

Searches for brand profiles based on name and filters. Supports pagination and optional inclusion of public brands and logo URLs.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Search completed successfully; returns an array of matching brand objects with pagination info.

```json
{ "brands": [ { ...brand object... } ], "count": 2, "pagination": { "total": 5, "page": 1, "limit": 20, "total_pages": 1 } }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - insufficient access rights if org_id is specified and user is not allowed.

```json
{ "error": "You do not have permission to access this organization" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Helpful Tip: Use this endpoint to implement search features in your application. You can search globally or limit by organization.
- Guide: When include_public is true, results include both the user's brands and public brands from other organizations.
- Note: Pagination parameters help manage large numbers of results. Use include_logos to get a preview of the brand logo when needed.
- Metadata: Each result includes org_name for display convenience. Public matches do not include interaction counts; use GET /public for ranked discovery feeds.

### List Public Brands

`GET https://api.storylinezads.com/public`

Returns public brands across Storylinez with optional smart sorting based on user interactions. Supports excluding your own organization, pagination, and on-demand logo URLs.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Successful response containing public brands enriched with like/dislike metadata for the requesting user.

```json
{ "public_brands": [ { "brand_id": "...", "name": "Summer Splash", "org_id": "org_123", "org_name": "Splash Corp", "likes": 12, "dislikes": 1, "net_score": 11, "comment_count": 4, "user_interaction": "like", "logo_key": "userdata/...", "logo_url": "https://signed-url" } ], "count": 1, "pagination": { "total": 87, "page": 1, "limit": 20, "total_pages": 5 } }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden if the caller cannot authenticate.

```json
{ "error": "Forbidden" }
```

**Response 500** — Internal server error while retrieving public brands.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Discovery: Ideal for building explore feeds or recommendation carousels showcasing public brands.
- Smart Sorting: Keep smart_sort=true to respect user likes/dislikes and ensure negatively-rated items fall to the end of the list.
- Metadata: Each item includes org_name, likes, dislikes, net_score, comment_count, and user_interaction so you can show social proof immediately.
- Logos: Presigned logo_url values expire; cache only logo_key or request include_logos when rendering.

## User Interactions

Endpoints for managing user interactions with brands including likes, dislikes, and interaction removal. These interactions affect content ordering with smart rearrangement.

### Like Brand

`POST https://api.storylinezads.com/like`

Like a specific brand. This interaction affects content ordering in future API responses, with liked brands appearing first.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Brand liked successfully. Returns updated like/dislike counters and net score for ranking.

```json
{ "success": true, "action": "like", "brand_id": "...", "likes": 5, "dislikes": 0, "net_score": 5 }
```

**Response 400** — Missing brand_id or invalid payload.

```json
{ "error": "brand_id is required" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden when the target brand is not public.

```json
{ "error": "Can only interact with public brands" }
```

**Response 404** — Brand not found.

```json
{ "error": "Brand not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Note: Liked brands surface first when smart_sort is enabled on GET /public.
- Guide: Use this to implement thumbs-up functionality in your brand discovery interface.
- Reminder: Interactions are tracked per user and brand; repeated likes overwrite previous dislikes automatically.

### Dislike Brand

`POST https://api.storylinezads.com/dislike`

Dislike a specific brand. This interaction affects content ordering in future API responses, with disliked brands appearing last.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Brand disliked successfully. Returns updated counters so the UI can reflect rankings.

```json
{ "success": true, "action": "dislike", "brand_id": "...", "likes": 3, "dislikes": 2, "net_score": 1 }
```

**Response 400** — Missing brand_id or invalid payload.

```json
{ "error": "brand_id is required" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden when attempting to interact with a private brand.

```json
{ "error": "Can only interact with public brands" }
```

**Response 404** — Brand not found.

```json
{ "error": "Brand not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Note: Disliked brands automatically sink to the bottom of GET /public results when smart_sort is active.
- Guide: Use this to implement thumbs-down functionality in your brand discovery interface.
- Reminder: Sending a dislike overwrites prior likes for the same brand.

### Remove Brand Interaction

`POST https://api.storylinezads.com/remove_interaction`

Remove any existing interaction (like or dislike) with a specific brand, resetting it to neutral status.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Interaction removed successfully. Returns updated counts so you can refresh UI badges.

```json
{ "success": true, "action": "removed", "brand_id": "...", "was_removed": true, "likes": 3, "dislikes": 1, "net_score": 2 }
```

**Response 400** — Missing brand_id or invalid payload.

```json
{ "error": "brand_id is required" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden when attempting to reset interaction on a private brand.

```json
{ "error": "Can only interact with public brands" }
```

**Response 404** — Brand not found. The was_removed flag returns false when no record existed.

```json
{ "error": "Brand not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Note: After removal, the brand returns to neutral ordering when smart_sort is enabled.
- Guide: Use this to implement an 'undo' or 'reset' feature in your interaction interface.
- Insight: was_removed lets you differentiate between a successful reset and a no-op.

## Brand Comments

Comprehensive commenting system for brands including creating, retrieving, updating, and deleting comments with support for replies and pagination.

### Add Brand Comment

`POST https://api.storylinezads.com/comment`

Add a new comment to a brand. Supports both top-level comments and replies to existing comments with automatic thread management.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 201** — Comment created successfully.

```json
{ "success": true, "message": "Comment added successfully", "comment": { "comment_id": "...", "brand_id": "...", "text": "This is a great brand design!", "user_info": { "user_id": "usr_123" }, "created_at": "2024-05-19T12:00:00Z", "updated_at": "2024-05-19T12:00:00Z" } }
```

**Response 400** — Missing required fields, empty text, or text exceeding 1000 characters.

```json
{ "error": "Comment text is required and cannot be empty" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden when attempting to comment on a private brand.

```json
{ "error": "Can only comment on public brands" }
```

**Response 404** — Brand not found or parent comment missing.

```json
{ "error": "Parent comment not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Note: Comments support threading - replies will be grouped under their parent comments.
- Guide: To create a reply, include the parent_comment_id of the comment you're replying to.
- Tip: Comments are rate-limited to prevent spam and capped at 1000 characters per entry.

### Get Brand Comments

`GET https://api.storylinezads.com/comments`

Retrieve comments for a specific brand with pagination support and hierarchical organization of replies.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Comments retrieved successfully.

```json
{ "comments": [ { "comment_id": "...", "brand_id": "...", "text": "Great brand!", "reply_count": 2, "user_info": { "user_id": "usr_123" }, "is_own_comment": true, "created_at": "2024-05-19T12:00:00Z", "updated_at": "2024-05-19T12:00:00Z" } ], "count": 1, "pagination": { "page": 1, "limit": 10, "total": 12, "total_pages": 2 } }
```

**Response 400** — Missing brand_id or invalid parent filter.

```json
{ "error": "brand_id is required" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden when the brand is private.

```json
{ "error": "Can only view comments on public brands" }
```

**Response 404** — Brand not found.

```json
{ "error": "Brand not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Note: Replies are fetched on demand via parent_comment_id, keeping top-level queries efficient.
- Guide: Use pagination parameters to handle large comment threads efficiently.
- Tip: Each comment includes user_info with the author's ID and is_own_comment to simplify client-side editing controls.
- Insight: reply_count is only returned for top-level comments to indicate whether more replies can be fetched.

### Update Brand Comment

`PUT https://api.storylinezads.com/comment`

Update the content of an existing comment. Only the comment author can edit their own comments.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Comment updated successfully.

```json
{ "success": true, "message": "Comment updated successfully", "comment": { "comment_id": "...", "text": "This is an updated comment!", "user_info": { "user_id": "usr_123" }, "is_own_comment": true, "updated_at": "2024-05-19T12:05:00Z" } }
```

**Response 400** — Missing required fields or invalid text length.

```json
{ "error": "Comment text is required and cannot be empty" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — User doesn't own the comment.

```json
{ "error": "You can only edit your own comments" }
```

**Response 404** — Comment not found.

```json
{ "error": "Comment not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Security: Only the original comment author can edit their comments.
- Note: The updated_at timestamp is automatically refreshed whenever a comment is edited.
- Guide: Implement edit permissions by checking if the current user matches the comment's user_id or by relying on is_own_comment.

### Delete Brand Comment

`DELETE https://api.storylinezads.com/comment`

Delete an existing comment. Only the comment author can delete their own comments. Deleting a parent comment also removes all replies.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Comment deleted successfully. Replies are also removed when a parent comment is deleted.

```json
{ "success": true, "message": "Comment and all replies deleted successfully" }
```

**Response 400** — Missing comment_id.

```json
{ "error": "comment_id is required" }
```

**Response 401** — Unauthorized access.

```json
{ "error": "User ID not found in token" }
```

**Response 403** — User doesn't own the comment.

```json
{ "error": "You can only delete your own comments" }
```

**Response 404** — Comment not found.

```json
{ "error": "Comment not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Security: Only the original comment author can delete their comments.
- Warning: Deleting a parent comment will also delete all of its replies.
- Guide: Show a confirmation dialog when deleting comments with replies.


---

# Files API

Source: https://storylinezads.com/docs/api/files
Last generated: 2026-07-20

Endpoints for managing files and folders within an organization. This includes uploading files, organizing them into folders, retrieving file details and analysis results, searching, and managing storage usage.

Base route: `/storage` (relative to `https://api.storylinezads.com`)

## File Upload & Processing

Endpoints related to the file upload workflow, from generating secure upload links to confirming uploads and triggering analysis.

### Generate Upload Link

`GET https://api.storylinezads.com/upload/create_link`

Generates a secure, time-limited pre-signed URL for uploading a file directly to S3 storage. It also creates an internal record to track the upload.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Upload link generated successfully.

```json
{
  "upload_link": "https://your-bucket.s3.amazonaws.com/userdata/org_id/unique_id/example.mp4?AWSAccessKeyId=...&Signature=...&Expires=...",
  "key": "userdata/org_id/unique_id/example.mp4",
  "upload_id": "upld_a1b2c3d4e5f6",
  "expires_in": 3600
}
```

**Response 400** — Bad Request - Missing required parameters (org_id, filename) or invalid file extension.

```json
{ "error": "Filename is required" }
```

**Response 401** — Unauthorized - Authentication failed or user not found.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization, or the estimated file size exceeds storage limits.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Failed to generate the S3 link or create the internal upload record.

```json
{ "error": "Failed to generate upload link" }
```

**Usage notes**

- This is the first step in the upload process. The client receives a URL (`upload_link`) to which they should send a PUT request with the file's binary data.
- The `key` returned is the unique path where the file will be stored in S3. It includes the organization ID and a unique identifier to prevent collisions.
- The `upload_id` is crucial; it must be passed to the `/upload/complete` endpoint after the file is successfully uploaded to the `upload_link`.
- The `upload_link` is valid for 1 hour (`expires_in`: 3600 seconds). The upload must be completed within this time.
- The system checks if the `filename` extension is allowed (e.g., mp4, jpg, pdf). See system configuration for the full list.
- Providing an accurate `file_size` allows for an early check against storage quotas, preventing unnecessary uploads if the limit would be exceeded.
- The `folder_path` determines the logical location within the application, not the physical S3 path.

### Mark Upload Complete

`POST https://api.storylinezads.com/upload/complete`

Confirms that a file upload to the pre-signed URL was successful. This endpoint registers the file in the database, verifies its size, updates storage usage, and triggers the background analysis process.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — File registered successfully and analysis initiated.

```json
{
  "message": "File registered successfully",
  "file": {
    "file_id": "file_a1b2c3d4",
    "org_id": "org_abc123",
    "s3_key": "userdata/org_abc123/unique_id/Product_Demo_Final.mp4",
    "filename": "Product_Demo_Final.mp4",
    "original_filename": "Product_Demo_Original.mp4",
    "folder_path": "/marketing/videos",
    "size": 15728640,
    "mimetype": "video/mp4",
    "uploaded_by": "user_xyz",
    "upload_date": "2024-07-26T10:30:00.000Z",
    "last_modified": "2024-07-26T10:30:00.000Z",
    "job_id": "job_1234567890",
    "media_type": "videos",
    "total_duration": 188.2,
    "analysis_params": {
      "context": "This video demonstrates the key features of our new product launch.",
      "tags": ["product demo", "marketing", "launch"],
      "company_details": "Fetched Company Details Summary...",
      "deepthink": false,
      "overdrive": false,
      "web_search": true,
      "eco": false,
      "temperature": 0.6,
      "analyze_audio": true,
      "advanced_detection": true,
      "model": "storylinez-1-reasoning",
      "auto_company_details": true,
      "company_details_id": "cd_xyz789"
    },
    "original_url": "https://your-bucket.s3.amazonaws.com/userdata/org_abc123/unique_id/Product_Demo_Final.mp4?..."
  },
  "job_id": "job_1234567890"
}
```

**Response 400** — Bad Request - Missing required fields, invalid upload record, or target folder does not exist.

```json
{ "error": "Either upload_id or key (S3 key) is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission, upload exceeds storage limits, or failed to retrieve company details.

```json
{ "error": "Upload would exceed storage limits" }
```

**Response 404** — Not Found - File not found at the specified S3 key (upload might have failed).

```json
{ "error": "File not found in storage. Upload may have failed or been interrupted." }
```

**Response 409** — Conflict - A file with the same S3 key already exists in the database.

```json
{ "error": "A file with the same key already exists. Please use a different file." }
```

**Response 413** — Payload Too Large - Media duration exceeds the organization's subscription limit. The uploaded object is deleted to prevent orphaned storage.

```json
{ "error": "This video is 1h 45m 12s long. Your current plan allows up to 30m 0s. Please trim the file or upgrade your subscription." }
```

**Response 500** — Internal Server Error - Database error or failure to initiate the analysis job.

```json
{ "error": "Failed to initiate file processing" }
```

**Usage notes**

- This endpoint *must* be called after successfully uploading the file to the URL from `/upload/create_link`.
- Provide either `upload_id` (recommended) or the `key` to identify the completed upload.
- The system verifies the file exists in S3 and retrieves its actual size to check against storage limits *before* creating the database record.
- If `auto_company_details` is true, the system attempts to fetch the relevant company profile (specified by `company_details_id` or the default) and uses its summary for the `analysis_params.company_details` field, overriding any value passed in the request's `company_details` field.
- Failure to retrieve company details when `auto_company_details` is true results in a 403 error.
- All provided analysis parameters (`context`, `tags`, `deepthink`, etc.) are stored with the file record and used to configure the background analysis job.
- `advanced_detection` controls enhanced perception pipelines (object/scene/entity detection). Leave it enabled unless you need a lighter analysis.
- When setting `model`, provide one of: 'auto', 'storylinez-1-reasoning', 'storylinez-1-turbo', or 'storylinez-1-lumina'. Using a concrete alias requires `eco=false` and the alias must be approved for the analysis domain.
- If the upload is a video or audio asset, the platform automatically measures duration and will reject files beyond the organization's limits with a 413 response.
- The `job_id` returned corresponds to the background analysis task. You can use `/file/analysis` to check the status (`processing_status`) and results later.
- The `original_url` in the response provides temporary access to the raw uploaded file.
- The internal `UploadRecord` is marked as 'registered' upon success, indicating the upload is complete and linked to a file record.

### Reprocess File

`POST https://api.storylinezads.com/file/reprocess`

Triggers a new analysis job for an existing file. This allows updating analysis parameters (like context, tags, or AI settings) and generating new results without re-uploading the file.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — File reprocessing initiated successfully.

```json
{ "message": "File reprocessing started", "file_id": "file_a1b2c3d4", "job_id": "job_new987654321" }
```

**Response 400** — Bad Request - Missing file_id in URL.

```json
{ "error": "File ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission or failed to retrieve company details.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified file_id does not exist.

```json
{ "error": "File not found" }
```

**Response 500** — Internal Server Error - Database error or failure to initiate the reprocessing job.

```json
{ "error": "Failed to initiate file processing" }
```

**Usage notes**

- This endpoint is useful for refining analysis results by changing parameters without needing to upload the file again.
- Only the parameters included in the request body are updated. Parameters omitted from the request will retain their previous values from the file's `analysis_params`.
- If `auto_company_details` is set to true (or remains true), the system will re-fetch the company details (using the new `company_details_id` if provided, or the default) and use that summary, overriding any `company_details` value in the request.
- A new background analysis job is created, and the file's `job_id` field is updated to this new ID.
- The file's `processing_status` will likely change to 'pending' or 'processing'. Monitor the status using `/file/analysis`.
- Reprocessing consumes processing quota similar to an initial upload.
- This does *not* modify the original file stored in S3.

### Import YouTube Download

`POST https://api.storylinezads.com/youtube-import`

Import a previously downloaded YouTube asset into storage and optionally trigger analysis.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Import completed successfully.

```json
{
  "message": "File imported successfully",
  "file": {
    "file_id": "file_yt_123",
    "filename": "Product Feature Breakdown.mp4"
  },
  "job_id": "job_yt_987"
}
```

**Response 400** — Missing required fields (org_id, s3_key, title, original_url).

**Response 403** — User lacks organization permission.

**Response 404** — Source key not found or no longer available.

**Response 500** — Internal server error during import.

**Usage notes**

- Use this endpoint after your YouTube ingestion pipeline has already downloaded media to S3.
- When analyze=true, the response includes a job_id for downstream analysis tracking.
- Imported files follow the same analysis options as regular uploads (context, tags, model flags).

## Folder Management

Endpoints for creating folders, browsing folder contents, and searching within folders.

### Get Folder Contents

`GET https://api.storylinezads.com/folder/contents`

Retrieves a list of files and direct subfolders within a specified folder path. Can optionally retrieve files recursively from subfolders.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Folder contents retrieved successfully.

```json
{
  "folders": [
    {
      "folder_id": "folder_xyz",
      "org_id": "org_abc123",
      "name": "subfolder1",
      "path": "/parent/subfolder1",
      "parent_path": "/parent",
      "created_by": "user_123",
      "created_at": "2024-07-25T11:00:00.000Z",
      "updated_at": "2024-07-25T11:00:00.000Z"
    }
  ],
  "files": [
    {
      "file_id": "file_a1b2c3d4",
      "org_id": "org_abc123",
      "filename": "report.pdf",
      "size": 102400,
      "mimetype": "application/pdf",
      "folder_path": "/parent",
      "upload_date": "2024-07-24T12:00:00.000Z",
      "last_modified": "2024-07-24T12:00:00.000Z",
      "media_type": "documents",
      "processing_status": "completed",
      "rating": {
        "avg_rating": 4.2,
        "rating_count": 15,
        "user_rating": 5
      },
      "urls": {
        "thumbnail": "https://.../thumbnail.jpg?..."
      },
      "analysis_data": null // Or full data if detailed=true
    }
  ],
  "pagination": {
    "current_page": 1,
    "page_size": 50,
    "total_files": 125,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}
```

**Response 400** — Bad Request - Missing org_id.

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Error retrieving data or generating URLs.

```json
{ "error": "Database query failed" }
```

**Usage notes**

- This endpoint is ideal for displaying the contents of a specific folder in a file browser UI.
- The `path` parameter is normalized (ensures leading '/', removes trailing '/' unless root).
- When `recursive` is true, the `files` array contains files from the target `path` and all nested subfolders, while the `folders` array still only shows direct children of `path`.
- Use the `detailed`, `generate_thumbnail`, `generate_streamable`, and `generate_download` parameters to control the amount of data returned per file, balancing detail against response size and performance.
- Setting `detailed=false` and disabling URL generation is recommended for listing large numbers of files quickly.
- The `processing_status` field indicates the state of the file's analysis ('pending', 'processing', 'completed', 'failed').
- Rating information is automatically included for all files. Each file includes `rating.avg_rating` (average across all users), `rating.rating_count` (total number of ratings), and `rating.user_rating` (current user's rating, if any).
- Pagination is applied only to files - folders are always returned in full (as they are typically few in number).
- The `pagination` object provides metadata for building pagination controls: `current_page`, `page_size`, `total_files`, `total_pages`, `has_next`, and `has_prev`.
- Use `sort_by` and `sort_direction` to control file ordering. Rating-based sorting is handled server-side for accuracy.
- When changing page, sorting, or navigation, reset `page` to 1 for the best user experience.
- Combine with `/tree` or `/folder/list` to build navigation structures.

### Create Folder

`POST https://api.storylinezads.com/folder/create`

Creates a new, empty folder within a specified parent folder.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Folder created successfully.

```json
{
  "message": "Folder created successfully",
  "folder": {
    "folder_id": "folder_new123",
    "org_id": "org_abc123",
    "name": "Project Alpha Files",
    "path": "/projects/Project Alpha Files",
    "parent_path": "/projects",
    "created_by": "user_xyz",
    "created_at": "2024-07-26T12:00:00.000Z",
    "updated_at": "2024-07-26T12:00:00.000Z"
  }
}
```

**Response 400** — Bad Request - Missing required fields, invalid folder name (contains '/'), or parent folder does not exist.

```json
{ "error": "Invalid folder name" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 409** — Conflict - A folder with the same name already exists at the specified parent path.

```json
{ "error": "Folder already exists" }
```

**Response 500** — Internal Server Error - Database error.

```json
{ "error": "Database insert failed" }
```

**Usage notes**

- Used to organize files within the application's logical structure.
- The specified `parent_path` must already exist (unless it's the root '/'). To create nested folders, create each level sequentially (e.g., create '/a', then create '/a/b').
- Folder names must be unique within the same parent folder.
- The full `path` for the new folder is constructed automatically based on `parent_path` and `folder_name`.

### Search Files by Name

`GET https://api.storylinezads.com/folder/search-by-name`

Performs a case-insensitive text search for files based on their filenames within a specified folder path. Can optionally search recursively through subfolders.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — File search completed successfully.

```json
{
  "message": "Search completed successfully",
  "path": "/reports",
  "query": "draft",
  "recursive": true,
  "files": [
    {
      "file_id": "file_rep1",
      "org_id": "org_abc123",
      "filename": "Q3_Report_Draft.docx",
      "folder_path": "/reports/archive", 
      "rating": {
        "avg_rating": 3.8,
        "rating_count": 5,
        "user_rating": 4
      },
      // ... other file fields ...
      "urls": {"thumbnail": "..."}
    }
  ],
  "count": 1,
  "pagination": {
    "current_page": 1,
    "page_size": 50,
    "total_files": 1,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
```

**Response 400** — Bad Request - Missing org_id or query.

```json
{ "error": "Search query is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Database query error.

```json
{ "error": "Database search failed" }
```

**Usage notes**

- This endpoint provides simple filename-based searching with pagination support.
- The `query` text is matched case-insensitively against any part of the `filename` field.
- Special characters in the `query` are automatically escaped to ensure safe database searching.
- If `recursive` is true, it searches files directly in `path` and files where `folder_path` starts with `path/`.
- Use the `detailed` and URL generation flags to control the richness of the file data returned.
- The `pagination` object provides metadata for building pagination controls, especially useful for large search result sets.
- Results are sorted by rating by default (`sort_by_rating=true`) to show the most relevant content first.
- For searching based on file *content* or semantic meaning, use the `/folder/vector-search` endpoint instead.

### Vector Search in Folder

`POST https://api.storylinezads.com/folder/vector-search`

Performs a semantic search using natural language queries to find files based on their content and metadata. Searches across vector embeddings generated during analysis.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Vector search completed successfully.

```json
{
  "message": "Vector search completed successfully",
  "path": "/marketing",
  "files": [
    {
      "file_id": "file_mkt1",
      "org_id": "org_abc123",
      "filename": "Q4_Strategy.pptx",
      // ... other file fields ...
      "media_type": "documents",
      "rating": {
        "avg_rating": 4.5,
        "rating_count": 12
      },
      "vector_similarity": 0.88,
      "vector_query": "marketing strategies for Q4",
      "urls": {"thumbnail": "..."}
    },
    {
      "file_id": "file_vid2",
      "org_id": "org_abc123",
      "filename": "Testimonial_Jane_Doe.mp4",
      // ... other file fields ...
      "media_type": "videos",
      "rating": {
        "avg_rating": 4.8,
        "rating_count": 7,
        "user_rating": 5
      },
      "vector_similarity": 0.85,
      "vector_query": "customer testimonials about product X",
      "urls": {"thumbnail": "..."}
    }
  ],
  "count": 2,
  "pagination": {
    "current_page": 1,
    "page_size": 50,
    "total_files": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}
```

**Response 400** — Bad Request - Missing org_id, invalid queries format, or invalid parameter values (num_results, threshold, etc.).

```json
{ "error": "queries must be a non-empty list" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Error communicating with the vector search service or retrieving file details.

```json
{ "error": "Vector search service unavailable" }
```

**Usage notes**

- This endpoint leverages vector embeddings created during file analysis to find semantically relevant content, going beyond simple keyword matching.
- **CRITICAL BEHAVIOR**: To search across ALL files in the organization, do NOT include the `path` parameter in your request, or pass an empty string. This is different from specifying a root path ('/').
- Provide one or more natural language `queries` in the request body.
- Use `file_types` to target specific media (e.g., only search videos and images).
- Adjust `num_results` and `similarity_threshold` to fine-tune the balance between the number of results and their relevance.
- Results from multiple queries are combined, deduplicated, and sorted by `vector_similarity` (highest first).
- Each result includes `vector_similarity` (0-1 score) and `vector_query` (the query that matched the file).
- The `pagination` object provides metadata for building pagination controls when dealing with large search result sets.
- This is powerful for discovering content based on concepts, topics, or descriptions.

### Delete Folder

`DELETE https://api.storylinezads.com/folder/delete`

Deletes a folder. Can optionally delete all files and subfolders contained within it recursively.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Folder deleted successfully.

```json
{ "message": "Folder deleted successfully", "folder_id": "folder_xyz", "files_deletion": { "status": "success", "deleted_count": 15 }, "vectors_deletion": { "status": "success", "deleted_count": 25 }, "analysis_deletion": { "status": "success", "deleted_count": 5 } }
```

**Response 400** — Bad Request - Missing folder_id, or folder is not empty when `delete_contents` is false.

```json
{ "error": "Folder is not empty", "files_count": 3, "subfolders_count": 1 }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified folder_id does not exist.

```json
{ "error": "Folder not found" }
```

**Response 500** — Internal Server Error - Error during database operations or recursive deletion.

```json
{ "error": "Error deleting folder contents" }
```

**Usage notes**

- **Caution:** This operation is irreversible.
- If `delete_contents` is false (default), the endpoint will fail with a 400 error if the folder contains any files or subfolders.
- If `delete_contents` is true, the system will first delete all files (including S3 objects, vector embeddings, analysis data) and subfolders within the target folder, update storage quotas accordingly, and then delete the target folder itself.
- Use `delete_contents=true` with extreme care, especially on folders containing many items.
- The response includes details about the deletion process (number of files, vectors, analysis jobs removed) when `delete_contents` is true.

### Rename Folder

`PUT https://api.storylinezads.com/folder/rename`

Renames a folder. This operation also updates the paths of all contained files and subfolders recursively to reflect the new folder name.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Folder renamed successfully.

```json
{ 
  "message": "Folder renamed successfully", 
  "folder_id": "folder_xyz", 
  "new_name": "Archived Projects", 
  "new_path": "/parent/Archived Projects" 
}
```

**Response 400** — Bad Request - Missing required fields or invalid new name (contains '/').

```json
{ "error": "Valid folder ID and new name are required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified folder_id does not exist.

```json
{ "error": "Folder not found" }
```

**Response 409** — Conflict - A folder with the new name already exists in the same parent directory.

```json
{ "error": "A folder with this name already exists" }
```

**Response 500** — Internal Server Error - Error during the cascading update of paths.

```json
{ "error": "Error updating child paths" }
```

**Usage notes**

- Renaming a folder is a potentially complex operation as it requires updating database records for the folder itself, all descendant folders, and all files contained within them.
- The system updates the `name` and `path` of the target folder.
- It recursively updates the `path` and `parent_path` of all subfolders.
- It recursively updates the `folder_path` and `last_modified` timestamp of all files within the renamed folder structure.
- This is a logical rename within the application; the physical S3 keys of the files are not changed.
- Ensure the `new_name` is unique within the parent directory to avoid a 409 conflict.

### Move Folder

`PUT https://api.storylinezads.com/folder/move`

Moves an existing folder to a different parent path without changing its folder_id.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Folder moved successfully.

```json
{
  "message": "Folder moved successfully",
  "folder": {
    "folder_id": "folder_xyz",
    "path": "/archive/2026/Project Assets"
  }
}
```

**Response 400** — Missing folder_id or target_parent_path.

**Response 403** — User lacks organization permission.

**Response 404** — Folder not found.

**Response 409** — Destination path conflicts with an existing folder name.

**Response 500** — Internal server error.

**Usage notes**

- The folder and all child paths are updated logically in metadata.
- Use normalized absolute paths for target_parent_path (for example, /archive/2026).
- Physical media object keys in S3 are not moved by this operation.

### Get Folder Tree

`GET https://api.storylinezads.com/tree`

Generates and retrieves a hierarchical tree structure representing folders and files, starting from a specified root path.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Folder tree retrieved successfully.

```json
{
  "path": "/projects",
  "folders": [
    {
      "name": "Project Alpha",
      "folder_id": "folder_alpha",
      "path": "/projects/Project Alpha",
      "folders": [
        {
          "name": "Assets",
          "folder_id": "folder_assets",
          "path": "/projects/Project Alpha/Assets",
          "folders": [],
          "files": [{"file_id": "file_asset1", "filename": "logo.png"}]
        }
      ],
      "files": [{"file_id": "file_readme", "filename": "README.md"}]
    }
  ],
  "files": [{"file_id": "file_overview", "filename": "Overview.docx"}]
}
```

**Response 400** — Bad Request - Missing org_id.

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Error during recursive database query.

```json
{ "error": "Failed to build tree structure" }
```

**Usage notes**

- This endpoint is designed for building UI elements like tree views or file explorers.
- It recursively fetches the entire folder and file hierarchy starting from the specified `path`.
- File entries within the tree are simplified, containing only `file_id` and `filename` to keep the response size manageable.
- To get full details for a specific file shown in the tree, use the `/file/analysis` endpoint with its `file_id`.
- Compared to `/folder/contents`, `/tree` provides the full nested structure in one call but with less detail per item.
- Compared to `/folder/list`, `/tree` includes file references.

### List Folders

`GET https://api.storylinezads.com/folder/list`

Retrieves a list of folder objects under a specified parent path. Can optionally list all descendant folders recursively.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Folders retrieved successfully.

```json
{
  "folders": [
    {
      "folder_id": "folder_alpha",
      "org_id": "org_abc123",
      "name": "Project Alpha",
      "path": "/projects/Project Alpha",
      "parent_path": "/projects",
      // ... other folder fields ...
    },
    {
      "folder_id": "folder_assets",
      "org_id": "org_abc123",
      "name": "Assets",
      "path": "/projects/Project Alpha/Assets",
      "parent_path": "/projects/Project Alpha",
      // ... other folder fields ...
    } // Included if recursive=true
  ],
  "count": 2,
  "path": "/projects"
}
```

**Response 400** — Bad Request - Missing org_id.

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Database query error.

```json
{ "error": "Failed to retrieve folders" }
```

**Usage notes**

- This endpoint returns only folder metadata, not the files contained within them.
- If `recursive` is false (default), only direct child folders of the specified `path` are returned.
- If `recursive` is true, all folders whose `parent_path` starts with or equals the specified `path` are returned, effectively listing all descendants.
- This is useful for building folder pickers or navigation elements where only the folder structure is needed, potentially offering better performance than `/tree` if file information is not required.

### Browse Folders (Paginated)

`GET https://api.storylinezads.com/folders/browse`

List folder entries at a given path with server-side pagination and sorting.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Folder page returned successfully.

```json
{
  "folders": [{"folder_id": "folder_alpha", "path": "/projects/alpha"}],
  "pagination": {"current_page": 1, "page_size": 50, "total": 12, "total_pages": 1}
}
```

**Response 400** — Missing org_id or invalid pagination/sort values.

**Response 403** — User lacks organization permission.

**Response 500** — Internal server error.

**Usage notes**

- Use this endpoint when folder counts are large and you need predictable pagination.
- Unlike /folder/list, this endpoint is optimized for page-by-page browsing interfaces.
- Sort defaults are stable and server-validated.

## File Management

Endpoints for managing individual files, including deletion, renaming, moving, downloading, and retrieving analysis results.

### Delete File

`DELETE https://api.storylinezads.com/file/delete`

Permanently deletes a file, including its S3 object(s), associated analysis data, and vector embeddings. Reclaims storage space.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — File deleted successfully.

```json
{
  "message": "File deleted successfully",
  "file_id": "file_a1b2c3d4",
  "file_deletion": { "status": "success", "deleted_count": 3 },
  "vector_deletion": { "status": "success", "deleted_count": 5 },
  "analysis_deletion": { "status": "success", "deleted_count": 1 },
  "associated_projects_count": 0
}
```

**Response 400** — Bad Request - Missing file_id.

```json
{ "error": "File ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified file_id does not exist.

```json
{ "error": "File not found" }
```

**Response 409** — Conflict - File cannot be deleted because it is associated with one or more projects.

```json
{ "error": "File is associated with one or more projects and cannot be deleted", "associated_projects": [{"project_id": "proj_1", "name": "Project Alpha"}] }
```

**Response 500** — Internal Server Error - Error during database or resource deletion.

```json
{ "error": "Error deleting S3 objects" }
```

**Usage notes**

- **Caution:** This operation is irreversible.
- Before deleting, the system checks if the `file_id` is listed in the `associated_files` array of any project documents. If associations exist, deletion is blocked (409 Conflict), and the associated projects are listed in the error response.
- Successful deletion removes the file record from the database, deletes related S3 objects (original, processed versions, thumbnails), removes associated vector embeddings, and deletes analysis job records.
- The file's size is subtracted from the organization's storage usage quota.
- The response provides details on the success and scope of deleting associated resources.

### Rename File

`PUT https://api.storylinezads.com/file/rename`

Updates the display name (`filename`) of a file. This is a logical change and does not affect the file's S3 key or its physical storage location.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — File renamed successfully.

```json
{ 
  "message": "File renamed successfully", 
  "file_id": "file_a1b2c3d4", 
  "new_name": "Final Report Q3.pdf" 
}
```

**Response 400** — Bad Request - Missing file_id or new_name.

```json
{ "error": "File ID and new name are required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified file_id does not exist.

```json
{ "error": "File not found" }
```

**Response 500** — Internal Server Error - Database update failed.

```json
{ "error": "Database update failed" }
```

**Usage notes**

- This operation only updates the `filename` field in the file's database record.
- The `original_filename` (name at the time of upload) and the `s3_key` (physical storage path) remain unchanged.
- The file's `last_modified` timestamp is updated to reflect this change.
- Changing the file extension in the `new_name` does not change the file's actual type or how it's processed; it only affects the display name.

### Move File

`PUT https://api.storylinezads.com/file/move`

Moves a file to a different logical folder within the organization by updating its `folder_path`. This does not change the file's physical S3 location.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — File moved successfully.

```json
{ 
  "message": "File moved successfully", 
  "file_id": "file_a1b2c3d4", 
  "target_folder_path": "/archive/2023" 
}
```

**Response 400** — Bad Request - Missing required fields or target folder does not exist.

```json
{ "error": "Target folder does not exist" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified file_id does not exist.

```json
{ "error": "File not found" }
```

**Response 500** — Internal Server Error - Database update failed.

```json
{ "error": "Database update failed" }
```

**Usage notes**

- This operation is used for organizing files within the application's folder structure.
- The `target_folder_path` must correspond to an existing folder (created via `/folder/create`), unless it's the root ('/').
- Only the `folder_path` field in the file's database record is updated.
- The file's `last_modified` timestamp is also updated.
- The physical location (`s3_key`) of the file in S3 remains unchanged.

### Generate Download Link

`GET https://api.storylinezads.com/file/download`

Generates a temporary, secure pre-signed URL for downloading a file. It prioritizes providing a link to a processed version if available, otherwise falls back to the original file.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Download link generated successfully.

```json
{ 
  "download_url": "https://your-bucket.s3.amazonaws.com/processed/org_id/unique_id/processed_file.mp4?...", 
  "filename": "example.mp4", 
  "expires_in": 3600 
}
```

**Response 400** — Bad Request - Missing file_id.

```json
{ "error": "File ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified file_id does not exist.

```json
{ "error": "File not found" }
```

**Response 500** — Internal Server Error - Failed to generate the S3 link.

```json
{ "error": "Error generating S3 link" }
```

**Usage notes**

- This endpoint provides a convenient way to get a downloadable link for a file.
- It checks if processed versions (e.g., optimized video, document preview) are available and provides a link to those first.
- If no processed version suitable for download exists, it provides a link to the original uploaded file.
- The generated `download_url` is temporary and typically expires after 1 hour (`expires_in`: 3600 seconds).
- To *guarantee* a link to the original, unprocessed file, use the `/file/download/original` endpoint instead.

### Get File Analysis

`GET https://api.storylinezads.com/file/analysis`

Retrieves comprehensive details about a single file, including its metadata, current processing status, the parameters used for analysis, the analysis results (if completed), and generated URLs (thumbnail, streamable, download).

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Analysis data retrieved successfully.

```json
{
  "file_id": "file_a1b2c3d4",
  "org_id": "org_abc123",
  "filename": "example.mp4",
  "original_filename": "example.mp4",
  "folder_path": "/videos",
  "size": 15728640,
  "mimetype": "video/mp4",
  "uploaded_by": "user_xyz",
  "upload_date": "2024-07-26T10:30:00.000Z",
  "last_modified": "2024-07-26T10:30:00.000Z",
  "job_id": "job_1234567890",
  "media_type": "videos",
  "processing_status": "completed",
  "urls": {
    "thumbnail": "https://.../thumbnail.jpg?...",
    "streamable": "https://.../streamable.mp4?...",
    "download": "https://.../download.mp4?...",
    "original_url": "https://.../original.mp4?..."
  },
  "analysis_data": {
    "scenes": [ ... ],
    "transcript": "...",
    "summary": "..."
    // Other video-specific analysis results
  },
  "analysis_params": {
    "context": "Product demo video.",
    // Other params used
  }
}
```

**Response 400** — Bad Request - Missing file_id.

```json
{ "error": "File ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified file_id does not exist.

```json
{ "error": "File not found" }
```

**Response 500** — Internal Server Error - Error retrieving data or generating URLs.

```json
{ "error": "Failed to enhance file data" }
```

**Usage notes**

- This is the primary endpoint for checking the status and results of a file's analysis.
- The `processing_status` field indicates the current state: 'pending', 'processing', 'completed', or 'failed'.
- If `processing_status` is 'completed' and `detailed` is true, the `analysis_data` object will contain the results. The structure of `analysis_data` varies depending on the `media_type` (video, audio, image, document).
- The `analysis_params` object shows the settings that were used for the most recent analysis job.
- Use the URL generation flags to control which temporary access URLs are included in the response.
- This endpoint can be polled periodically after an upload (`/upload/complete`) or reprocessing (`/file/reprocess`) call to check when analysis is finished.

### Get Reference Video

`GET https://api.storylinezads.com/reference/get`

Fetches a reference video by file_id with optional generated links and lightweight payload defaults.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Reference video retrieved successfully.

```json
{
  "file_id": "file_ref_123",
  "filename": "reference_clip.mp4",
  "urls": {"thumbnail": "https://...", "streamable": "https://..."}
}
```

**Response 400** — Missing file_id.

**Response 403** — User lacks permission for the file's organization.

**Response 404** — Reference file not found.

**Response 500** — Internal server error.

**Usage notes**

- Use this endpoint for reference-video specific retrieval flows where include_usage remains disabled by default.
- Compared to /file/analysis, this route is optimized for reference video viewing contexts.
- Generated URLs are temporary and should be refreshed when they expire.

### Get Files by IDs

`POST https://api.storylinezads.com/files/get_by_ids`

Retrieves detailed information for multiple files simultaneously, based on a provided list of file IDs. Useful for batch operations.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Files retrieved successfully.

```json
{
  "files": [
    { "file_id": "file_a1b2c3d4", /* ...file details... */ },
    { "file_id": "file_e5f6g7h8", /* ...file details... */ }
  ],
  "count": 2,
  "missing": ["file_invalid99"]
}
```

**Response 400** — Bad Request - Missing org_id, missing/empty file_ids list, or too many IDs requested (> 100).

```json
{ "error": "file_ids must be a non-empty list" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Database query error.

```json
{ "error": "Database query failed" }
```

**Usage notes**

- This endpoint provides an efficient way to fetch data for multiple specific files in one API call.
- It queries the database for files matching the provided `file_ids` *and* belonging to the specified `org_id`.
- The `files` array in the response contains the documents for the found files. The order generally matches the input `file_ids` array, skipping any missing IDs.
- Any `file_id` from the request list that was not found (or didn't belong to the specified `org_id`) is included in the `missing` array.
- Use the `detailed` and URL generation flags (in query parameters) to control the amount of data returned for each file.
- Useful after getting a list of IDs from search results (`/folder/search-by-name`, `/folder/vector-search`) or a tree view (`/tree`) if more details are needed.

### Download Original File

`GET https://api.storylinezads.com/file/download/original`

Generates a temporary, secure pre-signed URL specifically for downloading the original, unprocessed file exactly as it was uploaded.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Download link for the original file generated successfully.

```json
{ 
  "download_url": "https://your-bucket.s3.amazonaws.com/userdata/org_id/unique_id/original_file.mp4?...", 
  "filename": "example.mp4", 
  "expires_in": 3600 
}
```

**Response 400** — Bad Request - Missing file_id.

```json
{ "error": "File ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified file_id does not exist.

```json
{ "error": "File not found" }
```

**Response 500** — Internal Server Error - Failed to generate the S3 link.

```json
{ "error": "Error generating S3 link" }
```

**Usage notes**

- This endpoint guarantees access to the raw, unmodified file stored in the `userdata/` path in S3.
- It directly uses the file's `s3_key` to generate the download link.
- Unlike `/file/download`, this endpoint *never* provides a link to a processed version, even if one exists.
- Useful when you specifically need the original file for backup, external processing, or verification.
- The generated `download_url` is temporary and typically expires after 1 hour (`expires_in`: 3600 seconds).

### Rate File

`POST https://api.storylinezads.com/file/rate`

Allows users to rate a file on a scale of 1-5 stars. Updates existing rating if the user has already rated the file.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — File rated successfully.

```json
{
  "message": "File rated successfully",
  "file_id": "file_a1b2c3d4",
  "rating": {
    "avg_rating": 4.2,
    "rating_count": 15,
    "user_rating": 5
  }
}
```

**Response 400** — Bad Request - Missing file_id or rating, or invalid rating value (must be 1-5).

```json
{ "error": "Rating must be between 1 and 5" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified file_id does not exist.

```json
{ "error": "File not found" }
```

**Response 500** — Internal Server Error - Database error.

```json
{ "error": "Database operation failed" }
```

**Usage notes**

- Rating must be an integer between 1 and 5 (inclusive).
- If the user has already rated this file, their previous rating is updated.
- The response includes updated aggregate rating information for the file.
- Only users with permission to access the file's organization can rate it.
- Ratings are stored per user and aggregated to calculate average ratings.

### Remove File Rating

`POST https://api.storylinezads.com/file/remove_rating`

Removes the authenticated user's rating from a file. Does not affect other users' ratings.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Rating removal operation completed (regardless of whether a rating existed).

```json
{
  "message": "Rating removed successfully",
  "file_id": "file_a1b2c3d4",
  "was_removed": true,
  "rating": {
    "avg_rating": 3.8,
    "rating_count": 14
  }
}
```

**Response 400** — Bad Request - Missing file_id.

```json
{ "error": "File ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified file_id does not exist.

```json
{ "error": "File not found" }
```

**Response 500** — Internal Server Error - Database error.

```json
{ "error": "Database operation failed" }
```

**Usage notes**

- `was_removed` indicates whether a rating was actually found and removed.
- If the user hadn't rated the file, `was_removed` will be `false` but the operation succeeds.
- The response includes updated aggregate rating information after removal.
- Only affects the authenticated user's rating; other users' ratings remain unchanged.

### Get File Rating

`GET https://api.storylinezads.com/file/get_rating`

Retrieves rating information for a specific file, including average rating, total count, and the authenticated user's rating (if any).

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Rating information retrieved successfully.

```json
{
  "file_id": "file_a1b2c3d4",
  "rating": {
    "avg_rating": 4.2,
    "rating_count": 15,
    "user_rating": 5
  }
}
```

**Response 400** — Bad Request - Missing file_id.

```json
{ "error": "File ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified file_id does not exist.

```json
{ "error": "File not found" }
```

**Response 500** — Internal Server Error - Database error.

```json
{ "error": "Database operation failed" }
```

**Usage notes**

- `avg_rating` is the average of all user ratings for this file (0 if no ratings).
- `rating_count` is the total number of users who have rated this file.
- `user_rating` is only included if the authenticated user has rated this file.
- Ratings are calculated in real-time from the file ratings collection.
- Use this endpoint to get standalone rating information without full file details.

## Storage Management

Endpoints related to monitoring storage and processing usage against subscription limits.

### Get Storage Usage

`GET https://api.storylinezads.com/storage/usage`

Retrieves detailed information about the organization's current storage usage, storage limits, and content processing usage relative to their subscription plan.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Storage usage and limits retrieved successfully.

```json
{
  "tier": 1,
  "plan_name": "Premium",
  "storage_used_bytes": 5368709120,
  "storage_used_gb": 5.0,
  "storage_limit_bytes": 107374182400,
  "storage_limit_gb": 100.0,
  "content_processed_bytes": 8589934592,
  "content_processed_gb": 8.0,
  "period_content_processed_bytes": 1073741824,
  "period_content_processed_gb": 1.0,
  "period_content_processed_limit_bytes": 10737418240,
  "period_content_processed_limit_gb": 10.0,
  "period_start": "2024-07-01T00:00:00.000Z",
  "period_end": "2024-07-31T23:59:59.999Z",
  "percentage_used": 5.0,
  "percentage_processing_used": 10.0
}
```

**Response 400** — Bad Request - Missing org_id.

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized - Authentication failed.

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User lacks permission for the organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error - Failed to retrieve subscription or usage data.

```json
{ "error": "Error retrieving usage data" }
```

**Usage notes**

- This endpoint provides a snapshot of the organization's resource consumption against its plan limits.
- `storage_used_bytes` reflects the sum of sizes of all files currently stored for the organization.
- `storage_limit_bytes` is the maximum storage allowed under the current plan.
- `period_content_processed_bytes` tracks the amount of data processed (e.g., analyzed) within the current billing cycle (`period_start` to `period_end`).
- `period_content_processed_limit_bytes` is the limit for processing within the current cycle.
- Values are provided in both bytes and gigabytes (GB, using 1024^3) for convenience.
- `percentage_used` and `percentage_processing_used` are useful for displaying usage meters in a UI.
- If the organization doesn't have a specific subscription, details for the default (e.g., free) tier are returned.
- This data can be used to inform users about their usage and potential need for upgrades.

### List Unused Files

`GET https://api.storylinezads.com/files/unused`

Returns files in an organization that are not attached to any project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Unused files list returned successfully.

```json
{
  "files": [{"file_id": "file_123", "filename": "unused_clip.mp4"}],
  "pagination": {"current_page": 1, "page_size": 50, "total_files": 12, "total_pages": 1}
}
```

**Response 400** — Missing org_id or invalid pagination/sort parameters.

**Response 403** — User lacks organization permission.

**Response 500** — Internal server error.

**Usage notes**

- Use this endpoint to clean orphaned content and reduce storage footprint.
- Cursor fields help with stable scans when many files share the same sort key.
- Generated URLs are optional - disable them for faster large-page audits.


---

# Stock Media API

Source: https://storylinezads.com/docs/api/stock
Last generated: 2026-07-20

Search, filter, and retrieve stock media (videos, audios, images) from the StoryLinez platform

Base route: `/stock` (relative to `https://api.storylinezads.com`)

## Search

Search for stock media using different methods

### Vector Search for Stock Media

`POST https://api.storylinezads.com/search`

Searches for stock media using vector similarity to the provided natural language queries.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — OK

```json
{
  "videos": [
    {
      "_id": "60d21b4667d0d8992e610c85",
      "stock_id": "60d21b4667d0d8992e610c85",
      "media_type": "videos",
      "analysis_data": {
        "results": {
          "summary": "Description of the video",
          "nickname": "Short title",
          "tags": ["tag1", "tag2"],
          "points_of_interests": [
            {"time": 3.2, "description": "Important moment"}
          ]
        },
        "status": "COMPLETED"
      },
      "urls": {
        "thumbnail_url": "https://example.com/thumbnail.jpg",
        "low_quality_url": "https://example.com/streamable.mp4",
        "original_url": "https://example.com/download.mp4"
      },
      "original_metadata": {
        "artist": "Creator name",
        "description": "Original description"
      },
      "user_interaction": "like",
      "likes": 42,
      "dislikes": 2,
      "net_score": 40
    }
  ],
  "audios": [...],
  "images": [...],
  "counts": {
    "videos": 1,
    "audios": 2,
    "images": 1,
    "total": 4
  },
  "query": ["person running on a beach", "sunset over mountains"]
}
```

**Response 400** — Bad Request

```json
{ "error": "No queries provided" }
```

**Response 400** — Bad Request

```json
{ "error": "Invalid numeric parameters" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- The queries array must contain at least one natural language query string.
- Results honor both similarity scores and interaction data — liked items float to the top, while disliked ones appear last.
- Each item includes user_interaction, likes, dislikes, and net_score fields so you can render personalized state in the UI.
- When detailed=false, only a subset of analysis data is returned.
- The orientation filter only applies to videos, not audios or images.

## Retrieval

Retrieve specific stock media items by ID

### Get Stock Media by ID

`GET https://api.storylinezads.com/get_by_id`

Retrieves a specific stock media item by its ID.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "_id": "60d21b4667d0d8992e610c85",
  "stock_id": "60d21b4667d0d8992e610c85",
  "media_type": "videos",
  "analysis_data": {
    "results": {
      "summary": "Description of the video",
      "nickname": "Short title",
      "tags": ["tag1", "tag2"],
      "points_of_interests": [
        {"time": 3.2, "description": "Important moment"}
      ],
      "paths": {
        "original": "path/to/original.mp4",
        "thumbnail": "path/to/thumbnail.jpg",
        "low_quality": "path/to/low_quality.mp4"
      }
    },
    "status": "COMPLETED"
  },
  "urls": {
    "thumbnail_url": "https://example.com/thumbnail.jpg",
    "low_quality_url": "https://example.com/streamable.mp4",
    "original_url": "https://example.com/download.mp4"
  },
  "original_metadata": {
    "artist": "Creator name",
    "description": "Original description"
  },
  "user_interaction": "dislike",
  "likes": 5,
  "dislikes": 2,
  "net_score": 3
}
```

**Response 400** — Bad Request

```json
{ "error": "Both id and media_type are required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 404** — Not Found

```json
{ "error": "Stock item not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- The id can be either a MongoDB ObjectId or a stock_id string.
- The media_type must be one of: videos, audios, images.
- When detailed=true, full analysis data is returned including transcripts and metadata.
- Responses include user_interaction, likes, dislikes, and net_score so you can reflect the viewer's state.

### Get Multiple Stock Media Items by IDs

`POST https://api.storylinezads.com/get_by_ids`

Retrieves multiple stock media items by their IDs.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — OK

```json
{
  "items": [
    {
      "_id": "60d21b4667d0d8992e610c85",
      "stock_id": "60d21b4667d0d8992e610c85",
      "media_type": "videos",
      "analysis_data": {
        "results": {
          "summary": "Description of the video",
          "nickname": "Short title",
          "tags": ["tag1", "tag2"]
        },
        "status": "COMPLETED"
      },
      "urls": {
        "thumbnail_url": "https://example.com/thumbnail.jpg"
      },
      "user_interaction": "like",
      "likes": 9,
      "dislikes": 0,
      "net_score": 9
    },
    ...
  ],
  "count": 2,
  "missing": [
    {
      "id": "non-existent-id",
      "media_type": "images"
    }
  ]
}
```

**Response 400** — Bad Request

```json
{ "error": "media_types must have same length as ids" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- The ids array must have the same length as the media_types array.
- Each media_type must be one of: videos, audios, images.
- Maximum 100 IDs can be requested in a single call.
- Results maintain the original order of requested IDs.
- Responses include user_interaction, likes, dislikes, and net_score for each item.
- Missing items are reported in the 'missing' array.

## Browsing

Browse and filter stock media collections

### List Stock Media

`GET https://api.storylinezads.com/list`

Lists stock media with filtering, sorting, and pagination options.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "results": [
    {
      "_id": "60d21b4667d0d8992e610c85",
      "stock_id": "60d21b4667d0d8992e610c85",
      "media_type": "videos",
      "analysis_data": {
        "results": {
          "summary": "Description of the video",
          "nickname": "Short title",
          "tags": ["tag1", "tag2"]
        },
        "status": "COMPLETED"
      },
      "urls": {
        "thumbnail_url": "https://example.com/thumbnail.jpg"
      },
      "original_metadata": {
        "artist": "Creator name",
        "description": "Original description"
      },
      "user_interaction": null,
      "likes": 18,
      "dislikes": 1,
      "net_score": 17
    }
  ],
  "count": 20,
  "total": 157,
  "page": 1,
  "limit": 20,
  "total_pages": 8,
  "media_type": "videos"
}
```

**Response 400** — Bad Request

```json
{ "error": "Valid media_type (videos, audios, or images) is required" }
```

**Response 400** — Bad Request

```json
{ "error": "limit must be between 1 and 100" }
```

**Response 400** — Bad Request

```json
{ "error": "sort_order must be either asc or desc" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- The media_type parameter is required and must be one of: videos, audios, images.
- smart_sort=true keeps liked assets ahead of neutral results and sends disliked items to the bottom; set it to false to respect raw sort order only.
- Each item includes user_interaction, likes, dislikes, and net_score for rendering personalized UX states.
- limit must be between 1 and 100; requests outside this range are rejected.
- The search parameter performs a case-insensitive regex search on artist and description metadata.
- The orientation filter only applies when media_type is "videos".

## User Interactions

Endpoints for managing user interactions with stock media including likes, dislikes, and interaction removal. These interactions affect content ordering with smart rearrangement.

### Like Stock Media

`POST https://api.storylinezads.com/like`

Like a specific stock media item. This interaction affects content ordering in future API responses, with liked items appearing first.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Stock media liked successfully.

```json
{ "success": true, "message": "Stock media liked successfully", "interaction_type": "like" }
```

**Response 400** — Missing required fields.

```json
{ "error": "stock_id and media_type are required" }
```

**Response 404** — Stock media not found.

```json
{ "error": "Stock media not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Note: Liked stock media will appear first in search results and media listings for the authenticated user.
- Guide: Use this to implement thumbs-up functionality in your media discovery interface.
- Tip: Interactions are user-specific and affect all future API responses with smart content rearrangement.

### Dislike Stock Media

`POST https://api.storylinezads.com/dislike`

Dislike a specific stock media item. This interaction affects content ordering in future API responses, with disliked items appearing last.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Stock media disliked successfully.

```json
{ "success": true, "message": "Stock media disliked successfully", "interaction_type": "dislike" }
```

**Response 400** — Missing required fields.

```json
{ "error": "stock_id and media_type are required" }
```

**Response 404** — Stock media not found.

```json
{ "error": "Stock media not found" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Note: Disliked stock media will appear last in search results and media listings for the authenticated user.
- Guide: Use this to implement thumbs-down functionality in your media discovery interface.
- Tip: Users can change their interaction from like to dislike or vice versa by calling the appropriate endpoint.

### Remove Stock Media Interaction

`POST https://api.storylinezads.com/remove_interaction`

Remove any existing interaction (like or dislike) with a specific stock media item, resetting it to neutral status.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Interaction removed successfully.

```json
{ "success": true, "message": "Interaction removed successfully", "interaction_type": null }
```

**Response 400** — Missing required fields.

```json
{ "error": "stock_id and media_type are required" }
```

**Response 404** — Stock media not found or no interaction exists.

```json
{ "error": "Stock media not found or no interaction exists" }
```

**Response 500** — Internal server error.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Note: After removal, the stock media will appear in normal order (not first or last) in future API responses.
- Guide: Use this to implement an 'undo' or 'reset' feature in your interaction interface.
- Tip: This endpoint completely removes any interaction, returning the item to neutral status.


---

# Projects API

Source: https://storylinezads.com/docs/api/projects
Last generated: 2026-07-20

Manage projects in the Storylinez application

Base route: `/projects` (relative to `https://api.storylinezads.com`)

## Project Folders

Create, retrieve, update, and delete project folders

### Create Project Folder

`POST https://api.storylinezads.com/folders/create`

Creates a new folder for organizing projects within an organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 201** — Created

```json
{
  "folder_id": "fldr_12345",
  "name": "Marketing Folder",
  "org_id": "org_12345",
  "description": "Folder for marketing projects",
  "label_icon": "star",
  "label_color": "#FF8A4C",
  "created_by": "user_12345",
  "created_at": "2024-05-18T14:32:10Z",
  "updated_at": "2024-05-18T14:32:10Z"
}
```

**Response 400** — Bad Request

```json
{ "error": "Folder name is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 409** — Conflict

```json
{ "error": "A folder with this name already exists" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Ensure org_id is valid and the user has access.
- Folder names must be unique within an organization.
- label_icon and label_color values are trimmed automatically; send an empty string to clear either field.
- This endpoint creates a new project folder with a unique folder ID and timestamps.

### Get All Project Folders

`GET https://api.storylinezads.com/folders/get_all`

Retrieves all project folders for a given organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "folders": [
    {
      "folder_id": "fldr_12345",
      "name": "Marketing Folder",
      "org_id": "org_12345",
      "description": "Folder for marketing projects",
      "label_icon": "star",
      "label_color": "#FF8A4C",
      "created_by": "user_12345",
      "created_at": "2024-05-18T14:32:10Z",
      "updated_at": "2024-05-18T14:32:10Z"
    }
  ]
}
```

**Response 400** — Bad Request

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Use this to populate folder lists or dropdowns.
- Useful for listing all folders in settings or admin panels.
- Ensure the user has the correct permissions to access the organization.
- The response is an object with a folders array listing each folder including label_icon/label_color metadata.

### Update Project Folder

`PUT https://api.storylinezads.com/folders/update`

Updates an existing project folder’s name and/or description.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — OK

```json
{
  "folder_id": "fldr_12345",
  "name": "Updated Folder Name",
  "org_id": "org_12345",
  "description": "New folder description",
  "label_icon": "sparkles",
  "label_color": "#4F46E5",
  "created_by": "user_12345",
  "created_at": "2024-05-18T14:32:10Z",
  "updated_at": "2024-06-02T09:12:00Z"
}
```

**Response 400** — Bad Request

```json
{ "error": "No valid fields to update" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Folder not found" }
```

**Response 409** — Conflict

```json
{ "error": "A folder with this name already exists" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- At least one of name, description, label_icon, or label_color must be provided.
- Whitespace is trimmed automatically; send an empty string to remove label metadata.
- This endpoint updates the folder's details and refreshes the updated_at timestamp.

### Delete Project Folder

`DELETE https://api.storylinezads.com/folders/delete`

Deletes a project folder. Optionally moves projects to the root folder if they exist. Use this endpoint to permanently remove a folder while ensuring that any projects associated with the folder are either preserved or moved. This endpoint also explains what to do when folder contains projects and how to use the move_projects flag.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Folder deleted successfully. Returns a summary with a message, folder identifier and number of projects moved.

```json
{
  "message": "Folder deleted successfully",
  "folder_id": "<folder_id>",
  "projects_moved": 5
}
```

**Response 400** — Bad Request – folder_id missing or if the folder contains projects and move_projects flag is not true.

```json
{
  "error": "Folder contains projects. Use move_projects=true to move projects to root.",
  "projects_count": 3
}
```

**Response 401** — Unauthorized – API key or secret is invalid.

```json
{ "error": "Unauthorized access" }
```

**Response 403** — Forbidden – User does not have permission for the organization owning the folder.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found – The specified folder_id does not exist.

```json
{ "error": "Folder not found" }
```

**Response 500** — Internal Server Error – An unexpected error occurred.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Ensure that the folder_id parameter corresponds to an existing project folder.
- If the folder contains projects, set move_projects=true to avoid errors. Otherwise, deletion will fail.
- API credentials (X-API-Key and X-API-Secret) must be valid.
- This endpoint is best used in conjunction with project listing endpoints to verify folder contents before deletion.

## Project Management

Endpoints for managing projects

### Search Projects

`GET https://api.storylinezads.com/search/projects`

Advanced search for projects with filtering, sorting, and pagination. Supports searching by text query across multiple fields, filtering by various attributes, and date ranges.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "projects": [
    {
      "project_id": "proj_12345",
      "name": "Marketing Campaign",
      // ... other project fields
    }
  ],
  "pagination": {
    "total": 25,
    "page": 1,
    "limit": 10,
    "total_pages": 3
  },
  "search_info": {
    "query": "marketing",
    "search_fields": ["name", "purpose"],
    "results_count": 10,
    "filters_applied": { /* applied filters */ }
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Combine multiple filters to refine search results.
- Date filters must use ISO format (YYYY-MM-DDTHH:MM:SSZ).
- Use folder_id=none to find projects without a folder assignment.
- Search is case-insensitive across all specified fields.
- Response includes detailed pagination and search metadata.

### Search Folders

`GET https://api.storylinezads.com/search/folders`

Advanced search for project folders with filtering, sorting, and pagination. Supports searching by text query across multiple fields and filtering by date ranges.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "folders": [
    {
      "folder_id": "fldr_12345",
      "name": "Marketing Campaigns",
      // ... other folder fields
    }
  ],
  "pagination": {
    "total": 15,
    "page": 1,
    "limit": 10,
    "total_pages": 2
  },
  "search_info": {
    "query": "marketing",
    "search_fields": ["name", "description"],
    "results_count": 10,
    "filters_applied": { /* applied filters */ }
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Search is case-insensitive across all specified fields.
- Date filters must use ISO format (YYYY-MM-DDTHH:MM:SSZ).
- Combine multiple filters to refine search results.
- Response includes detailed pagination and search metadata.

### Create Project

`POST https://api.storylinezads.com/create`

Creates a new project within the organization using all required fields including name, orientation, and organization ID. Additional optional parameters allow you to associate company details, brands, folders, files, and custom settings. This endpoint provides a comprehensive guide with examples and requirements to customize your new project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 201** — Project created successfully. Returns the new project object along with the current project limit counts.

```json
{
  "project": {
    "project_id": "proj_12345",
    "name": "New Project Name",
    "org_id": "org_12345",
    "type": "v1",
    "status": "draft",
    "orientation": "landscape",
    "company_details_id": "comp_678",
    "brand_id": "brand_456",
    "folder_id": "fldr_marketing",
    "purpose": "Description of project purpose",
    "target_audience": "Description of target audience",
    "associated_files": ["file_1", "file_2"],
    "settings": {
      "resolution": "1080p",
      "theme": "bold"
    },
    "created_by": "user_67890",
    "created_at": "2024-05-18T14:32:10Z",
    "updated_at": "2024-05-18T14:32:10Z"
  },
  "project_limits": {
    "period_count": 5,
    "daily_count": 1
  }
}
```

**Response 400** — Bad Request – Occurs when required fields are missing or when input values do not meet the validation criteria.

```json
{ "error": "Project name is required" }
```

**Response 401** — Unauthorized – API credentials are missing or invalid.

```json
{ "error": "Unauthorized access" }
```

**Response 403** — Forbidden – The user does not have permission for the organization or the project creation quota is exhausted.

```json
{ "error": "Project creation limit reached for current billing period" }
```

**Response 404** — Not Found – One or more referenced resources (folder, company details, brand, or associated files) were not found.

```json
{ "error": "Specified folder not found or does not belong to this organization" }
```

**Response 415** — Unsupported Media Type – Requests must send application/json.

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal Server Error – An unexpected error occurred.

```json
{ "error": "Internal server error" }
```

**Usage notes**

- All required fields (name, org_id, and orientation) must be included in the request body.
- The type field defaults to 'v1'. Choose 'v2' to onboard projects into the sequence builder; v2 requests ignore associated_files and settings.
- If company_details_id or brand_id are omitted, Storylinez attempts to load the organization’s defaults. The call fails with 400 if no defaults exist.
- The associated_files array must reference files in the same organization and is only supported for v1 projects.
- The settings object applies to v1 projects and is useful for resolution, style, or scheduling preferences.
- Requests must be sent as application/json. Project creation consumes quota and may return 403 when billing limits are exhausted.
- For reusing existing projects, combine this creation endpoint with duplication and folder management flows.

### Move Project to Folder

`PUT https://api.storylinezads.com/move_to_folder`

Moves an existing project to a specified folder or to root.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — OK

```json
{ ...message with new folder info... }
```

**Response 400** — Bad Request

```json
{ "error": "Project ID is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project or folder not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Supply folder_id to move into a folder or omit to move to root.
- The endpoint validates folder existence and user's organization permission.

### Get Projects by Folder

`GET https://api.storylinezads.com/by_folder`

Retrieves projects within a given folder or root projects if folder_id is omitted.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "projects": [
    {
      "project_id": "proj_12345",
      "name": "Launch Campaign",
      "org_id": "org_12345",
      "folder_id": "fldr_marketing",
      "status": "draft",
      "type": "v1",
      "orientation": "landscape",
      "thumbnail_path": "thumbnails/proj_12345.png",
      "thumbnail_url": "https://cdn.storylinez.example/thumbnails/proj_12345.png"
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "limit": 10,
    "total_pages": 2
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Useful for displaying projects by folder with pagination and sorting.
- Omits folder_id to fetch unfiled projects (root).
- Set generate_thumbnail_links=true to include signed thumbnail URLs in the response.
- Returns a projects array with pagination metadata.

### Get Projects by Status

`GET https://api.storylinezads.com/by_status`

Retrieves projects with a specific status, optionally filtered by folder.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "projects": [
    {
      "project_id": "proj_67890",
      "name": "Retention Ads",
      "org_id": "org_12345",
      "folder_id": "fldr_growth",
      "status": "ongoing",
      "type": "v1",
      "orientation": "portrait",
      "thumbnail_url": "https://cdn.storylinez.example/thumbnails/proj_67890.png"
    }
  ],
  "pagination": {
    "total": 4,
    "page": 1,
    "limit": 10,
    "total_pages": 1
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "Invalid status or missing org_id" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Filter projects by status and optionally by folder.
- Status must be one of: draft, ongoing, error, or completed.
- Set generate_thumbnail_links=true to include signed thumbnail URLs in the result.
- Pagination parameters are supported.

### Get All Projects

`GET https://api.storylinezads.com/get_all`

Retrieves all projects for an organization with optional filtering and pagination.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "projects": [
    {
      "project_id": "proj_12345",
      "name": "Launch Campaign",
      "org_id": "org_12345",
      "status": "draft",
      "type": "v1",
      "orientation": "landscape",
      "created_at": "2024-05-18T14:32:10Z",
      "updated_at": "2024-06-01T10:05:54Z",
      "thumbnail_url": "https://cdn.storylinez.example/thumbnails/proj_12345.png"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "total_pages": 5
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "Organization ID is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Use this endpoint to retrieve projects with optional status filtering.
- Supports pagination, sorting, and optional inclusion of thumbnail URLs via generate_thumbnail_links=true.

### Get Unrendered Projects

`GET https://api.storylinezads.com/unrendered`

List projects that have not produced a successful render yet.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Unrendered projects retrieved successfully.

```json
{
  "projects": [{"project_id": "proj_123", "name": "Launch Campaign"}],
  "pagination": {"total": 4, "page": 1, "limit": 10, "total_pages": 1}
}
```

**Response 400** — Missing org_id or invalid pagination/sort values.

**Response 403** — User lacks organization permission.

**Response 500** — Internal server error.

**Usage notes**

- Use this endpoint to build render backlog dashboards.
- The response uses standard pagination metadata under a pagination object.
- Project thumbnails are included when available so cards can render without extra calls.

### Get Project Details

`GET https://api.storylinezads.com/get_one`

Retrieves detailed information for a specific project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "project_id": "proj_12345",
  "name": "Launch Campaign",
  "org_id": "org_12345",
  "type": "v1",
  "status": "draft",
  "orientation": "landscape",
  "company_details_id": "comp_678",
  "brand_id": "brand_456",
  "folder_id": "fldr_marketing",
  "purpose": "Drive product awareness",
  "target_audience": "Product marketers",
  "associated_files": ["file_1", "file_2"],
  "thumbnail_path": "thumbnails/proj_12345.png",
  "thumbnail_url": "https://cdn.storylinez.example/thumbnails/proj_12345.png",
  "created_at": "2024-05-18T14:32:10Z",
  "updated_at": "2024-06-01T10:05:54Z"
}
```

**Response 400** — Bad Request

```json
{ "error": "Project ID is required as a query parameter" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Project ID must be valid.
- If generate_thumbnail_links is true, the endpoint includes a thumbnail URL.

### Update Project Details

`PUT https://api.storylinezads.com/update`

Updates specific details of an existing project. Certain fields (orientation, status, files) are not allowed.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — OK

```json
{
  "project_id": "proj_12345",
  "name": "Updated Project Name",
  "org_id": "org_12345",
  "type": "v1",
  "status": "draft",
  "purpose": "Revised campaign messaging",
  "target_audience": "Marketing leads",
  "company_details_id": "comp_678",
  "brand_id": "brand_456",
  "settings": {
    "theme": "light",
    "resolution": "4k"
  },
  "updated_at": "2024-06-03T11:45:00Z"
}
```

**Response 400** — Bad Request

```json
{ "error": "Project ID is required as a query parameter" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Protected lifecycle fields such as status are controlled server-side and are not updated by this endpoint.
- V2 projects only accept updates for name, purpose, target_audience, company_details_id, and brand_id. Settings updates are ignored for v2.
- Company and brand IDs are validated against the organization, returning 404 if mismatched.
- Successful updates refresh updated_at and mark downstream v1 assets (prompts, storyboards, etc.) as cascade_outdated.
- This endpoint updates project metadata without modifying attached files.

### Delete a Project

`DELETE https://api.storylinezads.com/delete`

Deletes an existing project and its associated resources.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{ "message": "Project deleted successfully", "project_id": "..." }
```

**Response 400** — Bad Request

```json
{ "error": "Project ID is required as a query parameter" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project not found" }
```

**Response 409** — Conflict

```json
{ "error": "Project has already been deleted" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Performs a soft delete by marking the project as deleted and recording the actor/time.
- Repeat requests return 409 once a project is already deleted.
- Associated downstream assets remain for auditing but are flagged as deleted.

### Duplicate a Project

`POST https://api.storylinezads.com/duplicate`

Creates a duplicate of an existing project with an optional new name.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 201** — Created

```json
{
  "message": "Project duplicated successfully",
  "new_project_id": "proj_98765",
  "project": {
    "project_id": "proj_98765",
    "name": "Duplicated Project",
    "type": "v1",
    "status": "draft"
  },
  "duplication_summary": {
    "project": true,
    "prompt": true,
    "storyboard": true,
    "voiceover": true,
    "sequence": true,
    "render": true,
    "new_ids": {
      "project_id": "proj_98765",
      "prompt_id": "prompt_456"
    }
  },
  "project_limits": {
    "period_count": 6,
    "daily_count": 2
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "Project ID is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden – User lacks organization access or project creation quota is exhausted.

```json
{ "error": "Project creation limit reached for current billing period" }
```

**Response 404** — Not Found

```json
{ "error": "Project not found" }
```

**Response 409** — Conflict

```json
{ "error": "Duplicate is not supported for v2 projects via legacy routes. Use the /v2 APIs." }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Duplication counts towards project limits.
- Creates a deep copy of the project and its related resources with new IDs.
- Legacy duplication supports v1 projects only; use v2 project APIs to clone sequence builder assets.

### Add Associated File to Project

`POST https://api.storylinezads.com/files/add`

Associates an existing file with a project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — OK

```json
{ "message": "File added to project successfully" }
```

**Response 400** — Bad Request

```json
{ "error": "Project ID and File ID are required." }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project or File not found" }
```

**Response 409** — Conflict – File already linked or file operations disabled for v2 projects via legacy routes.

```json
{ "error": "File operations are disabled for v2 projects via legacy routes. Use /v2/media endpoints." }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Ensure the file belongs to the same organization as the project.
- Associates the specified file with the project and updates the thumbnail if needed.
- Legacy file operations only work for v1 projects; v2 projects must use the sequence media APIs.
- Attempting to add a file twice returns 409 with 'File is already associated with this project'.

### Remove Associated File from Project

`DELETE https://api.storylinezads.com/files/remove`

Removes an associated file from a project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{ "message": "File removed from project successfully" }
```

**Response 400** — Bad Request

```json
{ "error": "Project ID and File ID are required." }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project or File not associated with project" }
```

**Response 409** — Conflict – File operations are disabled for v2 projects via legacy routes.

```json
{ "error": "File operations are disabled for v2 projects via legacy routes. Use /v2/media endpoints." }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Only remove files currently associated with the project.
- Updates the project's thumbnail if the removed file was used.
- Legacy file operations only work for v1 projects; v2 projects must use the sequence media APIs.

### Add Stock File to Project

`POST https://api.storylinezads.com/stock-files/add`

Adds a stock file (video, audio, or image) to a project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — OK

```json
{ "message": "Stock file added to project successfully" }
```

**Response 400** — Bad Request

```json
{ "error": "Missing required parameters" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project not found" }
```

**Response 409** — Conflict – Stock file already linked or stock media operations disabled for v2 projects via legacy routes.

```json
{ "error": "Stock file operations are disabled for v2 projects via legacy routes. Use /v2/media endpoints." }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Media type must be one of: videos, audios, images.
- Associates a stock file with the project under the specified media category.
- Legacy stock file operations only work for v1 projects; v2 projects must use the sequence media APIs.
- Attempting to add the same stock file twice returns 409 with 'Stock file already exists in the specified media type'.

### Remove Stock File from Project

`DELETE https://api.storylinezads.com/stock-files/remove`

Removes a stock file from a project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{ "message": "Stock file removed from project successfully" }
```

**Response 400** — Bad Request

```json
{ "error": "Required parameters missing" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project or stock file not found" }
```

**Response 409** — Conflict – Stock media operations are disabled for v2 projects via legacy routes.

```json
{ "error": "Stock file operations are disabled for v2 projects via legacy routes. Use /v2/media endpoints." }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Stock file must exist in the specified media category.
- Removes the stock file from the project and updates related components.
- Legacy stock media operations only work for v1 projects; v2 projects must use the sequence media APIs.

### Get All Files Associated with a Project

`GET https://api.storylinezads.com/files/get_all`

Retrieves associated and stock files for a project, with optional details and URL generation.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{
  "associated_files": [
    {
      "file_id": "file_1",
      "filename": "launch.mp4",
      "mimetype": "video/mp4",
      "thumbnail_url": "https://cdn.storylinez.example/thumbnails/file_1.png"
    }
  ],
  "stock_files": {
    "videos": ["stock_vid_1"],
    "audios": [],
    "images": []
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "Project ID is required as a query parameter" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Set include_details=true to embed full file metadata in associated_files.
- Use generate_thumbnail_links or generate_streamable_links to request signed URLs in the response.
- Returns both associated and stock media categories for v1 projects; v2 projects manage media via the sequence APIs.

### Add/Update Project Voiceover

`POST https://api.storylinezads.com/voiceovers/add`

Adds or updates a voiceover for a project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — OK

```json
{ "message": "Voiceover added successfully" }
```

**Response 400** — Bad Request

```json
{ "error": "Missing file_id" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- The file must be an audio file and belong to the organization.
- Adds or updates the project's voiceover and adjusts dependent resources.

### Remove Project Voiceover

`DELETE https://api.storylinezads.com/voiceovers/remove`

Removes the voiceover from a project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{ "message": "Voiceover removed successfully" }
```

**Response 400** — Bad Request

```json
{ "error": "Project ID is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Removes current voiceover and marks dependent resources as outdated.
- Clears the voiceover field from the project document.

### Get Project Voiceover

`GET https://api.storylinezads.com/voiceovers/get`

Retrieves voiceover details for a project, with optional file details.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — OK

```json
{ ...voiceover object... }
```

**Response 400** — Bad Request

```json
{ "error": "Project ID is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Useful for retrieving the voiceover and its file details.
- Optionally includes detailed file info if requested.

### Add Multiple Files to Project

`POST https://api.storylinezads.com/files/add_bulk`

Associates multiple existing files with a project in a single operation. Provides validation, error tracking, and detailed results for each file.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Files processed successfully

```json
{
  "message": "3 files added to project successfully",
  "project_id": "<project_id>",
  "results": {
    "successful": ["file_id_1", "file_id_2", "file_id_3"],
    "failed": []
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "A list of file IDs is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- All file IDs must belong to the organization associated with the project.
- Invalid or duplicate file IDs are reported in the failed results array.
- The endpoint optimizes validation by checking files in bulk to reduce database load.
- If these are the first files added to the project, the thumbnail is automatically updated.
- Provides a consolidated report of both successful and failed file additions.

### Add Multiple Stock Files to Project

`POST https://api.storylinezads.com/stock-files/add_bulk`

Adds multiple stock media files (videos, audios, or images) to a project in a single operation. Validates each stock ID and provides detailed results.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Stock files processed successfully

```json
{
  "message": "3 stock files added to project successfully",
  "media_type": "videos",
  "project_id": "<project_id>",
  "results": {
    "successful": ["stock_id_1", "stock_id_2", "stock_id_3"],
    "failed": []
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "A list of stock IDs is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Media type must be one of: videos, audios, or images.
- The endpoint efficiently validates stock IDs across multiple collections.
- Supports both stock_id field and MongoDB ObjectId formats.
- Invalid or duplicate stock IDs are reported in the failed results array.
- If no associated files exist and this is first stock file, thumbnail is updated for videos and images.

### Add Multiple Voiceovers to Project

`POST https://api.storylinezads.com/voiceovers/add_bulk`

Processes multiple audio files as potential voiceovers and selects one as active. Validates each file and provides detailed results.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Voiceovers processed successfully

```json
{
  "message": "Voiceover added successfully",
  "file_id": "file_id_2",
  "project_id": "<project_id>",
  "results": {
    "successful": [
      {"file_id": "file_id_1", "voice_name": "Male Narrator"},
      {"file_id": "file_id_2", "voice_name": "Female Narrator"}
    ],
    "failed": [],
    "selected": {
      "file_id": "file_id_2",
      "voice_name": "Female Narrator",
      "added_at": "2024-07-25T14:30:00Z"
    }
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "A list of voiceover objects is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Project not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- All files must be audio files and belong to the project's organization.
- The voiceovers array contains objects with file_id and optional voice_name.
- One voiceover is selected as active based on selected_index (defaults to first valid one).
- Invalid files (non-audio or non-existent) are reported in the failed results array.
- The selected voiceover replaces any existing one on the project.


---

# V2 Project Media API

Source: https://storylinezads.com/docs/api/v2_projects
Last generated: 2026-07-20

Attach and manage analysed media assets for V2 projects, exposing the /v2/projects/media namespace.

Base route: `/v2/projects` (relative to `https://api.storylinezads.com`)

## V2 Project Media

Attach managed media assets to V2 projects and retrieve their analysis metadata.

### Get Generation Settings

`GET https://api.storylinezads.com/settings/generation`

Fetch effective generation settings used by the V2 sequence/render pipelines for a project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Generation settings retrieved successfully.

```json
{
  "success": true,
  "generation_settings": {
    "resolution": {"width": 1920, "height": 1080},
    "fps": 30,
    "default_transition": "cut"
  }
}
```

**Response 400** — Missing project_id or invalid query arguments.

**Response 403** — Authenticated user lacks organization access.

**Response 404** — Project not found or not a V2 project.

**Response 500** — Internal server error.

**Usage notes**

- Use this endpoint to hydrate client-side defaults before calling /v2/sequence/create or /v2/render/start.
- Settings are project-scoped and may differ across V2 projects in the same organization.
- This endpoint is read-only and does not mutate project state.

### Add Media

`POST https://api.storylinezads.com/media/add`

Attach a single analysed media item (user file or stock asset) to a V2 project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Media attached successfully.

```json
{
  "success": true,
  "media": {
    "media_id": "med_0b7c",
    "project_id": "proj_v2_789",
    "org_id": "org_12345",
    "media_type": "video",
    "path": "userdata/projects/proj_v2_789/video.mp4",
    "source": { "type": "user", "file_id": "file_abcd1234" },
    "result": {
      "paths": {"original": "userdata/.../video.mp4", "thumbnail": "userdata/.../thumb.jpg"},
      "duration_seconds": 42.6
    },
    "created_at": "2025-05-01T11:32:44.019Z",
    "updated_at": "2025-05-01T11:32:44.019Z"
  }
}
```

**Response 400** — Missing input or invalid combination (e.g. neither file_id nor stock_id supplied).

**Response 403** — Authenticated user lacks access to the organization.

**Response 404** — Project or referenced media not found.

**Response 409** — Media already attached to the project.

**Response 422** — Media analysis not available yet; retry later.

**Response 500** — Internal server error.

**Usage notes**

- Only V2 projects are accepted. The route validates project type before attaching media.
- V2 sequence builder surfaces assets exclusively from this catalogue, so attach every analysed cut you plan to remix.
- For stock attachments, supply both stock_id and media_type (plural).
- The response includes previously computed analysis results for downstream usage.

### Add Media (Bulk)

`POST https://api.storylinezads.com/media/add_bulk`

Attach multiple analysed media sources to a V2 project in a single call.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Bulk operation completed; response includes successes and failures.

```json
{
  "success": true,
  "added": [
    {"media_id": "med_a", "source": {"type": "user", "file_id": "file_a"}},
    {"media_id": "med_b", "source": {"type": "stock", "stock_id": "stk_42", "media_type": "videos"}}
  ],
  "failed": [
    {"item": {"file_id": "file_b"}, "error": "Media already attached to this project"}
  ],
  "count_added": 2
}
```

**Response 400** — No attachable items supplied or malformed payload.

**Response 403** — User lacks organization permissions.

**Response 404** — Project or one of the referenced items not found.

**Response 409** — Every item in the request duplicates existing media.

**Response 500** — Internal server error.

**Usage notes**

- Provide either file_ids or items (or both). Duplicate entries are surfaced in the failed list.
- Bulk loads are the fastest way to seed the V2 media library before starting timeline drafts.
- Analysis metadata is fetched in batch to minimize repeated enhancement calls.
- Successful attachments return trimmed analysis results identical to single add responses.

### List Media

`GET https://api.storylinezads.com/media/list`

Retrieve paginated media items for a V2 project with optional analysis details.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Media items retrieved.

```json
{
  "success": true,
  "media": [
    {"media_id": "med_a", "media_type": "video", "path": "userdata/...", "urls": {"streamable": "https://..."}},
    {"media_id": "med_b", "media_type": "audio", "path": "userdata/..."}
  ],
  "total": 12,
  "page": 1,
  "page_size": 20,
  "total_pages": 1
}
```

**Response 400** — Missing org_id/project_id parameters.

**Response 403** — Insufficient organization access.

**Response 404** — Project not found or not a V2 project.

**Response 500** — Internal server error.

**Usage notes**

- Analysis payloads are trimmed to omit heavy audio/video branches for faster transport.
- Use this endpoint to verify the media inventory the V2 builder will consider before running sequences.
- When include_analysis=true, presigned URLs are refreshed for any results missing URLs.
- Pagination defaults to 20 items per page; max size enforced by backend limits.


---

# V2 Context Library API

Source: https://storylinezads.com/docs/api/v2_context
Last generated: 2026-07-20

Upload and manage briefs, documents, and reference videos that ground V2 projects via /v2/context endpoints.

Base route: `/v2/context` (relative to `https://api.storylinezads.com`)

## V2 Project Context

Manage long-form documents and reference videos that drive V2 sequence generation. At least one high-quality brief or reference is required for reliable V2 story construction.

### Add Document

`POST https://api.storylinezads.com/documents/add`

Attach a text document to the project's V2 context library.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Document stored successfully.

```json
{
  "success": true,
  "document": {
    "doc_id": "doc_5f0d",
    "title": "Campaign Brief",
    "summary": "Short synopsis for quick scanning",
    "tags": ["campaign", "v2"],
    "content_length": 8421,
    "created_at": "2025-05-01T12:02:11.003Z"
  }
}
```

**Response 400** — Invalid payload (missing content, non-string tags, etc.).

**Response 403** — User lacks organization access.

**Response 404** — Project not found or not a V2 project.

**Response 413** — Document exceeds MAX_DOC_BODY_SIZE (200,000 characters).

**Response 500** — Internal server error.

**Usage notes**

- Each project may store up to v2_documents_max_count documents (see config).
- V2 sequence builder uses this corpus as the primary source for tone, facts, and guardrails—upload briefs before requesting generation.
- Summaries and nicknames are auto-derived when not supplied.
- Build server notices are emitted when documents are added (if the project session is active).

### List Documents

`GET https://api.storylinezads.com/documents/list`

Retrieve paginated document summaries for a V2 project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Documents listed.

```json
{
  "success": true,
  "documents": [
    {"doc_id": "doc_5f0d", "title": "Campaign Brief", "content": "Long-form script...", "tags": ["campaign"]}
  ],
  "pagination": {"page": 1, "page_size": 10, "total_count": 3, "total_pages": 1},
  "content_chars": 500
}
```

**Response 400** — Missing org_id/project_id.

**Response 403** — Access denied.

**Response 404** — Project not found or not V2.

**Response 500** — Internal server error.

**Usage notes**

- Content is truncated to content_chars when provided, enabling quick previews.
- Review this list to confirm the narrative base covered before launching V2 sequences.
- Pagination metadata mirrors other list endpoints.
- Tags are sanitised to at most 120 characters per entry.

### Get Document Page

`GET https://api.storylinezads.com/documents/get`

Fetch a specific page slice of a large document for incremental display.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Document slice returned.

```json
{
  "success": true,
  "document": {
    "doc_id": "doc_5f0d",
    "title": "Campaign Brief",
    "page": 1,
    "page_chars": 5000,
    "total_length": 8421,
    "total_pages": 2,
    "content": "First 5k characters..."
  }
}
```

**Response 400** — Missing doc_id.

**Response 403** — Access denied.

**Response 404** — Document not found.

**Response 500** — Internal server error.

**Usage notes**

- Use in editors or viewers to lazy-load long documents.
- Fine-tune the brief sections the V2 builder will ingest by chunking preview with this endpoint before generation.
- When a document is empty, total_pages is 0 and page is returned as 0.
- page_chars defaults to MAX_DOC_LENGTH (from configuration).

### Delete Document

`DELETE https://api.storylinezads.com/documents/delete`

Remove a document from the V2 context library.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Deletion acknowledged.

```json
{ "success": true, "deleted": 1 }
```

**Response 400** — Missing doc_id.

**Response 403** — Access denied.

**Response 404** — Document not found.

**Response 500** — Internal server error.

**Usage notes**

- Deletion emits a build-server notice when the project session is active.
- Remove outdated briefs so V2 sequences do not inherit stale guidance.
- The response reports the number of records deleted (1 or 0).

### Update Document

`PUT https://api.storylinezads.com/documents/update`

Update an existing context document without changing its doc_id.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Document updated successfully.

```json
{
  "success": true,
  "document": {
    "doc_id": "doc_5f0d",
    "title": "Campaign Brief v2",
    "summary": "Revised summary",
    "updated_at": "2025-05-03T10:15:21.000Z"
  }
}
```

**Response 400** — Missing identifiers or invalid payload fields.

**Response 403** — Access denied.

**Response 404** — Project or document not found.

**Response 500** — Internal server error.

**Usage notes**

- Submit only fields you want to modify; unspecified values remain unchanged.
- Updating context documents preserves existing document references and IDs.
- Updates emit V2 history notices so active sessions can refresh context state.

### Set Reference Video

`POST https://api.storylinezads.com/reference/set`

Create or update the primary reference video metadata for a project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Reference stored with enriched analysis summary.

```json
{
  "success": true,
  "reference": {
    "ref_id": "ref_1738",
    "file_id": "ref_file_4321",
    "nickname": "Launch Reel",
    "media_type": "video",
    "summary": "High-level cut featuring new product highlights...",
    "paths": { "thumbnail": "userdata/.../thumb.jpg" },
    "urls": { "streamable": "https://..." },
    "created_at": "2025-05-02T09:10:12.112Z"
  }
}
```

**Response 400** — Missing file_id (on create) or reference not found for given ref_id.

**Response 403** — Access denied.

**Response 404** — Reference video file not found or not in the organization.

**Response 500** — Internal server error.

**Usage notes**

- Either provide file_id for new references or ref_id + file_id to update an existing record.
- Reference videos anchor visual direction for the V2 sequence builder—add at least one hero clip before rendering.
- Analysis data is pruned to lightweight metadata and refreshed URLs.
- Reference updates emit v2 history notices when a session is active.

### Get Reference Video

`GET https://api.storylinezads.com/reference/get`

Retrieve a specific reference video's metadata, including refreshed URLs.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Reference retrieved.

```json
{
  "success": true,
  "reference": {
    "ref_id": "ref_1738",
    "file_id": "ref_file_4321",
    "nickname": "Launch Reel",
    "media_type": "video",
    "summary": "High-level cut featuring new product highlights...",
    "urls": { "streamable": "https://..." }
  }
}
```

**Response 400** — Missing ref_id.

**Response 403** — Access denied.

**Response 404** — Reference record not found.

**Response 500** — Internal server error.

**Usage notes**

- The endpoint backfills filenames, mimetypes, and file paths from storage if missing.
- Use this to verify the hero reference the V2 sequence builder will apply before triggering runs.
- URLs are regenerated on demand so callers always receive fresh links.
- Analysis payload omits heavy audio/video branches to stay lightweight.

### List Reference Videos

`GET https://api.storylinezads.com/reference/list`

Paginate through reference videos associated with a project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — References listed.

```json
{
  "success": true,
  "references": [
    {"ref_id": "ref_1738", "nickname": "Launch Reel", "media_type": "video", "summary": "High-level cut...", "urls": { "thumbnail": "https://..." }}
  ],
  "pagination": {"page": 1, "page_size": 10, "total_count": 1, "total_pages": 1, "has_next": false, "has_previous": false}
}
```

**Response 400** — Missing org_id/project_id.

**Response 403** — Access denied.

**Response 404** — Project not found or not V2.

**Response 500** — Internal server error.

**Usage notes**

- Analysis metadata is pruned and URLs regenerated in batch for entries missing active links.
- Use this inventory to curate the reference set that will inform tempo, framing, and grade in V2 timelines.
- Pagination mirrors other list endpoints and includes convenience flags (has_next/has_previous).
- Entries without analysis still return base metadata (file_id, nickname, timestamps).

### Clear Reference Videos

`DELETE https://api.storylinezads.com/reference/clear`

Remove one or all reference videos for a project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Deletion acknowledged.

```json
{ "success": true, "deleted": 3 }
```

**Response 403** — Access denied.

**Response 404** — Specified ref_id not found.

**Response 500** — Internal server error.

**Usage notes**

- Passing ref_id removes a single reference; omitting clears the entire set.
- Deletion emits v2 history notices for client-side refresh flows.
- A deleted count of 0 indicates no matching references existed.


---

# V2 Sequence Sessions API

Source: https://storylinezads.com/docs/api/v2_sequence
Last generated: 2026-07-20

Create, iterate, and inspect V2 agent sessions through the /v2/sequence namespace.

Base route: `/v2/sequence` (relative to `https://api.storylinezads.com`)

## Sequence Session Management

Endpoints that orchestrate session lifecycle, sequence listings, undo snapshots, and history streams for the V2 editor.

### Create Sequence Session

`POST https://api.storylinezads.com/create`

Create the first V2 session for a project and enqueue the agent to generate an initial sequence.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Session created and job enqueued.

```json
{
  "success": true,
  "session_id": "sess_v2_456",
  "job_id": "64f1c...",
  "message": "Sequence creation started successfully"
}
```

**Response 400** — Missing org_id/project_id or session already exists.

**Response 403** — Authenticated principal lacks organization access.

**Response 404** — Project not found or not a V2 project.

**Response 409** — Another sequence job is already running for the project.

**Response 502** — Build server returned an upstream error.

**Response 500** — Unexpected server error.

**Usage notes**

- Only one active session may exist per project; subsequent calls must use /continue.
- The route snapshots minimal project context (purpose, target audience, presets) before forwarding to the build server.
- Temperature and eco flags are validated before being forwarded upstream.
- Establish project context via /v2/context and /v2/projects/media before calling create so the agent starts with rich inputs.

### Continue Sequence Session

`POST https://api.storylinezads.com/continue`

Resume an existing V2 session with a follow-up instruction.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Follow-up job accepted by the build server.

```json
{
  "success": true,
  "session_id": "sess_v2_456",
  "job_id": "64f1f...",
  "message": "Sequence continue started successfully"
}
```

**Response 400** — No session exists for the project yet.

**Response 403** — Access denied for the supplied organization/project.

**Response 404** — Project not found or not a V2 project.

**Response 409** — Another sequence job is currently in-flight.

**Response 502** — Upstream build server returned an error.

**Response 500** — Unexpected server error.

**Usage notes**

- The route blocks if a previous job is still running to protect against concurrent mutations.
- Project context is forwarded again so the agent can react to updated presets.
- Lifecycle metadata is updated to maintain edited timestamps.
- Pair with /v2/sequence/history to display the agent's response stream once the job completes.

### Stop Sequence Session

`POST https://api.storylinezads.com/stop`

Gracefully stop an active V2 sequence session loop.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Session stop acknowledged.

```json
{
  "success": true,
  "session_id": "sess_v2_456",
  "message": "Session stop requested"
}
```

**Response 400** — Missing session_id or invalid stop request.

**Response 403** — Access denied for organization/project.

**Response 404** — Project/session not found.

**Response 500** — Unexpected server error.

**Usage notes**

- Use this endpoint when users explicitly cancel long-running session iterations.
- The stop request is graceful and allows in-flight tool operations to terminate cleanly.
- Always send the latest session_id from create/continue responses.

### List Sequences

`GET https://api.storylinezads.com/list`

List all sequences linked to the project's active session, including job metadata.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Returns paginated sequences with job snapshots and progress fields.

```json
{
  "success": true,
  "sequences": [
    {
      "sequence_id": "seq_main",
      "name": "Main Sequence",
      "job_status": "COMPLETED",
      "job_progress": 1.0
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "total_pages": 1
}
```

**Response 400** — Missing org_id/project_id.

**Response 403** — Project not accessible.

**Response 500** — Unexpected server error.

**Usage notes**

- Sequences are sorted primary-first, then by recency.
- Job metadata is merged with active jobs to expose live status in the UI.
- Legacy sequences without org_id remain visible through fallback logic.

### List Sequences (Lite)

`GET https://api.storylinezads.com/list_lite`

Lightweight listing for dropdowns that only returns identifiers and labels.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Array of sequence_id, name, description, is_primary metadata.

```json
{
  "success": true,
  "sequences": [
    {
      "sequence_id": "seq_main",
      "name": "Main Sequence",
      "is_primary": true
    }
  ],
  "total": 1
}
```

**Response 400** — Missing org_id/project_id.

**Response 403** — Access denied.

**Response 500** — Unexpected server error.

**Usage notes**

- Ideal for select inputs where the full sequence document is unnecessary.
- Results inherit the same ordering logic as /list.
- Timestamps are ISO strings when present; null otherwise.

### Get Sequence

`GET https://api.storylinezads.com/get`

Fetch a specific sequence (or the primary sequence when sequence_id is omitted).

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Returns the sequence document with job metadata merged in.

```json
{
  "success": true,
  "sequence": {
    "sequence_id": "seq_main",
    "name": "Main Sequence",
    "tracks": [...],
    "job_status": "COMPLETED"
  }
}
```

**Response 400** — Session does not exist for the project.

**Response 403** — Project access denied.

**Response 404** — Sequence not found.

**Response 500** — Unexpected server error.

**Usage notes**

- When org_id-scoped documents are missing, the route falls back to legacy records for backwards compatibility.
- Job metadata is refreshed so the client sees current progress.
- Use together with /media/list to resolve analysis details for referenced assets.

### List Sequence Media

`GET https://api.storylinezads.com/media/list`

Resolve media analysis for assets referenced by a sequence, highlighting missing items.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Returns media metadata, analysis results (when requested), and missing asset diagnostics.

```json
{
  "success": true,
  "sequence_id": "seq_main",
  "media": [
    {
      "asset": {"asset_id": "asset_01", "type": "video"},
      "media": {"media_id": "med_abcd", "has_analysis": true}
    }
  ],
  "missing_assets": [],
  "total": 1
}
```

**Response 400** — Session missing or invalid include_analysis flag.

**Response 403** — Access denied.

**Response 404** — Sequence not found.

**Response 500** — Unexpected server error.

**Usage notes**

- Analysis payloads are trimmed to avoid large downloads unless include_analysis=true.
- Missing assets are surfaced with reasons so editors can remediate gaps quickly.
- When include_analysis=true, presigned URLs are generated for stream/download access.

### Update Sequence

`PUT https://api.storylinezads.com/update`

Validate or persist manual sequence edits by forwarding the payload to the build server.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Validation or update succeeded.

```json
{
  "success": true,
  "message": "Sequence updated"
}
```

**Response 400** — Missing identifiers or malformed sequence payload.

**Response 403** — Access denied.

**Response 404** — Sequence not found for the session.

**Response 409** — Another sequence job is active (validate_only=false).

**Response 502** — Build server returned an error.

**Response 500** — Unexpected server error.

**Usage notes**

- validate_only prevents persistence so editors can preflight payloads without creating undo snapshots.
- Successful persistence records a manual update notice for the history timeline.
- Sequence writes leverage optimistic concurrency inside the build server to avoid conflicting edits.

### Import Sequence Asset

`POST https://api.storylinezads.com/asset/import`

Import a generated layer or project media asset into a target sequence through approved V2 tools.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Asset imported into the sequence successfully.

```json
{
  "success": true,
  "tool_name": "import_text_asset",
  "asset": {
    "asset_id": "asset_txt_01",
    "type": "text"
  }
}
```

**Response 400** — Missing required fields, invalid tool_name, or malformed parameters payload.

**Response 403** — Access denied for organization/project.

**Response 404** — Project/session/sequence not found.

**Response 500** — Unexpected server error.

**Usage notes**

- Use this endpoint for deterministic asset insertion workflows (text/solid/gradient/adjustment/project media imports).
- tool_name is validated server-side against a strict allow-list.
- This route mirrors how the V2 agent imports assets, so renderer compatibility metadata is preserved.

### List Sequence Snapshots

`GET https://api.storylinezads.com/snapshots`

List undo snapshots for a sequence, including full stored payloads.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Returns paginated snapshots including full sequence_snapshot documents.

```json
{
  "success": true,
  "snapshots": [
    {
      "buffer_id": "buf_123",
      "timestamp": "2025-05-01T12:30:00Z",
      "operation": "update_sequence"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_count": 4,
    "total_pages": 1
  }
}
```

**Response 400** — Missing identifiers.

**Response 403** — Session does not belong to the project.

**Response 500** — Unexpected server error.

**Usage notes**

- Use these snapshots to power undo/redo viewers or to diff prior states offline.
- Results are ordered from newest to oldest, with timestamps in UTC.
- Sequence payloads are sanitized to ensure ObjectIds appear as strings.

### Get Sequence History

`GET https://api.storylinezads.com/history`

Retrieve the filtered timeline used by the V2 editor (user messages, tool operations, agent notices).

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Returns the timeline items needed by the editor UI.

```json
{
  "success": true,
  "timeline": [
    {
      "type": "user_message",
      "message": "Kick off a hero video concept."
    },
    {
      "type": "tool_operation",
      "tool_friendly_name": "Sequence Update"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_count": 12,
    "total_pages": 1
  }
}
```

**Response 400** — Missing identifiers.

**Response 403** — Session does not belong to the project or no permission.

**Response 500** — Unexpected server error.

**Usage notes**

- Use X-API-Key and X-API-Secret headers for authentication.
- History is filtered to exclude system-only notices so the frontend sees a concise timeline.
- Tool operations include friendly names resolved via the build server for readability.
- Use higher page_size values when implementing infinite scroll UIs.


---

# V2 Render Service API

Source: https://storylinezads.com/docs/api/v2_render
Last generated: 2026-07-20

Launch and monitor renders produced from V2 sequences via the /v2/render namespace.

Base route: `/v2/render` (relative to `https://api.storylinezads.com`)

## Render Operations

Endpoints that orchestrate render jobs, fetch live status, and read archived history for V2 exports.

### Start Render

`POST https://api.storylinezads.com/start`

Validate preconditions and forward a render request to the dedicated render server.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Render job enqueued successfully.

```json
{
  "success": true,
  "render_id": "rnd_9c1a",
  "job_id": "6552f...",
  "sequence_id": "seq_main"
}
```

**Response 400** — Missing identifiers, invalid override combo, or project has no session/sequence.

**Response 403** — Project belongs to a different organization or lacks render entitlement.

**Response 409** — Another render job or sequence job is already running.

**Response 502** — Upstream render server returned an error.

**Response 503** — Render server not configured.

**Response 500** — Unexpected server error.

**Usage notes**

- The route performs extensive validation before forwarding to the render server.
- Subscription tier enforcement ensures free organizations always render with watermarks.
- Render metadata is persisted immediately so subsequent /get calls reflect the new job.
- When overriding resolution, provide both target_width and target_height or the request will be rejected upstream.

### Get Render

`GET https://api.storylinezads.com/get`

Retrieve live render documents for a project or a single render, optionally generating presigned URLs.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Returns either a single render document or a paginated collection with live job snapshots.

```json
{
  "success": true,
  "renders": [
    {
      "render_id": "rnd_9c1a",
      "status": "COMPLETED",
      "job_progress": 1.0,
      "download_url": "https://..."
    }
  ],
  "total": 1,
  "page": 1
}
```

**Response 400** — Missing identifiers or invalid option combinations.

**Response 403** — Access denied for the supplied organization/project.

**Response 404** — Render not found (when render_id supplied).

**Response 500** — Unexpected server error.

**Usage notes**

- Job metadata is refreshed on each call, ensuring progress fields stay current.
- Presigned URLs are generated only when renders are in a terminal status.
- Use include_results=false to reduce payload size in dashboards.
- Prefer generate_*_link=false while polling every few seconds; request links only once the job completes to avoid unnecessary presign work.

### Get Render History

`GET https://api.storylinezads.com/history`

List archived render records including presigned links when requested.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Returns archived render entries with optional presigned URLs.

```json
{
  "success": true,
  "items": [
    {
      "render_id": "rnd_1",
      "status": "COMPLETED",
      "streamable_url": "https://..."
    }
  ],
  "total": 4,
  "page": 1,
  "limit": 10
}
```

**Response 400** — Missing identifiers or invalid pagination parameters.

**Response 403** — Access denied for the supplied organization/project.

**Response 500** — Unexpected server error.

**Usage notes**

- History documents are copied from the live renders collection after completion, preserving past settings.
- Optional CDN flags control whether presigned URLs or CDN aliases are returned.
- Use small page sizes when rendering thumbnails to minimize pre-signed URL generation.
- The V2RenderClient.history helper automatically normalises boolean flags and removes unsupported combinations.


---

# V2 Schema Introspection API

Source: https://storylinezads.com/docs/api/v2_schema
Last generated: 2026-07-20

Retrieve JSON schemas describing sequence and asset payloads used by the V2 agent stack.

Base route: `/v2/schema` (relative to `https://api.storylinezads.com`)

## Schema Endpoints

Endpoints that expose the authoritative JSON schemas for V2 sequences and supporting assets.

### Get Sequence Schema

`GET https://api.storylinezads.com/sequence`

Fetch the JSON schema describing V2 sequence documents and their nested objects.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Returns the JSON schema describing the V2 sequence document structure.

```json
{
  "success": true,
  "schema": {
    "$id": "https://schemas.storylinez.ai/v2/sequence.json",
    "type": "object",
    "required": ["sequence_id", "title", "timeline"],
    "properties": {
      "sequence_id": {"type": "string"},
      "timeline": {
        "type": "array",
        "items": {"$ref": "#/definitions/timeline_block"}
      }
    }
  },
  "examples": include_examples ? [...] : null
}
```

**Response 403** — Authenticated principal lacks access to the requested organization/project.

**Response 500** — Internal server error while proxying the schema request.

**Usage notes**

- The upstream builder service owns the schema; all query parameters are forwarded verbatim.
- Use this endpoint to validate sequence payloads before calling /v2/sequence/update in custom tooling.
- user_id is appended automatically when available to aid schema analytics.
- include_examples=true instructs the builder to include trimmed reference objects that can be displayed alongside the schema for quick onboarding.

### Get Asset Schema

`GET https://api.storylinezads.com/assets`

Fetch the JSON schema describing V2 asset definitions (video, audio, image) used inside sequences.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Returns the JSON schema describing V2 asset payloads.

```json
{
  "success": true,
  "asset_type": "video",
  "schema": {
    "$id": "https://schemas.storylinez.ai/v2/assets/video.json",
    "type": "object",
    "required": ["asset_id", "source"],
    "properties": {
      "asset_id": {"type": "string"},
      "source": {
        "type": "object",
        "required": ["type"],
        "properties": {"type": {"enum": ["user", "stock"]}}
      }
    }
  }
}
```

**Response 403** — Authenticated principal lacks access to the requested organization/project.

**Response 500** — Internal server error while proxying the asset schema request.

**Usage notes**

- Schemas are generated upstream; the server forwards the payload without modification.
- Use this endpoint to drive dynamic form builders or schema validation inside custom integrations.
- When the upstream service exposes multiple versions, pass additional query flags (e.g. version) via the query string.
- Pair this endpoint with /v2/schema/sequence to validate both the parent sequence document and nested asset payloads before submitting updates.


---

# V2 Effects Catalogue API

Source: https://storylinezads.com/docs/api/v2_effects
Last generated: 2026-07-20

Access reusable visual effect presets surfaced by the V2 build server under the /v2/effects namespace.

Base route: `/v2/effects` (relative to `https://api.storylinezads.com`)

## Effects Catalogue

Endpoints that surface effect definitions and filtered listings for the V2 editor and agent system.

### Get Effects Catalog

`GET https://api.storylinezads.com/catalog`

Fetch the full catalog of available effects grouped by asset compatibility.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Returns the upstream catalog payload (effect definitions grouped by asset compatibility).

```json
{
  "success": true,
  "org_id": "org_demo123",
  "project_id": "proj_v2_001",
  "effects": [
    {
      "effect_id": "fx_light_leak",
      "name": "Light Leak",
      "asset_types": ["videos"],
      "parameters": {"intensity": {"default": 0.4, "min": 0, "max": 1}}
    }
  ],
  "updated_at": "2025-05-01T12:00:00.000Z"
}
```

**Response 400** — Invalid query parameters detected by the upstream service.

**Response 403** — Authenticated principal lacks access to the requested organization/project.

**Response 500** — Internal server error while proxying the upstream catalog request.

**Usage notes**

- All query parameters are forwarded to the build server verbatim; unsupported flags are ignored upstream.
- The route injects user_id automatically for auditing when present on the authenticated principal.
- Use this endpoint to hydrate dropdowns or caches before presenting effect options in the UI.
- Cache the response for a short interval (e.g. 5 minutes) to avoid repeatedly downloading large catalog payloads.

### List Effects

`GET https://api.storylinezads.com/list`

Retrieve effect definitions filtered by asset type or other parameters.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Returns the filtered list of effect presets for the requested asset type.

```json
{
  "success": true,
  "asset_type": "videos",
  "filters": {"search": "light", "page": 1, "page_size": 20},
  "items": [
    {
      "effect_id": "fx_light_leak",
      "name": "Light Leak",
      "summary": "Adds subtle light leak overlays",
      "tags": ["stylized", "ambient"],
      "parameters": {"intensity": 0.4}
    }
  ],
  "pagination": {"page": 1, "page_size": 20, "total_pages": 1, "total_items": 3}
}
```

**Response 400** — asset_type missing or other validation failure.

**Response 403** — Authenticated principal lacks organization access.

**Response 404** — Upstream service could not find any entries for the supplied constraints.

**Response 500** — Internal server error while proxying the list request.

**Usage notes**

- asset_type is validated by Storylinez_Server before the upstream call; missing values raise a 400 error immediately.
- Like the catalog route, additional query parameters are forwarded as-is, making the endpoint future-proof for new filters.
- Use this endpoint to power effect pickers scoped to the current clip or media type in the V2 editor.
- Map the "parameters" object into form controls to let editors tweak effect-specific knobs before applying presets.


---

# V2 Share API

Source: https://storylinezads.com/docs/api/v2_share
Last generated: 2026-07-20

Create and manage public share links for V2 sequence renders.

Base route: `/v2/share` (relative to `https://api.storylinezads.com`)

## Share Link Management

Create, view, list, and revoke V2 public share links.

### Create Share Link

`POST https://api.storylinezads.com/create`

Create a public share link for a rendered V2 sequence.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 201** — Share link created successfully.

```json
{
  "success": true,
  "share_id": "share_abc123",
  "share_url": "https://docs.storylinezads.com/share/share_abc123",
  "created_at": "2026-04-15T10:00:00Z"
}
```

**Response 400** — Missing project_id, org_id, or render_id.

**Response 403** — Permission denied for organization/project.

**Response 404** — Project, sequence, or render not found.

**Response 409** — Conflicting share state for requested render.

**Response 500** — Internal server error.

**Usage notes**

- A render is required before sharing. Calls without render_id are rejected.
- Use this endpoint after /v2/render/start jobs finish successfully.
- Returned share_url is public and can be opened without API authentication.

### Get Public Share

`GET https://api.storylinezads.com/public/{share_id}`

Fetch publicly viewable share payload by share_id.

- Auth required: no
- Rate limited: yes
- Action type: read-only

**Response 200** — Public share payload returned.

```json
{
  "success": true,
  "data": {
    "share_id": "share_abc123",
    "project_id": "proj_v2_789",
    "render": {"render_id": "rnd_9c1a", "streamable_url": "https://..."}
  }
}
```

**Response 400** — Missing or invalid share_id path value.

**Response 404** — Share not found or revoked.

**Response 500** — Internal server error.

**Usage notes**

- This endpoint is intentionally public and does not require auth headers.
- Set generate_streamable_link=false for metadata-only reads.
- Use stream_use_cdn=true only when CDN streaming is configured.

### List Share Links

`GET https://api.storylinezads.com/list`

List share links for a V2 project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Share links listed successfully.

```json
{
  "success": true,
  "items": [{"share_id": "share_abc123", "active": true}],
  "total": 3,
  "page": 1,
  "limit": 20
}
```

**Response 400** — Missing org_id or project_id.

**Response 403** — Permission denied.

**Response 500** — Internal server error.

**Usage notes**

- Use this endpoint to build share management dashboards.
- Pagination follows page/limit semantics used across V2 endpoints.

### Revoke Share Link

`POST https://api.storylinezads.com/revoke`

Deactivate an existing share link.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Share revoked successfully.

```json
{
  "success": true,
  "message": "Share link has been revoked",
  "share_id": "share_abc123"
}
```

**Response 400** — Missing share_id or org_id.

**Response 403** — Permission denied.

**Response 404** — Share not found.

**Response 500** — Internal server error.

**Usage notes**

- Revoked links stop resolving from the public endpoint.
- Keep share_id in your project metadata if you need revocation workflows.


---

# Data Collection API

Source: https://storylinezads.com/docs/api/data_collection
Last generated: 2026-07-20

Server-governed collection and extraction workflows for YouTube profile data.

Base route: `/data-collection` (relative to `https://api.storylinezads.com`)

## YouTube Collection

Collect YouTube dataset candidates and optionally extract selected items to storage.

### Service Status

`GET https://api.storylinezads.com/status`

Get Data Collection API status and endpoint map.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Service status returned.

```json
{
  "info": "Data collection API",
  "status": "OK",
  "endpoints": {"start": "POST /data-collection/youtube/start"}
}
```

**Usage notes**

- Use this endpoint for health checks before launching collection jobs.

### Start Collection Job

`POST https://api.storylinezads.com/youtube/start`

Start a server-constrained YouTube data collection job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Collection job accepted.

```json
{
  "message": "Data collection job started",
  "job_id": "dc_job_123",
  "input": {"query": "new product launch ad", "max_results": 50}
}
```

**Response 400** — Missing org_id or invalid payload.

**Response 403** — Permission denied for org.

**Response 429** — Collection limit exceeded.

**Response 502** — Upstream collection provider error.

**Usage notes**

- Only query/prompt/max_results are user-controlled. Other collection knobs are server-managed.
- Use /youtube/job/{job_id} or /youtube/jobs to track progress.

### Get Collection Job

`GET https://api.storylinezads.com/youtube/job/{job_id}`

Get details for a collection job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Job payload returned.

```json
{
  "job_id": "dc_job_123",
  "status": "COMPLETED",
  "results": {"items": []}
}
```

**Response 403** — Permission denied.

**Response 404** — Job not found.

**Usage notes**

- If org_id is omitted, access checks are derived from the job record.

### List Collection Jobs

`GET https://api.storylinezads.com/youtube/jobs`

List paginated collection jobs for an organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Collection jobs page returned.

```json
{
  "items": [{"job_id": "dc_job_123", "status": "IN_PROGRESS"}],
  "total": 6,
  "page": 1,
  "page_size": 20
}
```

**Response 400** — Missing org_id.

**Response 403** — Permission denied.

**Usage notes**

- Use search and status together for operator-style monitoring dashboards.

### Start Extraction

`POST https://api.storylinezads.com/youtube/job/{job_id}/extract`

Start extraction/download for selected collection items.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Extraction started.

```json
{
  "message": "Extraction started",
  "job_id": "dc_job_123",
  "extraction_job_id": "ext_456",
  "items_count": 3
}
```

**Response 400** — Missing org_id or invalid video_indices.

**Response 403** — Permission denied.

**Response 429** — Extraction limit exceeded.

**Usage notes**

- Extraction is separate from collection and can be triggered after a completed collection job.
- Use extraction-status endpoint to monitor extraction progress.

### Get Extraction Status

`GET https://api.storylinezads.com/youtube/job/{job_id}/extraction-status`

Get extraction progress and state for a collection job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Extraction status returned.

```json
{
  "job_id": "dc_job_123",
  "extraction_status": "IN_PROGRESS",
  "items": []
}
```

**Response 403** — Permission denied.

**Response 404** — Job not found.

**Usage notes**

- Poll this endpoint for extraction progress instead of repeatedly calling item URL endpoints.

### Get Extracted Item URL

`GET https://api.storylinezads.com/youtube/job/{job_id}/item/{item_index}/url`

Generate stream/download URL for one extracted item.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Item URL returned.

```json
{
  "job_id": "dc_job_123",
  "item_index": 0,
  "streamable_url": "https://...",
  "download_url": "https://..."
}
```

**Response 403** — Permission denied.

**Response 404** — Item not found.

**Usage notes**

- item_index is zero-based.
- Use short expiry values for browser playback sessions.


---

# Pipelines API

Source: https://storylinezads.com/docs/api/pipeline
Last generated: 2026-07-20

Start and track end-to-end V1 or V2 pipeline jobs from a single API surface.

Base route: `/pipeline` (relative to `https://api.storylinezads.com`)

## Pipeline Jobs

Create pipeline jobs and monitor full, status-only, or result-only views.

### Pipeline Service Status

`GET https://api.storylinezads.com/status`

Get pipeline API health information and endpoint map.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Service status returned.

```json
{
  "info": "Pipeline API",
  "status": "OK",
  "endpoints": {"v1": "POST /pipeline/v1", "v2": "POST /pipeline/v2"}
}
```

**Usage notes**

- Use this endpoint for readiness probes before triggering pipeline jobs.

### Start V1 Pipeline

`POST https://api.storylinezads.com/v1`

Start a V1 project pipeline job from prompt/media inputs.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Pipeline job accepted.

```json
{
  "message": "V1 Pipeline job started successfully",
  "job_id": "pipe_abc123",
  "pipeline": "v1",
  "status": "IN_QUEUE",
  "poll_endpoint": "/pipeline/pipe_abc123"
}
```

**Response 400** — Missing required fields or invalid config payload.

**Response 403** — Permission denied for organization.

**Response 500** — Internal server error.

**Usage notes**

- Either main_prompt or reference_video_id is required for V1 jobs.
- Alias fields are mapped server-side to canonical V1 config keys.
- Poll /pipeline/{job_id}/status for lightweight progress checks.

### Start V2 Pipeline

`POST https://api.storylinezads.com/v2`

Start a V2 sequence-builder pipeline job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — V2 pipeline job accepted.

```json
{
  "message": "V2 Pipeline job started successfully",
  "job_id": "pipe_v2_789",
  "pipeline": "v2",
  "status": "IN_QUEUE",
  "poll_endpoint": "/pipeline/pipe_v2_789"
}
```

**Response 400** — Missing required fields or invalid config.

**Response 403** — Permission denied.

**Response 500** — Internal server error.

**Usage notes**

- sequence_prompt (or message alias) is required for V2 jobs.
- Use context_documents/context_references to pre-seed V2 context at job start.

### Get Pipeline Job

`GET https://api.storylinezads.com/{job_id}`

Get full pipeline job document including progress and result payload.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Full job document returned.

```json
{
  "job_id": "pipe_abc123",
  "status": "IN_PROGRESS",
  "progress": 0.46,
  "result": null
}
```

**Response 404** — Job not found.

**Usage notes**

- Use this endpoint when you need full context, not just status fields.

### Get Pipeline Job Status

`GET https://api.storylinezads.com/{job_id}/status`

Get lightweight status payload for fast polling.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Status payload returned.

```json
{
  "job_id": "pipe_abc123",
  "status": "IN_PROGRESS",
  "current_stage": "render",
  "progress": 0.82
}
```

**Response 404** — Job not found.

**Usage notes**

- Preferred endpoint for frequent polling UIs due to smaller payload size.

### Get Pipeline Job Result

`GET https://api.storylinezads.com/{job_id}/result`

Return result/error view once job reaches terminal state.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Result payload returned.

```json
{
  "job_id": "pipe_abc123",
  "status": "COMPLETED",
  "result": {"project_id": "proj_123", "render_id": "rnd_456"}
}
```

**Response 404** — Job not found.

**Usage notes**

- Use this endpoint after status transitions to COMPLETED or FAILED.

### Cancel Pipeline Job

`DELETE https://api.storylinezads.com/{job_id}`

Cancel an in-queue or in-progress pipeline job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Job cancelled successfully.

```json
{
  "message": "Job cancelled successfully",
  "job_id": "pipe_abc123"
}
```

**Response 400** — Job not found or already terminal (cannot cancel).

**Response 500** — Internal server error.

**Usage notes**

- Cancellation is best-effort. Some worker tasks may complete but their results are discarded.


---

# Voice Library API

Source: https://storylinezads.com/docs/api/voice_library
Last generated: 2026-07-20

Discover voices, manage user-cloned voice samples, and generate single or multi-speaker TTS.

Base route: `/voice-library` (relative to `https://api.storylinezads.com`)

## System Voice Library

Browse and inspect built-in Storylinez voice library entries.

### List System Voices

`GET https://api.storylinezads.com/voices`

List built-in voices with optional search and filters.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Voice library page returned.

```json
{
  "voices": [{"voice_id": "sys_voice_1", "name": "Ava"}],
  "pagination": {"page": 1, "limit": 50, "total": 120}
}
```

### Get System Voice

`GET https://api.storylinezads.com/voices/{voice_id}`

Get one built-in voice by voice_id.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Voice returned.

```json
{
  "voice_id": "sys_voice_1",
  "name": "Ava",
  "category": "narration"
}
```

**Response 404** — Voice not found.

### List Voice Categories

`GET https://api.storylinezads.com/categories`

List available system voice categories.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Categories returned.

```json
{
  "categories": ["narration", "conversational", "announcer"]
}
```

## User Voice Samples

Upload, preprocess, list, update, and delete user-cloned voices.

### Create Upload Link

`GET https://api.storylinezads.com/user-voices/upload/create_link`

Create a secure upload link for a voice sample file.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Upload link generated.

```json
{
  "upload_id": "upl_abc123",
  "upload_link": "https://...",
  "key": "userdata/...",
  "expires_in": 3600
}
```

**Response 400** — Missing/invalid org_id, filename, or file_size.

**Response 403** — Permission denied.

### Create User Voice

`POST https://api.storylinezads.com/user-voices`

Register uploaded sample and start preprocessing job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Preprocessing job started.

```json
{
  "job_id": "voice_job_123",
  "status": "IN_QUEUE"
}
```

**Response 400** — Validation failure (missing required fields, invalid upload_id, etc).

**Response 403** — Permission denied.

**Response 429** — Voice sample limit exceeded.

**Response 502** — Build server preprocessing error.

### Get User Voice Job

`GET https://api.storylinezads.com/user-voices/jobs/{job_id}`

Poll voice sample preprocessing job and receive finalized voice on completion.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Job status returned.

```json
{
  "job_id": "voice_job_123",
  "status": "COMPLETED",
  "voice": {"voice_id": "usr_voice_1", "name": "My Warm Narrator"}
}
```

**Response 403** — Permission denied.

**Response 404** — Job not found.

### List User Voices

`GET https://api.storylinezads.com/user-voices`

List cloned voices for an organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Voices page returned.

```json
{
  "items": [{"voice_id": "usr_voice_1", "name": "My Warm Narrator"}],
  "total": 3
}
```

### Get User Voice

`GET https://api.storylinezads.com/user-voices/{voice_id}`

Get one cloned voice by voice_id.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Voice returned.

```json
{
  "voice_id": "usr_voice_1",
  "name": "My Warm Narrator"
}
```

**Response 404** — Voice not found.

### Update User Voice

`PUT https://api.storylinezads.com/user-voices/{voice_id}`

Update metadata for a cloned voice.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Voice updated successfully.

**Response 404** — Voice not found.

### Delete User Voice

`DELETE https://api.storylinezads.com/user-voices/{voice_id}`

Delete a cloned user voice.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Voice deleted successfully.

**Response 404** — Voice not found.

## TTS Generation

Generate TTS outputs and monitor generation jobs.

### Generate TTS

`POST https://api.storylinezads.com/generate`

Start single-speaker text-to-speech generation.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — TTS generation job accepted.

```json
{
  "message": "TTS generation started",
  "job": {"job_id": "tts_abc123", "status": "IN_QUEUE"}
}
```

**Response 400** — Missing org_id or text.

**Response 429** — Voiceover generation quota exceeded.

**Response 502** — Upstream TTS provider error.

### Generate Multi-speaker TTS

`POST https://api.storylinezads.com/generate/multi-speaker`

Start a multi-speaker generation job from segment/voice mapping.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Multi-speaker TTS job accepted.

**Response 400** — Missing org_id, segments, or voices.

**Response 429** — Voiceover generation quota exceeded.

### Get TTS Job

`GET https://api.storylinezads.com/jobs/{job_id}`

Get one TTS job status by job_id.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Job status returned.

**Response 404** — Job not found.

### List TTS Jobs

`GET https://api.storylinezads.com/jobs`

List paginated TTS jobs for an organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Jobs page returned.

```json
{
  "items": [{"job_id": "tts_abc123", "status": "COMPLETED"}],
  "page": 1,
  "limit": 20,
  "total": 8
}
```

**Response 400** — Missing org_id.


---

# Prompts API

Source: https://storylinezads.com/docs/api/prompts
Last generated: 2026-07-20

Create, update, and manage prompts and reference videos for Storylinez projects.

Base route: `/prompts` (relative to `https://api.storylinezads.com`)

## Prompt Management

Create and manage prompts for projects

### Create Prompt

`POST https://api.storylinezads.com/create`

Creates a new prompt associated with a v1 project.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 201** — Prompt created successfully

```json
{
  "prompt_id": "unique_prompt_id",
  "project_id": "project_id_1",
  "org_id": "org_id_1",
  "is_text_prompt": true,
  "temperature": 0.8,
  "total_length": 30,
  "iterations": 2,
  "deepthink": true,
  "overdrive": false,
  "web_search": true,
  "eco": false,
  "enable_context_augmentation": true,
  "engine": "bolt",
  "model": "auto",
  "created_by": "user_id",
  "created_at": "2024-07-25T12:00:00.000Z",
  "updated_at": "2024-07-25T12:00:00.000Z",
  "main_prompt": "Create a promotional video for our new product.",
  "document_context": ["Focus on the key features and benefits."],
  "skip_voiceover": false,
  "voiceover_mode": "generated"
}
```

**Response 400** — Bad Request - Missing required fields or invalid data

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 404** — Not Found - Project or referenced video not found

**Response 409** — Conflict - A prompt already exists for this project or the project is a v2 sequence builder (use /v2 APIs)

**Response 415** — Unsupported Media Type - Content-Type must be application/json

**Response 500** — Internal Server Error

**Usage notes**

- You must provide either main_prompt (for text prompts) or reference_video_id (for video prompts), but not both.
- The prompt type (is_text_prompt) is determined automatically.
- For video prompts, the referenced video must have been previously processed completely.
- Legacy /prompts routes only work for v1 projects. Sequence builder (v2) projects return 409 and must use the /v2/sequence APIs.
- eco=true cannot be combined with a custom model alias in either prompt or reference video workflows.

### Get Prompt

`GET https://api.storylinezads.com/get`

Retrieves a prompt by either prompt_id or project_id.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Prompt retrieved successfully

```json
{
  "prompt_id": "unique_prompt_id",
  "project_id": "project_id_1",
  "org_id": "org_id_1",
  "is_text_prompt": true,
  "temperature": 0.7,
  "total_length": 20,
  "iterations": 1,
  "deepthink": false,
  "overdrive": false,
  "web_search": false,
  "eco": false,
  "created_by": "user_id",
  "created_at": "2024-07-25T12:00:00.000Z",
  "updated_at": "2024-07-25T12:00:00.000Z",
  "main_prompt": "Create a promotional video.",
  "document_context": ["Focus on key features."],
  "skip_voiceover": false,
  "voiceover_mode": "generated"
}
```

**Response 400** — Bad Request - Missing required parameters

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 404** — Not Found - Prompt not found

**Response 500** — Internal Server Error

**Usage notes**

- Either prompt_id or project_id must be provided.

### Get Prompt by Project

`GET https://api.storylinezads.com/get_by_project`

Retrieves a prompt by project_id.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Prompt retrieved successfully

```json
{
  "prompt_id": "unique_prompt_id",
  "project_id": "project_id_1",
  "org_id": "org_id_1",
  "is_text_prompt": true,
  "temperature": 0.7,
  "total_length": 20,
  "iterations": 1,
  "deepthink": false,
  "overdrive": false,
  "web_search": false,
  "eco": false,
  "created_by": "user_id",
  "created_at": "2024-07-25T12:00:00.000Z",
  "updated_at": "2024-07-25T12:00:00.000Z",
  "main_prompt": "Create a promotional video.",
  "document_context": ["Focus on key features."],
  "skip_voiceover": false,
  "voiceover_mode": "generated"
}
```

**Response 400** — Bad Request - Missing required query parameters

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 404** — Not Found - No prompt found for this project

**Response 500** — Internal Server Error

**Usage notes**

- Simply provides the prompt for a specific project.

### Update Prompt

`PUT https://api.storylinezads.com/update`

Updates an existing prompt.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Prompt updated successfully

```json
{
  "message": "Prompt updated successfully",
  "updated_fields": {
    "temperature": 0.9,
    "total_length": 40,
    "main_prompt": "Updated prompt text",
    "voiceover_mode": "uploaded",
    "engine": "weave",
    "model": "storylinez-1-muse",
    "model_override": "storylinez-1-muse",
    "updated_at": "2024-07-25T13:00:00.000Z"
  }
}
```

**Response 400** — Bad Request - Missing required parameters or invalid data

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 404** — Not Found - Prompt or referenced video not found

**Response 500** — Internal Server Error

**Usage notes**

- Either prompt_id or project_id must be provided as a query parameter.
- Fields that can be updated depend on the prompt type (text or video).
- Any changes to the prompt will mark dependent downstream components as outdated.
- When setting a custom model alias, ensure eco remains false; otherwise the request will be rejected.

### Switch Prompt Type

`PUT https://api.storylinezads.com/switch_type`

Switches a prompt between text and video types.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Prompt type switched successfully

```json
{
  "prompt_id": "unique_prompt_id",
  "project_id": "project_id_1",
  "org_id": "org_id_1",
  "is_text_prompt": true,
  "temperature": 0.7,
  "total_length": 20,
  "iterations": 1,
  "deepthink": false,
  "overdrive": false,
  "web_search": false,
  "eco": false,
  "created_by": "user_id",
  "created_at": "2024-07-25T12:00:00.000Z",
  "updated_at": "2024-07-25T14:00:00.000Z",
  "main_prompt": "Create a new video.",
  "document_context": ["Focus on new features."],
  "skip_voiceover": false,
  "voiceover_mode": "generated"
}
```

**Response 400** — Bad Request - Missing required fields or invalid data

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 404** — Not Found - Prompt or referenced video not found

**Response 500** — Internal Server Error

**Usage notes**

- When switching to a text prompt, provide main_prompt in the request body.
- When switching to a video prompt, provide reference_video_id in the request body.
- Switching prompt types will mark downstream components as outdated.

### Self-update Prompt

`PUT https://api.storylinezads.com/selfupdate`

Refreshes prompt data from latest project state without creating a new prompt.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Prompt refreshed successfully.

```json
{
  "message": "Prompt refreshed successfully",
  "prompt_id": "prompt_id_1",
  "updated_at": "2026-04-15T12:00:00Z"
}
```

**Response 400** — Bad Request - Either prompt_id or project_id must be provided.

**Response 401** — Unauthorized - Invalid token.

**Response 403** — Forbidden - User does not have permission.

**Response 404** — Not Found - Prompt/project not found.

**Response 500** — Internal Server Error.

**Usage notes**

- Use this endpoint when project metadata, company details, or references changed and prompt context must be refreshed.
- Self-update does not start a generation job. Use query generation or downstream endpoints afterwards.

### Content Search Query

`POST https://api.storylinezads.com/query/generate`

Initiates a search for related content based on a prompt.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Search job started successfully

```json
{
  "message": "Search job started successfully",
  "job_id": "unique_job_id",
  "prompt_id": "prompt_id_1"
}
```

**Response 400** — Bad Request - Missing required fields or invalid parameter values

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 404** — Not Found - Prompt, project or reference video data not found

**Response 500** — Internal Server Error

**Response 502** — Bad Gateway - Error connecting to build server

**Usage notes**

- Uses the prompt's content (text or video analysis) to find related content.
- The response is a job ID which can be used to retrieve results later.
- For text prompts, main_prompt is used; for video prompts, analysis data is used.
- If not provided, company details will be fetched from the organization.

### Get Search Results

`GET https://api.storylinezads.com/query/results`

Retrieves the results of a previously initiated content search.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Search completed successfully and results are available

```json
{
  "job_id": "unique_job_id",
  "status": "COMPLETED",
  "search_params": {
    "num_videos": 5,
    "num_audio": 1,
    "num_images": 0,
    "temperature": 0.7
  },
  "search_timestamp": "2024-07-25T12:00:00.000Z",
  "results": {
    "videos": [
      {
        "path": "video_path_1",
        "title": "Video Title 1",
        "description": "A close-up shot of hands gently holding a beautifully designed eco-friendly product made from bamboo and recycled materials, set against a natural wood table, with soft morning sunlight streaming in and lush green plants in the background, emphasizing sustainability and craftsmanship.",
        "thumbnail": "thumbnail_url_1"
      },
      {
        "path": "video_path_2",
        "title": "Video Title 2",
        "description": "A dynamic, overhead view of a modern millennial apartment with minimalistic décor, where a young, diverse group of friends are happily unpacking and using eco-friendly products, laughing and enjoying each other's company in a bright, inviting space.",
        "thumbnail": "thumbnail_url_2"
      }
    ],
    "audio": [
      {
        "path": "audio_path_1",
        "title": "Audio Title 1",
        "description": "Upbeat, inspirational electronic indie music with organic elements such as gentle acoustic guitar strums and soft percussion, evoking a sense of hope, progress, and eco-conscious optimism, building in energy and warmth throughout the 30 seconds to support the brand's innovative and sustainable future."
      }
    ],
    "images": [],
    "video_count": 2,
    "audio_count": 1,
    "image_count": 0
  }
}
```

**Response 202** — Search job is still in progress

```json
{
  "job_id": "unique_job_id",
  "status": "IN_PROGRESS",
  "progress": 50,
  "search_params": {
    "num_videos": 5,
    "num_audio": 1,
    "num_images": 0,
    "temperature": 0.7
  },
  "search_timestamp": "2024-07-25T12:00:00.000Z"
}
```

**Response 400** — Bad Request - Missing required parameters

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 404** — Not Found - Prompt not found or no search has been performed

**Response 500** — Internal Server Error

**Response 502** — Bad Gateway - Error connecting to build server

**Usage notes**

- Either prompt_id or project_id must be provided.
- If the search is still processing, a 202 Accepted response will be returned with progress info.
- A completed search returns 200 OK with the full result set.
- Results include descriptive content for videos, audio, and images that can be used in your projects.

## Reference Video Management

Upload and manage reference videos for video prompts

### Generate Video Upload Link

`GET https://api.storylinezads.com/upload/create_link`

Generates a pre-signed URL for uploading a video to S3.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Upload link generated successfully

```json
{
  "upload_id": "unique_upload_id",
  "upload_link": "https://your-s3-bucket.s3.amazonaws.com/your-s3-key?AWSAccessKeyId=...",
  "s3_key": "userdata/your_org_id/video.mp4",
  "expiration": 3600
}
```

**Response 400** — Bad Request - Missing required fields or invalid file extension

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission or would exceed storage limits

**Response 500** — Internal Server Error

**Usage notes**

- The file must have a valid video extension (mp4, mov, mkv, webm, m4v, flv, wmv, mpg, mpeg, ts, m2ts, 3gp, asf).
- The upload link expires after 1 hour.
- If file_size is provided, it will check if you have enough storage quota before generating a link.

### Mark Video Upload Complete

`POST https://api.storylinezads.com/upload/complete`

Registers the completed video upload in the database and initiates processing.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Video registered successfully

```json
{
  "message": "Reference video registered successfully",
  "file": {
    "file_id": "unique_file_id",
    "org_id": "org_id_1",
    "s3_key": "userdata/org_id_1/video.mp4",
    "filename": "video.mp4",
    "original_filename": "video.mp4",
    "size": 2048576,
    "mimetype": "video/mp4",
    "uploaded_by": "user_id",
    "upload_date": "2024-07-25T12:00:00.000Z",
    "last_modified": "2024-07-25T12:00:00.000Z",
    "media_type": "video",
    "analysis_params": {
      "context": "Brand introduction",
      "tags": ["brand", "introduction"],
      "company_details": "Storylinez",
      "deepthink": false,
      "overdrive": true,
      "web_search": false,
      "eco": false,
      "temperature": 0.7,
      "analyze_audio": true,
      "advanced_detection": true,
      "model": "auto"
    },
    "original_url": "https://s3.amazonaws.com/your_bucket/userdata/org_id_1/video.mp4?..."
  },
  "job_id": "processing_job_id"
}
```

**Response 400** — Bad Request - Missing required fields or invalid file format

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission or would exceed storage limits

**Response 404** — Not Found - File not found in storage

**Response 413** — Payload Too Large - Reference video duration exceeds the plan limit

**Response 409** — Conflict - A reference video with the same key already exists

**Response 500** — Internal Server Error

**Usage notes**

- Either upload_id or key must be provided to identify the uploaded file.
- The file size is verified directly from S3 rather than trusting client input.
- The video will be processed automatically for later use with video prompts.
- If you supply a custom model alias, ensure eco is false; otherwise the request returns 400.
- Reference videos longer than your plan's limit return 413 with a helpful message.

### List Reference Videos

`GET https://api.storylinezads.com/reference-videos/list`

Retrieves a list of reference videos for an organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Reference videos retrieved successfully

```json
{
  "count": 45,
  "page": 2,
  "limit": 20,
  "total_pages": 3,
  "reference_videos": [
    {
      "file_id": "video_id_1",
      "org_id": "org_id_1",
      "s3_key": "userdata/org_id_1/video1.mp4",
      "filename": "video1.mp4",
      "original_filename": "video1.mp4",
      "size": 2048,
      "mimetype": "video/mp4",
      "uploaded_by": "user_id",
      "upload_date": "2024-07-25T12:00:00.000Z",
      "last_modified": "2024-07-25T12:00:00.000Z",
      "media_type": "video",
      "analysis_params": {
        "context": "Brand introduction",
        "tags": ["brand", "introduction"],
        "company_details": "Storylinez",
        "deepthink": false,
        "overdrive": false,
        "web_search": false,
        "eco": false,
        "temperature": 0.7,
        "analyze_audio": true
      },
      "urls": {
        "thumbnail": "https://s3.amazonaws.com/your_bucket/thumbnails/video1.jpg?...",
        "streamable": null,
        "download": null
      },
      "analysis_data": {
        "status": "COMPLETED"
      },
      "usage": {
        "count": 1,
        "prompts": [
          {
            "prompt_id": "prompt_id_1",
            "project_id": "project_id_1"
          }
        ]
      }
    }
  ]
}
```

**Response 400** — Bad Request - Missing required query parameters or invalid pagination parameters

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 500** — Internal Server Error

**Usage notes**

- Use detailed=true to include complete analysis data for each video.
- The include_usage parameter helps identify which videos are in use by which prompts.
- URLs are generated on-demand and expire after a period of time.
- Results are paginated; use page and limit parameters to navigate through the results.

### Delete Reference Video

`DELETE https://api.storylinezads.com/reference-videos/delete`

Deletes a reference video if it's not being used in any prompts.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Reference video deleted successfully

```json
{
  "message": "Reference video deleted successfully",
  "file_id": "your_file_id",
  "file_deletion": {
    "status": "success",
    "deleted_count": 1
  },
  "analysis_deletion": {
    "status": "success",
    "deleted_count": 1
  }
}
```

**Response 400** — Bad Request - Missing required query parameters

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 404** — Not Found - File not found

**Response 409** — Conflict - The video is currently in use by prompts

**Response 500** — Internal Server Error

**Usage notes**

- Videos in use by prompts cannot be deleted (returns 409 with a list of projects using the video).
- Deletion frees up storage quota for the organization.

### Get Reference Video Details

`GET https://api.storylinezads.com/reference-videos/details`

Retrieves detailed information about a specific reference video.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Reference video details retrieved successfully

```json
{
  "file_id": "video_id_1",
  "org_id": "org_id_1",
  "s3_key": "userdata/org_id_1/video1.mp4",
  "filename": "video1.mp4",
  "original_filename": "video1.mp4",
  "size": 2048,
  "mimetype": "video/mp4",
  "uploaded_by": "user_id",
  "upload_date": "2024-07-25T12:00:00.000Z",
  "last_modified": "2024-07-25T12:00:00.000Z",
  "media_type": "video",
  "analysis_params": {
    "context": "Brand introduction",
    "tags": ["brand", "introduction"],
    "company_details": "Storylinez",
    "deepthink": false,
    "overdrive": false,
    "web_search": false,
    "eco": false,
    "temperature": 0.7,
    "analyze_audio": true,
    "advanced_detection": false,
    "model": "auto"
  },
  "urls": {
    "thumbnail": "https://s3.amazonaws.com/your_bucket/thumbnails/video1.jpg?...",
    "streamable": "https://s3.amazonaws.com/your_bucket/streamable/video1.mp4?...",
    "download": "https://s3.amazonaws.com/your_bucket/download/video1.mp4?..."
  },
  "analysis_data": {
    "status": "COMPLETED",
    "results": {}
  },
  "usage": {
    "count": 1,
    "prompts": [
      {
        "prompt_id": "prompt_id_1",
        "project_id": "project_id_1"
      }
    ]
  }
}
```

**Response 400** — Bad Request - Missing required query parameters

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 404** — Not Found - File not found

**Response 500** — Internal Server Error

**Usage notes**

- Provides complete details including processing status and results.
- Use detailed=false to get basic information without analysis results.
- Generated URLs expire after a period of time.

### Search Reference Videos

`GET https://api.storylinezads.com/reference-videos/search`

Searches for reference videos within an organization using a text query.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Reference videos search completed successfully

```json
{
  "count": 15,
  "page": 1,
  "limit": 10,
  "total_pages": 2,
  "query": "brand",
  "reference_videos": []
}
```

**Response 400** — Bad Request - Missing required parameters or invalid pagination

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 500** — Internal Server Error

**Usage notes**

- Search is case-insensitive and matches partial filenames.
- Results are paginated; use page and limit parameters to navigate results.
- Searches only within the specified organization's videos.

### Get Reference Videos by IDs

`POST https://api.storylinezads.com/reference-videos/get_by_ids`

Retrieves specific reference videos by an array of file IDs.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Returns the list of found reference videos

```json
{
  "reference_videos": [],
  "count": 2,
  "missing": ["file_id_3"]
}
```

**Response 400** — Bad Request - Missing required fields or too many file IDs

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 500** — Internal Server Error

**Usage notes**

- File IDs not found will be listed in the 'missing' array.
- Videos are returned in the same order as requested.
- Limited to a maximum of 50 videos per request.

## Storage Management

Manage storage usage and quotas

### Get Storage Usage

`GET https://api.storylinezads.com/storage/usage`

Retrieves storage usage information for an organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Storage usage information retrieved successfully

**Response 400** — Bad Request - Missing required parameters

**Response 401** — Unauthorized - Invalid token

**Response 403** — Forbidden - User does not have permission

**Response 500** — Internal Server Error

**Usage notes**

- Provides information about storage usage, limits, and subscription details.
- Useful for monitoring storage quotas and usage trends.


---

# Storyboard API

Source: https://storylinezads.com/docs/api/storyboard
Last generated: 2026-07-20

Create and manage storyboards in the StoryLinez platform. Legacy /storyboard endpoints are available for v1 sequence builder projects only.

Base route: `/storyboard` (relative to `https://api.storylinezads.com`)

## Storyboard Creation

Create and regenerate storyboards

### Create Storyboard

`POST https://api.storylinezads.com/create`

Creates a new storyboard based on project data and starts the generation job

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Storyboard creation job started

```json
{
  "message": "Storyboard creation job started successfully",
  "storyboard": {
    "storyboard_id": "sb_12345",
    "project_id": "project_123",
    "org_id": "org_456",
    "is_prompt": true,
    "deepthink": true,
    "overdrive": false,
    "web_search": true,
    "eco": false,
    "temperature": 0.7,
    "iterations": 3,
    "full_length": 120,
    "skip_voiceover": false,
    "voiceover_mode": "generated",
    "created_by": "user_789",
    "created_at": "2023-04-15T10:30:00Z",
    "updated_at": "2023-04-15T10:30:00Z",
    "is_stale": false,
    "job_id": "job_123",
    "edited_storyboard": null,
    "regeneration_prompt": null,
    "cascade_outdated": false,
    "documents": ["Some context document"]
  },
  "job_id": "job_123"
}
```

**Response 400** — Missing required fields or invalid data

```json
{ "error": "Project ID is required" }
```

**Response 401** — Authentication error

```json
{ "error": "User ID not found in token" }
```

**Response 403** — User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Project not found or prompt not found for project

```json
{ "error": "Project not found" }
```

**Response 409** — Storyboard already exists for this project or the project uses the v2 sequence builder (legacy endpoint not supported)

```json
{ "error": "Legacy storyboard endpoints are only available for v1 projects. Use /v2/sequence workflows." }
```

**Response 415** — Request body isn't JSON

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Legacy /storyboard endpoints work exclusively with v1 sequence builder projects. Requests targeting v2 projects return HTTP 409 with guidance to use /v2/sequence workflows instead.
- The project must have an associated prompt before creating a storyboard
- At least 1 video must be available in the project's media files
- The storyboard creation process is asynchronous and returns a job_id for tracking
- The `is_prompt` field in the response indicates whether the storyboard was generated from a text prompt (true) or a reference video (false)
- The `cascade_outdated` field indicates if upstream components have been updated
- Parameters like deepthink and temperature control the AI behavior and quality of results
- When using `voiceover_mode=uploaded`, ensure the project has a voiceover file already uploaded
- The generation process considers both project media and company details for context
- For time-sensitive projects, enable `eco=true` for faster processing but with potentially lower quality
- If you need factual/current information in your storyboard, enable `web_search=true`
- For professional narratives, combine `deepthink=true` with a lower temperature value (0.3-0.5)
- For creative outputs, use higher temperature values (0.7-0.9) with multiple iterations

### Redo Storyboard

`POST https://api.storylinezads.com/redo`

Restarts a storyboard generation job, optionally with regeneration instructions

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Storyboard job restarted

```json
{
  "message": "Storyboard job restarted successfully",
  "storyboard_id": "sb_12345",
  "job_id": "job_124"
}
```

**Response 400** — Missing required fields

```json
{ "error": "Either storyboard_id or project_id is required" }
```

**Response 401** — Authentication error

```json
{ "error": "User ID not found in token" }
```

**Response 403** — User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Storyboard not found

```json
{ "error": "Storyboard not found" }
```

**Response 409** — Project uses the v2 sequence builder; legacy storyboard endpoint not supported

```json
{ "error": "Legacy storyboard endpoints are only available for v1 projects. Use /v2/sequence workflows." }
```

**Response 415** — Request body isn't JSON

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Server error or connection to build server failed

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Legacy /storyboard endpoints only support v1 sequence builder projects; using a v2 project returns a 409 conflict instructing you to use the /v2/sequence workflows.
- Either `storyboard_id` or `project_id` must be provided
- The storyboard will be regenerated using the latest project media and settings
- You can provide a `regeneration_prompt` in the request to override any stored prompt
- All existing AI parameters and settings are preserved for regeneration
- If a `regeneration_prompt` is stored and not overridden, it will be used to guide the generation
- When `include_history=true`, previous generations and prompts are provided as context to the AI
- After regeneration, both `edited_storyboard` and `regeneration_prompt` fields are cleared
- The storyboard is marked as not stale after regeneration
- This endpoint is useful after making updates with `selfupdate` or `update` endpoints
- The history context helps the AI understand the evolution of your storyboard requirements
- For best results, provide specific, actionable guidance in your regeneration prompt
- Example prompts: "Focus more on the product benefits", "Create a more emotional narrative"
- After redoing, check the job status via the `/get` endpoint with `include_results=true`
- The consistency between storyboard and sequence redo endpoints ensures a uniform experience

## Storyboard Updates

Update storyboards with new data or values

### Update Storyboard with Latest Data

`PUT https://api.storylinezads.com/selfupdate`

Updates an existing storyboard with the latest project and prompt information

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Storyboard updated

```json
{
  "message": "Storyboard updated successfully with latest project and prompt data",
  "storyboard": {
    "storyboard_id": "sb_12345",
    "project_id": "project_123",
    "org_id": "org_456",
    "is_prompt": true,
    "deepthink": true,
    "overdrive": false,
    "web_search": true,
    "eco": false,
    "temperature": 0.7,
    "iterations": 3,
    "full_length": 120,
    "skip_voiceover": false,
    "voiceover_mode": "generated",
    "job_id": "job_123",
    "created_by": "user_789",
    "created_at": "2023-04-15T10:30:00Z",
    "updated_at": "2023-04-15T11:15:00Z",
    "is_stale": true,
    "cascade_outdated": false,
    "documents": ["Some context document"]
  }
}
```

**Response 400** — Missing required fields

```json
{ "error": "Either storyboard_id or project_id is required" }
```

**Response 401** — Authentication error

```json
{ "error": "User ID not found in token" }
```

**Response 403** — User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Storyboard or project not found

```json
{ "error": "Storyboard not found" }
```

**Response 409** — Project uses the v2 sequence builder; legacy storyboard endpoint not supported

```json
{ "error": "Legacy storyboard endpoints are only available for v1 projects. Use /v2/sequence workflows." }
```

**Response 415** — Request body isn't JSON

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Legacy /storyboard endpoints only support v1 sequence builder projects; using a v2 project returns a 409 conflict instructing you to use the /v2/sequence workflows.
- Either `storyboard_id` or `project_id` must be provided
- The storyboard is marked as "stale" after update, indicating it needs to be regenerated
- Use the `/redo` endpoint to regenerate with the updated data
- When `update_ai_params=false`, AI parameters like deepthink, temperature, etc. are preserved from the existing storyboard
- This endpoint preserves any existing `edited_storyboard` and `regeneration_prompt`
- The current storyboard data is saved to history before updating
- When a storyboard is updated but upstream is not outdated, downstream components will be marked as outdated
- This endpoint is useful after adding new media to a project or updating the prompt
- For workflow efficiency, batch all project changes before using this endpoint
- After selfupdate, the storyboard won't automatically regenerate until you call the /redo endpoint
- Use `update_ai_params=false` when you've fine-tuned the AI parameters and don't want them reset
- This endpoint ensures your storyboard stays in sync with project changes
- The history tracking helps maintain an audit trail of all storyboard changes
- For complex projects, use this endpoint when you want to incorporate new media assets
- When working with teams, always selfupdate before editing to ensure you have the latest data

### Update Storyboard Values

`PUT https://api.storylinezads.com/update`

Updates specific values in an existing storyboard

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Storyboard values updated

```json
{
  "message": "Storyboard values updated successfully",
  "storyboard": {
    "storyboard_id": "sb_12345",
    "project_id": "project_123",
    "org_id": "org_456",
    "is_prompt": true,
    "edited_storyboard": { ... },
    "regeneration_prompt": "Please make the narration more casual and conversational",
    "deepthink": true,
    "overdrive": false,
    "web_search": true,
    "eco": false,
    "temperature": 0.8,
    "iterations": 3,
    "full_length": 120,
    "skip_voiceover": false,
    "voiceover_mode": "generated",
    "created_by": "user_789",
    "created_at": "2023-04-15T10:30:00Z",
    "updated_at": "2023-04-15T11:30:00Z",
    "is_stale": true,
    "cascade_outdated": false,
    "documents": ["Some context document"]
  }
}
```

**Response 400** — Missing required fields, invalid voiceover_mode, or invalid storyboard structure

```json
{ "error": "Either storyboard_id or project_id is required" }
```

**Response 401** — Authentication error

```json
{ "error": "User ID not found in token" }
```

**Response 403** — User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Storyboard not found

```json
{ "error": "Storyboard not found" }
```

**Response 409** — Project uses the v2 sequence builder; legacy storyboard endpoint not supported

```json
{ "error": "Legacy storyboard endpoints are only available for v1 projects. Use /v2/sequence workflows." }
```

**Response 415** — Request body isn't JSON

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Legacy /storyboard endpoints only support v1 sequence builder projects; using a v2 project returns a 409 conflict instructing you to use the /v2/sequence workflows.
- Either `storyboard_id` or `project_id` must be provided
- If providing `edited_storyboard`, the data must conform to the storyboard schema structure
- The `edited_storyboard` will be validated against available media paths in the project
- This endpoint marks the storyboard as "stale" to indicate settings have changed
- No new job is created; use `/redo` to regenerate with the new settings
- At least one setting field must be provided to update the storyboard
- The current storyboard data is saved to history before updating
- The `regeneration_prompt` field will be used during the next storyboard regeneration
- When setting `voiceover_mode`, it must be either "generated" or "uploaded"
- This is the most powerful endpoint for fine-tuning your storyboard content
- Use this endpoint for manual corrections or creative changes to the AI-generated content
- For specific instructions to the AI, set a descriptive `regeneration_prompt`
- When editing manually, ensure all `dir` paths reference valid media in the project
- For scene reordering, update the frame numbers in your edited_storyboard
- Combine with the `/redo` endpoint to apply changes and regenerate the storyboard
- Use this endpoint when you need precise control over scene descriptions and transitions
- For voice adjustments, update the voiceover object with specific pace and tone values
- The resulting storyboard can be used as a direct input to sequence generation

### Reorder Storyboard Items

`PUT https://api.storylinezads.com/reorder`

Reorders videos or background music tracks in a storyboard

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Items successfully reordered

```json
{
  "message": "Successfully reordered videos",
  "storyboard_id": "sb_12345"
}
```

**Response 400** — Invalid parameters or indices

```json
{ "error": "new_order contains invalid indices" }
```

**Response 401** — Authentication error

```json
{ "error": "User ID not found in token" }
```

**Response 403** — User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Storyboard not found

```json
{ "error": "Storyboard not found" }
```

**Response 409** — Storyboard belongs to a v2 sequence builder project; legacy endpoint not supported

```json
{ "error": "Legacy storyboard endpoints are only available for v1 projects. Use /v2/sequence workflows." }
```

**Response 415** — Request body isn't JSON

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Legacy /storyboard endpoints only support v1 sequence builder projects; using a v2 project returns a 409 conflict instructing you to use the /v2/sequence workflows.
- The `new_order` array must contain all indices from 0 to n-1 where n is the number of items in the array
- No duplicates are allowed in the `new_order` array
- The modified storyboard is validated against the schema before saving
- The current storyboard state is saved to history before reordering
- The storyboard is marked as "stale" after reordering
- Downstream components are marked as outdated after reordering
- This endpoint creates an `edited_storyboard` if one doesn't already exist
- This endpoint is perfect for re-arranging scenes without changing their content
- Use this endpoint when you want to change the narrative flow of your storyboard
- Combine with the `/redo` endpoint if you want the AI to adapt to the new order
- For minor adjustments, this is more efficient than manually editing the entire storyboard
- When reordering videos, consider adjusting your background music order to match
- The reordering maintains all properties of each item including highlights and transitions
- This is useful for A/B testing different narrative structures with the same content

### Edit Storyboard Item

`PUT https://api.storylinezads.com/edit/item`

Edits a specific item in the storyboard (video, background music, or voiceover)

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Item successfully edited

```json
{
  "message": "Successfully edited videos at index 2",
  "storyboard_id": "sb_12345"
}
```

**Response 400** — Invalid parameters or structure

```json
{ "error": "Invalid storyboard structure after editing" }
```

**Response 401** — Authentication error

```json
{ "error": "User ID not found in token" }
```

**Response 403** — User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Storyboard not found

```json
{ "error": "Storyboard not found" }
```

**Response 409** — Storyboard belongs to a v2 sequence builder project; legacy endpoint not supported

```json
{ "error": "Legacy storyboard endpoints are only available for v1 projects. Use /v2/sequence workflows." }
```

**Response 415** — Request body isn't JSON

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Legacy /storyboard endpoints only support v1 sequence builder projects; using a v2 project returns a 409 conflict instructing you to use the /v2/sequence workflows.
- For array items ("videos" and "background_music"), `item_index` must be valid
- For "voiceover", the entire voiceover object is replaced and item_index is not used
- The modified storyboard is validated against the schema before saving
- The current storyboard state is saved to history before editing
- The storyboard is marked as "stale" after editing
- Downstream components are marked as outdated after editing
- This endpoint creates an `edited_storyboard` if one doesn't already exist
- This endpoint is ideal for targeted edits to specific scenes or audio elements
- Use this for refining scene descriptions or highlight sections without changing the media
- When editing a video, ensure the frame number maintains the desired sequence order
- For voiceover edits, you can modify the transcription, pace, tone, and voice settings
- Combine multiple item edits to incrementally improve your storyboard
- After making edits, use the `/get` endpoint to verify your changes
- Use descriptive scene titles and details to improve sequence generation quality
- For background music, adjust highlight timestamps to synchronize with key video moments

### Change Storyboard Media

`PUT https://api.storylinezads.com/change_media`

Changes the media file for an item in the storyboard

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Media successfully changed

```json
{
  "message": "Successfully changed media for videos at index 0",
  "storyboard_id": "sb_12345",
  "media_path": "path/to/new/media.mp4"
}
```

**Response 400** — Invalid parameters

```json
{ "error": "One of file_id, stock_id, or path must be provided" }
```

**Response 401** — Authentication error

```json
{ "error": "User ID not found in token" }
```

**Response 403** — User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Storyboard or media file not found

```json
{ "error": "File with ID file_xyz123 not found" }
```

**Response 409** — Storyboard belongs to a v2 sequence builder project; legacy endpoint not supported

```json
{ "error": "Legacy storyboard endpoints are only available for v1 projects. Use /v2/sequence workflows." }
```

**Response 415** — Request body isn't JSON

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Legacy /storyboard endpoints only support v1 sequence builder projects; using a v2 project returns a 409 conflict instructing you to use the /v2/sequence workflows.
- The `item_type` must be either "videos" or "background_music"
- At least one of `file_id`, `stock_id`, or `path` must be provided
- For videos, both video and image files are accepted
- For background_music, only audio files are accepted
- The modified storyboard is validated against the schema before saving
- The current storyboard state is saved to history with type "media_change" before modification
- The storyboard is marked as "stale" after changing media
- Downstream components are marked as outdated after changing media
- This endpoint creates an `edited_storyboard` if one doesn't already exist
- This endpoint is perfect for swapping out media while keeping scene descriptions
- Use this to replace stock footage with your own branded content
- When changing video clips, consider if the existing highlight timestamps still apply
- For consistent visuals, change videos that match the scene description and context
- After changing media, you may need to adjust highlight sections with the edit/item endpoint
- This is useful for iterative refinement by trying different visual assets
- Using stock_id is efficient for testing various stock media options

## Storyboard Retrieval

Retrieve storyboards, their history and media

### Get Storyboard

`GET https://api.storylinezads.com/get`

Retrieves a storyboard by ID or project ID

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Storyboard retrieved successfully

```json
{
  "storyboard_id": "sb_12345",
  "project_id": "project_123",
  "org_id": "org_456",
  "is_prompt": true,
  "deepthink": true,
  "overdrive": false,
  "web_search": true,
  "eco": false,
  "temperature": 0.7,
  "iterations": 3,
  "full_length": 120,
  "skip_voiceover": false,
  "voiceover_mode": "generated",
  "job_id": "job_123",
  "created_by": "user_789",
  "created_at": "2023-04-15T10:30:00Z",
  "updated_at": "2023-04-15T10:30:00Z",
  "is_stale": false,
  "cascade_outdated": false,
  "edited_message": "This storyboard has been edited. The edited version is the latest version and will be used for sequence generation.",
  "edited_storyboard": { ... },
  "regeneration_prompt": "Make the narration more casual"
}
```

**Response 400** — Missing required parameters

```json
{ "error": "Either storyboard_id or project_id is required" }
```

**Response 401** — Authentication error

```json
{ "error": "User ID not found in token" }
```

**Response 403** — User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Storyboard not found

```json
{ "error": "Storyboard not found" }
```

**Response 409** — Storyboard belongs to a v2 sequence builder project; legacy endpoint not supported

```json
{ "error": "Legacy storyboard endpoints are only available for v1 projects. Use /v2/sequence workflows." }
```

**Response 500** — Server error or connection failure

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Legacy /storyboard endpoints only support v1 sequence builder projects; using a v2 project returns a 409 conflict instructing you to use the /v2/sequence workflows.
- Either `storyboard_id` or `project_id` must be provided
- Setting `include_results=true` will fetch the job results directly from MongoDB
- Setting `include_details=true` will include the full media details without very large data fields
- Setting `include_media=true` will include all media data including large fields (significantly increases response size)
- By default, large media details are excluded to reduce response size and improve performance
- The `is_stale` field indicates whether the storyboard is out of sync with the latest data
- If the storyboard has been edited, an `edited_message` field will be included
- Job results are returned as `old_job_result` to indicate they may not reflect current edits
- This endpoint is the starting point for inspecting your storyboard content
- Use it to check if your storyboard is stale or needs regeneration
- The cascade_outdated flag helps identify if upstream components have changed
- For UI display, avoid include_media=true unless needed, as it returns large media data
- Include_results=true is useful for debugging or examining AI-generated content
- Monitor the is_stale flag to know when to prompt users to regenerate
- Check edited_storyboard to see manual modifications made to the AI-generated content

### Get Storyboard History

`GET https://api.storylinezads.com/history`

Retrieves the job history for a given storyboard

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Storyboard history retrieved successfully

```json
{
  "storyboard_id": "sb_12345",
  "total_history": 5,
  "page": 1,
  "limit": 10,
  "current": {
    "storyboard_id": "sb_12345",
    "history_type": "current",
    "timestamp": "2023-04-15T12:00:00Z",
    "storyboard_data": { ... }
  },
  "history": [
    {
      "storyboard_id": "sb_12345",
      "history_type": "update",
      "timestamp": "2023-04-15T11:30:00Z",
      "storyboard_data": { ... },
      "user_id": "user_789"
    },
    {
      "storyboard_id": "sb_12345",
      "history_type": "prompt",
      "timestamp": "2023-04-15T11:00:00Z",
      "prompt_text": "Make the narration more casual",
      "user_id": "user_789"
    },
    {
      "storyboard_id": "sb_12345",
      "history_type": "media_change",
      "timestamp": "2023-04-15T10:45:00Z",
      "storyboard_data": { ... },
      "user_id": "user_789"
    }
  ]
}
```

**Response 400** — Missing required parameters

```json
{ "error": "storyboard_id is required" }
```

**Response 401** — Authentication error

```json
{ "error": "User ID not found" }
```

**Response 403** — User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Storyboard not found

```json
{ "error": "Storyboard not found" }
```

**Response 409** — Storyboard belongs to a v2 sequence builder project; legacy endpoint not supported

```json
{ "error": "Legacy storyboard endpoints are only available for v1 projects. Use /v2/sequence workflows." }
```

**Response 500** — Server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Legacy /storyboard endpoints only support v1 sequence builder projects; using a v2 project returns a 409 conflict instructing you to use the /v2/sequence workflows.
- History entries are returned in reverse chronological order (newest first)
- The `history_type` parameter can filter entries by their type (update, generation, prompt, selfupdate, media_change)
- When `include_current=true`, the most recent job results are included as a "current" entry
- History provides context for understanding changes over time
- This endpoint is invaluable for tracking the evolution of your storyboard
- Use history to compare different versions and see what worked best
- The prompt history helps understand the direction given to the AI
- For collaboration, history shows which team member made specific changes
- When troubleshooting issues, compare current state with previous versions
- Use this endpoint to recover previous storyboard versions if needed
- For complex projects, track the sequence of edits through history
- History entries can be included as context when redoing a storyboard
- Different history_type values show different aspects of storyboard development
- Use pagination parameters for storyboards with extensive history

### Get Media Involved in Storyboard

`GET https://api.storylinezads.com/media_involved`

Retrieves media files used in a storyboard with detailed information

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Media retrieved successfully

```json
{
  "storyboard_id": "sb_12345",
  "project_id": "project_123",
  "media": {
    "videos": [
      {
        "file_id": "file_v123",
        "path": "path/to/video/file.mp4",
        "type": "video",
        "thumbnail_url": "https://example.com/thumbnail/v123.jpg",
        "streamable_url": "https://example.com/stream/v123",
        "is_stock": true,
        "storyboard_metadata": {
          "frame": 1,
          "scene": "Introduction",
          "details": "Opening scene with product introduction",
          "highlight": {
            "in": 2.5,
            "out": 8.2
          },
          "transition_in": "fade"
        }
      }
    ],
    "background_music": [
      {
        "file_id": "file_a456",
        "path": "path/to/audio/file.mp3",
        "type": "audio",
        "streamable_url": "https://example.com/stream/a456",
        "is_stock": false,
        "storyboard_metadata": {
          "track": 1,
          "audio": "Upbeat background music",
          "details": "Low volume during narration",
          "highlight": {
            "in": 0.0,
            "out": 15.0
          },
          "transition_in": "fade"
        }
      }
    ],
    "voiceover": {
      "file_id": "file_v789",
      "path": "path/to/voiceover/file.mp3",
      "type": "audio",
      "streamable_url": "https://example.com/stream/v789",
      "storyboard_metadata": {
        "transcription": "Welcome to our product demonstration",
        "details": "Professional male voice",
        "pace": "medium",
        "tone": "friendly",
        "voice": "en-US-Neural2-D"
      }
    }
  },
  "total_count": 3,
  "counts": {
    "videos": 1,
    "background_music": 1,
    "has_voiceover": true
  }
}
```

**Response 400** — Missing required parameters

```json
{ "error": "Either storyboard_id or project_id is required" }
```

**Response 401** — Unauthorized - invalid or missing token

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - user doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Storyboard not found or no storyboard results found

```json
{ "error": "Storyboard not found" }
```

**Response 409** — Storyboard belongs to a v2 sequence builder project; legacy endpoint not supported

```json
{ "error": "Legacy storyboard endpoints are only available for v1 projects. Use /v2/sequence workflows." }
```

**Response 500** — Internal server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Legacy /storyboard endpoints only support v1 sequence builder projects; using a v2 project returns a 409 conflict instructing you to use the /v2/sequence workflows.
- Either `storyboard_id` or `project_id` must be provided
- Media files are categorized by their role in the storyboard (videos, background_music, voiceover)
- Each media file includes storyboard-specific metadata (e.g., frame numbers, scene descriptions)
- Missing media files are skipped in the response
- The `counts` field provides a summary of media usage
- The endpoint first checks for an `edited_storyboard` and uses that if available, otherwise uses job results
- This endpoint is essential for building the media preview in your application
- Use generate_thumbnail=true for creating video thumbnails in a UI display
- Set generate_streamable=true when you need to play the media directly
- For downloading files, set generate_download=true (but be mindful of bandwidth)
- The storyboard_metadata shows how each media file is used in the storyboard
- For efficient UI rendering, keep include_analysis=false unless needed
- Use the is_stock flag to differentiate between stock media and user uploads
- This endpoint handles both edited storyboards and AI-generated storyboards
- For interactive storyboards, use this endpoint to load all media assets
- Check highlight times to show the relevant portions of each media file


---

# Voiceover API

Source: https://storylinezads.com/docs/api/voiceover
Last generated: 2026-07-20

Generate and manage voiceovers in the Storylinez application

Base route: `/voiceover` (relative to `https://api.storylinezads.com`)

## Voiceover Management

Generate and manage voiceovers based on storyboard content

### Create Voiceover

`POST https://api.storylinezads.com/create`

Generates a new voiceover based on a storyboard. Validates storyboard data and initiates a voiceover generation job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Voiceover creation job started successfully

```json
{
  "message": "Voiceover creation job started successfully",
  "voiceover": { "voiceover_id": "<id>", "project_id": "<project_id>", ... },
  "job_id": "<job_id>"
}
```

**Response 400** — Bad Request - Missing/invalid parameters or storyboard issues.

**Response 401** — Unauthorized - Invalid or missing token.

**Response 403** — Forbidden - Insufficient permissions.

**Response 404** — Not Found - Project or storyboard not found.

**Response 409** — Conflict - Voiceover already exists for project or the project is managed by the v2 audio workflow.

**Response 500** — Internal Server Error.

**Usage notes**

- Storyboard must contain valid voiceover data and not be set to 'uploaded' mode.
- If voiceover_code is omitted, the default system voice is used.
- Retrieve valid voice identifiers via GET /utility/get-voice-types before passing a voiceover_code.

### Get Voiceover

`GET https://api.storylinezads.com/get`

Retrieves an existing voiceover by voiceover_id or project_id, with options to include job results and storyboard details.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Voiceover retrieved successfully

```json
{
  "voiceover_id": "<id>", "project_id": "<project_id>", ...
}
```

**Response 400** — Bad Request - Missing required parameters.

**Response 401** — Unauthorized - Invalid or missing token.

**Response 403** — Forbidden - Insufficient permissions.

**Response 404** — Not Found - Voiceover not found.

**Response 500** — Internal Server Error.

**Response 502** — Bad Gateway - Error connecting to build server.

**Usage notes**

- Either voiceover_id or project_id must be provided in the query parameters.

### Redo Voiceover

`POST https://api.storylinezads.com/redo`

Regenerates an existing voiceover using the latest storyboard data. An optional new voiceover_code can be provided.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Voiceover regeneration job started successfully

```json
{
  "message": "Voiceover regeneration job started successfully",
  "voiceover_id": "<id>",
  "job_id": "<job_id>"
}
```

**Response 400** — Bad Request - Missing required fields or storyboard generation incomplete.

**Response 401** — Unauthorized - Invalid or missing token.

**Response 403** — Forbidden - Insufficient permissions.

**Response 404** — Not Found - Associated voiceover or storyboard not found.

**Response 409** — Conflict - Project is managed by the v2 audio workflow and cannot use legacy voiceover regeneration.

**Response 500** — Internal Server Error.

**Response 502** — Bad Gateway - Error connecting to build server.

**Usage notes**

- Either voiceover_id or project_id must be provided.
- Storyboard generation must be complete for regeneration.
- Use GET /utility/get-voice-types to confirm replacement voice identifiers before sending voiceover_code overrides.

### Self-Update Voiceover

`PUT https://api.storylinezads.com/selfupdate`

Updates the voiceover document with the latest storyboard data without triggering a new generation job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Voiceover data updated successfully with latest storyboard information

```json
{
  "message": "Voiceover data updated successfully with latest storyboard information",
  "voiceover_id": "<voiceover_id>",
  "storyboard_id": "<storyboard_id>",
  "note": "To regenerate the voiceover with this data, use the /redo endpoint"
}
```

**Response 400** — Bad Request - Missing required fields or incomplete storyboard generation.

**Response 401** — Unauthorized - Invalid or missing token.

**Response 403** — Forbidden - Insufficient permissions.

**Response 404** — Not Found - Voiceover or associated storyboard not found.

**Response 409** — Conflict - Project is managed by the v2 audio workflow and cannot use legacy voiceover updates.

**Response 500** — Internal Server Error.

**Response 502** — Bad Gateway - Error connecting to build server.

**Usage notes**

- Updates the voiceover document without starting a new generation job.

## Voiceover History

View and manage voiceover generation history

### Get Voiceover History

`GET https://api.storylinezads.com/history`

Retrieves the job history for a voiceover with pagination support.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Voiceover history retrieved successfully

```json
{
  "voiceover_id": "<id>",
  "total_history": 25,
  "page": 1,
  "limit": 10,
  "jobs": [
    {
      "job_id": "<job_id>",
      "job": { "status": "COMPLETED", "created_at": "<datetime>", "updated_at": "<datetime>", "results": { ... } }
    }
  ]
}
```

**Response 400** — Bad Request - Missing required parameters.

**Response 401** — Unauthorized - Invalid or missing token.

**Response 403** — Forbidden - Insufficient permissions.

**Response 404** — Not Found - Voiceover not found.

**Response 500** — Internal Server Error.

**Usage notes**

- Voiceover history includes job IDs along with job details if available.

### Get Voiceover Generations

`GET https://api.storylinezads.com/generations`

Returns generated voiceover versions with optional streamable audio URLs.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Generation history retrieved successfully.

```json
{
  "voiceover_id": "vo_123",
  "generations": [
    {"generation_id": "gen_1", "is_current": true, "audio_url": "https://..."}
  ],
  "total": 3,
  "page": 1,
  "limit": 20,
  "has_more": false
}
```

**Response 400** — Bad Request - Either voiceover_id or project_id is required.

**Response 403** — Forbidden - Insufficient permissions.

**Response 404** — Not Found - Voiceover not found.

**Response 500** — Internal Server Error.

**Usage notes**

- Each generation represents a distinct previously generated audio file.
- Use switch-generation to make a historical generation active without regenerating.

### Switch Voiceover Generation

`POST https://api.storylinezads.com/switch-generation`

Switches the active voiceover audio to a previous generation.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Generation switched successfully.

```json
{
  "voiceover_id": "vo_123",
  "switched_to": {"generation_id": "gen_2"},
  "audio_url": "https://...",
  "message": "Voiceover generation switched successfully"
}
```

**Response 400** — Bad Request - generation_id missing or no voiceover/project selector provided.

**Response 403** — Forbidden - Insufficient permissions.

**Response 404** — Not Found - Voiceover or generation not found.

**Response 500** — Internal Server Error.

**Usage notes**

- Switching generation does not run a new TTS job.
- Downstream sequence/render artifacts may be marked outdated after switching.


---

# Sequence API

Source: https://storylinezads.com/docs/api/sequence
Last generated: 2026-07-20

Manage video sequences, including creation, retrieval, modification, and regeneration. Sequences represent the final step in the video generation pipeline before rendering.

Base route: `/sequence` (relative to `https://api.storylinezads.com`)

## Sequence Creation

Create and generate new sequences from storyboards and voiceovers

### Create Sequence

`POST https://api.storylinezads.com/create`

Creates a new sequence from an existing project's storyboard and optional voiceover.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Sequence creation job started successfully

```json
{
  "message": "Sequence creation job started successfully",
  "sequence": {
    "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
    "project_id": "8f7e6d5c-4b3a-2d1c-0e9f-8g7h6i5j4k3l",
    "org_id": "org123",
    "storyboard_id": "story456",
    "job_id": "job_abc123",
    "created_by": "user123",
    "created_at": "2023-05-15T14:30:45.123Z",
    "updated_at": "2023-05-15T14:30:45.123Z",
    "apply_template": true,
    "apply_grade": true,
    "grade_type": "multi",
    "orientation": "landscape",
    "deepthink": true,
    "overdrive": false,
    "web_search": false,
    "eco": false,
    "temperature": 0.8,
    "iterations": 1,
    "edited_sequence": null,
    "cascade_outdated": false
  },
  "job_id": "job_abc123"
}
```

**Response 400** — Bad Request - Missing parameters or storyboard processing incomplete

```json
{ "error": "Storyboard has not been processed yet." }
```

**Response 401** — Unauthorized - Invalid or missing token

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Project or storyboard not found

```json
{ "error": "Project not found" }
```

**Response 409** — Conflict - Sequence already exists for this project

```json
{ "error": "A sequence already exists for this project. Use update endpoint instead." }
```

**Response 500** — Internal server error or connection to build server failed

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- The project must have a completed storyboard before creating a sequence
- During creation, sequences store a complete copy of all necessary storyboard data for independence
- If a voiceover exists for the project and is complete, it will be included automatically
- A project can only have one sequence; for additional versions use the /redo endpoint
- The sequence creation process is asynchronous and returns a job_id for tracking
- AI parameters (deepthink, overdrive, web_search, eco, temperature) will be inherited from the storyboard if not explicitly provided
- Override the default provider by specifying engine or model_override; invalid aliases return a 400 with the allowed options
- Eco mode intentionally blocks power-hungry model overrides. Disable eco or choose an eco-safe model if you encounter a conflict
- Use enable_content_analysis=false to generate with a clean slate when you do not want storyboard context blending
- The grade_type parameter determines how color grading is applied - 'single' applies one grade to all clips, while 'multi' can vary grades
- Orientation determines the aspect ratio of the final video: landscape (16:9), portrait (9:16), or square (1:1)
- Use deepthink=true for more thoughtful AI reasoning when generating complex sequences
- Set web_search=true if you want the AI to gather additional context from online sources
- Lower temperature values (0.1-0.5) produce more conservative sequences, while higher values (0.6-1.0) create more creative variations

### Redo Sequence

`POST https://api.storylinezads.com/redo`

Regenerates an existing sequence with current project data or optional new parameters.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Sequence regeneration job started successfully

```json
{
  "message": "Sequence regeneration job started successfully",
  "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "job_id": "job_def456"
}
```

**Response 400** — Bad Request - Missing required parameters

```json
{ "error": "Either sequence_id or project_id is required" }
```

**Response 401** — Unauthorized - Invalid or missing token

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Sequence not found

```json
{ "error": "Sequence not found" }
```

**Response 500** — Internal server error

```json
{ "error": "An internal server error occurred" }
```

**Response 502** — Error connecting to build server

```json
{ "error": "Error connecting to build server" }
```

**Usage notes**

- The sequence will be regenerated using its own stored storyboard data, not fresh storyboard data
- This independence from storyboard changes ensures consistency and predictability in regeneration
- All existing AI parameters and rendering settings will be preserved from the original sequence
- Use regenerate_prompt to provide specific guidance on how to improve the sequence
- You can override any stored regenerate_prompt by providing a new one in the request
- Example prompts: "Make transitions smoother", "Focus more on product close-ups", "Create a more dramatic feel"
- When include_history=true (default), previous generations and prompts are provided to the AI as context
- Including history helps the AI understand what has already been tried and what changes are desired
- The current sequence data is automatically saved to history before regeneration
- After regeneration, edited_sequence and regenerate_prompt fields are cleared
- If you've made manual edits to the sequence, those will be considered during regeneration
- This endpoint is useful when you want to refine a sequence without changing the underlying storyboard
- Override engine or model aliases when you need to switch providers without recreating the sequence. Invalid aliases return a 400 with allowed values
- When eco mode is enabled on the sequence, custom model overrides are rejected to prevent conflicting settings
- Use enable_content_analysis=false to force a minimal context build if you want a clean-room regeneration
- For updating with the latest storyboard changes, use /selfupdate before /redo

## Sequence Retrieval

Retrieve sequence information, history, and related media details

### Get Sequence

`GET https://api.storylinezads.com/get`

Retrieves sequence information including optional job results.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Sequence retrieved successfully

```json
{
  "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "project_id": "8f7e6d5c-4b3a-2d1c-0e9f-8g7h6i5j4k3l",
  "org_id": "org123",
  "storyboard_id": "story456",
  "voiceover_id": "voice789",
  "job_id": "job_abc123",
  "created_by": "user123",
  "created_at": "2023-05-15T14:30:45.123Z",
  "updated_at": "2023-05-15T14:35:12.456Z",
  "apply_template": true,
  "apply_grade": true,
  "grade_type": "multi",
  "orientation": "landscape",
  "deepthink": true,
  "overdrive": false,
  "web_search": false,
  "eco": false,
  "temperature": 0.8,
  "iterations": 1,
  "is_stale": false,
  "cascade_outdated": false,
  "edited_message": "This sequence has been edited. The edited version is the latest version and will be used for video generation.",
  "edited_sequence": { ... },
  "old_job_result": { ... }
}
```

**Response 400** — Bad Request - Missing parameters

```json
{ "error": "Either sequence_id or project_id is required" }
```

**Response 401** — Unauthorized - Invalid or missing token

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Sequence not found

```json
{ "error": "Sequence not found" }
```

**Response 500** — Internal server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Use either sequence_id or project_id to identify which sequence to retrieve
- Setting include_results=true fetches the job results directly from MongoDB (recommended for most cases)
- Setting include_storyboard=true includes the full storyboard data, which can be large but useful for debugging
- The is_stale flag indicates whether the sequence is out of sync with its storyboard or needs regeneration
- The cascade_outdated flag indicates whether upstream components (storyboard or voiceover) have been changed
- When edited_sequence is present, it takes precedence over old_job_result and will be used for video generation
- The edited_message field will explain if edits have been made to the original generation
- Use this endpoint to check the status of a sequence before attempting further operations
- Check if is_stale=true to know if you should regenerate the sequence with /redo
- If cascade_outdated=true, consider using /selfupdate followed by /redo for best results
- Either sequence_id or project_id must be provided
- By default, large media details are excluded to reduce response size and improve performance
- Use include_media=true when you need the full media data (significantly increases response size)
- Use include_storyboard=true when you need the complete storyboard data in the response
- The include_results parameter controls whether job results are included (defaults to true for backward compatibility)
- If edited_sequence exists, an edited_message will be included to indicate this is the latest version
- Job results are returned as old_job_result to indicate they may not reflect the latest edits
- For mobile apps or bandwidth-constrained environments, keep include_media and include_storyboard as false
- When debugging, you may want to use include_media=true to see all data
- The API optimizes response size while maintaining backward compatibility

### Get Sequence History

`GET https://api.storylinezads.com/history`

Retrieves the history of changes and regenerations for a sequence.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Sequence history retrieved successfully

```json
{
  "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "total_history": 15,
  "page": 1,
  "limit": 10,
  "current": {
    "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
    "history_type": "current",
    "timestamp": "2023-05-16T10:30:45.123Z",
    "sequence_data": { ... }
  },
  "history": [
    {
      "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
      "history_type": "generation",
      "timestamp": "2023-05-15T15:30:45.123Z",
      "sequence_data": { ... },
      "user_id": "user123"
    },
    {
      "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
      "history_type": "prompt",
      "timestamp": "2023-05-15T15:25:12.456Z",
      "prompt_text": "Make the transitions between scenes smoother",
      "user_id": "user123"
    }
  ]
}
```

**Response 400** — Bad Request - Missing parameters

```json
{ "error": "sequence_id is required" }
```

**Response 401** — Unauthorized - Invalid or missing token

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Sequence not found

```json
{ "error": "Sequence not found" }
```

**Response 500** — Internal server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- History entries are returned in reverse chronological order (newest first)
- The history_type parameter can filter by specific types of history entries:
- - generation: Complete sequence generation results from jobs
- - update: Changes made through the /update endpoint
- - prompt: Regeneration prompts that were provided during /redo
- - selfupdate: Updates from storyboard/voiceover changes
- - media_change: Records of media file replacements
- Include include_current=true to see the current sequence data alongside historical entries
- Compare different history entries to understand how the sequence has evolved over time
- Use pagination with page and limit parameters to navigate through large history collections
- History is used to provide context for future regenerations when include_history=true in /redo
- The user_id field in history entries helps track which team member made specific changes
- Use this endpoint to review previous iterations before deciding on further modifications

### Get Media Involved in Sequence

`GET https://api.storylinezads.com/media_involved`

Retrieves detailed information about media files used in the sequence.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Media involved in sequence retrieved successfully

```json
{
  "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "project_id": "8f7e6d5c-4b3a-2d1c-0e9f-8g7h6i5j4k3l",
  "media": {
    "clips": [
      {
        "file_id": "file123",
        "path": "path/to/video/file.mp4",
        "type": "video",
        "thumbnail_url": "https://example.com/thumbnails/file123.jpg",
        "streamable_url": "https://example.com/videos/file123/stream",
        "download_url": "https://example.com/videos/file123/download",
        "sequence_metadata": {
          "clip_index": 0,
          "in": 2.5,
          "out": 15.0,
          "transition_in": "fade"
        }
      }
    ],
    "audios": [
      {
        "file_id": "file456",
        "path": "path/to/audio/file.mp3",
        "type": "audio",
        "streamable_url": "https://example.com/audio/file456/stream",
        "download_url": "https://example.com/audio/file456/download",
        "sequence_metadata": {
          "track_index": 0,
          "in": 0.0,
          "out": 20.0,
          "transition_in": "fade"
        }
      }
    ],
    "voiceover": {
      "file_id": "file789",
      "path": "path/to/voiceover/file.wav",
      "type": "audio",
      "is_voiceover": true,
      "streamable_url": "https://example.com/audio/file789/stream",
      "download_url": "https://example.com/audio/file789/download",
      "sequence_metadata": {
        "in": 1.0,
        "out": 25.0,
        "transition_in": "none"
      }
    }
  },
  "total_count": 3,
  "counts": {
    "clips": 1,
    "audios": 1,
    "has_voiceover": true
  }
}
```

**Response 400** — Bad Request - Missing parameters

```json
{ "error": "Either sequence_id or project_id is required" }
```

**Response 401** — Unauthorized - Invalid or missing token

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Sequence not found or no sequence results

```json
{ "error": "Sequence not found" }
```

**Response 500** — Internal server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- This endpoint provides a comprehensive inventory of all media used in the sequence
- Media files are categorized by their role: clips (video/images), audios (background tracks), and voiceover
- Each media file includes sequence-specific metadata like in/out points and transitions
- Set include_analysis=true to get detailed analysis data for each media file (larger response)
- Control URL generation with the generate_* parameters to optimize for your needs:
- - generate_thumbnail: Creates URLs for video preview thumbnails
- - generate_streamable: Creates URLs for media streaming (useful for previews)
- - generate_download: Creates URLs for downloading the original media files
- Missing or invalid media files are automatically skipped in the response
- Use this endpoint before rendering to ensure all required media is available
- The counts field provides a quick summary of how many media files are used by type
- Sequence metadata shows how each media file is used within the sequence (timing, transitions)
- This endpoint is useful for debugging missing media issues in sequences
- Combine with /edit/item or /change_media to replace missing or problematic media

## Sequence Modification

Modify and update sequence settings and data

### Update Sequence Settings

`PUT https://api.storylinezads.com/update`

Updates sequence settings and/or edited sequence data without altering underlying storyboard or voiceover data.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Sequence settings updated successfully

```json
{
  "message": "Sequence settings updated successfully",
  "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "project_id": "8f7e6d5c-4b3a-2d1c-0e9f-8g7h6i5j4k3l",
  "note": "To apply these settings, use the /redo endpoint to regenerate the sequence"
}
```

**Response 400** — Bad Request - Missing parameters or invalid sequence structure

```json
{ "error": "No settings provided to update" }
```

**Response 401** — Unauthorized - Invalid or missing token

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Sequence not found or storyboard not found

```json
{ "error": "Sequence not found" }
```

**Response 500** — Internal server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- This endpoint allows updating multiple sequence settings in a single request
- At least one setting parameter must be provided, or you'll receive a 400 error
- Changes are only saved but not applied - use /redo after updating to regenerate the sequence
- Updating apply_template and apply_grade affects how the sequence is rendered
- The edited_sequence parameter allows comprehensive manual edits to the entire sequence
- When providing edited_sequence, it must conform to the sequence schema structure
- All media paths in edited_sequence must exist in the project's media collections
- Previous sequence data is automatically saved to history before updating
- The regenerate_prompt parameter provides guidance for the next regeneration
- Persist engine or model overrides here so future /redo calls automatically use them
- Send model_override="auto" to clear any stored model and revert to default selection
- Eco mode prevents incompatible model overrides; disable eco or choose an eco-safe alias if you see a conflict error
- Set enable_content_analysis=false when you want the next regeneration to ignore historical context
- Use temperature and iterations to control AI creativity and thoroughness
- This endpoint marks the sequence as 'stale' to indicate settings have changed
- For simple edits to individual items, consider using /edit/item or /change_media instead
- Downstream components like renders will be marked as outdated when settings change

### Self Update Sequence

`PUT https://api.storylinezads.com/selfupdate`

Updates a sequence with the latest storyboard and voiceover data without starting a new job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Sequence data updated successfully

```json
{
  "message": "Sequence data updated successfully with latest information",
  "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "project_id": "8f7e6d5c-4b3a-2d1c-0e9f-8g7h6i5j4k3l",
  "note": "To regenerate the sequence with this data, use the /redo endpoint"
}
```

**Response 400** — Bad Request - Missing parameters

```json
{ "error": "Either sequence_id or project_id is required" }
```

**Response 401** — Unauthorized - Invalid or missing token

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Sequence not found

```json
{ "error": "Sequence not found" }
```

**Response 500** — Internal server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Use this endpoint when you want to explicitly update a sequence with the latest storyboard changes
- By default, sequences are independent from storyboards and won't automatically update
- The selfupdate process syncs the sequence with the latest upstream data but doesn't regenerate it
- Set update_ai_params=true (default) to also sync AI parameters from the storyboard:
- - deepthink, overdrive, web_search, eco, temperature, iterations
- Set update_ai_params=false to keep existing AI parameters unchanged
- This endpoint marks the sequence as 'stale' to indicate it needs regeneration
- No new job is created - use /redo afterward to regenerate with the updated data
- If significant changes are detected, the current sequence data is saved to history
- The system checks and updates the cascade_outdated flag based on upstream status
- Typical workflow: modify storyboard → /selfupdate sequence → /redo sequence
- This is more efficient than recreating the sequence from scratch
- This explicit update mechanism ensures sequences remain stable until you choose to update them

### Reorder Sequence Items

`PUT https://api.storylinezads.com/reorder`

Reorders items (clips or audio tracks) within a sequence.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Items reordered successfully

```json
{
  "message": "Successfully reordered clips",
  "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
}
```

**Response 400** — Bad Request - Missing parameters or invalid indices

```json
{ "error": "new_order must contain exactly 4 indices" }
```

**Response 401** — Unauthorized - Invalid or missing token

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Sequence not found

```json
{ "error": "Sequence not found" }
```

**Response 415** — Unsupported Media Type - Request must be JSON

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- This endpoint allows changing the order of clips or audio tracks without changing their content
- The array_type parameter specifies which array to reorder: either "clips" or "audios"
- The new_order array must contain all indices in the new desired order
- For example, if you have 4 clips (indices 0,1,2,3), new_order might be [2,0,1,3] to move clip 2 to the beginning
- All indices in the original array must be present in new_order without duplicates
- The new_order array must have the same length as the original array
- Reordering only changes position, not content - all properties of each item remain the same
- This operation marks the sequence as 'stale' - use /redo to regenerate after reordering
- Prior to updating, the current sequence state is saved to history
- Use this to experiment with different narrative flows by changing scene order
- For audio tracks, reordering can help with layering background music and effects
- This operation is validated against the sequence schema to ensure integrity
- If you want to change clip content rather than order, use /edit/item instead

### Edit Sequence Item

`PUT https://api.storylinezads.com/edit/item`

Edits the properties of an individual item (clip, audio track, or voiceover) in the sequence.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Sequence item edited successfully

```json
{
  "message": "Successfully edited clips at index 2",
  "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
}
```

**Response 400** — Bad Request - Missing parameters or invalid structure

```json
{ "error": "Either updated_item or file_id/stock_id is required" }
```

**Response 401** — Unauthorized - Invalid or missing token

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Sequence or item not found

```json
{ "error": "Sequence not found" }
```

**Response 415** — Unsupported Media Type - Request must be JSON

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- This endpoint allows detailed editing of individual sequence items' properties
- The item_type parameter defines which type of item to edit: "clips", "audios", or "voiceover"
- For array items (clips, audios), the item_index is required and specifies which item to edit
- For voiceover (not an array), item_index is not needed
- You must provide at least one of: updated_item, file_id, or stock_id
- The updated_item object should contain all properties you want to set, following the item schema
- If providing file_id or stock_id, the system will replace the media file while keeping other properties
- file_id refers to an uploaded file in the project's files collection
- stock_id refers to a stock media item appropriate for the item type
- For clips, you can edit properties like in/out points, transitions, templates, headings, etc.
- For audio tracks, you can edit in/out points and transitions
- For voiceover, you can replace the file or edit timing parameters
- Updates are validated against the sequence schema and available media paths
- Prior to updating, the current sequence state is saved to history
- The sequence is marked as 'stale' after editing - use /redo to apply changes
- For simply changing media files without editing other properties, consider using /change_media

### Change Sequence Media

`PUT https://api.storylinezads.com/change_media`

Changes the media file used for a specific item in the sequence without altering other properties.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Media changed successfully

```json
{
  "message": "Successfully changed media for clips at index 1",
  "sequence_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "media_path": "stock/videos/cityscape_aerial.mp4"
}
```

**Response 400** — Bad Request - Missing parameters

```json
{ "error": "One of file_id, stock_id, or path must be provided" }
```

**Response 401** — Unauthorized - Invalid or missing token

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden - User doesn't have permission

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Sequence, file, or stock media not found

```json
{ "error": "Stock media with ID stock_video_xyz123 not found" }
```

**Response 415** — Unsupported Media Type - Request must be JSON

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal server error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- This endpoint is optimized for replacing just the media file while preserving all other item properties
- It's more streamlined than /edit/item when you just need to swap media files
- The item_type parameter defines which type of item to modify: "clips", "audios", or "voiceover"
- For array items (clips, audios), the item_index specifies which item's media to change
- For voiceover (not an array), item_index is not needed
- You must provide exactly one of file_id, stock_id, or path to identify the new media
- file_id refers to an uploaded file in the project's files collection
- stock_id refers to a stock media item appropriate for the item type
- path is a direct file path that must exist in the project's media collections
- Media replacement is restricted by type to ensure compatibility:
- - clips can use video or image paths
- - audios can only use audio paths
- - voiceover can only use audio paths
- The current sequence state is saved to history with type "media_change" before updating
- The sequence is marked as 'stale' after changing media - use /redo to regenerate
- Use this for quick A/B testing of different media options in your sequence
- This is useful for replacing placeholder media with final assets without changing timing


---

# Render API

Source: https://storylinezads.com/docs/api/render
Last generated: 2026-07-20

Create, manage, and retrieve video rendering jobs in the StoryLinez platform. The Render API interacts with a dedicated render server to process video projects with customizable settings, allowing you to generate final video outputs based on your project sequences and brand configurations.

Base route: `/render` (relative to `https://api.storylinezads.com`)

## Render Creation & Restart

Endpoints for initiating new video render jobs based on project data and restarting existing render jobs, potentially with modified settings.

### Create Render Job

`POST https://api.storylinezads.com/create`

Initiates a new video rendering job for a specified project. This endpoint gathers necessary data from the project's sequence, associated brand settings, and company details, allows for overrides via the request body, and then queues the job for processing on the render server. A render record is created in the database to track this job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Render job accepted and initiated successfully.

```json
{
  "message": "Render job started successfully",
  "warning": null, // Or a warning message like "Subtitle data is empty or invalid."
  "render": {
    "render_id": "rndr_a1b2c3d4e5f6",
    "job_id": "job_789xyz123abc",
    "project_id": "proj_12345abc",
    "org_id": "org_fghij67890",
    "output_path": "userdata/a1b2c3d4e5f6.mp4",
    "created_by": "user_pqrst12345",
    "created_at": "2024-07-27T10:00:00.000Z",
    "updated_at": "2024-07-27T10:00:00.000Z",
    "orientation": "landscape",
    "target_width": 1280,
    "target_height": 720,
    "standardize_resolution_enabled": true,
    "subtitle_enabled": true,
    "color_balance_fix": true,
    "color_exposure_fix": false,
    "color_contrast_fix": false,
    "cascade_outdated": false,
    "is_stale": false,
    "company_name": "Innovate Inc.",
    "company_subtext": "Building Tomorrow's Solutions",
    "bg_music_volume": 0.08
    // ... other parameters used for this render ...
  },
  "job_id": "job_789xyz123abc"
}
```

**Response 400** — Bad Request - Missing `project_id`, invalid JSON, invalid resolution dimensions, or missing essential source data (like sequence).

```json
{ "error": "Project ID is required" }
```

**Response 401** — Unauthorized - Invalid or missing API Key/Secret.

```json
{ "error": "Authentication failed" }
```

**Response 403** — Forbidden - User does not have permission for the project's organization.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified project, sequence, brand, or company details could not be found.

```json
{ "error": "Project not found" }
```

**Response 409** — Conflict - Either a render already exists for the project or the project is a v2 sequence builder which must use the /v2 rendering workflow.

```json
{ "error": "Renders are disabled for v2 sequence builder projects via legacy endpoints. Use the /v2/render workflows instead." }
```

**Response 500** — Internal Server Error - An unexpected error occurred on the API server.

```json
{ "error": "An internal server error occurred" }
```

**Response 502** — Bad Gateway - Could not communicate with the downstream render server to initiate the job.

```json
{ "error": "Failed to connect to render service" }
```

**Usage notes**

- Legacy render endpoints only support v1 projects. Calling this endpoint with a v2 sequence builder project returns HTTP 409.
- This is the primary endpoint to start generating a video from a project.
- You only *need* to provide the `project_id`. All other parameters are optional and will default to values derived from the project's linked sequence, brand settings, and company details.
- Use the optional parameters in the request body to override specific settings for this particular render job (e.g., change the outro background color, adjust audio volumes, disable subtitles).
- The system automatically determines the correct default `target_width` and `target_height` based on the project's `orientation` (landscape or portrait) if you don't specify them.
- Resolution validation ensures `width` >= `height` for landscape and `height` > `width` for portrait, within the min (640x360) and max (7680x4320) limits.
- Color parameters (like `outro_bg_color`, `main_text_color`) expect an array of three integers `[R, G, B]`, each between 0 and 255.
- Volume parameters (`bg_music_volume`, etc.) expect a float between 0.0 (silent) and 1.0 (full volume). Values slightly above 1.0 might be accepted for amplification but use with caution.
- If the project's sequence data is missing or incomplete, the request will fail.
- A successful request (202 Accepted) means the job has been queued. It does not mean the video is ready.
- The response includes the `render_id` (unique ID for this render record) and the `job_id` (ID for the task on the render server). Use these IDs with other endpoints (`/get`, `/redo`) to track status or manage the render.
- The `render` object in the response shows the final parameters used for the job, including defaults and overrides.
- Check the `warning` field in the response for potential issues (e.g., problems with subtitle data) that didn't prevent the job from starting but might affect the output.
- Creating a render typically consumes usage quota associated with your subscription plan.
- Use advanced parameters like `extend_short_clips` and `extension_method` to control how the renderer handles clips that are shorter than the required minimum duration.
- The robustness parameters (`max_retries`, `adaptive_complexity`, `enable_emergency_mode`, etc.) can help ensure successful rendering under challenging conditions, but may affect processing time.
- Free-tier subscriptions always render with StoryLinez branding even if `include_branding_outro` or `watermark` is false.

### Redo Render Job

`POST https://api.storylinezads.com/redo`

Restarts a render job for an existing render record. This uses the settings currently stored in the render record (which might have been modified by `/update` or `/selfupdate`) and initiates a *new* job on the render server. Useful for regenerating a video after tweaking settings or if the previous attempt failed. This action counts against project usage limits.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Render job accepted and restarted successfully.

```json
{
  "message": "Render job restarted successfully",
  "render_id": "rndr_a1b2c3d4e5f6",
  "job_id": "job_new456def789ghi",
  "project_limits": {
    "period_count": 6, 
    "daily_count": 3
  }
}
```

**Response 400** — Bad Request - Missing `render_id` or `project_id`, or invalid override parameters.

```json
{ "error": "Either render_id or project_id is required" }
```

**Response 401** — Unauthorized - Invalid or missing API Key/Secret.

```json
{ "error": "Authentication failed" }
```

**Response 403** — Forbidden - User lacks permission for the organization, or has reached project rendering limits (daily or period).

```json
{ "error": "You have reached your daily rendering limit" }
```

**Response 404** — Not Found - The specified render record (`render_id` or associated with `project_id`) does not exist.

```json
{ "error": "Render not found" }
```

**Response 409** — Conflict - Legacy redo is blocked for v2 sequence builder projects; use the /v2 rendering workflow instead.

```json
{ "error": "Redo is disabled for v2 sequence builder projects. Use the /v2/render workflows instead." }
```

**Response 500** — Internal Server Error - An unexpected error occurred on the API server.

```json
{ "error": "An internal server error occurred" }
```

**Response 502** — Bad Gateway - Could not communicate with the downstream render server to initiate the job.

```json
{ "error": "Failed to connect to render service" }
```

**Usage notes**

- Legacy render endpoints only support v1 projects; attempting to redo a v2 project returns HTTP 409.
- Use this endpoint to generate a new video based on an existing render configuration.
- It's the standard way to apply changes made via `/update` or `/selfupdate`.
- You must identify the render using either its `render_id` or the associated `project_id`.
- You can provide override parameters in the request body. These overrides apply *only* to this specific redo job and do *not* permanently change the settings stored in the render record. For permanent changes, use the `/update` endpoint first.
- If you provide no overrides, the job runs with the exact settings currently stored in the identified render record.
- Each call to `/redo` initiates a completely new render task on the server and counts towards your usage limits (daily and billing period).
- The response includes the `render_id` being redone and the `job_id` of the *new* render task.
- It also returns the current state of your `project_limits` after incrementing the counts.
- If the render record was marked as `is_stale: true` (due to `/update` or `/selfupdate`), a successful `/redo` will typically reset `is_stale` to `false` on the render record.
- If the render record had `cascade_outdated: true`, redoing it ensures the latest upstream data (like sequence changes) is used, and the flag might be reset depending on the current upstream status.
- This is useful for iterating on a render: use `/update` to tweak settings, then `/redo` to see the result.

### Render History

`GET https://api.storylinezads.com/history`

Lists archived outputs from prior /redo calls, with optional temporary links for replaying older renders.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — History fetched successfully.

```json
{
  "total": 3,
  "page": 1,
  "limit": 10,
  "items": [
    {
      "render_id": "rndr_a1b2c3",
      "output_path": "userdata/past.mp4",
      "archived_at": "2024-08-01T12:00:00Z",
      "resolution": "1920x1080",
      "streamable_url": "https://..."
    }
  ]
}
```

**Response 400** — Bad Request - Missing identifiers or invalid pagination.

**Response 401** — Unauthorized.

**Response 403** — Forbidden - User lacks organization access.

**Response 404** — Not Found - Render record or project missing.

**Response 500** — Internal Server Error - Failed to retrieve history.

**Usage notes**

- Use this endpoint to surface past render outputs before a redo overwrote the main record.
- Archived entries store the S3 keys for prior outputs along with optional thumbnails and subtitle paths.
- Set the link generation flags to false if you only need metadata without generating temporary URLs.
- The response always includes pagination metadata (`total`, `page`, `limit`).
- Links expire after roughly one hour; call the endpoint again to refresh them if required.

## Render Information & Management

Endpoints for retrieving details about render jobs, checking their status, accessing generated media, and modifying render settings without initiating a new render.

### Get Render Information

`GET https://api.storylinezads.com/get`

Retrieves detailed information about a specific render job, including its configuration, status, results from the render server, and optionally generates temporary links to access the output video, thumbnail, and subtitles.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Render information retrieved successfully.

```json
{
  "render_id": "rndr_a1b2c3d4e5f6",
  "job_id": "job_789xyz123abc",
  "project_id": "proj_12345abc",
  "org_id": "org_fghij67890",
  "output_path": "userdata/a1b2c3d4e5f6.mp4", // S3 key
  "created_at": "2024-07-27T10:00:00.000Z",
  "updated_at": "2024-07-27T10:15:00.000Z",
  "orientation": "landscape",
  "company_name": "Innovate Inc.",
  "company_subtext": "Building Tomorrow's Solutions",
  "is_stale": false, // True if settings updated via /update but not re-rendered
  "cascade_outdated": false, // True if upstream data (sequence) changed after this render started
  // ... other parameters stored in the render document ...
  
  // Present if include_results=true and job_id exists
  "job_result": {
    "status": "COMPLETED", // or "PENDING", "PROCESSING", "FAILED"
    "results": { // Present only if status is COMPLETED
      "total_duration": 45.8,
      "actual_end_time": 42.5,
      "thumbnail_path": "thumbnails/a1b2c3d4e5f6.jpg", // S3 key
      "srt_path": "subtitles/a1b2c3d4e5f6.srt" // S3 key
    },
    "error": null, // Error message if status is FAILED
    "created_at": "2024-07-27T10:00:05.000Z", // Job creation time on render server
    "updated_at": "2024-07-27T10:14:55.000Z" // Job last update time on render server
  },
  
  // Present if generate_download_link=true and job is completed
  "download_url": "https://s3-signed-url-for-video-download...",
  "download_expires_in": 3600, // Seconds until URL expires
  
  // Present if generate_streamable_link=true and job is completed
  "streamable_url": "https://s3-signed-url-for-video-streaming...",
  "streamable_expires_in": 3600,
  
  // Present if generate_thumbnail_stream_link=true and job is completed and thumbnail exists
  "thumbnail_streamable_url": "https://s3-signed-url-for-thumbnail...",
  "thumbnail_streamable_expires_in": 3600,
  
  // Present if generate_download_link=true and job is completed and SRT file exists
  "srt_download_url": "https://s3-signed-url-for-srt-download...",
  "srt_download_expires_in": 3600,
  
  // Present if include_sequence=true
  "sequence": { /* Large sequence data object used for this render */ },
  
  // Present if include_subtitles=true
  "subtitles": { /* Subtitle data object used for this render */ }
}
```

**Response 400** — Bad Request - Missing `render_id` or `project_id`.

```json
{ "error": "Either render_id or project_id is required" }
```

**Response 401** — Unauthorized - Invalid or missing API Key/Secret.

```json
{ "error": "Authentication failed" }
```

**Response 403** — Forbidden - User does not have permission for the organization associated with this render.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified render record (`render_id` or associated with `project_id`) does not exist.

```json
{ "error": "Render not found" }
```

**Response 500** — Internal Server Error - An unexpected error occurred on the API server.

```json
{ "error": "An internal server error occurred" }
```

**Response 502** — Bad Gateway - Error communicating with the render server when `include_results=true`.

```json
{ "error": "Failed to fetch job results from render service" }
```

**Usage notes**

- This is the main endpoint to check the status and retrieve details of a render job.
- Identify the render using either its unique `render_id` or the associated `project_id`.
- By default (`include_results=true`), the API contacts the render server to get the latest job status (`PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`) and any results (like video duration, thumbnail path). Set `include_results=false` to skip this check and only get data stored in the API's database.
- If the job status is `COMPLETED`, the `job_result.results` object will contain details about the output.
- If the status is `FAILED`, the `job_result.error` field will contain an error message from the render server.
- Use the `generate_..._link` flags to obtain temporary, secure S3 URLs for accessing the generated files. These URLs typically expire after 1 hour (3600 seconds). Links are only generated if the job status is `COMPLETED` and the respective file exists.
- The `download_url` is for downloading the main video file.
- The `streamable_url` is suitable for embedding in web players.
- The `thumbnail_streamable_url` provides access to the preview image.
- The `srt_download_url` provides access to the subtitle file.
- The `is_stale` flag indicates whether the render's settings have been modified (via `/update` or `/selfupdate`) since the last time a render job was successfully started (`/create` or `/redo`). If `true`, the current settings might not match the last generated video file.
- The `cascade_outdated` flag indicates whether an upstream component (like the project's sequence) was potentially updated *after* this render job was initiated. If `true`, you might want to use `/redo` to incorporate the latest upstream changes.
- Set `include_sequence=true` or `include_subtitles=true` only if you specifically need the large data objects used for the render; omitting them keeps the response much smaller and faster.

### Update Render Settings

`PUT https://api.storylinezads.com/update`

Modifies specific settings stored within a render record *without* starting a new render job. This allows you to change parameters like colors, fonts, volumes, etc., directly. After updating, the render is marked as 'stale' (`is_stale: true`), indicating that a `/redo` is needed to apply these changes to a generated video.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Render settings updated successfully in the database.

```json
{
  "message": "Render settings updated successfully",
  "render_id": "rndr_a1b2c3d4e5f6",
  "project_id": "proj_12345abc",
  "note": "To apply these settings, use the /redo endpoint to regenerate the render"
}
```

**Response 400** — Bad Request - Missing `render_id` or `project_id`, no settings provided in the body, or invalid values for settings (e.g., invalid resolution).

```json
{ "error": "At least one setting must be provided to update" }
```

**Response 401** — Unauthorized - Invalid or missing API Key/Secret.

```json
{ "error": "Authentication failed" }
```

**Response 403** — Forbidden - User does not have permission for the organization associated with this render.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified render record (`render_id` or associated with `project_id`) does not exist.

```json
{ "error": "Render not found" }
```

**Response 500** — Internal Server Error - An unexpected error occurred while updating the database.

```json
{ "error": "Database update failed" }
```

**Usage notes**

- This endpoint allows you to modify the configuration of a render *after* it has been created, without immediately starting a new render process.
- It directly updates the specified fields in the render record stored in the database.
- You must identify the render using either `render_id` or `project_id`.
- You must include at least one valid setting parameter in the request body to perform an update.
- Any parameter *not* included in your request body will retain its current value in the render record.
- Successfully updating settings will mark the render record as 'stale' (`is_stale: true`). This flag signals that the stored settings may no longer match the last generated video file.
- To actually generate a video using these updated settings, you *must* subsequently call the `/redo` endpoint.
- This is useful for fine-tuning parameters iteratively. You can call `/update` multiple times to change different settings, and then call `/redo` once to generate the video with all the accumulated changes.
- If you update `target_width` or `target_height`, the values will be validated against the project's orientation and resolution limits, just like in `/create`.
- This endpoint does *not* fetch data from upstream sources (like brand settings or company details). Use `/selfupdate` for that purpose.
- This operation does not consume rendering quota.

### Self-Update Render from Sources

`PUT https://api.storylinezads.com/selfupdate`

Refreshes the data within a render record by fetching the latest values from its upstream sources (e.g., project details, sequence data, brand settings, company details) *without* starting a new render job. This is useful for ensuring the render configuration reflects recent changes in related entities. Marks the render as 'stale' (`is_stale: true`).

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Render data refreshed successfully from sources.

```json
{
  "message": "Render data updated successfully with latest information",
  "render_id": "rndr_a1b2c3d4e5f6",
  "project_id": "proj_12345abc",
  "note": "To regenerate the render with this data, use the /redo endpoint"
}
```

**Response 400** — Bad Request - Missing `render_id` or `project_id`.

```json
{ "error": "Either render_id or project_id is required" }
```

**Response 401** — Unauthorized - Invalid or missing API Key/Secret.

```json
{ "error": "Authentication failed" }
```

**Response 403** — Forbidden - User does not have permission for the organization associated with this render.

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - The specified render record, or its associated project, sequence, brand, or company details could not be found.

```json
{ "error": "Render not found" }
```

**Response 500** — Internal Server Error - An unexpected error occurred while fetching source data or updating the database.

```json
{ "error": "Failed to fetch brand settings" }
```

**Usage notes**

- Use this endpoint when you have made changes to related entities (like updating your company's tagline in Company Details, changing default Brand Settings, or updating the project's Sequence) and want an existing render configuration to reflect those changes.
- It fetches the latest data from these sources and updates the corresponding fields in the specified render record.
- This operation does *not* start a new render job.
- Like `/update`, it marks the render as 'stale' (`is_stale: true`) because the stored settings have changed.
- You must call `/redo` afterwards to generate a video incorporating these refreshed settings.
- You can optionally provide a `fields_to_update` array to limit the refresh to specific parameters. If omitted, all parameters that are normally sourced from project/sequence/brand/company details will be refreshed.
- This endpoint also updates the `cascade_outdated` flag based on the current status of the upstream sequence.
- This is different from `/update`, which allows you to set arbitrary values directly, whereas `/selfupdate` specifically pulls values from the linked source entities.
- This operation does not consume rendering quota.


---

# Settings API

Source: https://storylinezads.com/docs/api/settings
Last generated: 2026-07-20

Manage user settings and temporary job storage for the Storylinez application, including AI parameters, link preferences, and UI preferences.

Base route: `/settings` (relative to `https://api.storylinezads.com`)

## User Settings

Manage user-specific application settings, including AI parameters, link preferences, and UI customization options.

### Get Settings

`GET https://api.storylinezads.com/get`

Retrieves all settings for the authenticated user. If no settings exist, returns default values for all settings categories.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Settings retrieved successfully

```json
{
  "ai_params": {
    "eco": false,
    "deepthink": false,
    "temperature": 0.7,
    "iterations": 3,
    "web_search": false,
    "overdrive": false
  },
  "link_preferences": {
    "generate_thumbnail": true,
    "generate_streamable": false,
    "generate_download": false,
    "detail": false
  },
  "ui_preferences": {
    "dark_mode": false,
    "default_view": "grid",
    "language": "en",
    "current_org_id": null,
    "last_project_id": null,
    "current_tab": ""
  },
  "user_id": "user_id_value",
  "last_updated": "2023-11-01T12:34:56.789Z"
}
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An unexpected error occurred" }
```

**Usage notes**

- This is typically the first endpoint called when initializing application settings.
- All returned values can be safely used without additional validation.
- Settings are personalized per user, not per organization.
- Use this endpoint to initialize application state on user login or page refresh.

### Save Settings

`POST https://api.storylinezads.com/save`

Saves all settings for the authenticated user. Replaces entire settings objects with the provided values, filling in any missing fields with default values.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Settings saved successfully

```json
{
  "message": "Settings saved successfully",
  "settings": {
    "ai_params": {
      "eco": false,
      "deepthink": true,
      "temperature": 0.8,
      "iterations": 4,
      "web_search": true,
      "overdrive": false
    },
    "link_preferences": {
      "generate_thumbnail": true,
      "generate_streamable": true,
      "generate_download": false,
      "detail": true
    },
    "ui_preferences": {
      "dark_mode": true,
      "default_view": "list",
      "language": "fr",
      "current_org_id": "org_12345",
      "last_project_id": "project_67890",
      "current_tab": "search"
    },
    "user_id": "user_id_value",
    "last_updated": "2023-11-01T12:34:56.789Z"
  }
}
```

**Response 400** — Bad Request - Invalid parameters

```json
{ "error": "Temperature must be between 0 and 1" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found" }
```

**Response 415** — Unsupported Media Type

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An unexpected error occurred" }
```

**Usage notes**

- Use this endpoint when you need to replace all settings at once.
- Any omitted settings category will use the default values.
- All fields within a provided category will be merged with defaults.
- Consider using the /update endpoint when you only need to change specific settings.
- The temperature parameter affects AI randomness: higher values (closer to 1.0) yield more creative but potentially less accurate results.
- The iterations parameter controls how many passes the AI makes during analysis: higher values may improve quality but increase processing time and resource usage.
- The eco mode reduces resource consumption but may decrease result quality.
- The deepthink mode enhances result quality but increases resource usage.

### Update Settings

`PUT https://api.storylinezads.com/update`

Partially updates specific settings categories for the authenticated user. Only the provided fields will be modified.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Settings updated successfully

```json
{
  "message": "Settings updated successfully",
  "updated_fields": ["ai_params", "ui_preferences"],
  "settings": {
    "ai_params": {
      "eco": false,
      "deepthink": false,
      "temperature": 0.8,
      "iterations": 5,
      "web_search": false,
      "overdrive": false
    },
    "link_preferences": {
      "generate_thumbnail": true,
      "generate_streamable": false,
      "generate_download": false,
      "detail": false
    },
    "ui_preferences": {
      "dark_mode": true,
      "default_view": "grid",
      "language": "en",
      "current_org_id": null,
      "last_project_id": null,
      "current_tab": "search"
    },
    "user_id": "user_id_value",
    "last_updated": "2023-11-01T12:34:56.789Z"
  }
}
```

**Response 400** — Bad Request - Invalid parameters

```json
{ "error": "Temperature must be between 0 and 1" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found" }
```

**Response 415** — Unsupported Media Type

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An unexpected error occurred" }
```

**Usage notes**

- This endpoint is ideal for making targeted updates to specific settings.
- Only the specified fields within each category will be changed; others remain unchanged.
- If a user has no existing settings, default values will be used and then updated with your changes.
- Categories not included in the request body will remain completely untouched.
- The response includes the complete updated settings object for convenience.
- Use this endpoint when changing just one setting to reduce payload size and processing.
- For tracking UI state across sessions, update the current_tab and last_project_id fields.

### Reset Settings

`POST https://api.storylinezads.com/reset`

Resets all or specific settings categories to their default values for the authenticated user.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Settings reset successfully

```json
{
  "message": "Settings category \"ai_params\" reset to default",
  "settings": {
    "ai_params": {
      "eco": false,
      "deepthink": false,
      "temperature": 0.7,
      "iterations": 3,
      "web_search": false,
      "overdrive": false
    },
    "link_preferences": {
      "generate_thumbnail": true,
      "generate_streamable": true,
      "generate_download": false,
      "detail": true
    },
    "ui_preferences": {
      "dark_mode": true,
      "default_view": "list",
      "language": "fr",
      "current_org_id": "org_12345",
      "last_project_id": "project_67890",
      "current_tab": "search"
    },
    "user_id": "user_id_value",
    "last_updated": "2023-11-01T12:34:56.789Z"
  }
}
```

**Response 400** — Bad Request - Invalid category

```json
{ "error": "Invalid category. Must be one of: all, ai_params, link_preferences, ui_preferences" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An unexpected error occurred" }
```

**Usage notes**

- If no category is specified, all settings will be reset to default values.
- This endpoint is useful for troubleshooting when user settings may be causing issues.
- Consider adding a "Reset to Default" option in your settings UI for each category.
- After resetting, you may want to refresh your application state with the new default values.
- For new users, this endpoint has the same effect as never having set any preferences.
- The response includes the complete updated settings object after the reset operation.

### Update Theme

`PUT https://api.storylinezads.com/theme`

Updates the UI theme preference (specifically the dark mode setting) for the authenticated user. This is a convenience shortcut endpoint.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Theme updated successfully

```json
{
  "message": "Theme updated successfully",
  "dark_mode": true
}
```

**Response 400** — Bad Request - Missing or invalid parameter

```json
{ "error": "dark_mode parameter is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found" }
```

**Response 415** — Unsupported Media Type

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An unexpected error occurred" }
```

**Usage notes**

- This is a convenience endpoint specifically for updating just the dark mode setting.
- Useful for implementing a theme toggle switch in your application.
- More efficient than using the general update endpoint when only changing theme.
- The change takes effect immediately and persists across user sessions.
- Consider detecting user's system theme preference for initial setup.
- This endpoint updates only the dark_mode setting; other UI preferences remain unchanged.

### Update AI Defaults

`PUT https://api.storylinezads.com/ai-defaults`

Updates the default AI parameters for the authenticated user. This is a convenience shortcut endpoint.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — AI default parameters updated successfully

```json
{
  "message": "AI default parameters updated successfully",
  "ai_params": {
    "eco": true,
    "deepthink": false,
    "temperature": 0.9,
    "iterations": 4,
    "web_search": true,
    "overdrive": false
  }
}
```

**Response 400** — Bad Request - Invalid parameters

```json
{ "error": "Temperature must be between 0 and 1" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found" }
```

**Response 415** — Unsupported Media Type

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An unexpected error occurred" }
```

**Usage notes**

- This is a convenience endpoint for updating just the AI parameters.
- At least one AI parameter must be provided in the request.
- Only the specified parameters will be updated; others remain unchanged.
- Useful for implementing AI parameter presets in your application.
- Consider using this endpoint when users adjust AI settings before processing content.
- The eco and deepthink modes are mutually exclusive in practice - enabling one typically disables the other.
- Higher temperature values (closer to 1.0) produce more creative but potentially less focused results.
- The web_search option enables AI to incorporate internet information when processing content.

### Get Email Preferences

`GET https://api.storylinezads.com/email-preferences`

Get the authenticated user's email notification preferences.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Email preferences fetched successfully.

```json
{
  "email_preferences": {
    "marketing_emails": false,
    "product_updates": true,
    "usage_alerts": true
  }
}
```

**Response 401** — Unauthorized.

**Response 500** — Internal Server Error.

**Usage notes**

- Use this endpoint to hydrate notification settings UIs.
- If no preferences were explicitly saved yet, server defaults are returned.

### Save Email Preferences

`POST https://api.storylinezads.com/email-preferences`

Create or update email notification preferences for the authenticated user.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Email preferences saved successfully.

```json
{
  "message": "Email preferences updated",
  "email_preferences": {
    "marketing_emails": false,
    "product_updates": true,
    "usage_alerts": true
  }
}
```

**Response 400** — Bad Request - Invalid preferences payload.

**Response 401** — Unauthorized.

**Response 500** — Internal Server Error.

**Usage notes**

- Send only keys you want to update; omitted keys retain existing values.
- Use this endpoint when users toggle notification checkboxes in account settings.

## Job Management

Manage temporary job entries for tracking tasks and processes in the system.

### Add Job

`POST https://api.storylinezads.com/jobs/add`

Adds a new temporary job entry to the system for tracking asynchronous processes. The system maintains a limited history of jobs per organization and job type.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 201** — Job added successfully

```json
{
  "message": "Job added successfully",
  "entry_id": "507f1f77bcf86cd799439011",
  "job_id": "job_12345",
  "job_type": "query_generation"
}
```

**Response 400** — Bad Request - Missing or invalid parameters

```json
{ "error": "job_id, org_id, and job_type are required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - Organization access denied

```json
{ "error": "User does not have permission for this organization" }
```

**Response 415** — Unsupported Media Type

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An unexpected error occurred" }
```

**Usage notes**

- Jobs are automatically managed with a limited history per organization and job type.
- When the history limit is reached, the oldest job of the same type is removed.
- Job entries persist until manually deleted or automatically pruned.
- The job_id should be generated client-side and must be unique for tracking.
- Use the metadata object to store job-specific information needed for tracking or display.
- For query_generation jobs, include the original query and context in metadata.
- For search_recommendations jobs, include source document IDs or search parameters.
- The job entry created by this endpoint doesn't contain results - use fetch_results to get outcomes.
- Typically used in conjunction with the fetch_results endpoint to track async processes.

### List Jobs

`GET https://api.storylinezads.com/jobs/list`

Retrieves a paginated list of temporary job entries for the authenticated user and specified organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Jobs retrieved successfully

```json
{
  "jobs": [
    {
      "job_id": "job_12345",
      "user_id": "user_id_value",
      "org_id": "org_67890",
      "job_type": "query_generation",
      "created_at": "2023-11-01T12:34:56.789Z",
      "metadata": {
        "query": "marketing strategy presentation",
        "timestamp": "2023-11-01T12:34:56.789Z"
      },
      "project_id": "project_abcde"
    },
    {
      "job_id": "job_23456",
      "user_id": "user_id_value",
      "org_id": "org_67890",
      "job_type": "search_recommendations",
      "created_at": "2023-11-01T10:20:30.456Z",
      "metadata": {
        "source_id": "doc_12345"
      },
      "project_id": "project_abcde"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 10,
  "total_pages": 5
}
```

**Response 400** — Bad Request - Missing or invalid parameters

```json
{ "error": "org_id is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - Organization access denied

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An unexpected error occurred" }
```

**Usage notes**

- Use filters to narrow down results by project_id or job_type.
- The response is paginated - use page and limit parameters to navigate through results.
- Results are sorted by created_at timestamp by default (newest first).
- Jobs are only visible to users with access to the specified organization.
- The total field indicates the total number of jobs matching your filters.
- Use this endpoint to display job history or check status of recent operations.
- To get actual job results, use the job_id with the fetch_results endpoint.
- For a continuous polling pattern, track most recent job_id and query only newer entries.

### Delete Job

`DELETE https://api.storylinezads.com/jobs/delete`

Deletes a temporary job entry identified by job_id and organization.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Job deleted successfully

```json
{
  "message": "Job deleted successfully",
  "job_id": "job_12345"
}
```

**Response 400** — Bad Request - Missing parameters

```json
{ "error": "job_id is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - Organization access denied

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - Job doesn't exist or access denied

```json
{ "error": "Job not found or access denied" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An unexpected error occurred" }
```

**Usage notes**

- Only jobs belonging to the authenticated user can be deleted.
- This endpoint removes the job tracking entry, not the actual job results on the build server.
- Use this to clean up job history or remove completed jobs from the list.
- Jobs are automatically pruned when the history limit is reached, so manual deletion is optional.
- Deleted jobs can no longer be queried with the fetch_results endpoint.
- Consider using this endpoint when implementing a 'clear history' feature in your application.

### Fetch Job Results

`GET https://api.storylinezads.com/jobs/fetch_results`

Fetches the results of a job from the build server. This endpoint first checks if the job exists in the database, then contacts the build server to retrieve the actual results.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Job results retrieved successfully

```json
{
  "job_id": "job_12345",
  "job_type": "query_generation",
  "created_at": "2023-11-01T12:34:56.789Z",
  "metadata": {
    "query": "marketing strategy presentation",
    "timestamp": "2023-11-01T12:34:56.789Z"
  },
  "result": {
    "items": [
      {
        "id": "result_1",
        "title": "Marketing Strategy 2023",
        "score": 0.95,
        "source": "internal_database"
      },
      {
        "id": "result_2",
        "title": "B2B Marketing Presentation",
        "score": 0.87,
        "source": "internal_database"
      }
    ],
    "processing_time": 1.25,
    "total_matches": 24
  }
}
```

**Response 400** — Bad Request - Missing parameters

```json
{ "error": "job_id is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found" }
```

**Response 403** — Forbidden - Organization access denied

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found - Job doesn't exist or no results found

```json
{ "error": "Job not found or access denied" }
```

**Response 502** — Bad Gateway - Error connecting to build server

```json
{ "error": "Error connecting to build server: Connection timed out" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An unexpected error occurred" }
```

**Usage notes**

- This endpoint is typically called after receiving notification that a job is complete.
- The input data used to create the job is stripped from results to reduce response size.
- The result structure varies based on job_type.
- For query_generation jobs, results include search matches and relevance scores.
- For search_recommendations jobs, results include suggested queries and sources.
- Implement polling with appropriate backoff to check job status for long-running operations.
- Results are fetched directly from the build server, so network latency may affect response time.
- For real-time updates, consider implementing WebSockets instead of polling this endpoint.
- The job must exist in the jobs collection before results can be fetched.
- Results may not be available immediately after job creation - the job must complete first.


---

# AI Tools API

Source: https://storylinezads.com/docs/api/tools
Last generated: 2026-07-20

Use and manage AI-powered content generation and analysis tools for creating marketing materials, video plans, and analyzing content.

Base route: `/tools` (relative to `https://api.storylinezads.com`)

## Tool Types

Discover and explore available AI tool types

### Get Tool Types

`GET https://api.storylinezads.com/types`

Retrieves a list of all available AI tool types.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Tool types retrieved successfully

```json
{
  "message": "Tool types retrieved successfully",
  "tool_types": [
    {
      "type": "creative_brief",
      "name": "Creative Brief"
    },
    {
      "type": "audience_research",
      "name": "Audience Research"
    },
    {
      "type": "web_scraper_advanced",
      "name": "Web Scraper Advanced"
    },
    {
      "type": "trend_analysis",
      "name": "Trend Analysis"
    }
  ],
  "count": 8
}
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Returns all available tool types with their readable names.

## Tool Creation

Create and run AI tools to generate content

### Create Tool

`POST https://api.storylinezads.com/create`

Creates and starts a new AI tool job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Tool job started successfully

```json
{
  "message": "Creative Brief job started successfully",
  "tool": {
    "tool_id": "550e8400-e29b-41d4-a716-446655440000",
    "tool_type": "creative_brief",
    "org_id": "org-12345",
    "name": "Q4 Campaign Brief",
    "created_by": "user-67890",
    "created_at": "2023-11-15T14:22:31.456Z",
    "updated_at": "2023-11-15T14:22:31.456Z",
    "input_data": {
      "user_input": "Create a creative brief for our new summer product line",
      "company_details": "Company Name: Eco Apparel Inc.\nCompany Type: Clothing Retailer\nTag Line: Wear the Change\nVision: Sustainable fashion for everyone\n...",
      "documents": [...],
      "temperature": 0.7,
      "auto_company_details": true,
      "company_details_id": "company-details-xyz123"
    },
    "job_id": "job-abc123"
  },
  "job_id": "job-abc123"
}
```

**Response 400** — Bad Request

```json
{ "error": "user_input is required for creative_brief" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "Failed to retrieve company details: No default company details found for this organization" }
```

**Response 415** — Unsupported Media Type

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Required parameters vary by tool_type.
- Job processing happens asynchronously.
- Default flags (deepthink, overdrive) vary by tool type.
- When auto_company_details=true, company details are automatically populated from presets.
- For creative_brief, audience_research, video_plan: Auto-fills company_details field.
- For ad_concept: Auto-fills brand_details field.
- For scene_transitions: Auto-fills brand_guidelines field.
- For web_scraper_advanced: Company details are not used.
- Trend analysis requires a supported topic keyword and one of the allowed locations (US, GB, CA, AU, DE, FR, JP, IN, BR, MX, worldwide).
- Trend analysis does not support web_search; the flag is ignored if provided.
- Web scraper parameters are clamped server-side (depth ≤ 3, max_pages ≤ 20, timeout ≤ 60 seconds, max_batch_size ≤ 10).
- The legacy scene_splitter tool has been retired and now returns an error if invoked.

## Tool Management

Manage existing AI tools and their results

### Get Tool

`GET https://api.storylinezads.com/get`

Retrieves a specific AI tool by its ID.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Tool retrieved successfully

```json
{
  "tool_id": "550e8400-e29b-41d4-a716-446655440000",
  "tool_type": "creative_brief",
  "org_id": "org-12345",
  "name": "Q4 Campaign Brief",
  "created_by": "user-67890",
  "created_at": "2023-11-15T14:22:31.456Z",
  "updated_at": "2023-11-15T14:22:31.456Z",
  "input_data": {
    "user_input": "Create a creative brief for our new summer product line",
    "company_details": "Eco-friendly apparel brand focused on sustainability",
    "documents": [...],
    "temperature": 0.7
  },
  "job_id": "job-abc123",
  "job_result": {
    "status": "completed",
    "created_at": "2023-11-15T14:22:31.456Z",
    "updated_at": "2023-11-15T14:25:42.789Z",
    "result": {
      "sections": [...]
    }
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "tool_id is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Tool not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- The job_result field is only included if include_job=true and the job exists.
- Result structure varies by tool_type.

### List Tools

`GET https://api.storylinezads.com/list`

Lists AI tools based on filtering criteria.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Tools listed successfully

```json
{
  "total": 42,
  "page": 1,
  "limit": 20,
  "total_pages": 3,
  "tools": [
    {
      "tool_id": "550e8400-e29b-41d4-a716-446655440000",
      "tool_type": "creative_brief",
      "org_id": "org-12345",
      "name": "Q4 Campaign Brief",
      "created_by": "user-67890",
      "created_at": "2023-11-15T14:22:31.456Z",
      "updated_at": "2023-11-15T14:22:31.456Z",
      "input_data": {
        "user_input": "Create a creative brief for our new summer product line",
        "company_details": "Eco-friendly apparel brand focused on sustainability",
        "documents": [...],
        "temperature": 0.7
      },
      "job_id": "job-abc123",
      "job_result": {...}
    },
    ...
  ]
}
```

**Response 400** — Bad Request

```json
{ "error": "org_id is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Results are sorted by created_at in descending order (newest first).
- The job_result field is only included if include_results=true.

### Update Tool

`PUT https://api.storylinezads.com/update`

Updates metadata for an existing AI tool.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 200** — Tool updated successfully

```json
{
  "message": "Tool updated successfully",
  "tool": {
    "tool_id": "550e8400-e29b-41d4-a716-446655440000",
    "tool_type": "creative_brief",
    "org_id": "org-12345",
    "name": "Updated Brief Name",
    "created_by": "user-67890",
    "created_at": "2023-11-15T14:22:31.456Z",
    "updated_at": "2023-11-15T15:30:45.123Z",
    "input_data": {...},
    "job_id": "job-abc123",
    "tags": ["marketing", "summer", "campaign"]
  }
}
```

**Response 400** — Bad Request

```json
{ "error": "No valid fields to update" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Tool not found" }
```

**Response 415** — Unsupported Media Type

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Only name and tags can be updated.
- Other properties like input_data cannot be changed (use redo instead).

### Delete Tool

`DELETE https://api.storylinezads.com/delete`

Deletes an AI tool and optionally its associated job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Tool deleted successfully

```json
{
  "message": "Tool deleted successfully",
  "tool_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "job-abc123",
  "job_deleted": true
}
```

**Response 400** — Bad Request

```json
{ "error": "tool_id is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Tool not found" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Also attempts to delete the associated job data.
- The job_deleted field indicates whether the job was successfully deleted.

### Redo Tool

`POST https://api.storylinezads.com/redo`

Restarts a tool job with same or modified parameters.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response 202** — Tool job restarted successfully

```json
{
  "message": "Creative Brief job restarted successfully",
  "tool_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "job-def456"
}
```

**Response 400** — Bad Request

```json
{ "error": "tool_id is required" }
```

**Response 401** — Unauthorized

```json
{ "error": "User ID not found in token" }
```

**Response 403** — Forbidden

```json
{ "error": "Failed to retrieve company details: No default company details found for this organization" }
```

**Response 404** — Not Found

```json
{ "error": "Tool not found" }
```

**Response 415** — Unsupported Media Type

```json
{ "error": "Unsupported Media Type. Content-Type must be application/json" }
```

**Response 500** — Internal Server Error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Updates tool with a new job_id and reprocesses using original parameters with optional overrides.
- Default AI feature flags vary by tool type.
- Only parameters specified in input_data will be overridden.
- When auto_company_details=true, company details will be auto-populated based on the specified preset.
- You can use company_details_id to specify which preset to use, or omit to use the default preset.
- Company details are mapped to different fields based on tool type (company_details, brand_details, or brand_guidelines).


---

# Utilities API

Source: https://storylinezads.com/docs/api/utils
Last generated: 2026-07-20

Access utility data and AI-powered helper functions including voice types, transition effects, template types, prompt alteration, search recommendations, and organization information extraction.

Base route: `/utils` (relative to `https://api.storylinezads.com`)

## Utility Data

Retrieve utility data for various media generation options

### Get Supported Formats

`GET https://api.storylinezads.com/supported-formats`

Retrieves the supported upload and session storage formats for media ingestion.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Supported formats retrieved successfully

```json
{
  "message": "Supported formats retrieved successfully",
  "allowed_formats": {
    "video": ["mp4", "mov", "mkv"],
    "audio": ["wav", "mp3"],
    "image": ["png", "jpg", "jpeg"]
  },
  "session_storage_allowed_formats": {
    "video": ["mp4"],
    "audio": ["wav"],
    "image": ["png", "jpg"]
  },
  "all_allowed": ["mp4", "mov", "mkv", "wav", "mp3", "png", "jpg", "jpeg"],
  "all_session_storage_allowed": ["mp4", "wav", "png", "jpg"]
}
```

**Response 500** — Internal Server Error

```json
{ "error": "An internal server error occurred" }
```

**Usage notes**

- Use this endpoint to validate user uploads before sending them to processing routes.
- allowed_formats groups extensions by asset type, while all_allowed flattens them for quick validation.
- session_storage_allowed_formats lists media types that can be temporarily stored in session workflows.
- Cache these results in your client; the dataset rarely changes but avoids unnecessary calls.

### Get Voice Types

`GET https://api.storylinezads.com/voice-types`

Retrieves available voice types for audio generation, organized by language and gender.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Voice types retrieved successfully

```json
{
  "message": "Voice types retrieved successfully",
  "voice_types": {
    "en": {
      "male": {
        "voice1": {
          "id": "voice_id_1",
          "name": "Voice Name 1",
          "language": "English",
          "accent": "American",
          "gender": "male"
        }
      },
      "female": {
        "voice3": {
          "id": "voice_id_3",
          "name": "Voice Name 3",
          "language": "English",
          "accent": "American",
          "gender": "female"
        }
      }
    }
  }
}
```

**Response 500** — Internal Server Error

```json
{ "error": "Failed to fetch voice_types from cache" }
```

**Usage notes**

- Voice types are organized by language code, then gender, then voice identifier.
- Each voice includes details about language, accent, and gender.
- Voice IDs are required when using the voice generation features in other endpoints.
- For international content, select voices that represent the regional accent of your target market.
- Consider the brand personality when selecting voice gender and accent.
- The system caches voice data for optimal performance and quick response times.
- Voice selection significantly impacts how your brand is perceived by the audience.
- Test different voices with sample content to find the best match for your project.

### Get Transition Types

`GET https://api.storylinezads.com/transition-types`

Retrieves available video transition types for scene transitions.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Transition types retrieved successfully

```json
{
  "message": "Transition types retrieved successfully",
  "transition_types": {
    "fade": {
      "description": "Smooth fade between scenes",
      "duration_range": [0.5, 2.0],
      "parameters": {
        "speed": "Controls the speed of the fade"
      }
    },
    "dissolve": {
      "description": "Gradual dissolve transition",
      "duration_range": [0.5, 3.0],
      "parameters": {
        "blend_mode": "Controls how pixels blend together"
      }
    }
  }
}
```

**Response 500** — Internal Server Error

```json
{ "error": "Failed to fetch transition_types from cache" }
```

**Usage notes**

- Each transition type includes a description, recommended duration range, and configurable parameters.
- Duration ranges are in seconds [min, max].
- Different transitions set different moods and pacing for your video.
- Fast transitions (0.5-1.0s) create energetic pacing, while slower transitions (1.5-3.0s) create a more relaxed feel.
- Maintain consistency in transition types throughout a project for professional results.
- Consider the emotional impact: cuts are abrupt and direct, while dissolves are smooth and gradual.
- Use transitions that match your content's tone - corporate videos benefit from clean, simple transitions.
- The parameters for each transition can be adjusted to create custom effects.

### Get Template Types

`GET https://api.storylinezads.com/template-types`

Retrieves available video template types for different use cases.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Template types retrieved successfully

```json
{
  "message": "Template types retrieved successfully",
  "template_types": {
    "corporate": {
      "description": "Professional business style",
      "styles": ["modern", "classic"],
      "aspect_ratios": ["16:9", "4:3"],
      "suitable_for": ["presentations", "product demos"]
    },
    "social_media": {
      "description": "Optimized for social platforms",
      "styles": ["vertical", "square", "widescreen"],
      "aspect_ratios": ["9:16", "1:1", "16:9"],
      "suitable_for": ["Instagram", "TikTok", "YouTube"]
    }
  }
}
```

**Response 500** — Internal Server Error

```json
{ "error": "Failed to fetch template_types from cache" }
```

**Usage notes**

- Templates are categorized by use case and include available styles and aspect ratios.
- The 'suitable_for' field suggests appropriate platforms or contexts.
- Always match aspect ratios to your target platform (9:16 for most mobile stories, 16:9 for YouTube).
- Templates provide pre-configured designs that save time while maintaining professional quality.
- Corporate templates are designed for business communications with clean, professional aesthetics.
- Social media templates are optimized for specific platforms' requirements and viewing behaviors.
- Consider how template styles align with your brand identity and messaging.
- Use consistent template styles across campaigns to strengthen brand recognition.

### Get Color Grades

`GET https://api.storylinezads.com/color-grades`

Retrieves available color grading options for video processing.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Color grades retrieved successfully

```json
{
  "message": "Color grades retrieved successfully",
  "color_grades": {
    "cinematic": {
      "description": "Film-like color grading",
      "settings": {
        "contrast": "high",
        "saturation": "medium",
        "temperature": "warm"
      },
      "suitable_for": ["dramatic content", "storytelling"]
    },
    "vivid": {
      "description": "Bright and colorful",
      "settings": {
        "contrast": "medium",
        "saturation": "high",
        "temperature": "neutral"
      },
      "suitable_for": ["product showcases", "vibrant content"]
    }
  }
}
```

**Response 500** — Internal Server Error

```json
{ "error": "Failed to fetch color_grades from cache" }
```

**Usage notes**

- Each color grade includes recommended settings and suitable content types.
- Settings describe visual characteristics like contrast, saturation, and color temperature.
- Color grading dramatically affects the emotional impact and professional quality of your videos.
- Match color grades to your content's emotional tone and subject matter.
- Cinematic grades work well for storytelling and narrative content.
- Vibrant grades are excellent for product showcases and upbeat marketing content.
- Cool temperature grades convey calm, professionalism, or technology themes.
- Warm temperature grades convey friendliness, creativity, or nostalgic feelings.
- Consider your brand colors when selecting a color grade to maintain brand consistency.

## Utility Processing

Process data using AI for prompt alteration, search recommendations, and organization information extraction

### Alter Prompt

`POST https://api.storylinezads.com/alter-prompt`

Enhances or randomizes a provided prompt using AI and returns a job ID to track the process.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |
| Content-Type | yes |  |

**Request body**

```json
[object Object]
```

**Response 202** — Prompt alteration job started successfully

```json
{
  "message": "Prompt alteration job started successfully",
  "job_id": "job_0123456789",
  "job_name": "Enhanced Product Video Prompt"
}
```

**Response 400** — Bad Request

```json
{ "error": "old_prompt is required" }
```

**Response 400** — Bad Request

```json
{ "error": "org_id is required" }
```

**Response 400** — Bad Request

```json
{ "error": "alter_type must be either \"enhance\" or \"randomize\"" }
```

**Response 400** — Bad Request

```json
{ "error": "prompt_type must be either \"prompt\", \"storyboard\", or \"sequence\"" }
```

**Response 404** — Not Found

```json
{ "error": "Organization not found or access denied" }
```

**Response 404** — Not Found

```json
{ "error": "Company details not found or access denied" }
```

**Response 500** — Internal Server Error

```json
{ "message": "An internal server error occurred" }
```

**Usage notes**

- 'enhance' makes the prompt more detailed and effective, while 'randomize' creates variations.
- You can provide company details directly in the request body or reference a company profile via company_details_id.
- Company details are optional - if not provided, no company context will be included.
- The 'enhance' alter_type adds detail, structure, and clarity without changing the core message.
- The 'randomize' alter_type creates creative variations to explore new ideas.
- For storyboards, enhancement focuses on visual elements, scene transitions, and narrative flow.
- For sequences, enhancement focuses on logical progression, timing, and content structure.
- Lower temperature values (0.1-0.3) produce more conservative, predictable alterations.
- Higher temperature values (0.7-1.0) produce more creative, varied alterations.
- Use meaningful job names to easily identify jobs in the list-jobs endpoint.
- When refining iteratively, provide previous results in 'edited_json' to maintain context.
- Use the returned job_id with the /get-result endpoint to retrieve the completed alteration.
- For creative brainstorming, run multiple randomizations, then refine the best results.
- For brand consistency, use lower temperatures and provide company details for enhancement.
- This endpoint is ideal for improving existing prompts or generating creative alternatives.
- ADVANCED CONTROL PARAMETERS: All control parameters are optional and accept values 0-100.
- Control parameters are completely optional - omit them to use standard prompt alteration behavior.
- Invalid control parameter values (outside 0-100 or non-numeric) are silently ignored for backward compatibility.
- For creative content, try higher values for 'creativity', 'energy_level', and 'emotional_tone'.
- For corporate content, use higher 'formality' and lower 'sarcasm' values.
- Use 'retention_focus' and 'pacing' together to optimize for social media platforms.
- The 'cut_frequency' and 'clip_length' parameters are especially useful for video sequence prompts.
- Combine 'detail_level' and 'narrative_structure' for complex storytelling requirements.
- All control parameters are stored in the job record for future reference and analysis.
- Higher parameter values don't always mean better results - find the right balance for your specific use case.
- Control parameters work together harmoniously and are designed to complement each other.

### Search Recommendations

`POST https://api.storylinezads.com/search-recommendations`

Performs an AI search based on a query and returns a job ID to track the process.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |
| Content-Type | yes |  |

**Request body**

```json
[object Object]
```

**Response 202** — Search recommendations job started successfully

```json
{
  "message": "Search recommendations job started successfully",
  "job_id": "job_0123456789",
  "job_name": "Video Marketing Research"
}
```

**Response 400** — Bad Request

```json
{ "error": "user_query is required" }
```

**Response 400** — Bad Request

```json
{ "error": "org_id is required" }
```

**Response 500** — Internal Server Error

```json
{ "message": "An internal server error occurred" }
```

**Usage notes**

- The 'deepthink' flag enables more comprehensive analysis of the query.
- The 'web_search' flag enables retrieval of information from the internet.
- Use 'overdrive' for complex queries requiring intensive processing.
- The 'eco' flag uses a smaller model with reduced computational requirements.
- Use specific, focused queries rather than broad questions for better results.
- Include relevant documents to provide context and improve the relevance of results.
- Keep temperature below 0.5 for factual research to ensure accurate, consistent results.
- Use temperatures above 0.7 for creative exploration and diverse perspectives.
- Combine this endpoint with /alter-prompt to generate content based on research findings.
- For industry research, follow up with /organization-info on key companies discovered.
- For sequential research, use the results of one search as documents for the next search.
- The returned job_id can be used with /get-result to retrieve complete search findings.
- Search results include citations, allowing verification of information sources.
- Use the web_search flag when researching current trends or news-related topics.
- When planning content for specific industries, provide industry context in documents.

### Organization Information

`POST https://api.storylinezads.com/organization-info`

Extracts company information from a website URL and returns a job ID to track the process.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |
| Content-Type | yes |  |

**Request body**

```json
[object Object]
```

**Response 202** — Organization information extraction job started successfully

```json
{
  "message": "Organization information extraction job started successfully",
  "job_id": "job_0123456789",
  "job_name": "Example Company Analysis"
}
```

**Response 400** — Bad Request

```json
{ "error": "website_url is required" }
```

**Response 400** — Bad Request

```json
{ "error": "website_url must be a valid URL starting with http:// or https://" }
```

**Response 400** — Bad Request

```json
{ "error": "org_id is required" }
```

**Response 500** — Internal Server Error

```json
{ "message": "An internal server error occurred" }
```

**Usage notes**

- By default, the endpoint crawls the provided website to extract information.
- For faster processing, provide pre-scraped content in the 'scraped_content' field.
- The 'deepthink' flag is enabled by default for this endpoint.
- Results include company name, description, industry, values, and more.
- Provide the main company website URL for best results, not a specific page or subdomain.
- The 'web_search' flag improves results by adding information from external sources.
- For competitor analysis, run this endpoint on multiple companies and compare results.
- Use extracted company information with /alter-prompt to create brand-aligned content.
- For maximum accuracy, keep temperature at or below 0.5.
- The information extracted is ideal for tailoring marketing materials to specific companies.
- Information returned includes tone of voice, which is valuable for content creation.
- Use the returned job_id with /get-result to retrieve the complete company analysis.
- This endpoint works well in sequence with /search-recommendations for market research.
- For comprehensive analysis, provide supplementary documents with industry context.

### Brand Settings Extraction

`POST https://api.storylinezads.com/extract-brand-settings`

Extracts brand palette, fonts, colors, logo, and other settings from a website using AI.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |
| Content-Type | yes |  |

**Request body**

```json
[object Object]
```

**Response 202** — Brand settings extraction job started successfully

```json
{
  "job_id": "685ad049649bd0340ec38fac",
  "job_name": "Brand Settings Extraction - https://bgiving.one",
  "job_type": "brand_settings_extraction",
  "status": "COMPLETED",
  "result": {
    "results": {
      "brand_settings": { ... },
      "scraped_data": { ... }
    },
    "status": "COMPLETED"
  }
}
```

**Usage notes**

- Extracts brand palette, fonts, logo, and color codes for use in automated content generation.
- Returns both raw scraped data and AI-processed brand settings.
- Temperature accepts values between 0.0 and 2.0; use ≤0.5 for deterministic output.
- Do not enable both eco and overdrive; the API rejects conflicting efficiency flags.
- Useful for onboarding new brands or automating brand asset extraction.

## Job Management

Retrieve and manage utility jobs

### Get Job Result

`GET https://api.storylinezads.com/get-result`

Retrieves the result of a previously submitted job.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Job result retrieved successfully

```json
{
  "job_id": "job_0123456789",
  "job_name": "Example Job Name",
  "job_type": "alter_prompt",
  "created_at": "2023-07-20T15:30:45.123Z",
  "result": {
    "altered_prompt": "Enhanced prompt text",
    "additional_data": {}
  },
  "error": null
}
```

**Response 400** — Bad Request

```json
{ "error": "job_id is required" }
```

**Response 400** — Bad Request

```json
{ "error": "Invalid job ID format" }
```

**Response 404** — Not Found

```json
{ "error": "Job not found" }
```

**Response 404** — Not Found

```json
{ "error": "Job result not found on process server" }
```

**Response 403** — Forbidden

```json
{ "error": "Access denied" }
```

**Response 500** — Internal Server Error

```json
{ "message": "An internal server error occurred" }
```

**Usage notes**

- This endpoint retrieves results from completed jobs started by utility processing endpoints.
- The response structure varies based on the job_type.
- Job status can be 'pending', 'processing', 'completed', or 'failed'.
- Users can only access their own jobs or jobs from organizations they belong to.
- Poll this endpoint periodically to check job status (avoid polling more than once per second).
- Only completed jobs include full result data; pending or processing jobs return status only.
- Jobs with 'failed' status include an error message explaining what went wrong.
- For complex jobs, expect processing times of 10-60 seconds.
- Set up retry logic with exponential backoff for checking long-running jobs.
- Create a user-friendly loading indicator in your UI while waiting for job completion.
- Store job_ids in your application for later reference and status checking.
- This endpoint works well with all processing endpoints that return a job_id.

### List Jobs

`GET https://api.storylinezads.com/list-jobs`

Lists all utility jobs for a specific organization with pagination.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: read-only

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Response 200** — Jobs retrieved successfully

```json
{
  "total": 45,
  "page": 1,
  "limit": 10,
  "total_pages": 5,
  "jobs": [
    {
      "job_id": "job_0123456789",
      "job_name": "Enhanced Product Video Prompt",
      "job_type": "alter_prompt",
      "created_by": "user_0123456789",
      "org_id": "org_0123456789",
      "created_at": "2023-07-20T15:30:45.123Z",
      "parameters": {
        "alter_type": "enhance",
        "prompt_type": "sequence"
      }
    }
  ]
}
```

**Response 400** — Bad Request

```json
{ "error": "org_id is required" }
```

**Response 400** — Bad Request

```json
{ "error": "Invalid job_type. Must be one of \"alter_prompt\", \"search_recommendations\", \"organization_info\", or \"brand_settings_extraction\"" }
```

**Response 400** — Bad Request

```json
{ "error": "Invalid pagination parameters" }
```

**Response 403** — Forbidden

```json
{ "error": "User does not have permission for this organization" }
```

**Response 500** — Internal Server Error

```json
{ "message": "An internal server error occurred" }
```

**Usage notes**

- Jobs are returned in descending order by creation date (newest first).
- Pagination can be adjusted with 'page' and 'limit' parameters.
- For efficiency, job input data is not included in the response.
- Use this endpoint to track and manage all AI processing jobs in your organization.
- Filter by job_type to organize job lists by function and purpose.
- Use pagination to efficiently navigate through large job histories.
- The total_pages value helps in building pagination controls in your UI.
- Each job includes basic metadata but not the complete job results.
- Use the job_id with the /get-result endpoint to retrieve full job results.
- Monitor job history to optimize your AI usage patterns.
- Review past jobs for inspiration or to avoid duplicating previous work.
- Job metadata includes created_by to track which team member initiated each job.
- For teams, this endpoint provides valuable visibility into all ongoing projects.


---

# Search API

Source: https://storylinezads.com/docs/api/search
Last generated: 2026-07-20

Provides advanced search capabilities for various media types including video, audio, and images. This API allows you to search content based on scenes, objects, transcriptions, color analysis, and tags across your media library.

Base route: `/search` (relative to `https://api.storylinezads.com`)

## Advanced Search APIs

APIs for searching through media content

### Search Video Scenes

`POST https://api.storylinezads.com/files/video/scenes`

Searches for specific scenes and hierarchical segments in video files based on a query string

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Video scene search completed",
  "results": [{
    "file_id": "...",
    "matched_scenes": [{
      "scene_start": 1.2,
      "scene_end": 3.4,
      "description": "A person walking on the beach"
    }],
    "matchedSegments": [{
      "index": 3,
      "timing": 12.5,
      "segment_data": {
        "in": 12.5,
        "out": 18.0,
        "description": "Beach walk segment",
        "focus_area": "bottom",
        "segment_slug": "beach-walk",
        "level": 1,
        "path": [2,0]
      }
    }],
    "totalSegments": 24
  }],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 45,
    "total_pages": 3
  },
  "count": 1,
  "query": "a person walking on the beach",
  "media_source": "user"
}
```

**Usage notes**

- Ensure 'query' is provided in the request body.
- This endpoint now also searches hierarchical results.all_segments and returns matchedSegments with timing and hierarchy info when present.
- For user media, the 'org_id' parameter is required.
- Use pagination parameters to handle large result sets efficiently.

### Search Audio by Intelligence

`POST https://api.storylinezads.com/files/audio/by-intelligence`

Searches audio files by detected audio intelligence classes (e.g., vocals, crowd_cheer, engine, applause). Supports legacy instrument data for backward compatibility.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Audio intelligence search completed",
  "results": [{
    "file_id": "...",
    "audioDetails": {
      "intelligence": {
        "vocals": [{ "start": 12.3, "end": 18.2, "confidence": 0.91 }],
        "applause": [{ "timestamp": 45.0, "confidence": 0.74 }]
      }
    },
    "match_details": {
      "matched_classes": ["vocals", "applause"],
      "segments": [{ "label": "vocals", "in": 12.3, "out": 18.2 }]
    }
  }],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 6,
    "total_pages": 1
  },
  "count": 6,
  "classes": ["vocals", "applause"],
  "media_source": "user"
}
```

**Usage notes**

- Provide one or more intelligence class labels under 'classes'.
- This endpoint searches results.audio.audio_intelligence for matching labels and also maps legacy 'instruments' when available for backward compatibility.
- Include 'min_confidence' to filter out low-confidence events (0.0-1.0).
- Use pagination parameters to handle large result sets.

### Search Video Objects

`POST https://api.storylinezads.com/files/video/objects`

Searches for specific objects in video files

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Video object search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 15,
    "total_pages": 1
  },
  "count": 15,
  "objects": ["car", "person", "dog"],
  "media_source": "user"
}
```

**Usage notes**

- Provide an array of objects to search for in videos.
- Ensure 'org_id' is provided for user media searches.
- Use pagination to handle large result sets.

### Search Audio Files

`POST https://api.storylinezads.com/files/audio`

Searches audio files based on transcription, genre, mood, instruments, and hierarchical segments

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Audio content search completed",
  "results": [{
    "file_id": "...",
    "match_details": {
      "transcription_match": true,
      "matchedSegments": [{
        "index": 2,
        "timing": 45.0,
        "segment_data": {
          "in": 45.0,
          "out": 60.0,
          "description": "Chorus",
          "segment_slug": "chorus-1",
          "level": 0,
          "path": [1]
        }
      }],
      "totalSegments": 10
    }
  }],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 12,
    "total_pages": 1
  },
  "count": 1,
  "query": "love song",
  "genre": "pop",
  "mood": null,
  "instruments": ["piano", "guitar"],
  "media_source": "user"
}
```

**Usage notes**

- Provide at least one of 'query', 'genre', 'mood', or 'instruments'.
- This endpoint now also searches hierarchical results.all_segments and includes matchedSegments when present.
- Ensure parameter types match the specified schema.
- Use pagination parameters to navigate through large result sets.

### Search Combined Media Files

`POST https://api.storylinezads.com/files/combined`

Searches across multiple media types (video, audio, image) using a query string, including hierarchical segments when available

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Advanced combined search completed",
  "results": [{
    "content_id": "file123",
    "file_id": "file123",
    "filename": "beach_sunset.mp4",
    "original_filename": "PXL_20240202_173000.mp4",
    "mimetype": "video/mp4",
    "media_type": "video",
    "summary": "Cinematic beach sunset orbit",
    "tags": ["beach", "sunset", "waves"],
    "match_details": {
      "summary": [{
        "text": "sunset beach",
        "context": "...sunset beach boardwalk with neon lights..."
      }],
      "tags": [{
        "text": "beach",
        "context": "Tag: beach"
      }],
      "video_scenes": [{
        "scene_start": 3.2,
        "scene_end": 6.1,
        "matches": [{
          "text": "sunset beach",
          "context": "...sunset beach boardwalk..."
        }]
      }],
      "video_transitions": [{
        "type": "cross_dissolve",
        "direction": "left_to_right",
        "match_fields": {
          "type": "cross_dissolve"
        }
      }],
      "video_caption": [{
        "text": "sunset beach walkway",
        "context": "...sunset beach walkway..."
      }],
      "ocr_matches": [{
        "text": "BOARDWALK",
        "context": "BOARDWALK",
        "source": "video_description_ocr"
      }],
      "matchedSegments": [{
        "segment_slug": "beach-pan",
        "reason": "Sunset boardwalk",
        "path": [1, 0]
      }],
      "totalSegments": 24
    },
    "matchSources": ["summary", "tags", "video_scenes", "video_transitions"],
    "textMatches": [{
      "text": "sunset beach",
      "context": "...sunset beach boardwalk with neon lights...",
      "source": "summary"
    }],
    "ocrMatches": [{
      "text": "BOARDWALK",
      "context": "BOARDWALK",
      "source": "video_description_ocr"
    }],
    "videoOcrScenes": [{
      "scene_start": 3.2,
      "scene_end": 6.1,
      "ocr_matches": [{
        "text": "BOARDWALK",
        "context": "BOARDWALK",
        "source": "video_description_ocr"
      }]
    }],
    "colorAnalysis": {
      "summary": "Warm oranges with teal shadows",
      "palette": ["#fdb36b", "#0f3d4f"]
    },
    "colorMatches": [{
      "scene_start": 3.2,
      "scene_end": 6.1,
      "dominant_hue": "sunset",
      "match_type": "video_color_scene"
    }],
    "audioDetails": {
      "genres": [{ "genre": "ambient", "probability": 0.76 }],
      "intelligence": [{ "label": "ocean_waves", "events": [{ "start": 2.8, "end": 18.2, "confidence": 0.88 }] }]
    },
    "sceneDetails": {
      "segmentSummary": { "highlights": ["Dynamic intro", "Slow middle", "Energetic outro"] },
      "pacing": { "summary": "Dynamic opening, relaxed middle, energetic outro" }
    },
    "urls": {
      "thumbnail_url": "https://cdn.storylinez.com/file123-thumb.jpg",
      "streamable_url": "https://cdn.storylinez.com/file123-stream.mp4",
      "download_url": "https://cdn.storylinez.com/file123-download.mp4"
    },
    "paths": {
      "original": "s3://org/uploads/file123/original.mp4"
    },
    "media_source": "user"
  }],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 30,
    "total_pages": 2
  },
  "count": 1,
  "query": "beach sunset",
  "media_types": ["video", "image"],
  "media_source": "user"
}
```

**Usage notes**

- Provide a 'query' string and optionally a 'media_types' array.
- match_details breaks down hits across summaries, tags, media analyzers (video_scenes, audio_transcription, image_ocr), and matchedSegments when hierarchical segments exist.
- matchSources, textMatches, and ocrMatches give normalized views of why each asset matched, aligning with sceneDetails, audioDetails, and colorAnalysis blocks.
- Audio hits populate match_details.audio_transcription/audio_caption/audio_genres/audio_intelligence and audioDetails (genres, instruments, moodSegments, speakers).
- Image hits enrich match_details.image_ocr/image_objects and colorAnalysis.stripped_color_segments for quick UI rendering.
- generated urls.* entries appear when generate_thumbnail/streamable/download query parameters are true, providing ready-to-use asset links.
- Results include both metadata and analyzer summaries so you can render context without additional API calls.
- Use pagination parameters to manage large result sets.

### Search Audio by Harmony

`POST https://api.storylinezads.com/files/audio/by-harmony`

Searches audio assets by harmony metadata such as chord keywords, key signatures, and chord progressions.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with harmony search matches

```json
{
  "message": "Audio harmony search completed",
  "results": [{"file_id": "file_1", "matched_harmony": {"keys": ["C major"]}}],
  "pagination": {"page": 1, "page_size": 20, "total_results": 8, "total_pages": 1},
  "count": 1
}
```

**Usage notes**

- At least one of chord_keywords, key_signatures, or chord_progressions is required.
- All harmony search arrays must contain strings.
- Use with by-intelligence endpoint to combine musical and semantic audio filtering.

### Search Audio by Genre

`POST https://api.storylinezads.com/files/audio/by-genre`

Searches audio files by genre, such as rock, jazz, classical, etc.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Audio genre search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 10,
    "total_pages": 1
  },
  "count": 10,
  "genres": ["jazz", "blues"],
  "media_source": "user"
}
```

**Usage notes**

- Deprecated: This endpoint is superseded by '/search/files/audio/by-intelligence'.
- Provide a list of genres in the 'genres' field.
- Optionally include 'min_probability' to filter results.

### Search Audio by Mood

`POST https://api.storylinezads.com/files/audio/by-mood`

Searches audio files by mood, such as happy, sad, energetic, etc.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Audio mood search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 8,
    "total_pages": 1
  },
  "count": 8,
  "moods": ["relaxing", "peaceful"],
  "media_source": "user"
}
```

**Usage notes**

- Provide a list of moods in the 'moods' field.
- Ensure the moods accurately represent the desired audio sentiment.
- Use pagination parameters to handle large result sets.

### Search Audio by Instrument

`POST https://api.storylinezads.com/files/audio/by-instrument`

Searches audio files by instruments used, such as piano, guitar, drums, etc.

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Audio instrument search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 5,
    "total_pages": 1
  },
  "count": 5,
  "instruments": ["piano", "violin"],
  "media_source": "user"
}
```

**Usage notes**

- Deprecated: This endpoint is superseded by '/search/files/audio/by-intelligence'.
- Provide an array of instruments in the 'instruments' field.
- Optionally provide 'min_confidence' to set the detection threshold.

### Search Audio by Transcription

`POST https://api.storylinezads.com/files/audio/by-transcription`

Searches audio files by transcription text content

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Audio transcription search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 7,
    "total_pages": 1
  },
  "count": 7,
  "query": "welcome to our podcast",
  "media_source": "user"
}
```

**Usage notes**

- Provide the 'query' field to search within audio transcriptions.
- Ensure transcription text accurately reflects file content.
- Use pagination parameters to handle large result sets.

### Search Image by Objects

`POST https://api.storylinezads.com/files/image/by-objects`

Searches image files for specific objects

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Image object search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 25,
    "total_pages": 2
  },
  "count": 20,
  "objects": ["mountain", "lake", "trees"],
  "media_source": "user"
}
```

**Usage notes**

- Provide a list of objects for the search.
- Ensure that the object names are relevant to the image content.
- Use pagination parameters to handle large result sets.

### Search Image by Color

`POST https://api.storylinezads.com/files/image/by-color`

Searches image files by color mood or dominant hue

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Image color search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 18,
    "total_pages": 1
  },
  "count": 18,
  "color_moods": ["warm", "vibrant"],
  "dominant_hues": {"min": 20, "max": 60},
  "media_source": "user"
}
```

**Usage notes**

- Provide at least one of 'color_moods' or 'dominant_hues'.
- Ensure hue values are within 0-360 degrees.
- Use pagination parameters to handle large result sets.

### Search Image by Text

`POST https://api.storylinezads.com/files/image/by-text`

Searches image files for text content using OCR

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Image text search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 22,
    "total_pages": 2
  },
  "count": 20,
  "query": "welcome to our store",
  "media_source": "user"
}
```

**Usage notes**

- Provide a 'query' string to search within OCR text.
- Ensure the OCR text was properly extracted from the image.
- Use pagination parameters to handle large result sets.

### Search Files by Tags

`POST https://api.storylinezads.com/files/by-tags`

Searches files by tags across all media types

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "File tag search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 40,
    "total_pages": 2
  },
  "count": 20,
  "tags": ["nature", "landscape"],
  "media_types": ["video", "image"],
  "media_source": "user"
}
```

**Usage notes**

- Provide a list of tags in the 'tags' field.
- Use 'match_all' to require all tags match, or false to allow any match.
- Use pagination parameters to handle large result sets.

### Search Video by Tags

`POST https://api.storylinezads.com/files/video/by-tags`

Searches video files by tags

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Video tag search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 12,
    "total_pages": 1
  },
  "count": 12,
  "tags": ["aerial", "drone", "landscape"],
  "media_source": "user"
}
```

**Usage notes**

- Provide tags for video files.
- Set 'match_all' based on whether all tags must match.
- Use pagination parameters to handle large result sets.

### Search Audio by Tags

`POST https://api.storylinezads.com/files/audio/by-tags`

Searches audio files by tags

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Audio tag search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 9,
    "total_pages": 1
  },
  "count": 9,
  "tags": ["interview", "podcast"],
  "media_source": "user"
}
```

**Usage notes**

- Provide an array of tags for audio search.
- Use 'match_all' flag to indicate strict matching.
- Use pagination parameters to handle large result sets.

### Search Image by Tags

`POST https://api.storylinezads.com/files/image/by-tags`

Searches image files by tags

- Auth required: yes (X-API-Key + X-API-Secret headers)
- Rate limited: yes
- Action type: mutating

**Request headers**

| Name | Required | Description |
| --- | --- | --- |
| X-API-Key | yes | Your API key. |
| X-API-Secret | yes | Your API secret. |

**Request body**

```json
[object Object]
```

**Response undefined** — Successful response with search results

```json
{
  "message": "Image tag search completed",
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_results": 14,
    "total_pages": 1
  },
  "count": 14,
  "tags": ["portrait", "studio"],
  "media_source": "user"
}
```

**Usage notes**

- Provide tags for image search in the request body.
- Use 'match_all' to require complete tag matching if needed.
- Use pagination parameters to handle large result sets.


---

# Status API

Source: https://storylinezads.com/docs/api/status
Last generated: 2026-07-20

Check the health and status of the Storylinez API and its connected services.

Base route: `/` (relative to `https://api.storylinezads.com`)

## System Status

Monitor and check the health of all system components

### API Root

`GET https://api.storylinezads.com/`

Provides basic API information and confirms the server is running.

- Auth required: no
- Rate limited: yes
- Action type: read-only

**Response 200** — Server is operational

```json
{ "info": "This is the storylinez API", "status": "OK", "message": "Server is running. Use /status for detailed status." }
```

**Usage notes**

- Use this endpoint to quickly check if the API is accessible.
- No authentication required - useful for public health checks.
- Returns minimal information - use /status for more details.
- Helpful for monitoring scripts to verify basic connectivity.
- Can be used in load balancer health checks to confirm service availability.

### Basic Status

`GET https://api.storylinezads.com/status`

Provides basic status information including MongoDB connection status.

- Auth required: no
- Rate limited: yes
- Action type: read-only

**Response 200** — Status information retrieved successfully

```json
{ "info": "This is the storylinez API", "status": "OK", "message": "Server is running. Use /status/all for detailed status.", "mongodb_status": true }
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Use this endpoint to check basic system health including database connectivity.
- MongoDB status indicates if the database connection is working properly.
- No authentication required - suitable for public health checks.
- Useful for automated monitoring systems to verify core functionality.
- Returns more information than the root endpoint but less than /status/all.
- Can be used during troubleshooting to quickly identify database connection issues.

### Detailed Status

`GET https://api.storylinezads.com/status/all`

Provides comprehensive status information about all system components including internal microservices.

- Auth required: no
- Rate limited: yes
- Action type: read-only

**Response 200** — Detailed status information retrieved successfully

```json
{
  "main_server": {
    "status": "OK",
    "message": "Main server is running",
    "mongodb": true
  },
  "internal_servers": {
    "preprocess_server": {
      "status": "OK",
      "message": "Server is running",
      "details": { ... }
    },
    "build_server": {
      "status": "OK",
      "message": "Server is running",
      "details": { ... }
    },
    "render_server": {
      "status": "OK",
      "message": "Server is running",
      "details": { ... }
    }
  },
  "overall_status": "HEALTHY"
}
```

**Response 500** — Internal Server Error

```json
{ "error": "Internal server error" }
```

**Usage notes**

- Use this endpoint to get a comprehensive health check of all system components.
- Checks connectivity to all internal microservices including preprocessing, build, and render servers.
- The overall_status will be one of: HEALTHY, WARNING, or DEGRADED.
- HEALTHY means all systems are operational.
- WARNING indicates potential issues but the system is still functional.
- DEGRADED means critical services are unavailable.
- Useful for debugging system-wide issues and identifying specific failing components.
- No authentication required, but due to its comprehensive nature, it may take slightly longer to respond.
- Consider using this endpoint in your diagnostic workflows when issues are reported.
- Can be integrated with monitoring systems to track the health of all microservices.


---

## Rules for AI assistants
- Use only the facts provided above; they come from the official Storylinez API docs.
- Do not invent endpoints, parameters, response fields, pricing, or rate limits.
- Ask the user for API keys/secrets — never guess or fabricate credentials.
- Warn the user before suggesting changes that touch production, billing, security, or deletion.