API Reference: Technical Documentation

The StoryCycle Genie™ API provides programmatic access to all platform capabilities, enabling you to integrate AI-powered brand storytelling into your applications, workflows, and tools.

Getting Started with the API

Authentication

All API requests require authentication using Bearer tokens.

Authentication Header:

Authorization: Bearer YOUR_API_KEY

How to Get Your API Key:

1. Log into your StoryCycle Genie™ account
2. Navigate to any Genie (e.g., Brand Story Genie™)
3. Scroll to the "API Keys" section on the Genie page
4. Click "+ Add New API Key"
5. Enter a name for your API key
6. Click "Add API Key"
7. Copy the generated key immediately (shown only once)

Note: API keys are created per-agent/Genie, not globally. Each Genie can have multiple API keys for different use cases.

Base URL

https://storycycle.ai/api/v1beta

Request Format

All requests use standard REST conventions:

• GET: Retrieve resources
• POST: Create resources or send messages
• PUT: Update resources
• DELETE: Remove resources

Content Type: application/json

Core Resources

Agents

Agents are the specialized Genies you interact with (Brand Story Genie™, Blog Post Genie™, etc.).

Get Agent Details

GET /agents/{agentId}

Parameters:

• agentId (required): The unique identifier for the agent

Response:

{
  "id": "brand-story-genie",
  "name": "Brand Story Genie™",
  "description": "Build your brand brain with foundational brand narrative strategy",
  "status": "active"
}

Chats

Chats represent conversations with a specific agent.

Create a New Chat

POST /agents/{agentId}/chats

Request Body:

{
  "message": "Help me create a brand story for my company"
}

Response:

{
  "chatId": "chat_abc123",
  "status": "active",
  "created_at": "2025-10-01T12:00:00Z"
}

Get Chat Details

GET /agents/{agentId}/chats/{chatId}

Response:

{
  "chat": {
    "id": "chat_abc123",
    "agent_id": "brand-story-genie",
    "status": "active",
    "created_at": "2025-10-01T12:00:00Z",
    "updated_at": "2025-10-01T12:05:00Z"
  }
}

Messages

Messages are the individual interactions within a chat.

Send a Message

POST /agents/{agentId}/chats/{chatId}/messages

Request Body:

{
  "content": [
    {
      "type": "text",
      "text": "Create a blog post about brand storytelling"
    }
  ]
}

Response:

{
  "id": "msg_xyz789",
  "content": [
    {
      "type": "text",
      "text": "I'll help you create a compelling blog post..."
    }
  ],
  "created_at": "2025-10-01T12:01:00Z"
}

Get Chat Messages

GET /agents/{agentId}/chats/{chatId}/messages

Response:

{
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": [{"type": "text", "text": "Help me..."}]
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": [{"type": "text", "text": "I'll help..."}]
    }
  ]
}

Delete a Message

DELETE /agents/{agentId}/chats/{chatId}/messages/{messageId}

Response: 200 OK

Attachments

Upload files to provide context for agents.

Upload an Attachment

POST /agents/{agentId}/chats/{chatId}/messages/{messageId}/attachments
Content-Type: multipart/form-data

Form Data:

• file: The file to upload (PDF, Word, images)

Supported File Types:

• PDF documents (.pdf)
• Word documents (.doc, .docx)
• Images (.jpg, .png, .webp)
• Text files (.txt, .md)

Response:

{
  "id": "msg_xyz789",
  "attachments": [
    {
      "filename": "brand-guidelines.pdf",
      "url": "https://...",
      "type": "application/pdf"
    }
  ]
}

Delete an Attachment

DELETE /agents/{agentId}/chats/{chatId}/messages/{messageId}/attachments/{filename}

Response: 200 OK

Streaming Responses

For long-form content generation, the API supports streaming responses to display results as they're generated.

Streaming Request:

POST /agents/{agentId}/chat/completion
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "stream": true,
  "message": {
    "role": "user",
    "content": [{"type": "text", "text": "Your message here"}]
  }
}

The response will be sent as Server-Sent Events (SSE) format.

Error Handling

The API uses standard HTTP status codes.

Status Codes

