{ "openapi": "3.1.0", "info": { "title": "Headless Profeed API", "version": "1.0.0", "description": "Public LinkedIn company, showcase, and school feeds. Protected feed requests require an active subscription. Browser keys are public, read-only, and require a matching Origin." }, "servers": [ { "url": "https://api.profeedwp.com/api/headless-profeed/v1" } ], "tags": [ { "name": "Feeds" }, { "name": "Account" }, { "name": "Billing" } ], "paths": { "/demo": { "get": { "summary": "Read the fixed public demo feed", "responses": { "200": { "description": "Demo posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedResponse" } } } }, "202": { "description": "Background refresh accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "retry_after_seconds": { "type": "integer", "example": 5 } } } } } }, "429": { "description": "Demo allowance reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pricing": { "get": { "summary": "Public plan metadata and checkout readiness", "responses": { "200": { "description": "Pricing", "content": { "application/json": { "schema": { "type": "object", "properties": { "ready": { "type": "boolean" }, "sandbox": { "type": "boolean" }, "currency": { "const": "USD" }, "tiers": { "type": "array", "items": { "type": "object" } } } } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/readiness": { "get": { "summary": "Public service readiness", "responses": { "200": { "description": "Feature and checkout state" } } } }, "/feeds": { "get": { "tags": [ "Feeds" ], "summary": "List account feeds using a secret key", "security": [ { "secretOrPublishableKey": [] }, { "apiKeyHeader": [] } ], "responses": { "200": { "description": "Configured feed connections", "content": { "application/json": { "schema": { "type": "object", "properties": { "feeds": { "type": "array", "items": { "$ref": "#/components/schemas/Feed" } } } } } } }, "401": { "description": "Invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Subscription or secret key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Allowance reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/feeds/{id}/posts": { "get": { "tags": [ "Feeds" ], "summary": "Read visible posts", "security": [ { "secretOrPublishableKey": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Posts, including available stale posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedResponse" } } } }, "202": { "description": "Initial collection pending; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedResponse" } } } }, "400": { "description": "Invalid pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Subscription, scope, or origin denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Feed not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Allowance reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable or initial collection failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/feeds/{id}/status": { "get": { "tags": [ "Feeds" ], "summary": "Read refresh status", "security": [ { "secretOrPublishableKey": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Refresh status", "content": { "application/json": { "schema": { "type": "object", "properties": { "feed_id": { "type": "string", "format": "uuid" }, "refresh": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "idle", "queued", "running", "failed" ] }, "last_success_at": { "type": [ "string", "null" ] }, "next_refresh_at": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" } } } } } } } }, "401": { "description": "Invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Feed not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Allowance reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/feeds/{id}/refresh": { "post": { "tags": [ "Feeds" ], "summary": "Request a manual refresh using a secret key", "security": [ { "secretOrPublishableKey": [] }, { "apiKeyHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Background refresh accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "retry_after_seconds": { "type": "integer", "example": 5 } } } } } }, "401": { "description": "Invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Secret key or subscription required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Feed not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Allowance reached or 15-minute source cooldown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account": { "get": { "tags": [ "Account" ], "summary": "Load the signed-in account, entitlement, feed connections, key metadata, and pricing", "security": [ { "accountSession": [] } ], "responses": { "200": { "description": "Own account only; full API keys are never returned here" }, "401": { "description": "Sign-in required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/feeds": { "post": { "tags": [ "Account" ], "summary": "Connect a public LinkedIn page", "security": [ { "accountSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "company_url" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "company_url": { "type": "string", "format": "uri", "example": "https://www.linkedin.com/company/example" } } } } } }, "responses": { "201": { "description": "Feed connected; initial refresh enqueued" }, "400": { "description": "Invalid source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Subscription or feed allowance required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Duplicate source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/feeds/{id}": { "patch": { "tags": [ "Account" ], "summary": "Rename, pause, or enable an owned feed", "security": [ { "accountSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Updated feed" }, "403": { "description": "Active feed allowance reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Feed not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Account" ], "summary": "Remove an owned feed connection", "security": [ { "accountSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Removed" }, "404": { "description": "Feed not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/feeds/{id}/preview": { "get": { "tags": [ "Account" ], "summary": "Preview owned feed posts using the account session", "security": [ { "accountSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedResponse" } } } }, "202": { "description": "Initial collection pending" }, "403": { "description": "Subscription or enabled feed required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Feed not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/feeds/{id}/refresh": { "post": { "tags": [ "Account" ], "summary": "Queue an owned feed refresh from the dashboard", "security": [ { "accountSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Background refresh accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "retry_after_seconds": { "type": "integer", "example": 5 } } } } } }, "429": { "description": "Source cooldown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/keys": { "post": { "tags": [ "Account" ], "summary": "Create a key; full value is returned once", "security": [ { "accountSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "kind" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "kind": { "enum": [ "secret", "publishable" ] }, "feed_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 25 }, "origins": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 } } } } } }, "responses": { "201": { "description": "One-time key value", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid scope or origins", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Subscription required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/keys/{id}": { "patch": { "tags": [ "Account" ], "summary": "Update key name and browser scope; kind is immutable", "security": [ { "accountSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "kind" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "kind": { "enum": [ "secret", "publishable" ] }, "feed_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 25 }, "origins": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 20 } } } } } }, "responses": { "200": { "description": "Updated key metadata" }, "400": { "description": "Invalid scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Account" ], "summary": "Revoke a key", "security": [ { "accountSession": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Revoked" }, "404": { "description": "Key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/billing/checkout": { "post": { "tags": [ "Billing" ], "summary": "Create a verified-account checkout or upgrade link", "security": [ { "accountSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tier", "cycle" ], "properties": { "tier": { "enum": [ "single", "business", "agency" ] }, "cycle": { "enum": [ "monthly", "annual" ] } } } } } }, "responses": { "200": { "description": "Hosted checkout URL" }, "503": { "description": "Checkout not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/billing/confirm": { "post": { "tags": [ "Billing" ], "summary": "Verify a signed checkout return bound to the account", "security": [ { "accountSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } } } } }, "responses": { "200": { "description": "Synchronized entitlement" }, "403": { "description": "Purchase ownership or signature denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/billing/sync": { "post": { "tags": [ "Billing" ], "summary": "Reconcile the linked purchase against Freemius", "security": [ { "accountSession": [] } ], "responses": { "200": { "description": "Current entitlement" }, "404": { "description": "No linked purchase", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/billing/portal": { "post": { "tags": [ "Billing" ], "summary": "Open the account’s hosted billing portal", "security": [ { "accountSession": [] } ], "responses": { "200": { "description": "Hosted portal URL" }, "404": { "description": "No linked billing account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "secretOrPublishableKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Headless Profeed API key" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "accountSession": { "type": "http", "scheme": "bearer", "bearerFormat": "Supabase access token" } }, "schemas": { "Error": { "type": "object", "required": [ "success", "error", "message" ], "properties": { "success": { "const": false }, "error": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "Feed": { "type": "object", "required": [ "id", "name", "company_url", "enabled" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "company_url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" } } }, "Post": { "type": "object", "required": [ "id", "text", "media_items" ], "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "headline": { "type": [ "string", "null" ] }, "date_published": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] }, "company_avatar_url": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "is_video": { "type": "boolean" }, "video_url": { "type": [ "string", "null" ] }, "media_items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] } } } }, "engagement_likes": { "type": [ "integer", "null" ] }, "engagement_comments": { "type": [ "integer", "null" ] }, "engagement_shares": { "type": [ "integer", "null" ] } } }, "FeedResponse": { "type": "object", "required": [ "success", "feed_id", "company_url", "posts", "total_posts", "page", "page_size", "refresh" ], "properties": { "success": { "const": true }, "feed_id": { "type": "string" }, "company_url": { "type": "string", "format": "uri" }, "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "total_posts": { "type": "integer" }, "page": { "type": "integer" }, "page_size": { "type": "integer" }, "refresh": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "idle", "queued", "running", "failed" ] }, "last_success_at": { "type": [ "string", "null" ] }, "next_refresh_at": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" } } }, "retry_after_seconds": { "type": "integer" } } } } } }