{
  "openapi": "3.1.0",
  "info": {
    "title": "MonoChalk API",
    "version": "0.1.0-beta",
    "description": "Public quickstart specification for the MonoChalk unified social media publishing API. MonoChalk is in private beta; enabled platform connections can vary by workspace.",
    "contact": {
      "name": "MonoChalk",
      "url": "https://www.monochalk.com/pages/about.html",
      "email": "contact@monochalk.com"
    }
  },
  "servers": [{ "url": "https://app.monochalk.com", "description": "Production beta API" }],
  "externalDocs": {
    "description": "MonoChalk developer quickstart",
    "url": "https://www.monochalk.com/pages/docs.html"
  },
  "tags": [
    { "name": "Service" },
    { "name": "Accounts" },
    { "name": "OAuth" },
    { "name": "Posts" }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["Service"],
        "summary": "Check API process health",
        "security": [],
        "responses": {
          "200": {
            "description": "API is reachable",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }
          }
        }
      }
    },
    "/v1/accounts": {
      "get": {
        "tags": ["Accounts"],
        "summary": "List connected social accounts",
        "responses": {
          "200": { "description": "Connected accounts for the authenticated workspace" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/oauth/{platform}/start": {
      "get": {
        "tags": ["OAuth"],
        "summary": "Start a managed platform OAuth flow",
        "parameters": [{
          "name": "platform",
          "in": "path",
          "required": true,
          "schema": { "$ref": "#/components/schemas/Platform" }
        }],
        "responses": {
          "200": {
            "description": "Platform authorization URL",
            "content": { "application/json": { "schema": { "type": "object", "required": ["authorization_url"], "properties": { "authorization_url": { "type": "string", "format": "uri" } } } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/oauth/bluesky/connect": {
      "post": {
        "tags": ["Accounts"],
        "summary": "Connect a Bluesky account with an app password",
        "description": "Exchanges the app password for AT Protocol session tokens. The app password is never stored.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["identifier", "app_password"], "properties": { "identifier": { "type": "string", "example": "alice.bsky.social" }, "app_password": { "type": "string", "format": "password" } } } } }
        },
        "responses": {
          "200": { "description": "Bluesky account connected" },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/posts": {
      "post": {
        "tags": ["Posts"],
        "summary": "Publish now or schedule a post",
        "parameters": [{
          "name": "Idempotency-Key",
          "in": "header",
          "required": false,
          "description": "Unique caller-generated key that makes creation retries safe.",
          "schema": { "type": "string" }
        }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePost" } } }
        },
        "responses": {
          "201": { "description": "Post created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "get": {
        "tags": ["Posts"],
        "summary": "List posts",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "A cursor-paginated post list" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/v1/posts/{id}": {
      "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": {
        "tags": ["Posts"],
        "summary": "Get one post and its delivery targets",
        "responses": {
          "200": { "description": "Post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "delete": {
        "tags": ["Posts"],
        "summary": "Cancel a post that has not completed delivery",
        "responses": {
          "200": { "description": "Post canceled" },
          "202": { "description": "Some targets were already processing" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "description": "Post can no longer be canceled" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "MonoChalk API key" }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "required": ["status"],
        "properties": { "status": { "type": "string", "const": "ok" } }
      },
      "Platform": {
        "type": "string",
        "enum": ["facebook", "instagram", "threads", "linkedin", "x", "tiktok", "youtube", "pinterest", "bluesky"]
      },
      "MediaInput": {
        "oneOf": [
          { "type": "object", "required": ["media_id"], "properties": { "media_id": { "type": "string" } } },
          { "type": "object", "required": ["type", "url"], "properties": { "type": { "type": "string", "enum": ["image", "video"] }, "url": { "type": "string", "format": "uri" } } }
        ]
      },
      "AccountTarget": {
        "oneOf": [
          { "type": "string" },
          { "type": "object", "required": ["account_id"], "properties": { "account_id": { "type": "string" }, "board_id": { "type": "string", "description": "Pinterest only" } } }
        ]
      },
      "CreatePost": {
        "type": "object",
        "required": ["account_ids"],
        "properties": {
          "account_ids": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/AccountTarget" } },
          "text": { "type": ["string", "null"] },
          "media": { "type": "array", "items": { "$ref": "#/components/schemas/MediaInput" }, "default": [] },
          "scheduled_at": { "type": ["string", "null"], "format": "date-time" },
          "scheduled_tz": { "type": ["string", "null"] }
        }
      },
      "PostTarget": {
        "type": "object",
        "properties": {
          "platform": { "$ref": "#/components/schemas/Platform" },
          "status": { "type": "string" },
          "account_id": { "type": ["string", "null"] },
          "platform_post_id": { "type": ["string", "null"] },
          "error_code": { "type": ["string", "null"] },
          "error_message": { "type": ["string", "null"] }
        }
      },
      "Post": {
        "type": "object",
        "required": ["id", "status", "targets"],
        "properties": {
          "id": { "type": "string" },
          "status": { "type": "string" },
          "text": { "type": ["string", "null"] },
          "scheduled_at": { "type": ["string", "null"], "format": "date-time" },
          "published_at": { "type": ["string", "null"], "format": "date-time" },
          "created_at": { "type": "string", "format": "date-time" },
          "targets": { "type": "array", "items": { "$ref": "#/components/schemas/PostTarget" } }
        }
      },
      "Error": {
        "type": "object",
        "required": ["code", "message", "retryable", "platform"],
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" },
          "retryable": { "type": "boolean" },
          "platform": { "type": ["string", "null"] },
          "details": { "type": "object", "additionalProperties": true }
        }
      }
    },
    "responses": {
      "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  },
  "security": [{ "bearerAuth": [] }]
}