{
  "openapi": "3.1.0",
  "info": {
    "title": "JustNeeda API",
    "version": "1.3.0",
    "summary": "Order websites, social media management, content packs and local SEO plans for small local businesses over HTTP.",
    "description": "JustNeeda (https://justneeda.com) is a turnkey, made-to-measure agency for small local businesses, US first. Websites: see the site before paying, 2 free changes, then $99/month, $0 down (hosting, SSL, domain, maintenance, 10 edits a month, local SEO basics, support), month-to-month. Every catalog service (social media management, content pack, local SEO and Google Business Profile) is a month-to-month plan in USD with $0 down. The same API exposes 32 AI writing tools (brand names, landing copy, ad sets, plans) through `POST /api/free-generate`.\n\nAn authenticated MCP server (Streamable HTTP, OAuth 2.1) is available at https://justneeda.com/api/mcp; see https://justneeda.com/docs/mcp.\n\nAnonymous endpoints are rate limited per IP. Generation endpoints call an AI model and take from a few seconds (writing tools) to a few minutes (websites, asynchronous: poll the preview).",
    "termsOfService": "https://justneeda.com/legal/terms",
    "contact": {
      "name": "JustNeeda support",
      "email": "contact@justneeda.com",
      "url": "https://justneeda.com/support"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://justneeda.com/legal/terms"
    },
    "x-logo": {
      "url": "https://justneeda.com/icon-512.png",
      "altText": "JustNeeda"
    },
    "x-privacy-policy": "https://justneeda.com/legal/privacy"
  },
  "externalDocs": {
    "description": "JustNeeda API and MCP documentation",
    "url": "https://justneeda.com/docs"
  },
  "servers": [
    {
      "url": "https://justneeda.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Websites",
      "description": "Free website previews, changes and publishing."
    },
    {
      "name": "Services",
      "description": "Catalog services (content pack, social media management, local SEO and Google Business Profile): order, follow delivery, revise."
    },
    {
      "name": "Writing tools",
      "description": "32 AI tools that turn a short brief into a first draft."
    },
    {
      "name": "MCP",
      "description": "Remote Model Context Protocol endpoint (JSON-RPC 2.0, OAuth 2.1)."
    },
    {
      "name": "System",
      "description": "Health and status."
    }
  ],
  "paths": {
    "/api/free-generate": {
      "post": {
        "tags": [
          "Writing tools"
        ],
        "operationId": "freeGenerate",
        "summary": "Run a writing tool (free tier)",
        "description": "Runs one of the writing tools on a free-text brief. No authentication: anonymous callers get a short teaser under a per-IP daily quota; passing `email` unlocks the email tier (3 full runs per tool per month). Signed-in users with a paid unlock or Pro subscription get unlimited full runs (session cookie).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FreeGenerateRequest"
              },
              "example": {
                "toolId": "instant-brand-name",
                "input": "A mobile dog grooming van serving Austin, Texas"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated draft (markdown).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FreeGenerateResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid toolId",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Invalid toolId"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted for this tier.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuotaError"
                }
              }
            }
          },
          "500": {
            "description": "Generation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Generation failed"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/generate": {
      "post": {
        "tags": [
          "Writing tools"
        ],
        "operationId": "generateWithApiKey",
        "summary": "Run a writing tool with an API key",
        "description": "Unlimited full runs with the best model. Requires an API key (Settings, API keys) and an active Pro subscription.",
        "security": [
          {
            "apiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "toolId",
                  "input"
                ],
                "properties": {
                  "toolId": {
                    "$ref": "#/components/schemas/ToolId"
                  },
                  "input": {
                    "type": "string",
                    "maxLength": 2000,
                    "description": "Free-text brief."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated draft.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "tool",
                    "output"
                  ],
                  "properties": {
                    "tool": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      }
                    },
                    "output": {
                      "type": "string",
                      "description": "Markdown."
                    },
                    "modelUsed": {
                      "type": "string"
                    },
                    "generationId": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid toolId",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Invalid toolId"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Invalid or revoked API key"
                }
              }
            }
          },
          "402": {
            "description": "API access requires an active Pro subscription",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "API access requires an active Pro subscription"
                }
              }
            }
          },
          "500": {
            "description": "Generation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Generation failed"
                }
              }
            }
          }
        }
      }
    },
    "/api/sites/draft": {
      "post": {
        "tags": [
          "Websites"
        ],
        "operationId": "createWebsitePreview",
        "summary": "Start a free website preview",
        "description": "Validates the brief and starts writing the website in the background. Returns the preview id immediately; poll `GET /api/sites/draft/{id}` until `status` is `ready` (about a minute). Limited to 3 previews per IP per day.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SiteBrief"
              },
              "example": {
                "businessName": "Harbor Lane Bakery",
                "description": "Neighbourhood sourdough bakery in Portland, Maine. Naturally leavened breads, morning pastries and custom celebration cakes ordered 48 hours ahead.",
                "email": "hello@example.com",
                "city": "Portland, Maine",
                "hours": "Tue-Sun 7am-2pm",
                "style": "warm",
                "language": "en"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preview started.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "id"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Describe what you do in a sentence or two (30 characters minimum).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Describe what you do in a sentence or two (30 characters minimum)."
                }
              }
            }
          },
          "403": {
            "description": "Previews are not available from this network.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Previews are not available from this network."
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Wait a minute and try again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Too many requests. Wait a minute and try again."
                }
              }
            }
          },
          "503": {
            "description": "We have hit today's preview capacity. Please try again in a few hours.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "We have hit today's preview capacity. Please try again in a few hours."
                }
              }
            }
          }
        }
      }
    },
    "/api/sites/draft/{id}": {
      "get": {
        "tags": [
          "Websites"
        ],
        "operationId": "getWebsitePreviewStatus",
        "summary": "Get a preview's status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Preview id (UUID) returned by POST /api/sites/draft.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Preview status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewStatus"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Not found"
                }
              }
            }
          }
        }
      }
    },
    "/api/sites/draft/{id}/revise": {
      "post": {
        "tags": [
          "Websites"
        ],
        "operationId": "reviseWebsitePreview",
        "summary": "Request a change to a preview",
        "description": "Applies one plain-English change in the background (poll the status). Previews include 2 changes.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Preview id (UUID) returned by POST /api/sites/draft.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "instruction"
                ],
                "properties": {
                  "instruction": {
                    "type": "string",
                    "minLength": 4,
                    "maxLength": 600
                  }
                }
              },
              "example": {
                "instruction": "Make the headline warmer and mention the custom cakes."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Change accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Describe the change you want.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Describe the change you want."
                }
              }
            }
          },
          "403": {
            "description": "Previews include 2 changes. Put the site online to get 10 changes every month.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Previews include 2 changes. Put the site online to get 10 changes every month."
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Not found"
                }
              }
            }
          },
          "409": {
            "description": "The preview is not ready yet.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "The preview is not ready yet."
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Wait a minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Too many requests. Wait a minute."
                }
              }
            }
          }
        }
      }
    },
    "/api/sites/checkout": {
      "post": {
        "tags": [
          "Websites"
        ],
        "operationId": "startWebsiteCheckout",
        "summary": "Get a checkout link to put a preview online",
        "description": "Creates a Stripe Checkout session in subscription mode: the monthly plan (99 USD, $0 down, nothing else on the first invoice). Month-to-month: cancelled from the Stripe billing portal; at the end of the subscription the site is paused, not deleted. The site is published as soon as payment succeeds.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "draftId"
                ],
                "properties": {
                  "draftId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout URL to open in a browser.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Preview not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Preview not found."
                }
              }
            }
          },
          "409": {
            "description": "This site is already published.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "This site is already published."
                }
              }
            }
          },
          "503": {
            "description": "Payments are not configured.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Payments are not configured."
                }
              }
            }
          }
        }
      }
    },
    "/api/sites/order-status": {
      "get": {
        "tags": [
          "Websites"
        ],
        "operationId": "getWebsiteOrderStatus",
        "summary": "Check whether a paid site is live",
        "description": "Polled after Stripe redirects back. Only the payer knows the Checkout session id.",
        "parameters": [
          {
            "name": "session_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^cs_"
            },
            "description": "Stripe Checkout session id."
          }
        ],
        "responses": {
          "200": {
            "description": "Publication status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "published"
                  ],
                  "properties": {
                    "published": {
                      "type": "boolean"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "manageUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Private owner dashboard."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/preview/{id}": {
      "get": {
        "tags": [
          "Websites"
        ],
        "operationId": "renderWebsitePreview",
        "summary": "Render a preview as HTML",
        "description": "The full preview page (noindex). Use `example-<id>` for the public example sites.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Preview id (UUID) returned by POST /api/sites/draft.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML page.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Not found."
          }
        }
      }
    },
    "/api/offers": {
      "get": {
        "tags": [
          "Services"
        ],
        "operationId": "listServices",
        "summary": "List every service with price and brief fields",
        "description": "community: Social media management, $349/month, $0 down. content: Content pack, $199/month, $0 down. seo: Local SEO & Google Business Profile, $149/month, $0 down.",
        "responses": {
          "200": {
            "description": "The catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/offers/{offerId}/order": {
      "post": {
        "tags": [
          "Services"
        ],
        "operationId": "orderService",
        "summary": "Start a subscription and get a Stripe checkout link",
        "description": "Validates the brief against the offer's fields (see GET /api/offers), saves the order and returns a Stripe Checkout URL. The order is a month-to-month plan in USD with $0 down (no setup fee). The first delivery starts when payment succeeds, then every month; follow it at orderUrl. Nothing is charged by this call.",
        "parameters": [
          {
            "name": "offerId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "community",
                "content",
                "seo"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "brief"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "brief": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Keys from brief_fields of the offer."
                  }
                }
              },
              "example": {
                "email": "owner@example.com",
                "brief": {
                  "businessName": "Harbor Street Bakery",
                  "description": "Family bakery in Portland since 2019: sourdough, pastries, custom cakes.",
                  "website": "https://example.com"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "orderId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "orderUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "checkoutUrl": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Business name is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Business name is required."
                }
              }
            }
          },
          "429": {
            "description": "Too many requests. Wait a minute and try again.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Too many requests. Wait a minute and try again."
                }
              }
            }
          }
        }
      }
    },
    "/api/offers/orders/{token}": {
      "get": {
        "tags": [
          "Services"
        ],
        "operationId": "getOrder",
        "summary": "Order status and deliverables",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Private order token (48 hex characters) from the order URL. It is the credential for the order: keep it secret.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{48}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status, deliveries, scheduled posts and connections.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "404": {
            "description": "Order not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Order not found."
                }
              }
            }
          }
        }
      }
    },
    "/api/offers/orders/{token}/revise": {
      "post": {
        "tags": [
          "Services"
        ],
        "operationId": "reviseContent",
        "summary": "Rewrite one article or post of a content pack",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Private order token (48 hex characters) from the order URL. It is the credential for the order: keep it secret.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{48}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "deliveryId",
                  "target",
                  "instruction"
                ],
                "properties": {
                  "deliveryId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "target": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": [
                          "article",
                          "post"
                        ]
                      },
                      "index": {
                        "type": "integer",
                        "minimum": 0
                      }
                    }
                  },
                  "instruction": {
                    "type": "string",
                    "maxLength": 800
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated pack.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "No revisions left on this order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "No revisions left on this order."
                }
              }
            }
          }
        }
      }
    },
    "/api/offers/orders/{token}/recheck": {
      "post": {
        "tags": [
          "Services"
        ],
        "operationId": "recheckSeo",
        "summary": "Re-crawl the site of an SEO order",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Private order token (48 hex characters) from the order URL. It is the credential for the order: keep it secret.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{48}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The report with the new check.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/offers/orders/{token}/posts/{postId}": {
      "patch": {
        "tags": [
          "Services"
        ],
        "operationId": "updatePost",
        "summary": "Edit, rewrite, skip or restore a scheduled post",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Private order token (48 hex characters) from the order URL. It is the credential for the order: keep it secret.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{48}$"
            }
          },
          {
            "name": "postId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string"
                  },
                  "instruction": {
                    "type": "string"
                  },
                  "skip": {
                    "type": "boolean"
                  },
                  "restore": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "409": {
            "description": "This post is already published.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "This post is already published."
                }
              }
            }
          }
        }
      }
    },
    "/api/offers/orders/{token}/connections": {
      "post": {
        "tags": [
          "Services"
        ],
        "operationId": "connectNetwork",
        "summary": "Connect Bluesky, Mastodon or a publishing webhook",
        "description": "Credentials are verified with the network, then stored encrypted. Webhooks receive a signed test call.",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Private order token (48 hex characters) from the order URL. It is the credential for the order: keep it secret.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{48}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "network"
                ],
                "properties": {
                  "network": {
                    "type": "string",
                    "enum": [
                      "bluesky",
                      "mastodon",
                      "webhook"
                    ]
                  },
                  "identifier": {
                    "type": "string",
                    "description": "Bluesky handle"
                  },
                  "appPassword": {
                    "type": "string",
                    "description": "Bluesky app password"
                  },
                  "instance": {
                    "type": "string",
                    "description": "Mastodon server"
                  },
                  "token": {
                    "type": "string",
                    "description": "Mastodon access token"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Webhook URL (https)"
                  },
                  "networks": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Networks the webhook publishes to"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Connected.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Could not connect: Bluesky answered 401.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "Could not connect: Bluesky answered 401."
                }
              }
            }
          }
        }
      }
    },
    "/api/offers/orders/{token}/billing": {
      "get": {
        "tags": [
          "Services"
        ],
        "operationId": "listInvoices",
        "summary": "Invoices of the order",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Private order token (48 hex characters) from the order URL. It is the credential for the order: keep it secret.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{48}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invoices from Stripe.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Services"
        ],
        "operationId": "manageSubscription",
        "summary": "Cancel or resume a subscription, or open the billing portal",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Private order token (48 hex characters) from the order URL. It is the credential for the order: keep it secret.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{48}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "cancel",
                      "resume",
                      "portal"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/offers/orders/{token}/download": {
      "get": {
        "tags": [
          "Services"
        ],
        "operationId": "downloadDeliverable",
        "summary": "Download the content pack or SEO report as Markdown",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Private order token (48 hex characters) from the order URL. It is the credential for the order: keep it secret.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{48}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Markdown file.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/support/ask": {
      "post": {
        "tags": [
          "System"
        ],
        "operationId": "askSupport",
        "summary": "Ask the AI support assistant",
        "description": "Answers from the help content. If it cannot, and an email is given, the question is forwarded to a person.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "question"
                ],
                "properties": {
                  "question": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Answer.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "answer": {
                      "type": "string"
                    },
                    "escalated": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "tags": [
          "MCP"
        ],
        "operationId": "mcp",
        "summary": "MCP endpoint (JSON-RPC 2.0, Streamable HTTP)",
        "description": "Remote MCP server. Send one JSON-RPC 2.0 message per POST (initialize, tools/list, tools/call, resources/list, prompts/list). Requires an OAuth 2.1 access token; unauthenticated calls get 401 with a `WWW-Authenticate` header pointing to the protected resource metadata. Full tool reference: https://justneeda.com/docs/mcp.",
        "security": [
          {
            "oauth2": [
              "sites:read",
              "sites:write"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jsonrpc",
                  "method"
                ],
                "properties": {
                  "jsonrpc": {
                    "const": "2.0"
                  },
                  "id": {
                    "type": [
                      "string",
                      "integer"
                    ]
                  },
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                }
              },
              "example": {
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/list"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "202": {
            "description": "Notification accepted."
          },
          "401": {
            "description": "Missing or invalid access token."
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": [
          "System"
        ],
        "operationId": "health",
        "summary": "Service health",
        "responses": {
          "200": {
            "description": "Configuration and database health (booleans only).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "db": {
                      "type": "string",
                      "enum": [
                        "ok",
                        "fail"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "jn_live_<key>",
        "description": "API key from Settings, API keys (Pro)."
      },
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1, authorization code with PKCE (S256). Dynamic client registration at /api/oauth/register.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://justneeda.com/oauth/authorize",
            "tokenUrl": "https://justneeda.com/api/oauth/token",
            "refreshUrl": "https://justneeda.com/api/oauth/token",
            "scopes": {
              "sites:read": "Read your website previews and their status",
              "sites:write": "Create previews, request edits, start publishing"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "ToolId": {
        "type": "string",
        "enum": [
          "instant-email-subjects",
          "instant-brand-name",
          "instant-linkedin-bio",
          "instant-website-copy",
          "instant-ad-copy",
          "instant-product-descriptions",
          "instant-personas",
          "instant-cold-email",
          "instant-keyword-research",
          "instant-website-audit",
          "instant-seo-audit",
          "instant-competitor-spy",
          "instant-email-sequence",
          "instant-google-ads",
          "instant-social-pack",
          "instant-pitch-deck",
          "instant-content-strategy",
          "instant-launch-plan",
          "instant-investor-update",
          "instant-onboarding-flow",
          "instant-pricing-page",
          "instant-changelog-pack",
          "instant-positioning-doc",
          "instant-feature-spec",
          "instant-objection-playbook",
          "instant-churn-winback",
          "instant-faq-pack",
          "instant-financial-model",
          "instant-hiring-brief",
          "instant-okr-doc",
          "instant-postmortem",
          "instant-churn-diagnostic"
        ],
        "description": "- `instant-email-subjects`: Email Subject Line Pack. 30 email subject lines in five styles, with A/B variants and preview text.\n- `instant-brand-name`: Brand Name Generator. 50 brand name ideas with a rationale for each, plus the domain and trademark points to check yourself.\n- `instant-linkedin-bio`: LinkedIn Bio Kit. 5 LinkedIn bio variations + headline + about section.\n- `instant-website-copy`: Website Copy Pack. Hero, headlines, calls to action and about page copy, ready to paste.\n- `instant-ad-copy`: Ad Copy Pack. 20 Google/Meta ad copies with headlines, descriptions, and CTAs.\n- `instant-product-descriptions`: Product Descriptions Pack. 20 product descriptions for your store, written around the search terms you give.\n- `instant-personas`: Customer Persona Pack. 3 detailed personas with demographics, pains, goals.\n- `instant-cold-email`: Cold Email Templates. 10 cold email templates + follow-up sequences.\n- `instant-keyword-research`: Keyword Research Report. Keyword ideas grouped by topic and intent, with rough estimates to check against real search data.\n- `instant-website-audit`: Website Audit. A review checklist for your site built from what you describe: performance, SEO, UX and conversion, with a prioritized fix list.\n- `instant-seo-audit`: SEO Audit. An SEO checklist and 90-day plan built from your brief: technical points, content gaps, competitors to look at.\n- `instant-competitor-spy`: Competitor Spy Report. A structured comparison with 3 competitors, built from what you tell the tool about them.\n- `instant-email-sequence`: Email Welcome Sequence. A 5-email welcome sequence for new subscribers, with subject lines and send timing.\n- `instant-google-ads`: Google Ads Launch Pack. Campaign structure + 20 keywords + 5 ad variations + tracking.\n- `instant-social-pack`: Social Media Content Pack. 30 post captions + 50 hashtags + content calendar.\n- `instant-pitch-deck`: Pitch Deck Outline. 12-slide investor pitch deck with speaker notes.\n- `instant-content-strategy`: Content Strategy Plan. 90-day content plan with topics, keywords, distribution.\n- `instant-launch-plan`: Product Hunt Launch Kit. Complete Product Hunt launch package: taglines, maker comment, 7-day tweet countdown, hunter DMs, reply scripts, and thank-you email.\n- `instant-investor-update`: Investor Update Template. Monthly investor update: subject line, TL;DR, metrics table, asks, runway, and follow-ups for non-responders.\n- `instant-onboarding-flow`: SaaS Onboarding Flow. Full SaaS onboarding system: welcome copy, setup microcopy, 5-email drip, upgrade nudge, sticky-points checklist, and activation metric.\n- `instant-pricing-page`: Pricing Strategy + Page Copy. Pricing tiers plus full page copy: headers, bullets, CTA, 8 FAQs, annual framing, value-anchor table, and psychology rationale.\n- `instant-changelog-pack`: Changelog + Release Notes Pack. Ship-day content kit: changelog entry, in-app modal, 3 tweet variants, LinkedIn post, customer email, and why-this-matters lines.\n- `instant-positioning-doc`: Positioning + Messaging Doc. Positioning doc in the April Dunford method: competitive alternatives, unique attributes, market category, one-line statement, elevator pitches and 5 tagline candidates.\n- `instant-feature-spec`: Feature Spec / PRD. A short PRD: problem, user stories, acceptance criteria, edge cases, scope cuts and kill criteria. Pastes clean into Notion or Linear.\n- `instant-objection-playbook`: Sales Objection Playbook. 15 common objections (price, timing, competitor, ROI, security, switching cost) with responses, follow-up questions and what to send after the call. Plus red flags.\n- `instant-churn-winback`: Churn Winback Sequence. 4-email winback (day 7/14/30/60), segmented by churn reason. Discount logic, sunset survey for ghosts, SMS variants for high-value accounts.\n- `instant-faq-pack`: FAQ + Support Macros Pack. 25-question website FAQ by buying stage, 15 Intercom/Crisp macros, a refund script, a churn-save script and an onboarding FAQ.\n- `instant-financial-model`: Startup Financial Model. Bottom-up 24-month SaaS model: MRR, CAC, LTV, runway, three scenarios and an assumptions doc for every input.\n- `instant-hiring-brief`: Hiring Brief + JD Pack. First-hire pack: job description, 5-step interview, scorecard rubric, where to source candidates and early reject criteria.\n- `instant-okr-doc`: Quarterly OKR Doc. Quarterly OKRs: 3 objectives, 9 measurable key results, confidence scores, a weekly check-in and a retro template.\n- `instant-postmortem`: Incident Postmortem Template. Blameless postmortem: timeline, 5-whys, action items with owners, customer impact statement and the email to affected users.\n- `instant-churn-diagnostic`: Customer Churn Diagnostic. Diagnose why customers leave: classification, root cause per segment, 10-step retention playbook, 3 experiments, early-warning signals."
      },
      "FreeGenerateRequest": {
        "type": "object",
        "required": [
          "toolId",
          "input"
        ],
        "properties": {
          "toolId": {
            "$ref": "#/components/schemas/ToolId"
          },
          "input": {
            "type": "string",
            "maxLength": 2000,
            "description": "Free-text brief describing what you need."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Optional. Unlocks the email tier."
          },
          "website_url": {
            "type": "string",
            "description": "Honeypot. Leave empty; filled requests are treated as spam."
          }
        }
      },
      "FreeGenerateResponse": {
        "type": "object",
        "required": [
          "tier",
          "output"
        ],
        "properties": {
          "tier": {
            "type": "string",
            "enum": [
              "anon",
              "email",
              "authed",
              "paid"
            ]
          },
          "output": {
            "type": "string",
            "description": "Generated markdown (a teaser on the anon tier)."
          },
          "remaining": {
            "type": "integer",
            "description": "Runs left in the window; -1 means unlimited."
          },
          "windowResetAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "ctaToUpgrade": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "email",
              "pay",
              null
            ]
          }
        }
      },
      "QuotaError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "tier": {
            "type": "string"
          },
          "remaining": {
            "type": "integer"
          },
          "windowResetAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "requiresEmail": {
            "type": "boolean"
          },
          "requiresPayment": {
            "type": "boolean"
          }
        }
      },
      "SiteBrief": {
        "type": "object",
        "required": [
          "businessName",
          "description",
          "email"
        ],
        "properties": {
          "businessName": {
            "type": "string",
            "minLength": 2,
            "maxLength": 80
          },
          "description": {
            "type": "string",
            "minLength": 30,
            "maxLength": 1500,
            "description": "What the business does. Only facts: nothing is invented."
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Shown on the site; receives enquiries and the receipt."
          },
          "city": {
            "type": "string",
            "maxLength": 80
          },
          "phone": {
            "type": "string",
            "maxLength": 40
          },
          "address": {
            "type": "string",
            "maxLength": 200
          },
          "hours": {
            "type": "string",
            "maxLength": 200
          },
          "link": {
            "type": "string",
            "maxLength": 300,
            "description": "Existing booking, menu or shop link."
          },
          "style": {
            "type": "string",
            "enum": [
              "auto",
              "calm",
              "professional",
              "warm",
              "bold",
              "premium"
            ],
            "default": "auto"
          },
          "language": {
            "type": "string",
            "enum": [
              "en",
              "fr",
              "es",
              "de",
              "it",
              "pt",
              "nl"
            ],
            "default": "en"
          },
          "website_url": {
            "type": "string",
            "description": "Honeypot. Leave empty."
          }
        }
      },
      "PreviewStatus": {
        "type": "object",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "generating",
              "ready",
              "failed"
            ]
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "businessName": {
            "type": "string"
          },
          "editsLeft": {
            "type": "integer"
          },
          "published": {
            "type": "boolean"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}