ContextStellar Developer Documentation
Real API contracts, authentication requirements, local CLI instructions and agent integration guidance.
Choose the right interface
The public editor analyzes prompts locally without an account. Hosted APIs ingest and query project telemetry; they do not run the browser prompt optimizer for you. The CLI installs local scoring hooks for Claude Code.
Start with the OpenAPI specification for operation IDs, typed request and response schemas, authentication and examples. Do not send prompts or credentials to endpoints that are not listed.
Authenticate without changing your security boundary
Sign in with Clerk for dashboard and management operations. In an existing project where you are an owner or admin, generate an API key in Settings. Save it at creation: only a hash is stored and the full key is not shown again. Keep keys out of prompts, source control and browser URLs.
Use Authorization: Bearer with a project key for ingest and hook endpoints. Read-scoped keys can query traces and hook statistics. They cannot create projects, issue keys or manage policies. Account sessions are not OAuth access tokens.
Make your first request
This read-only request uses a read-scoped project key. The project comes from the key, so it cannot select another tenant. Set CONTEXTSTELLAR_URL to the origin of the installation you intend to use and provide the key through your secret manager or shell environment.
curl "$CONTEXTSTELLAR_URL/api/v1/traces?limit=5" \
-H "Authorization: Bearer $CONTEXTSTELLAR_API_KEY"Errors, limits and safe retries
API errors retain the legacy error string and add code, message and hint fields. Follow the hint, check the HTTP status, and do not treat a non-2xx response as success. Ingestion returns 207: inspect accepted and rejected event counts, not just the HTTP class.
The application applies 100 requests per minute globally and 30 per minute to application API routes, per client IP. Limits are process-local and hosting may impose additional limits. Honor Retry-After and RateLimit headers. Ingestion also enforces the organization monthly event quota; a monthly-quota response is not resolved by immediately retrying.
No dedicated hosted sandbox or automatic organization signup is promised. Use a project provisioned by your organization for testing. Self-serve key generation requires an existing project and appropriate membership.
Machine-readable content
Request supported public pages with Accept: text/markdown. Both HTML and markdown variants vary on Accept. Missing public pages requested as markdown return a real 404 with recovery links. Unknown API paths return structured JSON 404s.
curl -i "$CONTEXTSTELLAR_URL/docs" -H "Accept: text/markdown"