Contentdrips API Documentation

Authentication

All endpoints (except /queue/stats) require Bearer token authentication.

Headers:

Authorization: Bearer {your_token}

Content-Type: application/json

Endpoints Overview

Method Endpoint Type Description
POST /render Async Submit job to queue for processing
GET /job/:jobId/status Async Check job processing status
GET /job/:jobId/result Async Get completed job result
GET /queue/stats Info Get queue statistics
POST /generate Sync Original synchronous processing

1. `POST /render` (Async Processing)

Request Example

Submit a job to the processing queue for asynchronous handling.

POST /render
Authorization: Bearer {token}
Content-Type: application/json

 

{
  “template_id”: “123”,
  “output”: “png”,
  “tool”: “carousel-maker”,
  “branding”: {
    “name”: “John Doe”,
    “handle”: “@johndoe”,
    “bio”: “Software Developer”,
    “website_url”: “https://johndoe.com”,
    “avatar_image_url”: “https://example.com/avatar.jpg”
  },
  “content_update”: [
    { “type”: “textbox”, “label”: “title”, “value”: “New Title Text” },
    { “type”: “image”, “label”: “main_image”, “value”: “https://example.com/image.jpg” }
  ],
  “carousel”: [
    {
      “content_fields”: [
        { “type”: “textbox”, “label”: “slide_title”, “value”: “Slide 1 Title” }
      ]
    }
  ]
}

Response Examples

Success Response (202 Accepted)

{
  “job_id”: “a1b2c3d4-e5f6-7890-abcd-ef1234567890”,
  “status”: “queued”,
  “message”: “Job has been queued for processing”,
  “estimated_time”: “2-5 minutes”,
  “check_status_url”: “/job/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status”
}

400 Bad Request

{ “error”: “Validation error”, “message”: “template_id is required” }

401 Unauthorized

{ “error”: “Unauthorized”, “message”: “Invalid or missing Bearer token” }

500 Internal Server Error

{ “error”: “Failed to queue job”, “message”: “Redis connection failed” }

2. `GET /job/:jobId/status`

Request Example

Check the current status of a queued job

GET /job/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status

Response Examples

Queued

{ “job_id”: “…”, “status”: “queued”, “updated_at”: “…”, “queue_position”: 3 }

Processing

{ “job_id”: “…”, “status”: “processing”, “updated_at”: “…”, “progress”: “Loading fonts and templates” }

Completed

{ “job_id”: “…”, “status”: “completed”, “updated_at”: “…”, “completedAt”: “…” }

Failed

{ “job_id”: “…”, “status”: “failed”, “updated_at”: “…”, “error”: “Template not found” }

404 Not Found

{ “error”: “Job not found”, “job_id”: “invalid-job-id” }

3. `GET /job/:jobId/result`

Request Example

Retrieve the result of a completed job.
GET /job/a1b2c3d4-e5f6-7890-abcd-ef1234567890/result

Response Examples

Single Image

{ “date”: “…”, “type”: “normal”, “export_url”: “https://your-bucket.s3.amazonaws.com/…” }

Carousel Images

{ “date”: “…”, “type”: “carousel”, “export_url”: [“https://…frame-0.png”, “…frame-1.png”] }

PDF Result

{ “date”: “…”, “type”: “carousel”, “export_url”: “https://…output.pdf” }

Job Not Ready

{ “job_id”: “…”, “status”: “processing”, “message”: “Job not yet completed”, “check_again_in”: “30 seconds” }

404 Not Found

{ “error”: “Job not found”, “job_id”: “invalid-job-id” }

404 Result Not Found

{ “error”: “Job result not found”, “job_id”: “…” }

408 Request Timeout

{ “error”: “Request timeout”, “message”: “Request took too long to process” }

500 Processing Error

{ “error”: “Error generating image”, “message”: “Failed to load template: HTTP 404 – Not Found”, “type”: “Error” }

500 Template Error

{ “error”: “Error fetching or processing JSON”, “message”: “Failed to fetch template: Template not found”, “type”: “Error” }

500 Canvas Error

{ “error”: “Error loading canvas”, “message”: “Invalid JSON format in template”, “type”: “SyntaxError” }

4. `POST /generate` (Synchronous)

Direct synchronous image/PDF generation.

POST /generate
Authorization: Bearer {token}
Content-Type: application/json

{
  “template_id”: “123”,
  “output”: “png”
}

5. `GET /queue/stats`

Get real-time statistics on the job queue.

GET /queue/stats

Request parameters

Parameter Type Description
template_id string Required. Unique identifier for the template
output string Optional. "png" (default) or "pdf"
tool string Optional. "carousel-maker" or blank
branding object Optional. Branding information (name, handle, etc)
content_update array Optional. Content updates (textbox/image)
carousel array Optional. Carousel slides, each with content_fields

Error Handling

All errors follow this format:

{
  “error”: “Error Type”,
  “message”: “Detailed error description”,
  “type”: “ErrorClassName” // optional
}
Code Description
200 Success (synchronous)
202 Accepted (async job queued)
400 Bad Request (validation error)
401 Unauthorized (invalid token)
404 Not Found (job/template)
408 Request Timeout
500 Internal Server Error

Rate Limiting & Concurrency

  • Asynchronous `/render` endpoint uses job queue; no direct client-side rate limit.
  • Multiple workers can process jobs in parallel.

File Upload & Storage

  • Generated images/PDFs are uploaded to AWS S3.
  • URLs are returned in responses.
  • Files are organized by profile ID: `server/{profile_id}/uploads/`.
  • File names include random prefixes for uniqueness.

Example Usage Workflows

Async Processing

1. Submit Job

curl -X POST http://localhost:3000/render \
      -H “Authorization: Bearer your-token” \
      -H “Content-Type: application/json” \
      -d ‘{“template_id”: “123”, “output”: “png”}’

2. Check Status

curl http://localhost:3000/job/{job_id}/status

3. Get Result

curl http://localhost:3000/job/{job_id}/result

Sync Processing

1. Direct Processing

curl -X POST http://localhost:3000/generate \
      -H “Authorization: Bearer your-token” \
      -H “Content-Type: application/json” \
      -d ‘{“template_id”: “123”, “output”: “png”}’

Monitoring & Debugging

  • Check queue status with `GET /queue/stats`
  • Memory usage is logged on the server console
  • Job statuses tracked in Redis
  • Failed jobs include error details for debugging

Frequently Asked Questions

In AWS S3, organized by profile ID.

Poll /job/:jobId/status until you get "completed".

Error details are returned in responses. See “Error Handling” above.