Orazaka
Pages of the documentation

API reference

Every REST endpoint of every service, with the authorisation rule that guards it.

  • For developers
  • Generated from the code

🤖 Generated from code by scripts/generate-docs.mjs — do not hand-edit. Run orazaka docs build to refresh.

Access is read from each service's SecurityConfig, most-specific matcher first — the same order Spring Security applies. SERVICE is the machine-to-machine authority required on /internal/v1/** (ADR-035); public means no credential at all, and ⚠ no rule means no matcher covers the path — the service has no security on it whatsoever.

automation-service

MethodPathAccessControllerSummary
GET/api/v1/automationsauthenticatedAutomationControllerThe caller's automations.
POST/api/v1/automationsauthenticatedAutomationControllerCreates an automation.
GET/api/v1/automations/{automationId}/runsauthenticatedRunControllerThe runs of one automation.
GET/api/v1/automations/{automationId}/triggersauthenticatedTriggerControllerThe triggers of the automation (no secrets).
POST/api/v1/automations/{automationId}/triggersauthenticatedTriggerControllerAdds a trigger.
DELETE/api/v1/automations/{automationId}/triggers/{triggerId}authenticatedTriggerControllerRemoves a trigger; its runs stay in the history.
PATCH/api/v1/automations/{automationId}/triggers/{triggerId}authenticatedTriggerControllerEnables or disables a trigger.
POST/api/v1/automations/{automationId}/triggers/{triggerId}/rotateauthenticatedTriggerControllerIssues a new secret.
DELETE/api/v1/automations/{id}authenticatedAutomationControllerRemoves an automation with its triggers and history.
GET/api/v1/automations/{id}authenticatedAutomationControllerOne automation.
PATCH/api/v1/automations/{id}authenticatedAutomationControllerChanges an automation; a missing field is left as it is.
GET/api/v1/automations/runsauthenticatedRunControllerEvery run of every automation of the caller.
GET/api/v1/automations/runs/{runId}authenticatedRunControllerOne run, with the webhook body it was started with.
POST/hooks/{triggerId}authenticatedWebhookIngressControllerReceives a signed call and starts the automation it stands for.

conversation-service

