{ "openapi": "3.1.0", "info": { "title": "Export Social API", "version": "1.0.0", "description": "Independent low-traffic media export. No publication, pArticles dependency or LLM. All timestamps are UTC epoch milliseconds." }, "servers": [ { "url": "/" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "sessionAuth": { "type": "apiKey", "in": "cookie", "name": "es_session" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false }, "Media": { "type": "object", "properties": { "index": { "type": "integer" }, "mediaType": { "enum": ["image", "video"] }, "postShortcode": { "type": "string" }, "previewUrl": { "type": ["string", "null"] }, "caption": { "type": "string" }, "author": { "type": "string" }, "creditsText": { "type": "string", "description": "Ready-to-copy author, caption and source." } }, "required": ["index", "mediaType"], "additionalProperties": false }, "Job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "enum": ["pending", "running", "completed", "failed", "expired"] }, "attempts": { "type": "integer" }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" }, "expiresAt": { "type": ["integer", "null"] }, "fileName": { "type": ["string", "null"] }, "contentType": { "type": ["string", "null"] }, "bytes": { "type": ["integer", "null"] }, "error": { "type": ["string", "null"] }, "metadata": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "platform": { "type": "string" }, "index": { "type": "integer" }, "mediaType": { "enum": ["image", "video"] }, "postShortcode": { "type": "string" }, "caption": { "type": "string" }, "author": { "type": "string" } }, "required": [], "additionalProperties": false } }, "downloadUrl": { "type": ["string", "null"] }, "creditsText": { "type": "string", "description": "Deduplicated author, caption and source blocks, also available after file expiry." } }, "required": ["id", "status", "metadata"], "additionalProperties": false }, "ExportRequest": { "type": "object", "properties": { "mode": { "enum": ["original", "compose"], "default": "original" }, "selections": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "properties": { "inspectionId": { "type": "string", "format": "uuid" }, "index": { "type": "integer", "minimum": 0, "maximum": 19 } }, "required": ["inspectionId", "index"], "additionalProperties": false } }, "layout": { "enum": ["auto", "horizontal", "vertical", "grid", "diagonal"], "default": "auto" }, "separatorColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "default": "#ffffff" }, "separatorSize": { "type": "integer", "minimum": 0, "maximum": 64, "default": 8 }, "format": { "enum": ["original", "1:1", "4:5", "9:16", "16:9"], "description": "Default original. Editorial JPEG dimensions: 1080x1080, 1080x1350, 1080x1920, 1920x1080 respectively. Requires one Instagram still or a composition; crops the final image and enlarges small sources." }, "crop": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 100 }, "y": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": ["x", "y"], "additionalProperties": false, "description": "Crop position from left/top (0) to right/bottom (100); default centered (50,50). Ignored for original dimensions." }, "includeCredits": { "type": "boolean", "description": "Default false. Produces a ZIP containing media, metadata.json and UTF-8 crediti.txt, including for a single image or composition." } }, "required": ["selections"], "additionalProperties": false }, "Inspection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "platform": { "enum": ["instagram", "x", "facebook", "tiktok"] }, "title": { "type": "string" }, "expiresAt": { "type": "integer" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/Media" } } }, "required": ["id", "media", "expiresAt"], "additionalProperties": false }, "Key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "enum": ["inspect", "export", "read"] } }, "created": { "type": "integer" }, "revoked": { "type": ["integer", "null"] } }, "required": [], "additionalProperties": false } } }, "paths": { "/auth/login": { "post": { "summary": "Sign in", "description": "JSON browser session. HttpOnly strict cookie, 12 hours. Foreign Origin denied. 429 when the source or email limit is exceeded or all password checks are busy.", "operationId": "post__auth_login", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } }, "required": ["email", "password"], "additionalProperties": false } } } } } }, "/auth/logout": { "post": { "summary": "Sign out", "description": "Revokes the current browser session.", "operationId": "post__auth_logout", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } } } }, "/v1/me": { "get": { "summary": "Current account", "description": "Identity and workspace; no secrets.", "operationId": "get__v1_me", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "workspace": { "type": "string" }, "fixtures": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ] } }, "/v1/keys": { "get": { "summary": "List own API keys", "description": "Browser session only. Hashes and raw key material are never returned.", "operationId": "get__v1_keys", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Key" } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ] }, "post": { "summary": "Create scoped API key", "description": "Browser session only. The random bearer key is returned once.", "operationId": "post__v1_keys", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" } }, "required": ["id", "key"], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "enum": ["inspect", "export", "read"] } } }, "required": ["name", "scopes"], "additionalProperties": false } } } } } }, "/v1/keys/{id}": { "delete": { "summary": "Revoke key", "description": "Browser session only; ownership enforced.", "operationId": "delete__v1_keys_id", "responses": { "204": { "description": "Revoked (no body)" }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/social/inspect": { "post": { "summary": "Inspect public social media", "description": "Scope inspect. Instagram post/reel/profile returns individual media. Other platforms return a single post/video bundle. 15 minute lifetime. Upstream media URLs never leave the server. 429 when the inspection wait list is full.", "operationId": "post__v1_social_inspect", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inspection" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000 } }, "required": ["url"], "additionalProperties": false } } } } } }, "/v1/social/inspections/{id}/media/{index}/preview": { "get": { "summary": "Preview selected image", "description": "Scope inspect. Owner protected, bounded proxied JPEG preview; expired inspection returns 404.", "operationId": "get__v1_social_inspections_id_media_index_preview", "responses": { "200": { "description": "JPEG image", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "index", "required": true, "schema": { "type": "integer", "minimum": 0, "maximum": 19 } } ] } }, "/v1/social/exports": { "post": { "summary": "Queue an export", "description": "Scope export. One process, one durable export at a time; max 50 queued/running globally. Select 1–20 media. Compose requires 2–4 Instagram stills; grid requires 3–4 and diagonal exactly 2. Idempotency replay returns 200; conflicting replay returns 409. Selection order determines composition order. Optional editorial format/crop and credits archive; omitted options preserve existing exports.", "operationId": "post__v1_social_exports", "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" }, "200": { "description": "Existing matching job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$" } } ] }, "get": { "summary": "List recent own exports", "description": "Scope read. Up to 50 latest jobs, newest first. Millisecond UTC timestamps.", "operationId": "get__v1_social_exports", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } } }, "required": ["jobs"], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ] } }, "/v1/social/exports/{id}": { "get": { "summary": "Get export status and provenance", "description": "Scope read. Ownership and workspace enforced; foreign and nonexistent identifiers return 404.", "operationId": "get__v1_social_exports_id", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/social/exports/{id}/download": { "get": { "summary": "Download completed export", "description": "Scope read. Owner protected. Local files stream with attachment filename; private R2 uses 302 to a signed URL valid for at most 60s and remaining job lifetime. 409 pending/running, 410 expired.", "operationId": "get__v1_social_exports_id_download", "responses": { "200": { "description": "Binary media or archive", "headers": { "Content-Disposition": { "schema": { "type": "string" } } }, "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } }, "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" }, "302": { "description": "R2 signed download", "headers": { "Location": { "schema": { "type": "string", "format": "uri" } } } } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/health/live": { "get": { "summary": "Process liveness", "description": "Does not establish provider extraction or R2 access.", "operationId": "get__health_live", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [] } }, "/health/ready": { "get": { "summary": "SQLite readiness", "description": "Does not establish provider extraction or R2 access.", "operationId": "get__health_ready", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [] } }, "/v1/social/preview": { "post": { "summary": "Preview the final image", "description": "Scope inspect. Same rendering as export, reduced to fit 600x600. Requires one Instagram still or a valid composition; includeCredits is ignored. Ownership and inspection expiry enforced. Returns 429 immediately while an export or another editor preview occupies the renderer. No job or file is persisted.", "operationId": "post__v1_social_preview", "responses": { "200": { "description": "JPEG image", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Scope or origin denied" }, "404": { "description": "Unknown or foreign resource" }, "409": { "description": "Conflict / not ready" }, "410": { "description": "Expired file" }, "429": { "description": "Rate, queue or processing limit" }, "500": { "description": "Service failure" } }, "security": [ { "bearerAuth": [] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRequest" } } } } } } } }