{
 "openapi": "3.1.0",
 "info": {
  "title": "Plainly Guide API",
  "version": "1.0",
  "description": "Read-only JSON for every entry in Plainly Guide, a plain-English catalogue of creative AI tools (pictures, video, voice, music, talking presenters, 3D). Static files, no key needed, CORS open. The same data is also available to AI assistants through the MCP server at https://mcp.plainly.guide/mcp. Each fact carries its source URL, the date it was last checked and a confidence level. Nobody pays to be listed or ranked. Entries are listed alphabetically or by task, never by payment. If an entry ever carries an affiliate link it appears in links.affiliate and is labelled on the page. Data from Plainly Guide (https://plainly.guide). Please credit Plainly with a link to the entry page when you use it.",
  "contact": {
   "email": "hello@plainly.guide",
   "url": "https://plainly.guide/about/"
  }
 },
 "servers": [
  {
   "url": "https://plainly.guide"
  }
 ],
 "paths": {
  "/api/index.json": {
   "get": {
    "summary": "List every entry",
    "description": "All entries in short form, with links to categories, vocab and this spec.",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Index"
        }
       }
      }
     },
     "404": {
      "description": "No such entry or area"
     }
    }
   }
  },
  "/api/tools/{slug}.json": {
   "get": {
    "summary": "Get one entry",
    "description": "Everything Plainly knows about one tool, model or host, with sources.",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Entry"
        }
       }
      }
     },
     "404": {
      "description": "No such entry or area"
     }
    },
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Permanent entry id, the same as in /tools/{slug}/. List them from /api/index.json."
     }
    ]
   }
  },
  "/api/categories/{area}.json": {
   "get": {
    "summary": "Get one area",
    "description": "Every entry in one area, grouped by task.",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Category"
        }
       }
      }
     },
     "404": {
      "description": "No such entry or area"
     }
    },
    "parameters": [
     {
      "name": "area",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "image",
        "video",
        "voice",
        "music",
        "avatar",
        "3d"
       ]
      }
     }
    ]
   }
  },
  "/api/vocab.json": {
   "get": {
    "summary": "Get the vocabulary",
    "description": "Every id used in the data (tasks, openness, licence families, commercial use, units...) with its plain-English label.",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "No such entry or area"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Summary": {
    "type": "object",
    "properties": {
     "slug": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "type": {
      "type": "string",
      "enum": [
       "tool",
       "model",
       "host"
      ]
     },
     "areas": {
      "type": "array",
      "items": {
       "type": "string",
       "enum": [
        "image",
        "video",
        "voice",
        "music",
        "avatar",
        "3d"
       ]
      }
     },
     "summary": {
      "type": "string",
      "description": "Plain-English summary written by Plainly"
     },
     "main_task": {
      "type": [
       "string",
       "null"
      ]
     },
     "main_task_label": {
      "type": [
       "string",
       "null"
      ]
     },
     "tasks": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Task ids, make.{area}.{task}"
     },
     "openness": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "open_source",
       "open_weights",
       "closed",
       null
      ]
     },
     "open_source": {
      "type": [
       "boolean",
       "null"
      ],
      "description": "True for open_source and open_weights"
     },
     "commercial_use": {
      "type": [
       "string",
       "null"
      ],
      "enum": [
       "yes",
       "paid_plans_only",
       "with_conditions",
       "no",
       "unclear",
       "depends_on_model",
       null
      ],
      "description": "Can you use what you make commercially?"
     },
     "free_option": {
      "type": "boolean"
     },
     "cheapest_paid": {
      "type": [
       "object",
       "null"
      ],
      "properties": {
       "plan": {
        "type": "string"
       },
       "price_per_month": {
        "type": "number"
       },
       "currency": {
        "type": "string",
        "description": "ISO 4217 code"
       },
       "billed": {
        "type": [
         "string",
         "null"
        ]
       }
      }
     },
     "skill_level": {
      "type": [
       "string",
       "null"
      ]
     },
     "last_updated": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "page": {
      "type": "string",
      "format": "uri"
     },
     "json": {
      "type": "string",
      "format": "uri"
     }
    }
   },
   "Index": {
    "type": "object",
    "properties": {
     "api_version": {
      "type": "string"
     },
     "count": {
      "type": "integer"
     },
     "last_updated": {
      "type": "string",
      "format": "date"
     },
     "categories": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "independence": {
      "type": "string"
     },
     "attribution": {
      "type": "string"
     },
     "entries": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Summary"
      }
     }
    }
   },
   "Category": {
    "type": "object",
    "properties": {
     "area": {
      "type": "string"
     },
     "label": {
      "type": "string"
     },
     "count": {
      "type": "integer"
     },
     "tasks": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "id": {
         "type": "string"
        },
        "label": {
         "type": "string"
        },
        "entries": {
         "type": "array",
         "items": {
          "type": "string"
         }
        }
       }
      }
     },
     "entries": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Summary"
      }
     }
    }
   },
   "Entry": {
    "type": "object",
    "required": [
     "slug",
     "name",
     "type",
     "summary",
     "sources",
     "links"
    ],
    "properties": {
     "api_version": {
      "type": "string"
     },
     "slug": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "type": {
      "type": "string"
     },
     "type_label": {
      "type": "string"
     },
     "summary": {
      "type": "string"
     },
     "areas": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "id": {
         "type": "string"
        },
        "label": {
         "type": "string"
        }
       }
      }
     },
     "what_its_for": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "id": {
         "type": "string"
        },
        "label": {
         "type": "string"
        },
        "main": {
         "type": "boolean"
        }
       }
      }
     },
     "inputs_outputs": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "e.g. text_to_image"
     },
     "openness": {
      "type": [
       "object",
       "null"
      ]
     },
     "licence": {
      "type": [
       "object",
       "null"
      ]
     },
     "commercial_use": {
      "type": [
       "object",
       "null"
      ]
     },
     "cost": {
      "type": "object",
      "properties": {
       "free_option": {
        "type": "boolean"
       },
       "cheapest_paid": {
        "type": [
         "object",
         "null"
        ],
        "properties": {
         "plan": {
          "type": "string"
         },
         "price_per_month": {
          "type": "number"
         },
         "currency": {
          "type": "string",
          "description": "ISO 4217 code"
         },
         "billed": {
          "type": [
           "string",
           "null"
          ]
         }
        }
       },
       "plans": {
        "type": "array",
        "items": {
         "type": "object"
        }
       },
       "estimates": {
        "type": "array",
        "items": {
         "type": "object"
        },
        "description": "Plainly estimates, not maker prices"
       }
      }
     },
     "access": {
      "type": "object"
     },
     "skill_level": {
      "type": [
       "object",
       "null"
      ]
     },
     "made_by": {
      "type": [
       "object",
       "null"
      ]
     },
     "status": {
      "type": [
       "object",
       "null"
      ]
     },
     "rights_and_safety": {
      "type": "object"
     },
     "related": {
      "type": "object",
      "properties": {
       "uses_models": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "slug": {
           "type": "string"
          },
          "name": {
           "type": "string"
          },
          "type": {
           "type": "string"
          },
          "json": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       },
       "available_on": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "slug": {
           "type": "string"
          },
          "name": {
           "type": "string"
          },
          "type": {
           "type": "string"
          },
          "json": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       },
       "hosts_models": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "slug": {
           "type": "string"
          },
          "name": {
           "type": "string"
          },
          "type": {
           "type": "string"
          },
          "json": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       },
       "replaced_by": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "slug": {
           "type": "string"
          },
          "name": {
           "type": "string"
          },
          "type": {
           "type": "string"
          },
          "json": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       }
      }
     },
     "alternatives": {
      "type": "object",
      "properties": {
       "for_task": {
        "type": [
         "string",
         "null"
        ]
       },
       "entries": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "slug": {
           "type": "string"
          },
          "name": {
           "type": "string"
          },
          "type": {
           "type": "string"
          },
          "json": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       }
      }
     },
     "last_updated": {
      "type": [
       "string",
       "null"
      ],
      "format": "date",
      "description": "Most recent date any fact was checked"
     },
     "sources": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "field": {
         "type": "string"
        },
        "url": {
         "type": "string",
         "format": "uri"
        },
        "checked": {
         "type": [
          "string",
          "null"
         ],
         "format": "date"
        },
        "confidence": {
         "type": [
          "string",
          "null"
         ],
         "enum": [
          "high",
          "medium",
          "low",
          null
         ]
        },
        "note": {
         "type": [
          "string",
          "null"
         ]
        }
       }
      }
     },
     "links": {
      "type": "object",
      "properties": {
       "page": {
        "type": "string",
        "format": "uri"
       },
       "website": {
        "type": "string",
        "format": "uri"
       },
       "affiliate": {
        "type": [
         "string",
         "null"
        ],
        "format": "uri",
        "description": "Affiliate link where Plainly has one, otherwise null. Never affects listing or order."
       }
      }
     },
     "attribution": {
      "type": "string"
     }
    }
   }
  }
 }
}