API Concepts

The endpoint reference for ValYouRise is generated from the real route definitions and rendered through Fumadocs at /docs/development/api.

Use this page for cross-cutting concepts only. Endpoint-level request, response, and operation details live in the generated OpenAPI reference.

Security and Auth

• Session-cookie auth and PAT header auth are both supported.
• PAT scopes are enforced server-side with the hierarchy read < write < admin.
• The docs playground masks PAT input and redacts it from generated example/code output.
• Once entered, the PAT persists across API pages within the same browser tab (session-scoped). It is cleared automatically when the tab closes and is never written to permanent storage.
• RBAC and workspace privacy decisions are enforced in the API layer, not in the client.

Error Model

Guarded routes return structured JSON errors and attach a code for client-side handling.

Common response patterns include:

• authorization failures such as unauthorized, forbidden, or pat_scope_insufficient
• validation failures for request body, query params, or path params
• domain-specific conflict and state errors such as scrape job state guards or stale item updates

Workspace Privacy Model

• option_1: all workspace members can read all items; writes stay restricted to owners and admins
• option_2: objectives are visible to all members; key results and actions are limited to owners and admins
• Board, list, and related workspace payloads are filtered server-side and should be treated as authoritative

AI Streaming

The AI chat endpoint streams server-sent events instead of returning a single JSON payload.

The generated OpenAPI reference documents the stream response under text/event-stream. The stream emits structured event payloads for:

• text deltas
• tool lifecycle events
• proposed changes
• conversation identifiers
• errors
• completion

AI Provider Modes

• Platform-managed OpenAI key via OPENAI_API_KEY
• User-provided BYOK credentials stored in the Appwrite-backed BYOK configuration

If no provider is available, AI chat routes fail fast instead of silently degrading.

Org Scrape Workflow

The organization scrape flow is designed for guided onboarding and profile enrichment:

1. Create a scrape job for an organization.
2. Poll the job until it reaches a terminal state.
3. Review the generated prefill data.
4. Commit the approved result into organization and optional workspace records.

The background execution is handled by the dedicated Appwrite function org_scrape.

Related Docs

• API reference: /docs/development/api
• Database model: /docs/development/database