feat(docs): publish OpenAPI spec, auth docs and developer portal

.github/workflows/deploy_doc.yml

@@ -68,17 +68,22 @@ jobs:
           set -euo pipefail
           git fetch origin gh-pages
           git worktree add ghpages gh-pages
+          # Static root files. Copy each published artifact explicitly so repo-only
+          # files in site_root/ (e.g. README.md) never leak onto the live site.
           cp site_root/robots.txt ghpages/robots.txt
           cp site_root/llms.txt   ghpages/llms.txt
           cp site_root/index.html ghpages/index.html
+          cp -R site_root/developers ghpages/developers
           if [ -f ghpages/latest/llms-full.txt ]; then
             cp ghpages/latest/llms-full.txt ghpages/llms-full.txt
           fi
+          # Public OpenAPI document, served at the predictable /openapi.json.
+          python scripts/build_public_openapi.py ghpages/openapi.json
           cd ghpages
-          git add robots.txt llms.txt index.html llms-full.txt
+          git add robots.txt llms.txt index.html llms-full.txt openapi.json developers
           if git diff --cached --quiet; then
             echo "Site-root files already up to date."
           else
-            git commit -m "chore(docs): publish root llms.txt, robots.txt and landing page"
+            git commit -m "chore(docs): publish root llms.txt, robots.txt, openapi.json, developer portal"
             git push origin gh-pages
           fi

docs/authentication.md

