{
  "openapi": "3.1.0",
  "info": {
    "title": "Beulog Publishing API",
    "version": "1.2.2",
    "description": "Keep workspace keys server-side. Published content only by default. 120 requests/minute/key. Generation is limited to 20 jobs/hour/account."
  },
  "servers": [
    {
      "url": "https://beulog.com/api/v1",
      "description": "Beulog production"
    },
    {
      "url": "/api/v1",
      "description": "Current installation"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error", "code"],
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        }
      },
      "Article": {
        "type": "object",
        "required": [
          "id",
          "revision",
          "html",
          "head_html",
          "seo",
          "json_ld",
          "content",
          "schema_version"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "schema_version": {
            "const": "1.1"
          },
          "revision": {
            "type": "string",
            "description": "Opaque digest of content and workspace publishing settings; compare for change detection."
          },
          "version": {
            "type": "integer"
          },
          "status": {
            "enum": ["draft", "published"]
          },
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "html": {
            "type": "string",
            "description": "Escaped semantic article fragment for the page body."
          },
          "head_html": {
            "type": "string",
            "description": "Server-rendered head metadata and safely serialized JSON-LD. Use this OR map seo/json_ld through your framework, never both."
          },
          "content": {
            "type": "object",
            "description": "Editable structured sections, subsections, steps, tables, callouts, FAQs, imageAlt and imageCaption."
          },
          "seo": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "canonical": {
                "type": ["string", "null"],
                "format": "uri"
              },
              "robots": {
                "type": "string"
              },
              "language": {
                "type": "string"
              },
              "openGraph": {
                "type": "object"
              },
              "twitter": {
                "type": "object"
              }
            }
          },
          "json_ld": {
            "type": "object"
          },
          "publishing_checks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "passed": {
                  "type": "boolean"
                }
              }
            }
          },
          "image_url": {
            "type": ["string", "null"]
          },
          "image_width": {
            "type": ["integer", "null"]
          },
          "image_height": {
            "type": ["integer", "null"]
          }
        }
      },
      "ArticlePage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Article"
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer"
              },
              "offset": {
                "type": ["integer", "null"]
              },
              "has_more": {
                "type": "boolean"
              },
              "next_cursor": {
                "type": ["string", "null"],
                "description": "Opaque cursor. Keep the same workspace and drafts filter. Null ends the list."
              },
              "next_offset": {
                "type": ["integer", "null"],
                "description": "Legacy offset pagination; prefer next_cursor."
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/articles": {
      "get": {
        "summary": "List articles with rendered HTML and JSON-LD",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100000,
              "default": 0
            }
          },
          {
            "in": "query",
            "name": "drafts",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Requires drafts:read scope"
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string",
              "maxLength": 1000
            },
            "description": "Use pagination.next_cursor from the previous page. Do not combine with offset."
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Article page; detail returns a one-item data array.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-API-Version": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticlePage"
                }
              }
            }
          },
          "401": {
            "description": "Invalid key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "304": {
            "description": "Unchanged since If-None-Match. No response body; use your stored copy."
          },
          "400": {
            "description": "Invalid query or cursor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/articles/{id}": {
      "get": {
        "summary": "Retrieve one article",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "drafts",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Set drafts=true to retrieve an unpublished article. Requires drafts:read in addition to articles:read."
          },
          {
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Article page; detail returns a one-item data array.",
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-API-Version": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ArticlePage"
                }
              }
            }
          },
          "404": {
            "description": "Not found in this workspace"
          },
          "304": {
            "description": "Unchanged since If-None-Match. No response body; use your stored copy."
          },
          "400": {
            "description": "Invalid query or cursor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/generate": {
      "post": {
        "summary": "Queue a generation job (articles:generate scope)",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "topic": {
                    "type": "string",
                    "maxLength": 1500
                  },
                  "image": {
                    "type": "boolean",
                    "default": true
                  },
                  "autoPublish": {
                    "type": "boolean",
                    "default": false
                  },
                  "kind": {
                    "type": "string",
                    "enum": ["article", "research"],
                    "default": "article"
                  },
                  "researchId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optional existing research brief in the same workspace to use for generation."
                  },
                  "maxCredits": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1000000,
                    "description": "Optional spending guard. A current reservation above this limit returns 409 without charging."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Job ID, status, cost (reserved while pending; final charge after completion), reserved_credits, settled_at. Same idempotency key returns the existing job without another reservation."
          },
          "402": {
            "description": "Insufficient credits"
          },
          "403": {
            "description": "Missing scope or unverified account"
          },
          "429": {
            "description": "Rate limit"
          },
          "409": {
            "description": "Reservation exceeds maxCredits; retrieve /pricing and review the limit."
          }
        }
      }
    },
    "/jobs/{id}": {
      "get": {
        "summary": "Poll a generation job (articles:generate scope)",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Job state including cost, reserved_credits and settled_at. On completion cost is the final charge; failures are fully refunded. No provider cost information is returned."
          },
          "404": {
            "description": "Job not found in this workspace"
          }
        }
      }
    },
    "/connection": {
      "get": {
        "summary": "Validate publishing access and identify the workspace",
        "responses": {
          "200": {
            "description": "Connected workspace and permissions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_version": {
                      "type": "string"
                    },
                    "workspace": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "language": {
                          "type": "string"
                        }
                      }
                    },
                    "scopes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "analytics": {
                      "type": ["object", "null"],
                      "description": "Public browser configuration when analytics is enabled. Publishing API keys must remain server-side. See docs/embedding-and-analytics.md.",
                      "properties": {
                        "site_id": {
                          "type": "string",
                          "pattern": "^[a-f0-9]{36}$"
                        },
                        "consent_required": {
                          "type": "boolean",
                          "const": true
                        },
                        "allowed_origins": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/sync": {
      "get": {
        "summary": "Discover new or changed published articles without downloading their bodies",
        "description": "Uses an inclusive five-minute overlap for commit timing. Deduplicate using id and revision. Advance checkpoint and settings_revision only after queuing every page. Workspace setting changes trigger a full scan. This feed does not delete already imported posts. A 400 cursor response requires restarting the current scan.",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "in": "query",
            "name": "since",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "in": "query",
            "name": "settings_revision",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string",
              "maxLength": 2000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lightweight published-article manifest",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workspace_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "settings_revision": {
                      "type": "string"
                    },
                    "checkpoint": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "title": {
                            "type": "string"
                          },
                          "revision": {
                            "type": "string",
                            "description": "Manifest change token, distinct from full export revision."
                          }
                        }
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "next_cursor": {
                          "type": ["string", "null"]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or outdated cursor. Restart current scan."
          },
          "401": {
            "description": "Invalid key"
          },
          "403": {
            "description": "Requires articles:read"
          },
          "429": {
            "description": "Retry after Retry-After header"
          }
        }
      }
    },
    "/pricing": {
      "get": {
        "summary": "Get generation credit limits",
        "description": "Requires articles:generate. Limits are reservations; unused credits are automatically returned after successful completion. Failed jobs are fully refunded.",
        "responses": {
          "200": {
            "description": "Current maximum credit reservations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "billing": {
                      "type": "string",
                      "enum": ["usage_based"]
                    },
                    "article": {
                      "type": "integer"
                    },
                    "article_with_image": {
                      "type": "integer"
                    },
                    "research": {
                      "type": "integer"
                    },
                    "description": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Missing articles:generate scope"
          }
        }
      }
    }
  }
}