MethodPathAccessControllerSummary
POST/api/v1/agent/reportauthenticatedAgentControllerReceives execution reports from the CLI agent after local task completion.
GET/api/v1/agent/streamauthenticatedAgentControllerEstablishes a persistent SSE stream for the CLI agent.
GET/api/v1/assets/{jobId}/{filename}ADMIN + USERAssetControllerStreams one asset to its owner, or to an administrator.
GET/api/v1/chat/sessionsauthenticatedChatController
POST/api/v1/chat/sessionsauthenticatedChatController
DELETE/api/v1/chat/sessions/{sessionId}authenticatedChatController
PATCH/api/v1/chat/sessions/{sessionId}authenticatedChatController
GET/api/v1/chat/stream/{conversationId}ADMIN + USERChatControllerStreams chat via SSE using GET.
POST/api/v1/chat/stream/{conversationId}ADMIN + USERChatControllerStreams chat via SSE using POST (supporting file reference mappings).
POST/api/v1/codeauthenticatedCodeControllerStreams code generation via SSE using POST.
POST/api/v1/embeddingsADMIN + USEREmbeddingController
GET/api/v1/featuresADMIN + USERFeatureControllerWhat this deployment can currently run: every enabled capability with its live degraded-mode state.
PUT/api/v1/features/{featureKey}ADMINFeatureControllerAdmin: toggles an existing capability's enabled state.
GET/api/v1/features/allADMINFeatureControllerAdmin: all capabilities (enabled or not) from the database.
POST/api/v1/intentauthenticatedIntentControllerDispatches a synchronous user intention through the App Factory and returns the result.
POST/api/v1/intent/routepublicIntentControllerM2M Level-0 gate routing: verifies the envelope and returns a signed intent token.
GET/api/v1/jobsauthenticatedJobControllerRetrieves a paginated list of jobs for the authenticated user (or all jobs for admins).
DELETE/api/v1/jobs/{id}ADMIN + USERJobControllerDeletes a finished job's result: files out of every store, row marked deleted (orazaka-web-client#86).
GET/api/v1/jobs/{id}ADMIN + USERJobControllerFetches the single, atomic state of a specific job.
POST/api/v1/jobs/{id}/progressADMIN + USERJobControllerUpdates progress of a running job and broadcasts it to connected users.
POST/api/v1/jobs/{jobId}/approveADMIN + USERJobControllerApproves a pending automation job and dispatches its payload to the execution queue.
POST/api/v1/jobs/{jobId}/revokeADMIN + USERJobControllerRevokes a pending automation job, preventing its execution.
GET/api/v1/jobs/active-connectionsADMINJobControllerRetrieves the current active SSE connection count.
POST/api/v1/jobs/purgeADMINJobControllerPurges jobs, chat sessions and rate-limit cache for the default test accounts.
GET/api/v1/jobs/streamADMIN + USERJobControllerRegisters a Server-Sent Events stream for real-time job status notifications.
GET/api/v1/mcp/servers/platformADMINMcpController
POST/api/v1/mcp/servers/platformADMINMcpController
DELETE/api/v1/mcp/servers/platform/{id}ADMINMcpController
GET/api/v1/mcp/servers/userauthenticatedMcpController
POST/api/v1/mcp/servers/userauthenticatedMcpController
DELETE/api/v1/mcp/servers/user/{id}authenticatedMcpController
GET/api/v1/mcp/toolsauthenticatedMcpControllerRetrieves all registered tools and their schemas.
POST/api/v1/mcp/tools/{name}/executeauthenticatedMcpControllerExecutes a tool by name with the provided arguments.
DELETE/api/v1/media/assets/{assetId}authenticatedMediaAnalysisControllerDeletes one of the caller's own uploads (the sealed file in <uploads>/<user>/temp).
GET/api/v1/media/searchauthenticatedMediaAnalysisControllerPerforms a passive RAG context search against the semantic index.
POST/api/v1/media/uploadauthenticatedMediaAnalysisControllerSecurely uploads a raw binary asset, isolated per authenticated user.
GET/api/v1/modelsADMIN + USERModelControllerRetrieves the local catalog of Ollama models.
POST/api/v1/modelsADMINModelControllerAdds a new model definition to the catalog.
DELETE/api/v1/models/{id}ADMINModelControllerDeletes a model definition by its database ID.
PUT/api/v1/models/{id}ADMINModelControllerUpdates an existing model definition in the catalog.
GET/api/v1/models/admin/auditADMINOperatorAuditController
GET/api/v1/models/catalogauthenticatedModelControllerRetrieves the complete AI model catalog definitions from the database.
GET/api/v1/models/providersauthenticatedModelControllerRetrieves all available AI provider names from the database.
GET/api/v1/models/supportedauthenticatedModelControllerRetrieves the list of supported model names grouped by media type.
GET/api/v1/pipeline/interceptorsADMINPipelineControllerRetrieves all pipeline interceptor configurations ordered by execution order.
PUT/api/v1/pipeline/interceptorsADMINPipelineControllerBulk-updates pipeline interceptor ordering and enabled state.
POST/api/v1/pipeline/interceptors/resetADMINPipelineControllerResets all pipeline interceptor configurations to hardcoded defaults.
GET/api/v1/pipeline/validationADMINPipelineControllerRetrieves all validation pipeline tier configurations ordered by execution order.
PUT/api/v1/pipeline/validationADMINPipelineControllerBulk-updates validation pipeline tier ordering and enabled state.
GET/api/v1/status/graphADMIN + USERStatusControllerCompiles and outputs the operations graph.
GET/api/v1/status/healthpublicStatusControllerReturns sovereign readiness health details (public probe).
GET/api/v1/status/infrastructureauthenticatedStatusControllerReturns the current online/offline snapshot of the local inference engines.
GET/api/v1/voice/clips/{clipId}publicVoiceControllerOne spoken sentence, by its signed URL — no bearer token, because an <audio> element cannot send one; the signature and its five-minute expiry are the authorisation.
POST/api/v1/voice/turnsADMIN + USERVoiceControllerTakes a turn: audio (WAV, Ogg/Opus, WebM, MP3; ~30 s at most) or text, answered over SSE — transcript, delta, sentence (text and a signed audio URL valid 300 s), safety.crisis or scope.refused when a guard answers, then done with the turn's usage and timings.
POST/internal/v1/protected-conversations/eraseSERVICEProtectedConversationControllerErases a person's conversations under a pack.

