# ContextStellar — Complete Agent Integration Guide ## Purpose and when to use ContextStellar provides local prompt-review tools and separate hosted project telemetry. Use its browser editor to inspect suggested reductions of filler, indirect phrasing and redundant text. Changes can affect meaning; review them and validate results with your chosen model. Counts and reductions are estimates, not guaranteed savings or quality improvements. Use the hosted API to record trace/segment/span events, query authorized telemetry and collect Claude Code hook statistics. Do not call an invented `/optimize` endpoint. The CLI is a local hook installer and scorer, not an arbitrary API client. ## Discovery - [Developer documentation](/docs) - [OpenAPI 3.0.3 contract](/openapi.json) - [Authentication and onboarding](/docs/authentication.md) - [API reference](/docs/api-reference.md) - [Quickstart](/docs/quickstart.md) - [CLI guide](/docs/cli.md) - [SDK availability](/docs/sdk-reference.md) - [Product overview](/docs/overview.md) - [Context concepts](/docs/concepts.md) - [Agent instructions](/CLAUDE.md) - [About](/about) - [Contact](/contact) - [Privacy](/privacy) - [Terms](/terms) - [Sitemap](/sitemap.xml) ## Authentication and tenant boundaries Public content, the browser editor and GET /api/waitlist require no account. GET /api/waitlist is a legacy display count that falls back to zero on dependency failure, not an anonymous scoring service or a health check. Project keys are bearer credentials starting with cs_live_. Obtain a key through the dashboard settings for an existing project where you are an owner or admin. The full secret is shown only once. Generated keys currently have ingest and read scopes. Protect them with a secret manager; do not send them in a URL, source file, prompt or public issue. Clerk cookie sessions authenticate browser management routes. Project keys cannot create projects, issue other keys, edit policies, reorder context segments or delete user data. An invalid project key never grants access to a different tenant. Session-authenticated trace and hook list requests need a permitted project identifier. The app does not currently accept OAuth access tokens or publish an OAuth authorization server. Do not infer OAuth support from the Google login button. A real OAuth implementation requires registered clients, PKCE, consent, token validation and mapping granted permissions to existing local project membership. ## API operations The current OpenAPI file is the source of truth for schemas, operation IDs, parameters and error responses. - POST /api/v1/ingest — ingest-scoped key; record 1–100 events for the key's project. - GET /api/v1/traces and GET /api/v1/traces/{traceId} — read-scoped key or authorized browser session. - POST /api/v1/hooks/claude-code — ingest-scoped key; native snake_case and legacy camelCase hook payloads. - GET /api/v1/hooks/stats — read-scoped key or authorized session. - GET /api/v1/hooks/shell-stats — read-scoped key; compact terminal metrics. - GET/POST /api/v1/projects — browser session; project creation requires organization admin/owner permissions. - GET/PUT/DELETE /api/v1/projects/{id} — browser session; updates require admin/owner, deletion requires owner. - GET /api/v1/projects/{id}/stats — authorized browser session. - GET/POST/DELETE /api/v1/api-keys — browser session; key creation/revocation requires project admin/owner. - GET/POST /api/v1/policies and GET/PUT/DELETE /api/v1/policies/{id} — browser session with membership; writes require admin/owner. - GET /api/v1/alerts — authorized browser session. - GET/PUT /api/learning-progress — browser session, current user only. - GET/POST /api/waitlist — displayed count is public; joining requires a session and configured Google Sheets. - GET/DELETE /api/v1/user/data — browser session, personal application data. Deletion is destructive and does not assert erasure in external services. ## Read-only example Set CONTEXTSTELLAR_URL to the intended installation origin and supply the key securely: ```sh curl "$CONTEXTSTELLAR_URL/api/v1/traces?limit=5" \ -H "Authorization: Bearer $CONTEXTSTELLAR_API_KEY" ``` ## Ingestion and retries Batch JSON contains projectId, idempotencyKey and events. Every event has eventType, id and an ISO-8601 timestamp. Trace and span events also have startedAt; traces include projectId, segments and spans include traceId. Segment events include type, content and a nonnegative integer position. The service returns HTTP 207 with accepted, rejected, errors and policyViolations. An errors entry identifies the event index and a safe error string. Always inspect rejected, even for a 2xx status. The required idempotencyKey field does not establish whole-batch replay suppression; do not promise exactly-once delivery. Use the actual event-ID ownership and update behavior. API failures have error (legacy string), code, message and hint. Examples include UNAUTHORIZED, FORBIDDEN, INVALID_REQUEST, NOT_FOUND, METHOD_NOT_ALLOWED, RATE_LIMITED and INTERNAL_ERROR. Validation details may be included. 5xx responses do not expose internal exceptions. Limits are 100 site requests/minute and 30 application API requests/minute, per client IP and process. Respect Retry-After and RateLimit headers. Ingestion additionally reserves the organization's monthly event allowance, including attempted events. A monthly quota failure needs administrator attention or a later period; immediate retries do not help. ## CLI and package availability The repository contains packages/cli with a self-contained Node.js scorer and installer. The public npm registry returned 404 for @contextstellar/cli when this guide was prepared. Do not recommend npx installation until a maintainer actually publishes and verifies it. From a source checkout: ```sh node packages/cli/bin/contextstellar.mjs --help node packages/cli/bin/contextstellar.mjs stats ``` With the user's permission, `node packages/cli/bin/contextstellar.mjs init` installs a local hook and modifies ~/.claude/settings.json after making a backup. `uninstall` removes hooks but preserves local data. Review these filesystem effects before invoking them. No API key is required for these local commands. The checkout does not contain a functioning @contextstellar/sdk implementation. Use the direct REST contract; do not invent SDK classes or claim an npm package is available. ## Content negotiation and recovery The homepage, editor introduction, guide introduction, /docs, /about and /contact support Accept: text/markdown. This is a readable public representation, not an API for running interactive controls. HTML remains the default, and negotiated variants include Vary: Accept. Unknown public paths requested as markdown return real HTTP 404 with navigation to /docs, /openapi.json, /llms.txt and /sitemap.xml. Unknown API routes return structured JSON 404; unsupported API methods return 405 with Allow. Do not retry the same nonexistent operation as if it succeeded. ## Onboarding, privacy and trust The browser editor is free without signup. Hosted use requires a Clerk account plus existing organization/project membership; there is no promised automatic organization provisioning or dedicated hosted sandbox. Create a separate test project only when you have the required permissions and understand telemetry retention and quotas. Local browser analysis does not submit prompt text to the ingestion endpoint. Hosted trace/segment events can contain content; optional extension Full sync can transmit selected prompt text, while Meta sends counts/scores and site origin. Local CLI history and weights live under ~/.contextstellar. Review the Privacy Policy before uploading sensitive information. About and Contact describe the product and point to the existing privacy/legal contact pages. No public postal address, telephone or newly verified general-support inbox is claimed. No audit score, legal certification, uptime or response-time guarantee is implied.