{"openapi":"3.0.3","info":{"title":"OG Pilot API","version":"1.0.0","description":"Generate dynamic Open Graph images"},"servers":[{"url":"https://ogpilot.com/api/v1"}],"tags":[{"name":"Images","description":"Generate Open Graph images from signed JWT payloads."}],"paths":{"/images":{"post":{"tags":["Images"],"summary":"Generate OG image","description":"POST endpoint that accepts a signed JWT in the request body (`token`). Returns redirect to CDN URL by default, or JSON metadata if Accept: application/json header is present. If the image is still processing, returns 202.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"},"examples":{"basic":{"value":{"token":"YOUR_JWT_TOKEN"}}}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"302":{"description":"Redirect to CDN URL (default HTML/PNG behavior)","headers":{"Location":{"schema":{"type":"string","format":"uri"},"description":"CDN URL of generated image"},"X-OG-Pilot-Cache":{"schema":{"type":"string","enum":["HIT","MISS"]},"description":"Cache status"}}},"200":{"description":"Image metadata (JSON response when Accept: application/json header is present)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResponse"},"examples":{"completed":{"value":{"id":"s_abc123","status":"completed","url":"https://cdn.ogpilot.com/images/s_abc123.jpg","width":1200,"height":630,"created_at":"2026-02-06T12:00:00Z","cached":true,"stale":false}}}}}},"202":{"description":"Image is processing; JSON includes metadata and optional placeholder_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageResponse"},"examples":{"processing":{"value":{"id":"s_abc123","status":"processing","url":"https://ogpilot.com/status/processing.jpg","width":1200,"height":630,"created_at":"2026-02-06T12:00:00Z","cached":false,"stale":false,"placeholder_url":"https://ogpilot.com/status/processing.jpg"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"schemas":{"TokenRequest":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Signed JWT token generated in your application."}}},"ImageResponse":{"type":"object","required":["id","status","url","width","height","created_at","cached","stale"],"properties":{"id":{"type":"string","example":"s_abc123"},"status":{"type":"string","enum":["processing","completed","failed"],"example":"completed"},"url":{"type":"string","format":"uri","example":"https://cdn.ogpilot.com/images/s_abc123.jpg"},"width":{"type":"integer","example":1200},"height":{"type":"integer","example":630},"created_at":{"type":"string","format":"date-time","example":"2026-02-06T12:00:00Z"},"cached":{"type":"boolean","example":true},"stale":{"type":"boolean","example":false},"placeholder_url":{"type":"string","format":"uri","nullable":true},"error":{"type":"string","nullable":true}}},"ErrorResponse":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string","example":"Invalid or expired JWT token"},"code":{"type":"string","example":"unauthorized"},"details":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"object"}],"nullable":true}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Bad request","code":"bad_request"}}}},"Unauthorized":{"description":"Missing/invalid token or invalid signature","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid or expired JWT token","code":"unauthorized"}}}},"Forbidden":{"description":"Domain not verified or subscription required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Domain not verified for this account","code":"forbidden"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Not found","code":"not_found"}}}},"ValidationError":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Validation failed","code":"validation_error","details":["Title can't be blank"]}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Rate limit exceeded","code":"rate_limited"}}}}}}}