• 200 OK: Request successful
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Missing or invalid API key
• 402 Payment Required: Insufficient credits
• 404 Not Found: Resource doesn't exist
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Error Response Format

{
  "error": {
    "message": "Insufficient credits available",
    "code": "insufficient_credits",
    "details": {
      "required": 5,
      "available": 2
    }
  }
}

Common Errors

Insufficient Credits:

{
  "error": {
    "message": "No available credits"
  }
}

Solution: Add credits to your account or upgrade your plan.

Invalid API Key:

{
  "error": {
    "message": "Invalid authentication credentials"
  }
}

Solution: Verify your API key is correct and hasn't been revoked.

Rate Limits

Current Limits:

• 100 requests per minute per API key
• 1,000 requests per hour per API key

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1696176000

When Rate Limited:

{
  "error": {
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 60
  }
}

Best Practices

Efficient API Usage

Reuse Chat Sessions: Continue existing chats rather than creating new ones for related work.

Batch Related Requests: Group related operations to minimize API calls.

Handle Errors Gracefully: Implement retry logic with exponential backoff for transient errors.

Monitor Your Credits: Check credit balance before starting large operations.

Security Recommendations

Protect Your API Key:

• Never commit API keys to version control
• Use environment variables for key storage
• Rotate keys regularly
• Use separate keys for development and production

Secure Your Requests:

• Always use HTTPS
• Validate all input data
• Implement request signing for sensitive operations

Performance Optimization

Use Streaming Responses: For long-form content generation, use streaming to display results as they're generated.

Cache Responses: Cache frequently accessed data like agent details and workflow definitions.

Paginate Large Results: Request data in smaller chunks for better performance.

Code Examples

Python

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://storycycle.ai/api/v1beta"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create a chat
response = requests.post(
    f"{BASE_URL}/agents/brand-story-genie/chats",
    headers=headers,
    json={"message": "Help me create my brand story"}
)

chat_data = response.json()
chat_id = chat_data["chatId"]

# Send a message
response = requests.post(
    f"{BASE_URL}/agents/brand-story-genie/chats/{chat_id}/messages",
    headers=headers,
    json={
        "content": [
            {"type": "text", "text": "My company name is TechStartup..."}
        ]
    }
)

message_data = response.json()
print(message_data["content"][0]["text"])

JavaScript/Node.js

const fetch = require('node-fetch');

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://storycycle.ai/api/v1beta';

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

// Create a chat
async function createChat() {
  const response = await fetch(
    `${BASE_URL}/agents/brand-story-genie/chats`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        message: 'Help me create my brand story'
      })
    }
  );
  
  const data = await response.json();
  return data.chatId;
}

// Send a message
async function sendMessage(chatId, message) {
  const response = await fetch(
    `${BASE_URL}/agents/brand-story-genie/chats/${chatId}/messages`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        content: [{type: 'text', text: message}]
      })
    }
  );
  
  return await response.json();
}

// Usage
(async () => {
  const chatId = await createChat();
  const result = await sendMessage(chatId, 'My company is...');
  console.log(result.content[0].text);
})();

cURL

# Create a chat
curl -X POST https://storycycle.ai/api/v1beta/agents/brand-story-genie/chats \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Help me create my brand story"}'

# Send a message
curl -X POST https://storycycle.ai/api/v1beta/agents/brand-story-genie/chats/CHAT_ID/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": [{"type": "text", "text": "My company name is..."}]}'

# Upload a file
curl -X POST https://storycycle.ai/api/v1beta/agents/brand-story-genie/chats/CHAT_ID/messages/MSG_ID/attachments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@brand-guidelines.pdf"

SDK Libraries

Official SDK libraries are in development and will be available soon.

API Changelog

v1beta (Current):

• Initial API release
• Support for agents, chats, messages
• File attachments
• Streaming responses

Support & Resources

Need Help?

• Contact Support - Get help from our team
• FAQ: Advanced Usage - Common technical questions

Getting Started

1. Get Your API Key: Navigate to any Genie page and scroll to the "API Keys" section
2. Review Code Examples: See the Python, JavaScript, and cURL examples above
3. Start Building: Use the endpoints and examples to integrate StoryCycle into your applications

This API is in beta. Features and endpoints may change. Subscribe to our changelog for updates.