@@ -0,0 +1,63 @@
+# Authentication
+
+The Rapidata API uses **OAuth 2.0 / OpenID Connect**. The authorization server is
+`https://auth.rapidata.ai`, and its discovery document is published at
+[`/.well-known/openid-configuration`](https://auth.rapidata.ai/.well-known/openid-configuration).
+
+For programmatic access (the SDK, scripts, agents) you authenticate with the
+**client credentials** grant using a client ID and secret.
+
+## Get credentials
+
+Create a client ID and secret under [Rapidata Settings → Tokens](https://app.rapidata.ai/settings/tokens).
+
+## With the SDK
+
+The SDK performs the token exchange for you. Pass the credentials directly:
+
+```python
+from rapidata import RapidataClient
+
+client = RapidataClient(
+    client_id="YOUR_CLIENT_ID",
+    client_secret="YOUR_CLIENT_SECRET",
+)
+```
+
+or set `RAPIDATA_CLIENT_ID` and `RAPIDATA_CLIENT_SECRET` in the environment
+(useful for headless or containerised runs) and construct `RapidataClient()`
+with no arguments. On a workstation, calling `RapidataClient()` with no
+credentials instead opens a browser login once and caches the token in
+`~/.config/rapidata/credentials.json`.
+
+## Direct token request
+
+To call the API without the SDK, request a token from the token endpoint and
+send it as a bearer token:
+
+```bash
+curl -X POST https://auth.rapidata.ai/connect/token \
+  -d grant_type=client_credentials \
+  -d client_id=YOUR_CLIENT_ID \
+  -d client_secret=YOUR_CLIENT_SECRET \
+  -d scope="openid email roles"
+
+# → {"access_token": "...", "token_type": "Bearer", "expires_in": 3600}
+
+curl https://api.rapidata.ai/order/openapi/v1.json \
+  -H "Authorization: Bearer ACCESS_TOKEN"
+```
+
+## Scopes
+
+Tokens are scoped. The SDK requests `openid roles email` by default, which is
+sufficient for all SDK operations. Request only the scopes you need. Every
+endpoint in the [OpenAPI specification](https://docs.rapidata.ai/openapi.json)
+declares the scopes it requires under its `OpenIdConnect` security scheme.
+
+| Scope | Grants |
+|-------|--------|
+| `openid` | Required for OIDC; identifies the token subject. |
+| `email` | Access to the account email claim. |
+| `roles` | The account's role claims, which gate API operations. |
+| `offline_access` | A refresh token for long-lived sessions. |

mkdocs.yml

@@ -58,6 +58,7 @@ plugins:
         Guides:
           - starting_page.md
           - quickstart.md
+          - authentication.md
           - audiences.md
           - signals.md
           - job_definition_parameters.md
@@ -120,6 +121,7 @@ nav:
     - Guides:
       - Overview: starting_page.md
       - Quick Start: quickstart.md
+      - Authentication: authentication.md
       - Custom Audiences: audiences.md
       - Signals: signals.md
       - Parameter Reference: job_definition_parameters.md

scripts/build_public_openapi.py

@@ -0,0 +1,58 @@
+"""Produce the public OpenAPI document served at docs.rapidata.ai/openapi.json.
+
+The combined spec under ``openapi/schemas/`` is the contract the SDK is generated
+from, but it carries the internal ``rabbitdata.ch`` host and an inaccurate title.
+Rewrite those to the public ``rapidata.ai`` host (which already serves the same
+per-service specs and OIDC discovery document) so agents get an accurate surface.
+
+Usage: python scripts/build_public_openapi.py <output.json>
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+SOURCE = (
+    Path(__file__).resolve().parent.parent
+    / "openapi"
+    / "schemas"
+    / "rapidata.filtered.openapi.json"
+)
+
+
+def build() -> dict:
+    spec = json.loads(SOURCE.read_text(encoding="utf-8"))
+
+    # The internal build host is the only thing standing between this and the
+    # live public spec at api.rapidata.ai — rewrite both the server and the
+    # OIDC discovery URL in the security scheme.
+    serialized = json.dumps(spec).replace("rabbitdata.ch", "rapidata.ai")
+    spec = json.loads(serialized)
+
+    spec["servers"] = [{"url": "https://api.rapidata.ai/"}]
+    info = spec.setdefault("info", {})
+    info["title"] = "Rapidata API"
+    info.setdefault(
+        "description",
+        "Public Rapidata API. Authentication uses OAuth 2.0 (OpenID Connect) — "
+        "see https://docs.rapidata.ai/latest/authentication/.",
+    )
+    return spec
+
+
+def main() -> None:
+    if len(sys.argv) != 2:
+        print(__doc__)
+        raise SystemExit(2)
+    out = Path(sys.argv[1])
+    spec = build()
+    out.write_text(json.dumps(spec), encoding="utf-8")
+    print(
+        f"Wrote {out} ({out.stat().st_size} bytes, {len(spec.get('paths', {}))} paths)"
+    )
+
+
+if __name__ == "__main__":
+    main()

site_root/developers/index.html

@@ -0,0 +1,80 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Rapidata Developer Portal</title>
+  <meta name="description" content="Developer resources for Rapidata: Python SDK, OpenAPI specification, OAuth 2.0 authentication, quickstart, and API reference.">
+  <link rel="canonical" href="https://docs.rapidata.ai/developers/">
+
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="Rapidata Documentation">
+  <meta property="og:title" content="Rapidata Developer Portal">
+  <meta property="og:description" content="Python SDK, OpenAPI spec, OAuth 2.0 auth, quickstart, and API reference for the Rapidata API.">
+  <meta property="og:url" content="https://docs.rapidata.ai/developers/">
+
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "@type": "WebAPI",
+    "name": "Rapidata API",
+    "description": "Request human feedback at scale — labeling, model evaluation, ranking, and preference data — over an OAuth 2.0 secured REST API.",
+    "documentation": "https://docs.rapidata.ai/latest/",
+    "termsOfService": "https://rapidata.ai/terms",
+    "provider": {
+      "@type": "Organization",
+      "name": "Rapidata",
+      "url": "https://www.rapidata.ai"
+    },
+    "EntryPoint": {
+      "@type": "EntryPoint",
+      "urlTemplate": "https://api.rapidata.ai/",
+      "contentType": "application/json"
+    }
+  }
+  </script>
+</head>
+<body>
+  <main>
+    <h1>Rapidata Developer Portal</h1>
+    <p>
+      Rapidata provides human feedback at scale — crowd-sourced labeling, model
+      evaluation, ranking, and preference data. Integrate with the Python SDK or
+      directly against the OAuth 2.0 secured REST API.
+    </p>
+
+    <h2>Get started</h2>
+    <ul>
+      <li><a href="/latest/quickstart/">Quick Start</a> — install, authenticate, create your first order</li>
+      <li>Install the SDK: <code>pip install rapidata</code></li>
+      <li><a href="https://app.rapidata.ai/settings/tokens">Create API credentials</a> (client ID &amp; secret)</li>
+    </ul>
+
+    <h2>Reference</h2>
+    <ul>
+      <li><a href="/openapi.json">OpenAPI specification</a> (<code>/openapi.json</code>)</li>
+      <li><a href="/latest/api/">API reference</a> — the <code>RapidataClient</code> and its managers</li>
+      <li><a href="/latest/authentication/">Authentication</a> — OAuth 2.0 / OpenID Connect, scopes, token endpoint</li>
+      <li><a href="https://auth.rapidata.ai/.well-known/openid-configuration">OpenID Connect discovery document</a></li>
+    </ul>
+
+    <h2>Guides &amp; examples</h2>
+    <ul>
+      <li><a href="/latest/">Documentation home</a></li>
+      <li><a href="/latest/audiences/">Custom audiences</a>, <a href="/latest/understanding_the_results/">results</a>, <a href="/latest/confidence_stopping/">early stopping</a></li>
+      <li><a href="/latest/examples/compare_job/">Examples</a> — classify, compare, locate, draw, rank, free text</li>
+    </ul>
+
+    <h2>For AI agents</h2>
+    <ul>
+      <li><a href="/latest/ai_agents/">Use Rapidata from your AI agent</a> — official coding-agent skill</li>
+      <li><a href="/llms.txt">llms.txt</a> · <a href="/llms-full.txt">llms-full.txt</a></li>
+    </ul>
+
+    <h2>Source</h2>
+    <ul>
+      <li><a href="https://github.com/RapidataAI/rapidata-python-sdk">GitHub</a> · <a href="https://pypi.org/project/rapidata/">PyPI</a></li>
+    </ul>
+  </main>
+</body>
+</html>

site_root/index.html

@@ -49,6 +49,18 @@
         "softwareHelp": "https://docs.rapidata.ai/latest/quickstart/",
         "publisher": { "@id": "https://www.rapidata.ai/#organization" },
         "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" }
+      },
+      {
+        "@type": "WebAPI",
+        "name": "Rapidata API",
+        "description": "OAuth 2.0 secured REST API for requesting human feedback at scale.",
+        "documentation": "https://docs.rapidata.ai/developers/",
+        "provider": { "@id": "https://www.rapidata.ai/#organization" },
+        "EntryPoint": {
+          "@type": "EntryPoint",
+          "urlTemplate": "https://api.rapidata.ai/",
+          "contentType": "application/json"
+        }
       }
     ]
   }
@@ -73,9 +85,11 @@ <h1>Rapidata Python SDK</h1>
     <p>Install with <code>pip install rapidata</code>, then authenticate with a token from
       <a href="https://app.rapidata.ai/settings/tokens">app.rapidata.ai/settings/tokens</a>.</p>
     <ul>
+      <li><a href="developers/">Developer portal</a></li>
       <li><a href="latest/">Documentation home</a></li>
       <li><a href="latest/quickstart/">Quick Start</a></li>
-      <li><a href="latest/starting_page/">Overview &amp; core concepts</a></li>
+      <li><a href="latest/authentication/">Authentication (OAuth 2.0)</a></li>
+      <li><a href="openapi.json">OpenAPI specification</a></li>
       <li><a href="latest/api/">API reference</a></li>
       <li><a href="latest/ai_agents/">Use Rapidata from your AI agent</a></li>
       <li><a href="llms.txt">llms.txt</a> · <a href="llms-full.txt">llms-full.txt</a></li>

site_root/llms.txt

@@ -5,9 +5,15 @@
 > people. The supported way to access it programmatically is the Rapidata
 > Python SDK, documented on this site (docs.rapidata.ai).
 
-Integrate via the Python SDK (`pip install rapidata`). Authenticate either with
-an interactive browser login on first run, or with a client ID/secret token
-created at https://app.rapidata.ai/settings/tokens.
+Integrate via the Python SDK (`pip install rapidata`). The API is OAuth 2.0 /
+OpenID Connect secured; authenticate with a client ID/secret created at
+https://app.rapidata.ai/settings/tokens, or via interactive browser login on
+first run.
+
+- Developer portal: https://docs.rapidata.ai/developers/
+- OpenAPI specification: https://docs.rapidata.ai/openapi.json
+- Authentication (OAuth 2.0): https://docs.rapidata.ai/latest/authentication/
+- OpenID Connect discovery: https://auth.rapidata.ai/.well-known/openid-configuration
 
 ## Guides
 
@@ -37,10 +43,13 @@ created at https://app.rapidata.ai/settings/tokens.
 - [Getting Started](https://docs.rapidata.ai/latest/mri/)
 - [Advanced](https://docs.rapidata.ai/latest/mri_advanced/)
 
-## AI agents & API
+## API & AI agents
 
-- [Use Rapidata from your AI agent](https://docs.rapidata.ai/latest/ai_agents/): an official skill that teaches coding agents (Claude Code, Cursor, Copilot, and others) to write Rapidata integrations
+- [Developer portal](https://docs.rapidata.ai/developers/): all developer resources in one place
+- [OpenAPI specification](https://docs.rapidata.ai/openapi.json): the full API surface (OAuth 2.0 / OpenID Connect)
+- [Authentication](https://docs.rapidata.ai/latest/authentication/): OAuth 2.0 client-credentials flow, scopes, token endpoint
 - [API reference](https://docs.rapidata.ai/latest/api/): the `RapidataClient` class and its managers
+- [Use Rapidata from your AI agent](https://docs.rapidata.ai/latest/ai_agents/): an official skill that teaches coding agents (Claude Code, Cursor, Copilot, and others) to write Rapidata integrations
 
 ## Access