{ "openapi": "3.0.3", "info": { "title": "Unicorn Platform Partner API", "version": "1.0.0", "description": "CMS-style blog content and redirects API. These endpoints use the Seobot webhook key as a bearer token." }, "servers": [ { "url": "/", "description": "Current host. The same routes are available through the shared backend host and partner-api host." } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Blog" }, { "name": "Posts" }, { "name": "Redirects" } ], "paths": { "/api/v1/blog": { "get": { "tags": [ "Blog" ], "summary": "Get the current blog for the authenticated website.", "operationId": "getPartnerBlog", "responses": { "200": { "description": "Blog details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Blog" } } } }, "404": { "description": "The authenticated website has no active blog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Blog" ], "summary": "Create the active blog for the authenticated website.", "description": "A website can have only one active blog. Returns 409 when an active blog already exists.", "operationId": "createPartnerBlog", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogInput" } } } }, "responses": { "201": { "description": "Blog was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Blog" } } } }, "400": { "description": "Invalid blog payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The authenticated website already has an active blog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Blog" ], "summary": "Update the active blog for the authenticated website.", "operationId": "updatePartnerBlog", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlogPatch" } } } }, "responses": { "200": { "description": "Blog was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Blog" } } } }, "400": { "description": "Invalid blog payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The authenticated website has no active blog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Blog" ], "summary": "Soft-delete the active blog for the authenticated website.", "operationId": "deletePartnerBlog", "responses": { "204": { "description": "Blog was soft-deleted." }, "404": { "description": "The authenticated website has no active blog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/posts": { "get": { "tags": [ "Posts" ], "summary": "List blog posts for the authenticated website.", "operationId": "listPartnerPosts", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "includeHtml", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include post HTML in list items. Defaults to false. Page size is capped at 25 when true." }, { "name": "published", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true returns public posts, false returns non-public posts." }, { "name": "slug", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "directory", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Simple case-insensitive search over prepared text content." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "-updatedAt", "updatedAt", "-createdAt", "createdAt", "-headline", "headline" ], "default": "-updatedAt" } } ], "responses": { "200": { "description": "Paginated post list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostList" } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The authenticated website has no active blog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Posts" ], "summary": "Create a blog post for the authenticated website.", "operationId": "createPartnerPost", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostInput" } } } }, "responses": { "201": { "description": "Post was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Invalid post payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The authenticated website has no active blog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Post path already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/posts/{post_public_id}": { "get": { "tags": [ "Posts" ], "summary": "Get one blog post by public id.", "operationId": "getPartnerPost", "parameters": [ { "name": "post_public_id", "in": "path", "required": true, "schema": { "type": "string", "example": "post_abc123def" } }, { "name": "includeHtml", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include post HTML. Defaults to true for detail endpoints." } ], "responses": { "200": { "description": "Post details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Post not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Posts" ], "summary": "Update one blog post by public id.", "operationId": "updatePartnerPost", "parameters": [ { "name": "post_public_id", "in": "path", "required": true, "schema": { "type": "string", "example": "post_abc123def" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostPatch" } } } }, "responses": { "200": { "description": "Post was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Invalid post payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Post not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Post path already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Posts" ], "summary": "Soft-delete one blog post by public id.", "operationId": "deletePartnerPost", "parameters": [ { "name": "post_public_id", "in": "path", "required": true, "schema": { "type": "string", "example": "post_abc123def" } } ], "responses": { "204": { "description": "Post was soft-deleted." }, "404": { "description": "Post not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/posts/by-path": { "get": { "tags": [ "Posts" ], "summary": "Get one blog post by public URL path.", "operationId": "getPartnerPostByPath", "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "example": "/blog/my-post" } }, { "name": "includeHtml", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Include post HTML. Defaults to true for detail endpoints." } ], "responses": { "200": { "description": "Post details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Missing or invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Post not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/redirects": { "get": { "tags": [ "Redirects" ], "summary": "List redirects for the authenticated website.", "description": "This endpoint lists redirects stored in the Redirect table. Redirects are rendered before live content, matching the legacy dashboard redirects behavior.", "operationId": "listPartnerRedirects", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "perPage", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Paginated redirect list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectList" } } } }, "400": { "description": "Invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Redirects" ], "summary": "Create a redirect.", "operationId": "createPartnerRedirect", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectInput" } } } }, "responses": { "201": { "description": "Redirect was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Redirect" } } } }, "400": { "description": "Invalid redirect payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Redirect from path already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/redirects/{redirect_public_id}": { "get": { "tags": [ "Redirects" ], "summary": "Get one redirect by public id.", "operationId": "getPartnerRedirect", "parameters": [ { "name": "redirect_public_id", "in": "path", "required": true, "schema": { "type": "string", "example": "rdr_abc123def" } } ], "responses": { "200": { "description": "Redirect details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Redirect" } } } }, "404": { "description": "Redirect not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Redirects" ], "summary": "Update a redirect.", "operationId": "updatePartnerRedirect", "parameters": [ { "name": "redirect_public_id", "in": "path", "required": true, "schema": { "type": "string", "example": "rdr_abc123def" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectPatch" } } } }, "responses": { "200": { "description": "Redirect was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Redirect" } } } }, "400": { "description": "Invalid redirect payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Redirect not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Redirect from path already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Redirects" ], "summary": "Soft-delete one redirect by public id.", "operationId": "deletePartnerRedirect", "parameters": [ { "name": "redirect_public_id", "in": "path", "required": true, "schema": { "type": "string", "example": "rdr_abc123def" } } ], "responses": { "204": { "description": "Redirect was soft-deleted." }, "404": { "description": "Redirect not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/redirects/by-source": { "get": { "tags": [ "Redirects" ], "summary": "Get one redirect by source path.", "operationId": "getPartnerRedirectBySource", "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "example": "/old-path" } } ], "responses": { "200": { "description": "Redirect details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Redirect" } } } }, "400": { "description": "Missing or invalid query parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Redirect not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Use Website.webhooks[\"seobot\"] as the bearer token." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "example": "Unauthorized" } } }, "Blog": { "type": "object", "required": [ "id", "postsDirectory", "metaTitle", "metaDescription", "canonicalOrigin", "hosts", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "example": "blog_abc123def" }, "postsDirectory": { "type": "string", "example": "/blog" }, "metaTitle": { "type": "string" }, "metaDescription": { "type": "string" }, "canonicalOrigin": { "type": "string", "example": "https://example.com" }, "hosts": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "BlogInput": { "type": "object", "properties": { "postsDirectory": { "type": "string", "description": "Blog root directory. Defaults to /blog when omitted.", "example": "/blog" }, "metaTitle": { "type": "string" }, "metaDescription": { "type": "string" } } }, "BlogPatch": { "type": "object", "minProperties": 1, "properties": { "postsDirectory": { "type": "string", "description": "Blog root directory.", "example": "/blog" }, "metaTitle": { "type": "string" }, "metaDescription": { "type": "string" } } }, "Post": { "type": "object", "required": [ "id", "headline", "metaTitle", "metaDescription", "thumbnailUrl", "slug", "directory", "path", "url", "published", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "example": "post_abc123def" }, "headline": { "type": "string" }, "metaTitle": { "type": "string" }, "metaDescription": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "html": { "type": "string", "description": "Present when includeHtml is true, and included by default for detail endpoints." }, "slug": { "type": "string", "example": "my-post" }, "directory": { "type": "string", "example": "/blog" }, "path": { "type": "string", "example": "/blog/my-post" }, "url": { "type": "string", "example": "https://example.com/blog/my-post" }, "published": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PostInput": { "type": "object", "required": [ "headline", "html", "slug" ], "properties": { "headline": { "type": "string", "example": "How to build a landing page" }, "metaTitle": { "type": "string", "description": "Defaults to headline when omitted." }, "metaDescription": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "html": { "type": "string", "example": "

Post content

" }, "slug": { "type": "string", "description": "Single URL segment, without slashes, query string, or fragment.", "example": "my-post" }, "directory": { "type": "string", "description": "Post directory. Omit it to use the active blog directory; use another directory such as /news for alternate folders.", "example": "/blog" }, "published": { "type": "boolean", "default": true }, "createdAt": { "type": "string", "format": "date-time", "description": "Optional published/created timestamp to preserve imported content dates." } } }, "PostPatch": { "type": "object", "minProperties": 1, "properties": { "headline": { "type": "string" }, "metaTitle": { "type": "string" }, "metaDescription": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "html": { "type": "string" }, "slug": { "type": "string", "description": "Single URL segment, without slashes, query string, or fragment." }, "directory": { "type": "string", "description": "Post directory. Use the active blog directory to move the post back to the default blog folder." }, "published": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "description": "Optional published/created timestamp to preserve imported content dates." } } }, "PostList": { "type": "object", "required": [ "items", "page", "perPage", "total", "hasMore" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } }, "page": { "type": "integer" }, "perPage": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } } }, "Redirect": { "type": "object", "required": [ "id", "from", "to", "statusCode", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "example": "rdr_abc123def" }, "from": { "type": "string", "example": "/old-path" }, "to": { "type": "string", "example": "/new-path" }, "statusCode": { "type": "integer", "enum": [ 301 ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "RedirectInput": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "description": "Local source path without query string or fragment. It is normalized to a leading slash and lower case.", "example": "/old-path" }, "to": { "type": "string", "description": "Legacy-style destination: a relative site path such as new-path or /new-path, or an absolute http/https URL.", "example": "new-path" }, "statusCode": { "type": "integer", "enum": [ 301 ], "default": 301 } } }, "RedirectPatch": { "type": "object", "minProperties": 1, "properties": { "from": { "type": "string", "description": "Local source path without query string or fragment. It is normalized to a leading slash and lower case.", "example": "/old-path" }, "to": { "type": "string", "description": "Legacy-style destination: a relative site path such as new-path or /new-path, or an absolute http/https URL.", "example": "new-path" }, "statusCode": { "type": "integer", "enum": [ 301 ] } } }, "RedirectList": { "type": "object", "required": [ "items", "page", "perPage", "total", "hasMore" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Redirect" } }, "page": { "type": "integer" }, "perPage": { "type": "integer" }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } } } } } }