Build with PLAYSTE

Quick Start

Get your first script analysis in under 5 minutes.

1. Get API Credentials

# Sign up at https://playste.com/developers
# Retrieve your API key from the dashboard
export PLAYSTE_API_KEY="your_api_key_here"

2. Upload and Analyze a Script

curl -X POST https://api.playste.com/v1/scripts \
  -H "Authorization: Bearer $PLAYSTE_API_KEY" \
  -F "file=@screenplay.pdf" \
  -F "tier=advanced"

# Response: {"script_id": "abc-123", "job_id": "job-456"}

3. Poll for Results

curl https://api.playste.com/v1/analysis/job-456 \
  -H "Authorization: Bearer $PLAYSTE_API_KEY"

Authentication

PLAYSTE uses Bearer token authentication for all API requests.

Authorization: Bearer pk_live_xxxxxxxxxxxx

Environment Types

Token Scopes

Test Mode & Live Mode

PLAYSTE provides separate environments for development and production.

Test Mode Behavior

• Instant results: Analysis completes in ~2 seconds with mock data
• Predictable outputs: Same script always returns same mock results
• No billing: All requests are free
• Rate limits apply: Same limits as production for realistic testing

Test Scripts

Use these magic filenames for predictable test scenarios:

Best Practice: Store keys in environment variables. Never commit live keys to version control.

API Versioning

PLAYSTE uses date-based API versioning to ensure backward compatibility.

Version Header

Playste-Version: 2025-11-01

Version Changelog

Deprecation Policy

• 6-month notice before deprecating any version
• Email notifications sent to account owners
• 12-month support window after deprecation notice

REST API Reference

Upload Script

POST /v1/scripts
Content-Type: multipart/form-data

Parameters:

Get Analysis Results

GET /v1/analysis/{job_id}

Response (Complete):

{
  "job_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "status": "complete",
  "summary": "Modern urban drama with strong commercial appeal...",
  "revenue_low": 18000.00,
  "revenue_high": 42000.00,
  "scenes_analyzed": 47,
  "opportunities": [...],
  "ip_flags": [...]
}

View full API reference →

Idempotency & Request IDs

Idempotency Keys

Safely retry requests without duplicate processing:

POST /v1/scripts
Idempotency-Key: unique-request-id-12345

• Same key + same parameters = cached response returned
• Same key + different parameters = 400 idempotent_request_mismatch
• Keys expire after 24 hours

Request IDs

Every API response includes a unique request ID for debugging:

X-Request-Id: req_a1b2c3d4e5f6

Include this ID when contacting support for faster issue resolution.

Pagination

List endpoints use cursor-based pagination for consistent results.

Request Parameters

Response Format

{
  "data": [...],
  "has_more": true,
  "next_cursor": "opp_xyz789"
}

MCP Integration

PLAYSTE provides a Model Context Protocol (MCP) server for seamless integration with AI assistants like Claude Desktop, VS Code, and Cursor.

Why MCP?

• Conversational Analysis: Ask follow-up questions about results
• IDE Integration: Analyze scripts without leaving your editor
• Agent Workflows: Build autonomous screenplay analysis pipelines
• Real-time Feedback: Get instant insights during writing

Installation Methods

Remote Server (Recommended)

Use PLAYSTE's hosted MCP server—no installation required:

Server URL: https://mcp.playste.com/v1

npm Package

npm install -g @playste/mcp-server

Docker

docker run -i --rm \
  -e PLAYSTE_API_KEY=pk_live_xxx \
  ghcr.io/playste/mcp-server

Host Application Support

Claude Desktop Configuration

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "playste": {
      "type": "http",
      "url": "https://mcp.playste.com/v1",
      "headers": {
        "Authorization": "Bearer pk_live_xxxxxxxxxxxx"
      }
    }
  }
}

Available MCP Tools

• analyze_script - Full script analysis
• analyze_scene - Single scene quick check
• get_placement_opportunities - Filter and query placements
• check_ip_risks - Check content for IP issues
• estimate_revenue - Revenue projections with parameters
• list_scenes - Get all scenes from analysis

Webhooks & Events

Available Events

Webhook Payload

{
  "id": "evt_123456",
  "type": "analysis.complete",
  "created": "2025-11-22T10:35:00Z",
  "data": {
    "job_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "status": "complete",
    "revenue_low": 18000,
    "revenue_high": 42000
  }
}

SDKs & Libraries

Official SDKs

Node.js Example

import { Playste } from '@playste/sdk';

const playste = new Playste({
  apiKey: process.env.PLAYSTE_API_KEY
});

const result = await playste.analyze('./screenplay.pdf', {
  tier: 'advanced',
  metadata: { title: 'My Film', genres: ['Drama'] }
});

console.log(`Revenue: $${result.revenue_low} - $${result.revenue_high}`);

Python Example

from playste import Playste

client = Playste(api_key=os.environ['PLAYSTE_API_KEY'])

result = client.analyze(
    './screenplay.pdf',
    tier='advanced',
    metadata={'title': 'My Film', 'genres': ['Drama']}
)

print(f"Revenue: ${result.revenue_low} - ${result.revenue_high}")

Developer Tools

PLAYSTE CLI

npm install -g @playste/cli

# Authenticate
playste auth login

# Analyze a script
playste analyze ./screenplay.pdf --tier advanced

# Check job status
playste jobs status job-456

# Export results
playste export job-456 --format csv --output results.csv

API Playground

Test API endpoints directly in your browser:

playground.playste.com →

Postman Collection

Import our complete API collection:

https://api.playste.com/v1/postman/collection.json

OpenAPI Specification

curl -o openapi.yaml https://api.playste.com/v1/openapi.yaml

Dashboard

Manage your integration at dashboard.playste.com:

• API Keys: Create, rotate, and revoke keys
• Usage: Monitor requests, costs, and quotas
• Logs: View request history with full details
• Webhooks: Configure and test webhook endpoints