# Custom Endpoints

Custom endpoints let you run server-side business logic “inside” Curiosity Workspace. They are typically used to:

• compute aggregates and analytics over the graph
• implement domain-specific retrieval (similarity, scoping, enrichment)
• orchestrate AI workflows safely (retrieve → validate → generate)
• expose controlled APIs to external systems

The demo repository includes endpoints that combine embeddings-based similarity with graph constraints. A simplified pattern looks like:

class SimilarRequest { public string Query { get; set; } }
var req = Body.FromJson<SimilarRequest>();

// Semantic retrieval for similar items (optionally constrain by type)
return Q().StartAtSimilarText(req.Query, nodeTypes: new[] { "SupportCase" }, count: 50)
          .EmitWithScores();

In production, you typically add:

• input validation (max length, required fields)
• permission-aware scoping
• additional constraints (facets or graph relationships)

Endpoints provide:

• security: authorization and token scoping
• performance: run close to the data
• reusability: one endpoint can serve multiple interfaces/integrations
• governance: endpoints can be reviewed and promoted like code

• Keep endpoints small and composable (single responsibility).
• Prefer read-only endpoints for retrieval and analytics.
• For long-running work, use an asynchronous/polling pattern (if supported in your deployment).
• Always enforce permission-aware retrieval for user-facing endpoints.

• Query endpoints
  • return nodes, neighbors, and graph projections
• Search endpoints
  • wrap search requests with custom defaults and scoping
• Similarity endpoints
  • compute “similar items” using embeddings + constraints
• AI orchestration endpoints
  • retrieve context, construct prompts, trigger generation, store results

If an endpoint is called externally:

• require an endpoint token
• scope tokens to the minimum required endpoint path(s)
• validate inputs (schema and limits) and return safe errors

• Schedule periodic endpoint runs: Scheduled Tasks
• Build a UI that calls endpoints: Interfaces and Integrations