API Overview

Curiosity Workspace exposes its capabilities through three intentionally different surfaces. Picking the right one for each integration is what keeps your deployment secure, performant, and maintainable.

The graph, search, and AI engines are not exposed as raw HTTP routes. You wrap whatever you need in a custom endpoint and ship a stable, versioned contract to your callers. This makes it impossible to bypass scoping or permissions through clever URL manipulation, and gives you a clean place to add validation, rate limiting, and tracing.

What's reachable inside the workspace

Inside a custom endpoint, AI tool, scheduled task, or the admin Shell, you have C# access to:

• Graph
  • Q() fluent traversals: StartAt, Out, In, Where, Take, Emit, EmitWithScores, EmitWithEdges, SortByTimestamp, SortByConnectivity, AsUIDEnumerable.
  • Schema management: CreateNodeSchemaAsync<T>(), CreateEdgeSchemaAsync(...).
  • Upserts and edges: graph.TryAdd(...), graph.Link(a, b, edge).
  • Access control: CreateTeamAsync, CreateUserAsync, AddUserToTeam, RestrictAccessToTeam, RestrictAccessToUser, MarkFileAsPrivate.
• Search
  • SearchRequest.For(text), BeforeTypesFacet, TargetUIDs.
  • Graph.CreateSearchAsync(...) for system-context search, Graph.CreateSearchAsUserAsync(..., CurrentUser, ...) for permission-aware search.
• AI
  • Semantic similarity via Q().StartAtSimilarText(...).
  • ToolScope (in AI tools): scope.Graph, scope.CurrentUser, scope.ChatAI.GetTextFromNode, scope.AddSnippet, scope.SetToolCallDisplayName.
• HTTP context (inside endpoints): Body.FromJson<T>(), CurrentUser, CancellationToken.

See the Graph Query Language, Search DSL, and Schema Reference for the full API surface.

What's reachable from outside

Over HTTP from external code, you can:

• Authenticate via the login endpoints (POST /api/login/create).
• Invoke custom endpoints at POST /api/endpoints/run/{name} (session JWT) or POST /api/endpoints/token/run/{name} (endpoint token).
• Use SSO flows under /api/{provider}sso/... and /api/saml/....
• Read admin metrics at /api/endpoints/metrics and /api/chatai/tools/metrics (admin token).

For the complete contract see the REST API reference.

Authentication

Every authenticated request carries a bearer token:

Authorization: Bearer <token>

There are three token types, each with different lifetimes and scopes:

• User session JWT — issued by the login flow; carries user identity for ReBAC.
• API token — long-lived, scoped to one or more capabilities (ingestion, read, …). Used by connectors and external scripts.
• Endpoint token — long-lived, scoped to one or more endpoint paths. Used by external systems that only need a specific endpoint.

Read the full matrix in Token scopes.

A short decision guide

Versioning and environments

• The Workspace itself ships as versioned container images (curiosityai/curiosity:vX.Y.Z). Breaking changes to the built-in endpoints come with a major version bump and migration notes in the release notes.
• Your endpoints are versioned by you. Put the version in the endpoint name (similar-tickets-v2) and keep the old endpoint live during the deprecation window.
• Treat workspace configuration like code: export connector code, endpoint code, tool code, search/index config, and NLP config from dev → staging → prod with review.

Next steps

• API Usage — practical examples with curl, the SDK, and the chat view.
• Custom Endpoints — write the server side.
• AI Tools — expose endpoints to the chat assistant.
• REST API reference — exact request/response shapes.
• Token scopes — pick the right token type for each caller.
• Error codes — what every status code means.