edge

MethodPathAccessControllerSummary
ANY/**⚠ no ruleProxyControllerCatch-all proxy entry point — everything not served by the edge itself is forwarded.

job-service

MethodPathAccessControllerSummary
DELETE/internal/v1/capabilities/{featureKey}SERVICECapabilityControllerRemoves one capability.
PUT/internal/v1/capabilities/{featureKey}SERVICECapabilityControllerRegisters or replaces one capability a pack contributes.
GET/internal/v1/capabilities/{featureKey}/routeSERVICECapabilityControllerResolves where one capability's work is executed.
GET/internal/v1/jobs/{jobId}/input/imageSERVICEJobOutputControllerThe starting image of a job, for a worker that does not share the platform's disk.
GET/internal/v1/jobs/{jobId}/output/{filename}SERVICEJobOutputControllerReads one of the actor's own outputs back (a step whose input is an earlier step's clip).
PUT/internal/v1/jobs/{jobId}/output/{filename}SERVICEJobOutputControllerStores one output file of a job, sealed, and answers the URL it is served under.
POST/internal/v1/jobs/eraseSERVICEJobErasureControllerErases jobs of one person: rows, files and the durable copy.
GET/internal/v1/models/optionsSERVICEModelOptionsControllerThe published models of one category, the ones that answer first, the default marked.
GET/internal/v1/models/queueSERVICEModelOptionsControllerThe queue a job on a model is published with when it is not the capability's own (a hosted video model is run by the CPU worker's queue, a self-hosted one by the GPU worker's).
POST/internal/v1/workersSERVICEWorkerControllerRegisters a worker, or refreshes what is known about it.
POST/internal/v1/workers/{workerName}/heartbeatSERVICEWorkerControllerRecords a heartbeat from an already-registered worker.

knowledge-service

MethodPathAccessControllerSummary
POST/api/v1/analytics/erasuresauthenticatedAnalyticsControllerForgets subjects and items, in the analytics and the recommender's events.
POST/api/v1/analytics/eventsauthenticatedAnalyticsControllerRecords a batch of events (idempotent by id).
GET/api/v1/analytics/funnelauthenticatedAnalyticsControllerThe ordered funnel of steps over [from, to).
GET/api/v1/analytics/insightsauthenticatedAnalyticsControllerKPIs, series, top items and cohorts over [from, to) (UTC dates, to excluded).
POST/api/v1/recommendations/erasuresauthenticatedRecommendationControllerForgets people and items.
POST/api/v1/recommendations/eventsauthenticatedRecommendationControllerRecords a batch of interaction events (idempotent by id).
GET/api/v1/recommendations/for-youauthenticatedRecommendationControllerThe person's "For you" feed.
GET/api/v1/recommendations/insightsauthenticatedRecommendationControllerA creator's analytics.
POST/api/v1/recommendations/itemsauthenticatedRecommendationControllerUpserts eligible items; the ones whose text changed are embedded.
GET/api/v1/recommendations/similarauthenticatedRecommendationControllerItems like an item.
POST/internal/v1/knowledge/retrieveSERVICEKnowledgeControllerSemantic RAG retrieval over the vector store.
POST/internal/v1/knowledge/sources/searchSERVICEKnowledgeControllerSubstring search over a tool's registered RAG sources.

krizaka-billing-service

MethodPathAccessControllerSummary
GET/api/v1/billing/admin/auditADMINOperatorAuditController
GET/api/v1/billing/configurationADMINConfigurationControllerThe declared key vocabulary — type, permitted domain and code default per key.
PATCH/api/v1/billing/configurationADMINConfigurationControllerApplies one validated configuration change.
GET/api/v1/billing/pack-subscriptionsADMINPackSubscriptionControllerEvery live holder of a pack — what an admin checks before withdrawing one.
GET/api/v1/billing/pack-subscriptions/{actorId}ADMINPackSubscriptionControllerThe packs one actor holds.
GET/api/v1/billing/pack-subscriptions/meauthenticatedPackSubscriptionControllerThe packs the signed-in user holds.
DELETE/api/v1/billing/pack-subscriptions/me/{packKey}authenticatedPackSubscriptionControllerRemoves a pack from the signed-in user.
POST/api/v1/billing/pack-subscriptions/me/{packKey}authenticatedPackSubscriptionControllerAdds a pack to the signed-in user.
GET/api/v1/billing/packsauthenticatedPackControllerThe priced catalogue.
DELETE/api/v1/billing/packs/{packKey}ADMINPackControllerWithdraws a pack from sale.
GET/api/v1/billing/packs/{packKey}authenticatedPackControllerOne pack with its entitlement matrix.
PUT/api/v1/billing/packs/{packKey}ADMINPackControllerCreates or replaces a pack's price and entitlements.
GET/api/v1/billing/packs/pricesauthenticatedPackControllerThe whole price table, for the Pack catalogue to render a marketplace page from.
GET/api/v1/billing/plansauthenticatedPlanControllerThe catalogue.
DELETE/api/v1/billing/plans/{planKey}ADMINPlanControllerRetires a plan — deactivated, never deleted, because subscriptions reference it.
GET/api/v1/billing/plans/{planKey}authenticatedPlanControllerOne plan with its entitlement matrix.
PUT/api/v1/billing/plans/{planKey}ADMINPlanControllerCreates or replaces a plan.
GET/api/v1/billing/pricebookADMINPricebookController
POST/api/v1/billing/pricebookADMINPricebookController
GET/api/v1/billing/pricebook/estimateauthenticatedPricebookControllerWhat an action would cost the signed-in user, and whether they can cover it.
GET/api/v1/billing/pricebook/historyADMINPricebookController
POST/api/v1/billing/pricebook/previewADMINPricebookController
GET/api/v1/billing/subscriptionsADMINSubscriptionControllerEvery live subscriber of a plan — what an admin checks before retiring one.
DELETE/api/v1/billing/subscriptions/{actorId}ADMINSubscriptionControllerEnds an actor's subscription.
GET/api/v1/billing/subscriptions/{actorId}ADMINSubscriptionControllerThe subscription in force for an actor.
POST/api/v1/billing/subscriptions/{actorId}ADMINSubscriptionControllerMoves an actor onto a plan — upgrade, downgrade or trial.
POST/api/v1/billing/subscriptions/{actorId}/rolloverADMINSubscriptionControllerRolls a subscription into its next period, honouring a pending cancellation.
GET/api/v1/billing/usage/capabilitiesADMINUsageControllerConsumption and refusals per capability × model.
GET/api/v1/billing/usage/top-consumersADMINUsageControllerThe heaviest consumers.
GET/api/v1/billing/wallets/{actorId}ADMINWalletControllerReads an actor's balances.
POST/api/v1/billing/wallets/{actorId}/adjustmentsADMINWalletControllerIssues a manual credit adjustment — support goodwill, or a claw-back.
GET/api/v1/billing/wallets/{actorId}/entitlementsADMINWalletControllerReads an actor's effective entitlements plus their balance summary.
GET/api/v1/billing/wallets/adjustments/todayADMINWalletControllerWhat an admin has already adjusted today, against their ceiling.
GET/api/v1/billing/wallets/meauthenticatedWalletControllerThe signed-in user's own balances.
GET/api/v1/billing/wallets/me/entitlementsauthenticatedWalletControllerThe signed-in user's own entitlements and available balance.
POST/internal/v1/billing/credits/{holdId}/releaseSERVICECreditControllerCloses a hold with no debit.
POST/internal/v1/billing/credits/{holdId}/settleSERVICECreditControllerCloses a hold against measured consumption.
POST/internal/v1/billing/credits/{holdId}/settle-aggregateSERVICECreditControllerCloses one hold against the measurements of the several steps it authorised.
POST/internal/v1/billing/credits/{holdId}/settle-measuredSERVICECreditControllerCloses a hold against an executor's raw measurements, pricing them in the unit the hold's pinned rate uses.
POST/internal/v1/billing/credits/holdsSERVICECreditControllerReserves the estimated cost of a request.
GET/internal/v1/billing/entitlements/{actorId}SERVICEEntitlementControllerReads an actor's effective entitlements plus their balance summary.
DELETE/internal/v1/billing/packs/{packKey}SERVICEPackProvisioningControllerWithdraws a pack from sale, so a failed install can undo the half it already applied.
PUT/internal/v1/billing/packs/{packKey}SERVICEPackProvisioningControllerCreates or replaces a pack's price and entitlement matrix.

krizaka-users-service

MethodPathAccessControllerSummary
GET/api/v1/admin/usersADMINAdminUserController
DELETE/api/v1/admin/users/{id}ADMINAdminUserController
GET/api/v1/admin/users/{id}ADMINAdminUserController
PUT/api/v1/admin/users/{id}/adminADMINAdminUserController
GET/api/v1/admin/users/{id}/exportADMINAdminUserController
POST/api/v1/admin/users/{id}/restoreADMINAdminUserController
POST/api/v1/admin/users/{id}/suspendADMINAdminUserController
GET/api/v1/admin/users/auditADMINAdminUserController
GET/api/v1/api-keysauthenticatedApiKeyController
POST/api/v1/api-keysauthenticatedApiKeyController
DELETE/api/v1/api-keys/{id}ADMIN + USERApiKeyController
POST/api/v1/auth/forgotpublicAuthControllerForgot password endpoint.
POST/api/v1/auth/loginpublicAuthControllerLogin endpoint.
POST/api/v1/auth/oauthpublicAuthControllerOAuth2 Token-Exchange login endpoint.
POST/api/v1/auth/registerpublicAuthControllerRegister endpoint.
POST/api/v1/auth/resetpublicAuthControllerReset password endpoint.
POST/api/v1/auth/verifypublicAuthControllerVerifies the provided account activation token.
GET/api/v1/credentialsauthenticatedCredentialController
POST/api/v1/credentialsauthenticatedCredentialController
DELETE/api/v1/credentials/{providerName}ADMIN + USERCredentialController
GET/api/v1/interceptions/{schemaId}authenticatedInterceptionControllerReturns the raw interception schema JSON for the given schema id, served as text so the JSON string is not double-encoded by Jackson (the client parses it).
POST/api/v1/interceptions/resolveauthenticatedInterceptionControllerResolves an active interception by merging the user's responses.
GET/api/v1/profileauthenticatedProfileControllerReturns the authenticated user's profile.
PUT/api/v1/profile/preferencesADMIN + USERProfileControllerUpdates the authenticated user's preference map and returns the refreshed profile.
GET/internal/v1/tiers/{key}SERVICEInternalUserControllerBucket parameters of a rate-limit tier.
GET/internal/v1/tiers/defaultSERVICEInternalUserControllerThe DB-flagged default rate-limit tier (anonymous callers).
POST/internal/v1/tokens/exchangeSERVICEInternalUserControllerExchanges a valid oz_ API key for a session JWT (performed by the edge).
GET/internal/v1/users/{id}SERVICEInternalUserControllerFull user snapshot for downstream principal hydration (404 via UserNotFoundException).
GET/internal/v1/users/{id}/credentials/{provider}SERVICEInternalUserControllerThe user's decrypted BYOK provider key (service-to-service only).
GET/internal/v1/users/{id}/profileSERVICEInternalUserControllerThe user's profile for pipeline context assembly.

studio-service

MethodPathAccessControllerSummary
GET/api/v1/studiosauthenticatedStudioControllerThe catalogue, optionally narrowed to one profession.
GET/api/v1/studios/{studioKey}authenticatedStudioControllerOne Studio's detail, including the schemas its forms are generated from.
GET/api/v1/studios/{studioKey}/blueprintsADMINStudioBlueprintControllerEvery version of a Studio, drafts included — the Builder's version list.
DELETE/api/v1/studios/{studioKey}/blueprints/{version}ADMINStudioBlueprintControllerDeprecates a version without deleting it.
PUT/api/v1/studios/{studioKey}/blueprints/{version}ADMINStudioBlueprintControllerCreates or replaces a draft version.
POST/api/v1/studios/{studioKey}/blueprints/{version}/publishADMINStudioBlueprintControllerPublishes a draft, minting it as the Studio's latest version.
POST/api/v1/studios/{studioKey}/installationsauthenticatedStudioInstallationControllerInstalls a Studio, pinning its newest published version.
POST/api/v1/studios/{studioKey}/policy-checkauthenticatedStudioRunControllerDry-run of the content policy: what would a run with these inputs do? Nothing is held, stored or sent to a provider.
POST/api/v1/studios/{studioKey}/runsauthenticatedStudioRunControllerStarts a run of a Studio, addressed by its key rather than by an installation.
GET/api/v1/studios/{studioKey}/versionsauthenticatedStudioControllerA Studio's version history.
GET/api/v1/studios/admin/auditADMINOperatorAuditController
GET/api/v1/studios/composerauthenticatedStudioControllerThe Studios that belong in a chat composer, for this actor.
GET/api/v1/studios/installationsauthenticatedStudioInstallationController"My Studios".
DELETE/api/v1/studios/installations/{installationId}authenticatedStudioInstallationControllerUninstalls, keeping the configuration for a future reinstall.
GET/api/v1/studios/installations/{installationId}authenticatedStudioInstallationControllerOne installation.
PATCH/api/v1/studios/installations/{installationId}authenticatedStudioInstallationControllerReplaces an installation's configuration.
POST/api/v1/studios/installations/{installationId}/runsauthenticatedStudioRunControllerStarts a run.
POST/api/v1/studios/installations/{installationId}/upgradeauthenticatedStudioInstallationControllerMoves the pin to the newest published version — never automatic.
GET/api/v1/studios/packsauthenticatedPackCatalogControllerThe marketplace, optionally narrowed to one shelf.
GET/api/v1/studios/packs/{packKey}authenticatedPackCatalogControllerOne Pack's detail.
GET/api/v1/studios/packs/{packKey}/consentauthenticatedProtectedDataControllerWhat a person agrees to, in their language, with the verified crisis line of each region.
DELETE/api/v1/studios/packs/{packKey}/my-dataauthenticatedProtectedDataControllerErases everything the pack holds of the caller: entries, inputs and outputs, files, installations and the consent they recorded.
POST/api/v1/studios/packs/bundlesADMINPackBundleControllerInstalls a bundle.
DELETE/api/v1/studios/packs/bundles/{bundleKey}ADMINPackBundleControllerRemoves a bundle's catalogue rows and withdraws its pack from sale.
POST/api/v1/studios/packs/bundles/validationADMINPackBundleControllerChecks a bundle against this platform without writing anything.
GET/api/v1/studios/packs/categoriesauthenticatedPackCatalogControllerThe shelves themselves, so the client renders headings it did not have to invent.
GET/api/v1/studios/runsauthenticatedStudioRunControllerThis actor's run history.
DELETE/api/v1/studios/runs/{runId}authenticatedProtectedDataControllerErases one entry of the caller's: a run of a protected pack, with its inputs, outputs and files.
GET/api/v1/studios/runs/{runId}authenticatedStudioRunControllerOne run with its per-step states and outputs.
POST/api/v1/studios/runs/{runId}/approveauthenticatedStudioRunControllerResolves an approval step, resuming the run.
POST/api/v1/studios/runs/{runId}/cancelauthenticatedStudioRunControllerCancels a run and releases its hold.
GET/api/v1/studios/runs/{runId}/eventsauthenticatedStudioRunControllerFollows a run as Server-Sent Events instead of polling it (orazaka#189, ADR-083).
GET/api/v1/studios/runs/eventsauthenticatedStudioRunControllerFollows every run of the caller on one connection (the per-key stream of orazaka#189): event: run whenever a run in flight changes, event: done when one ends, each carrying the run as GET /runs/runId would.
GET/api/v1/studios/webhooksauthenticatedWebhookEndpointControllerThe caller's endpoints (no secrets).
POST/api/v1/studios/webhooksauthenticatedWebhookEndpointControllerCreates an endpoint.
DELETE/api/v1/studios/webhooks/{id}authenticatedWebhookEndpointControllerRemoves an endpoint and its log.
GET/api/v1/studios/webhooks/{id}/deliveriesauthenticatedWebhookEndpointControllerThe delivery log of an endpoint, newest first.
POST/api/v1/studios/webhooks/{id}/rotateauthenticatedWebhookEndpointControllerIssues a new secret.
GET/internal/v1/installations/{installationId}/turn-declarationsSERVICEInstallationDeclarationControllerWhat a turn taken under this installation must carry: the pack's guards, the reviewed crisis reply for the installation's region, and the pack's system prompt.

View the source on GitHub