From b321f9db770d02fc0865a06da20b6465a6e44d58 Mon Sep 17 00:00:00 2001 From: moneycaringcoder <265054401+moneycaringcoder@users.noreply.github.com> Date: Wed, 7 Oct 2026 15:38:01 +0000 Subject: [PATCH] Slim developer API page, fix nav order collision, update publishing notes --- README.md | 33 ++---- docs/automations/index.md | 2 +- docs/automations/reports-and-notifications.md | 2 +- docs/publishing/index.md | 2 +- docs/reference/developer-api.md | 102 ++++++------------ docs/reference/index.md | 2 +- docs/reference/security-and-data.md | 2 +- 7 files changed, 44 insertions(+), 101 deletions(-) diff --git a/README.md b/README.md index 10f74d3..a9a303d 100644 --- a/README.md +++ b/README.md @@ -32,31 +32,14 @@ and requires no provider or deployment secrets. ## Publishing -Edit pages under `docs/`, run `npm run check`, and open a pull request. Once connected, -merges to `main` affecting that folder enqueue a Claire sync. CI checks the repository; -it does not publish the pages itself. Check Site → Docs sync status and rendered navigation -before announcing a change as live. - -Before publishing the token/vesting update, verify the advertised workflows in production. -Ethereum/Stockereum availability and the SDK's new token fields must match the enabled -deployment and released npm version. Remove rollout/unreleased notes only after verification. - -If the workspace has not switched its existing docs source to this repository, the owner -must first complete the one-time source switch: - -- Repository: `tryclaire/docs` -- Branch: `main` -- Folder: `docs` - -Give the Claire GitHub App access to this repository and refresh the workspace's GitHub -connection if it is missing from the verified repository list. Change the existing source -in Site → Docs and sync; do not disconnect first, because disconnecting removes imported pages. -The existing domain and hosting stay in place. Verify navigation and existing URLs after syncing. - -Once connected through the GitHub App, pushes to `main` affecting `docs/` enqueue a sync; -merged documentation publishes without a separate approval in Claire. CI does not deploy -anything itself. The old monorepo copy remains until the owner completes and verifies the -source switch; remove it afterward so there is one source of truth. +This repository (`tryclaire/docs`, branch `main`, folder `docs`) is the connected source for +[docs.tryclaire.net](https://docs.tryclaire.net). Merging to `main` with changes under `docs/` +enqueues a Claire sync; pages publish without a separate approval step. CI checks the +repository but does not publish anything. + +After merging, check Site → Docs sync status and the rendered navigation before announcing +a change as live. Do not document rollout-gated features (such as Ethereum/Stockereum +availability) as generally available until they are verified in production. ## License diff --git a/docs/automations/index.md b/docs/automations/index.md index 4ff05e4..5b95318 100644 --- a/docs/automations/index.md +++ b/docs/automations/index.md @@ -1,6 +1,6 @@ --- title: Automations -order: 8 +order: 9 --- # Automations diff --git a/docs/automations/reports-and-notifications.md b/docs/automations/reports-and-notifications.md index f1627ab..71b5f27 100644 --- a/docs/automations/reports-and-notifications.md +++ b/docs/automations/reports-and-notifications.md @@ -1,6 +1,6 @@ --- title: Reports and notifications -order: 9 +order: 10 --- # Reports and notifications diff --git a/docs/publishing/index.md b/docs/publishing/index.md index 0ce8a2c..f48ca9f 100644 --- a/docs/publishing/index.md +++ b/docs/publishing/index.md @@ -1,6 +1,6 @@ --- title: Publishing -order: 7 +order: 8 --- # Publishing diff --git a/docs/reference/developer-api.md b/docs/reference/developer-api.md index 35454ff..c7f07b3 100644 --- a/docs/reference/developer-api.md +++ b/docs/reference/developer-api.md @@ -1,11 +1,11 @@ --- title: Developer API and SDK -order: 11 +order: 12 --- # Developer API and SDK -Read permitted workspace data through the REST API or the official TypeScript and JavaScript SDK, [`@tryclaire/sdk`](https://www.npmjs.com/package/@tryclaire/sdk). Both use the same workspace-scoped keys and permissions. Neither can publish content or send messages. +Give your scripts and agents read access to a workspace's collected data: context, Knowledge, asset metadata, Telegram history, X mentions, and token observations. Use the REST API directly or the official TypeScript and JavaScript SDK, [`@tryclaire/sdk`](https://www.npmjs.com/package/@tryclaire/sdk). Both use the same workspace-scoped keys. Neither can publish content, send messages, or sign transactions. ## Create a key @@ -15,96 +15,56 @@ Read permitted workspace data through the REST API or the official TypeScript an A key stops working if its issuing user loses owner or admin membership. Keep it in your server environment or agent's secret store, never in browser code, public environment variables, or a repository. -## Read workspace data +## Choose scopes -Use `/api/v1` with a bearer key. Depending on scopes, the API exposes workspace context, Knowledge search and source detail, asset metadata, linked Telegram chats and stored messages, stored X mentions, and stored token observations. Private material requires its specific read scope. +| Scope | What it reads | +| --- | --- | +| `context:read` | Workspace identity, granted scopes, and which sources are connected. | +| `knowledge:read` | Knowledge search and bounded source detail, respecting existing visibility rules. | +| `assets:read` | File and folder metadata. Never file contents or signed download URLs. | +| `telegram:read` | Linked chats and stored messages. | +| `x:read` | Stored mentions. | +| `token:read` | Stored token observations and identity. | -The API does not supply private file contents, publish content, send Telegram messages, or write to X. Responses expose collection state and timestamps; response time alone is not a freshness claim. +Grant only what the integration needs. Private material requires its specific scope; a key cannot widen its own access or select another workspace. -## Install the SDK +## Make your first request -The SDK requires **Node.js 22 or newer and ESM**. It includes TypeScript declarations and has no runtime dependencies. Choose the command for your package manager: +Create a key with `knowledge:read` and set it as `CLAIRE_API_KEY`. ```sh npm install @tryclaire/sdk -pnpm add @tryclaire/sdk -yarn add @tryclaire/sdk -bun add @tryclaire/sdk ``` -Package-manager choice does not change the supported runtime: use the SDK in a server, CLI, or agent process, not a browser bundle. - -## Make your first SDK request - -Create a key with `knowledge:read` and provide it as the `CLAIRE_API_KEY` environment variable. Save this example as `example.mjs`, then run `node example.mjs`: - ```js import { Claire } from "@tryclaire/sdk"; -const apiKey = process.env.CLAIRE_API_KEY; -if (!apiKey) throw new Error("Set CLAIRE_API_KEY before running this example."); - -const claire = new Claire({ apiKey }); -const result = await claire.knowledge.list({ q: "getting started", page: 1 }); +const claire = new Claire({ apiKey: process.env.CLAIRE_API_KEY }); +const { data, meta } = await claire.knowledge.list({ q: "getting started" }); -for (const item of result.data) { - console.log(item.title, item.preview); -} -console.log(result.meta.freshness); -console.log(result.pagination.hasNextPage); +for (const item of data) console.log(item.title, item.preview); +console.log(meta.freshness); ``` -The key selects the workspace; you do not pass an organization ID to the client. - -## SDK resources and scopes - -| Method | Required scope | -| --- | --- | -| `claire.context.get()` | `context:read` | -| `claire.knowledge.list(query)` | `knowledge:read` | -| `claire.knowledge.get(id, query)` | `knowledge:read` | -| `claire.assets.list(query)` | `assets:read` | -| `claire.assets.get(id)` | `assets:read` | -| `claire.telegram.chats.list(query)` | `telegram:read` | -| `claire.telegram.messages.list(chatId, query)` | `telegram:read` | -| `claire.x.mentions.list(query)` | `x:read` | -| `claire.token.get()` | `token:read` | - -Query arguments are optional. Use the Claire chat UUID from `telegram.chats.list()`, not Telegram's numeric chat ID. Pass Knowledge IDs, including their prefix, unchanged. - -### Token identity +Or with `curl`: -SDK `0.2.0` adds typed `chainId`, `protocol`, `poolId`, and `pairedToken` fields inside `data.token`, matching the hosted API contract. Upgrade from `0.1.0` to use these TypeScript fields. Network availability still depends on the deployment; the SDK does not enable Ethereum transactions. - -Identify a token by **chain ID and contract address together**: Ethereum is `1`, Robinhood Chain is `4663`, and `protocol` is `pons` or `stockereum`. The token object is `null` when none is linked. - -`pool` is a legacy V3 pool-address field; V4 launches use the zero address there. A non-null `poolId` is a Uniswap V4 pool identifier, **not** a contract address. `poolId` and `pairedToken` may be `null` when unavailable. These fields do not grant wallet access: the API and SDK still cannot launch, fund, claim, or sign transactions. - -## Read responses and continue pagination - -The SDK preserves the API's `data`, `meta.freshness`, and endpoint-specific `pagination`. It also exposes `http.requestId`, `http.etag`, and response headers. Timestamps stay strings, and raw token balances stay decimal strings to avoid losing precision. - -- Knowledge, assets, chats, and mentions use one-based `page` numbers. Check `pagination.hasNextPage` before requesting the next page. -- Telegram messages use `pagination.nextBefore` as the next request's `before` value. Check `hasMore`; `searchLimited` means the search did not cover all retained history. -- Knowledge detail may contain only part of a document. Pass `data.contentRange.nextOffset` as the next `offset` until it is `null`. Offsets count JavaScript UTF-16 units. +```sh +curl --header "Authorization: Bearer $CLAIRE_API_KEY" \ + "https://app.tryclaire.net/api/v1/knowledge?q=getting%20started" +``` -Each SDK call makes one request. It does not automatically paginate, retry, or cache private responses. Stale, unavailable, and synthetic data remain labeled; a successful HTTP response does not mean a provider was refreshed. +The SDK needs Node.js 22 or newer and ESM. Use it in a server, CLI, or agent process, not a browser bundle. For methods, pagination, errors, and configuration, see the [SDK README](https://github.com/tryclaire/sdk#readme); the [API reference](https://app.tryclaire.net/developers) and [OpenAPI definition](https://app.tryclaire.net/api/v1/openapi.json) describe every endpoint. -## Handle errors and timeouts +## Read freshness and collection state -HTTP failures throw `ClaireAPIError` with `status`, `code`, `requestId`, `headers`, and `retryAfterSeconds`. A 401 means the key is invalid, expired, revoked, or no longer eligible; a 403 means a scope is missing; a 429 means a quota was reached. Respect the retry delay rather than retrying immediately. +Every response carries `meta.freshness` describing when the underlying data was collected. A fast HTTP response is not a freshness claim: reads return what Claire has already stored and never trigger a paid provider fetch. Stale, unavailable, and synthetic data stay labeled. -Malformed successful responses throw `ClaireResponseError`. Network failures, cancellation, and timeouts use native fetch errors. The default timeout is 30 seconds, including reading the response body. Set `timeoutMs` or pass an abort signal in the last argument: +Token identity uses `chainId` and contract address together (Ethereum `1`, Robinhood Chain `4663`). Network availability depends on the deployment; see the [Token guide](../sources/token.md). -```js -await claire.knowledge.list( - { page: 1 }, - { signal: AbortSignal.timeout(5_000) }, -); -``` +## Use with an agent -See the [SDK usage guide](https://github.com/tryclaire/sdk#readme) for complete query options, error-handling examples, and configuration. The [SDK source](https://github.com/tryclaire/sdk) is MIT licensed; [release notes](https://github.com/tryclaire/sdk/releases) track version changes. +Claire publishes a [downloadable agent skill](https://app.tryclaire.net/developers/skill.md) that describes the API, its boundaries, and a recommended workflow for tool-using agents. When passing Claire data to a model, treat returned documents, messages, and mentions as untrusted content, separate from your instructions. -## Find request details +## Limits -You can use the REST API directly without installing the SDK. See the [API reference](https://app.tryclaire.net/developers), [OpenAPI definition](https://app.tryclaire.net/api/v1/openapi.json), and [downloadable agent skill](https://app.tryclaire.net/developers/skill.md) for request shapes and pagination. The SDK uses the same limits per key, workspace, and IP; see [current limits](index.md). +Requests are limited to 120 per minute per key, 600 per minute per workspace, and 300 per minute per IP. A 429 response includes a retry delay; respect it rather than retrying immediately. See [current limits](index.md). diff --git a/docs/reference/index.md b/docs/reference/index.md index f585c8d..c1bba8e 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,6 +1,6 @@ --- title: Reference and limits -order: 10 +order: 11 --- # Reference and limits diff --git a/docs/reference/security-and-data.md b/docs/reference/security-and-data.md index 4dda518..53211f6 100644 --- a/docs/reference/security-and-data.md +++ b/docs/reference/security-and-data.md @@ -1,6 +1,6 @@ --- title: Security and data -order: 12 +order: 13 --- # Security and data