feat: add API v2 documentation

docs/api.md

@@ -0,0 +1,188 @@
+# API Documentation
+
+The OpenCVE REST API lets your own tools interact with OpenCVE programmatically. Connect it to your CMDB, inventory, ITSM, SOAR, SIEM, or internal scripts to build vulnerability workflows that fit the way your team already works.
+
+The API v2 is available at [https://app.opencve.io/api/v2/](https://app.opencve.io/api/v2/).
+
+Interactive documentation is available on Swagger: [https://app.opencve.io/api/v2/docs/](https://app.opencve.io/api/v2/docs/).
+
+![API v2 Swagger](images/api_v2_swagger.png){.center style="width:100%"}
+
+With API v2, you can both **read** and **write** data:
+
+- **Read**: browse the CVE catalog, search with advanced filters, list vendors and products, inspect project CVEs, read reports, and review automation execution history.
+- **Write**: manage projects, update subscriptions, triage CVEs (status and assignee), configure notifications and automations, and manage organization members.
+
+## Quick start
+
+Set your organization API token in your shell, then list CVEs from the catalog:
+
+```bash
+export OPENCVE_TOKEN="opc_org.<token_id>.<secret>"
+
+curl https://app.opencve.io/api/v2/cves \
+  -H "Authorization: Bearer $OPENCVE_TOKEN" \
+  -H "Accept: application/json"
+```
+
+## Example
+
+Sync your software inventory with OpenCVE by replacing all subscriptions of a project in a single request:
+
+```bash
+curl -X PUT \
+  "https://app.opencve.io/api/v2/organizations/acme/projects/production/subscriptions" \
+  -H "Authorization: Bearer $OPENCVE_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "vendors": ["python", "microsoft"],
+    "products": {
+      "apache": ["http_server", "airflow"],
+      "fortinet": ["fortios"]
+    }
+  }'
+```
+
+This request **replaces** the entire subscription set of the project. You can subscribe to whole vendors (e.g. `python`, `microsoft`) and specific products (e.g. `apache/http_server`) in a single operation.
+
+## Authentication
+
+The API v2 uses **Organization API Tokens** only. They provide a secure way to authenticate requests without relying on user credentials, and are designed for automation and machine-to-machine access (scripts, CI/CD pipelines, SIEM integrations, and more).
+
+Each organization can create multiple tokens and revoke them at any time. If a token is compromised, it can be revoked without impacting user accounts or other tokens.
+
+Tokens use the Bearer authentication scheme and must be sent in the `Authorization` header:
+
+```
+Authorization: Bearer opc_org.<token_id>.<secret>
+```
+
+Organization API tokens can be created from the organization settings page. For security reasons, the token secret is displayed **only once** at creation time. Make sure to copy and store it securely, for example in an environment variable:
+
+```bash
+export OPENCVE_TOKEN="opc_org.<token_id>.<secret>"
+```
+
+![API Organization Token](images/api_org_token.png){.center style="width:90%"}
+
+On OpenCVE [Community](https://github.com/opencve/opencve), tokens support two access modes:
+
+- **Read-only**: can only perform read operations
+- **Read-write**: can perform both read and write operations
+
+On OpenCVE [Cloud](https://www.opencve.io), you can create tokens with **granular scopes** to follow the principle of least privilege. For example:
+
+- A monitoring dashboard token limited to `catalog:read` and `tracker:read`
+- An onboarding pipeline token with `projects:read` and `subscriptions:write` to sync subscriptions from your inventory without granting full write access
+
+A write scope automatically includes read access to the same resource. For example, `projects:write` also grants `projects:read`.
+
+![API Organization Token Scopes](images/api_org_token_scopes.png){.center style="width:90%"}
+
+!!! info "Availability"
+    Granular API token scopes are available on OpenCVE Cloud, starting from the **Pro** plan.
+    On OpenCVE Community, tokens support read-only or read-write access only.
+
+## Pagination
+
+Some endpoints can return lots of results (listing CVEs, for instance). In these cases, results are paginated with the `page` parameter.
+
+Example with the list of CVEs:
+
+```bash
+curl -H "Authorization: Bearer $OPENCVE_TOKEN" \
+    "https://app.opencve.io/api/v2/cves?page=2"
+```
+
+```json
+{
+  "count": 262939,
+  "next": "https://app.opencve.io/api/v2/cves?page=3&page_size=20",
+  "previous": "https://app.opencve.io/api/v2/cves?page=1&page_size=20",
+  "results": [
+    ...
+  ]
+}
+```
+
+The `next` and `previous` keys help you navigate through pages. The default page size is **20** items. You can adjust it with the `page_size` parameter (maximum **100**).
+
+When no result is found (the page parameter is too high), a `404` HTTP status code is returned.
+
+## Error responses
+
+When a request fails, the API returns a structured JSON error:
+
+```json
+{
+  "error": {
+    "code": "read_only_token",
+    "message": "This token is read-only and cannot perform write operations."
+  }
+}
+```
+
+Every error includes a `code` and a `message`. Some errors include extra fields such as `details` (field-level validation errors) or `required_scope` (when the token lacks a specific scope).
+
+### Error codes
+
+| Code | HTTP status | Description |
+|------|-------------|-------------|
+| `invalid_token` | 401 | Missing, malformed, revoked, or invalid Bearer token |
+| `not_found` | 404 | Resource not found (including an out-of-range pagination page) |
+| `permission_denied` | 403 | The request is not allowed |
+| `read_only_token` | 403 | A read-only token was used for a write operation |
+| `missing_scope` | 403 | The token does not have the required scope for this operation |
+| `validation_error` | 400 | Invalid request body or query parameters |
+
+### Examples
+
+```json
+{
+  "error": {
+    "code": "read_only_token",
+    "message": "This token is read-only and cannot perform write operations."
+  }
+}
+```
+
+```json
+{
+  "error": {
+    "code": "not_found",
+    "message": "Not found."
+  }
+}
+```
+
+```json
+{
+  "error": {
+    "code": "validation_error",
+    "message": "Validation error.",
+    "details": {
+      "vendors": ["Vendor does not exist: 'foobar'."]
+    }
+  }
+}
+```
+
+## Explore the API (Swagger)
+
+All endpoints, parameters, request bodies, and response schemas are documented in the interactive Swagger UI: **[https://app.opencve.io/api/v2/docs/](https://app.opencve.io/api/v2/docs/)**.
+
+The API is organized around these main areas:
+
+- **cves**: CVE catalog, details, and change history
+- **vendors**: vendors, products, and related CVEs
+- **weaknesses**: CWE weaknesses and related CVEs
+- **organizations**: organization settings, members, and audit logs
+- **projects**: projects, subscriptions, CVE tracker, notifications, automations, and reports
+
+Use Swagger to try requests directly in your browser and copy ready-to-use examples.
+
+## API v1 (deprecated)
+
+The API v1 (`/api/`) is deprecated and no longer receives new features. New integrations should use API v2.
+
+The v1 documentation is archived [here](https://github.com/opencve/opencve-docs/tree/master/archives/api_v1).

mkdocs.yml

@@ -53,13 +53,7 @@ nav:
       - Multi-Factor Authentication: 'guides/mfa.md'
       - SSO (SAML 2.0): 'guides/sso_saml2.md'
       - SMTP Configuration: 'guides/smtp_configuration.md'
-  - API:
-      - Introduction: 'api/index.md'
-      - /cve: 'api/cve.md'
-      - /organizations: 'api/organizations.md'
-      - /products: 'api/products.md'
-      - /vendors: 'api/vendors.md'
-      - /weaknesses: 'api/weaknesses.md'
+  - API: 'api.md'
   - Troubleshooting: 'troubleshooting.md'
   - Old Doc (v1):
     - Home: 'v1/index.md'