From 7e4feb39d6000ff072ccd5d1672413ba170695aa Mon Sep 17 00:00:00 2001 From: RapidPoseidon Date: Fri, 26 Jun 2026 14:33:24 +0000 Subject: [PATCH] docs(agent-readiness): add when-to-use guidance and step-by-step agent auth Addresses the two remaining gaps that are genuinely fixable in this repo: - Identity "when-to-use": add a "When to use Rapidata" section to llms.txt naming best-fit jobs and how an agent should call it. - Access agent-auth warning: add an explicit step-by-step client-credentials flow to the Authentication page and the /developers portal. Co-Authored-By: Claude Opus 4.8 Co-Authored-By: lino --- docs/authentication.md | 9 +++++++++ site_root/developers/index.html | 10 ++++++++++ site_root/llms.txt | 17 +++++++++++++++++ 3 files changed, 36 insertions(+) diff --git a/docs/authentication.md b/docs/authentication.md index c58ceed1c..0e8bb4642 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -11,6 +11,15 @@ For programmatic access (the SDK, scripts, agents) you authenticate with the Create a client ID and secret under [Rapidata Settings → Tokens](https://app.rapidata.ai/settings/tokens). +## Programmatic / agent authentication, step by step + +For headless or agent-driven use, authenticate with the client-credentials grant: + +1. Create a client ID and secret at [Rapidata Settings → Tokens](https://app.rapidata.ai/settings/tokens). +2. Expose them to the SDK as the `RAPIDATA_CLIENT_ID` and `RAPIDATA_CLIENT_SECRET` environment variables, so no interactive browser login is needed. +3. Construct `RapidataClient()` with no arguments — it exchanges the credentials for a bearer token at `https://auth.rapidata.ai/connect/token` and refreshes it automatically. +4. To call the API without the SDK, request a token yourself and send it as a bearer token (see [Direct token request](#direct-token-request)). + ## With the SDK The SDK performs the token exchange for you. Pass the credentials directly: diff --git a/site_root/developers/index.html b/site_root/developers/index.html index ce3b651c0..a9379a29c 100644 --- a/site_root/developers/index.html +++ b/site_root/developers/index.html @@ -50,6 +50,16 @@

Get started

  • Create API credentials (client ID & secret)
    • +

    Authenticate as an agent

    +

    The API uses OAuth 2.0 (OpenID Connect), client-credentials grant:

    +
      +
    1. Create a client ID & secret.
      2. +
    2. Set RAPIDATA_CLIENT_ID and RAPIDATA_CLIENT_SECRET in the environment.
      3. +
    3. Construct RapidataClient() — it fetches and refreshes a bearer token automatically.
      4. +
    4. Without the SDK: POST https://auth.rapidata.ai/connect/token with grant_type=client_credentials, then send the token as Authorization: Bearer ….
      5. +
    +

    Full details: Authentication.

    +

    Reference

    • OpenAPI specification (/openapi.json)
      • diff --git a/site_root/llms.txt b/site_root/llms.txt index 4caad3d48..8ea6a1256 100644 --- a/site_root/llms.txt +++ b/site_root/llms.txt @@ -15,6 +15,23 @@ first run. - Authentication (OAuth 2.0): https://docs.rapidata.ai/latest/authentication/ - OpenID Connect discovery: https://auth.rapidata.ai/.well-known/openid-configuration +## When to use Rapidata + +Reach for Rapidata when a task needs **real human judgment at scale** rather than +a model's own output: + +- Evaluate or compare model outputs (image, video, audio, text) with human preferences — pairwise A/B comparisons, ranking, leaderboards. +- Build RLHF / preference datasets and reward-model training data. +- Annotate or label data: classification, locating, bounding/drawing, transcription, free text, select-words. +- Collect targeted human feedback by country, language, or demographic, with built-in quality control and confidence-based early stopping. + +It is **not** the right tool for fully automated labeling with no human in the +loop, or for sub-second real-time inference. + +How an agent calls it: use the Python SDK (`pip install rapidata`, see Quick +Start) or the OAuth 2.0 REST API (see Authentication). Coding agents can install +the official skill (see AI agents) to have integrations written for them. + ## Guides - [Overview](https://docs.rapidata.ai/latest/starting_page/): what Rapidata does and its core concepts