API Overview

API Overview

The Splinterpic API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL

All API requests should be made to your deployed Worker URL:

https://your-worker-name.workers.dev

Request Format

The Splinterpic API uses standard HTTP methods:

Method	Usage
GET	Retrieve resources
POST	Create new resources
PUT	Update existing resources
DELETE	Remove resources

All POST and PUT requests must include a Content-Type: application/json header.

Response Format

All responses are returned as JSON:

{
  "id": "img_abc123",
  "prompt": "A beautiful sunset",
  "created_at": "2024-01-15T10:30:00.000Z"
}

HTTP Status Codes

Splinterpic uses conventional HTTP response codes:

Code	Meaning
200	Success - Request completed successfully
201	Created - Resource was created successfully
400	Bad Request - Invalid parameters or request format
403	Forbidden - IP not whitelisted or insufficient permissions
404	Not Found - Resource doesn’t exist
500	Internal Server Error - Something went wrong on our end

Error Responses

When an error occurs, you’ll receive a JSON response with an error field:

{
  "error": "Invalid prompt parameter",
  "details": {
    "field": "prompt",
    "message": "Prompt must be at least 3 characters"
  }
}

Common Error Scenarios

IP Not Whitelisted (403)

HTTP/1.1 403 Forbidden

Forbidden

Invalid Request Body (400)

{
  "error": "Invalid request body",
  "details": "Expected JSON content-type"
}

Resource Not Found (404)

{
  "error": "Image not found",
  "details": {
    "image_id": "img_invalid"
  }
}

Available Endpoints

Images

Endpoint	Method	Description
/api/generate	POST	Generate a new AI image
/api/images	GET	List all images
/api/images/:id	GET	Get a specific image
/api/images/:id	DELETE	Delete an image (soft delete)

Full images documentation →

Collections

Endpoint	Method	Description
/api/collections	GET	List all collections
/api/collections	POST	Create a new collection
/api/collections/:id	GET	Get collection details
/api/collections/:id/images	GET	List images in collection
/api/collections/:id	DELETE	Delete a collection

Full collections documentation →

Models

Endpoint	Method	Description
/api/models	GET	List available AI models
/api/models/:id	GET	Get model details

Full models documentation →

Analytics

Endpoint	Method	Description
/api/analytics/usage	GET	Get usage statistics
/api/analytics/costs	GET	Get cost analytics

Full analytics documentation →

Rate Limiting

Currently, Splinterpic does not implement rate limiting. However, Cloudflare Workers have the following limits:

• Free Plan: 100,000 requests/day
• Paid Plan: 10 million requests/day

For high-volume use cases, consider implementing client-side rate limiting or contact us for enterprise options.

Pagination

Endpoints that return lists support pagination via query parameters:

Parameter	Type	Default	Description
limit	integer	20	Number of results per page (max 100)
offset	integer	0	Number of results to skip

Example

# Get images 21-40
curl "https://your-worker.workers.dev/api/images?limit=20&offset=20"

Response

{
  "images": [...],
  "pagination": {
    "limit": 20,
    "offset": 20,
    "total": 150,
    "has_more": true
  }
}

Timestamps

All timestamps are returned in ISO 8601 format (UTC):

2024-01-15T10:30:00.000Z

To parse in JavaScript:

const date = new Date('2024-01-15T10:30:00.000Z');
console.log(date.toLocaleString());

To parse in Python:

from datetime import datetime

date = datetime.fromisoformat('2024-01-15T10:30:00.000Z'.replace('Z', '+00:00'))
print(date.strftime('%Y-%m-%d %H:%M:%S'))

User Identification

Currently, all requests use a default user ID (default_user). For multi-tenant deployments, you can extend the authentication system to include user identification.

CORS

The Splinterpic API includes CORS headers for all responses:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type

This allows you to make requests from any frontend application.

Idempotency

Image generation requests are not idempotent. Each POST /api/generate request creates a new image, even with identical prompts.

To avoid duplicate generations, implement client-side deduplication or use templates to save generation settings.

Versioning

The current API version is v1 (implied, not included in URLs). When we release breaking changes, we’ll introduce a versioned API path (e.g., /v2/api/...) and provide migration guides.

SDKs & Libraries

Official SDKs are available for:

• JavaScript/Node.js
• Python

Community SDKs:

• Submit yours via GitHub!

Testing

Test Environment

Use the same Worker for development and production. Configure IP whitelisting to include both environments:

[vars]
ALLOWED_IPS = "dev.ip,staging.ip,prod.ip"

Sample Data

The Worker includes sample data (templates and models) inserted via database/schema-init.sql. This data uses user_id = 'system' and should not be deleted.

Support

Need help with the API?

• API Questions: support@splinterpic.com
• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions

Next Steps

• Generate Images - Learn how to generate AI images Generate →
• Manage Collections - Organize images into collections Collections →
• View Models - Explore available AI models Models →
• Track Analytics - Monitor usage and costs Analytics →