openapi: 3.1.0
info:
  title: ChartForge API
  description: Generate stunning, publication-quality charts and diagrams from natural language. Supports bar charts, line charts, pie charts, architecture diagrams, flowcharts, Sankey diagrams, and more.
  version: 1.0.0
  contact:
    name: ChartForge
    url: https://chartforgeai.com
    email: crawde@agentmail.to

servers:
  - url: https://chartforgeai.com
    description: Production

paths:
  /api/generate:
    post:
      operationId: generateChart
      summary: Generate a chart from a natural language description
      description: |
        Creates a publication-quality chart or diagram from a text prompt. 
        Returns base64-encoded PNG image data along with a chart ID that can be used for refinements.
        Free tier: 3 charts/day. API plan: unlimited.
      security:
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
              properties:
                prompt:
                  type: string
                  minLength: 3
                  description: Natural language description of the chart to generate. Be specific about data, labels, chart type, and what you want to visualize.
                  examples:
                    - "Bar chart showing quarterly revenue from $2M to $18M over 3 years"
                    - "System architecture diagram for a microservices backend with API gateway, message queue, and 3 services"
                    - "Sankey diagram of marketing budget flow through channels to conversions"
                style:
                  type: string
                  enum: [midnight, frost, ember, minimal, corporate, neon, light]
                  description: Visual style preset. If omitted, AI chooses the best style for the chart type.
                width:
                  type: integer
                  minimum: 400
                  maximum: 3840
                  default: 1200
                  description: Chart width in pixels
                height:
                  type: integer
                  minimum: 300
                  maximum: 2160
                  default: 800
                  description: Chart height in pixels
                format:
                  type: string
                  enum: [png, html]
                  default: png
                  description: Output format. PNG returns base64 image data, HTML returns raw chart HTML.
      responses:
        "200":
          description: Chart generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  chartId:
                    type: string
                    description: Unique chart ID. Use with refine endpoint to modify this chart.
                  image:
                    type: string
                    description: Base64-encoded PNG image data (when format is png)
                  mimeType:
                    type: string
                    enum: [image/png]
                  html:
                    type: string
                    description: Raw HTML chart code (when format is html)
        "400":
          description: Invalid prompt (too short or missing)
        "401":
          description: Invalid API key
        "402":
          description: Daily free limit reached (3/day) or payment required

  /api/refine:
    post:
      operationId: refineChart
      summary: Modify an existing chart
      description: Takes a chart ID from a previous generation and applies modifications. Requires API plan access.
      security:
        - apiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - chartId
                - modification
              properties:
                chartId:
                  type: string
                  description: Chart ID from a previous generateChart call
                modification:
                  type: string
                  description: "What to change about the chart, e.g. 'make the bars blue', 'add a title', 'switch to horizontal layout'"
      responses:
        "200":
          description: Chart refined successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  chartId:
                    type: string
                    description: New chart ID for the refined version
                  image:
                    type: string
                    description: Base64-encoded PNG image data
                  mimeType:
                    type: string
                    enum: [image/png]
        "402":
          description: API plan required for refinement
        "404":
          description: Chart session not found

  /api/usage:
    get:
      operationId: getUsage
      summary: Check remaining chart generation quota
      description: Returns current usage stats including whether the user has pro access and remaining free generations.
      responses:
        "200":
          description: Usage stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  pro:
                    type: boolean
                    description: Whether the user has pro or API access
                  used:
                    type: integer
                    description: Charts generated today
                  remaining:
                    type: integer
                    description: Charts remaining today (Infinity for pro/API users)
                  limit:
                    type: integer
                    description: Daily limit (3 for free users)

components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: "API key from chartforgeai.com. Format: cf_<hex>. Get one at https://chartforgeai.com/pricing"