Nistro AI API Reference

GET/.api-spec

Serves this static API reference from the running server.

Public

HEAD/.api-spec

Returns the API reference headers without the HTML body.

Public

GET/healthz

Returns process health for probes and load balancers.

Public

POST/v1/waitlist

Stores a waitlist signup in Postgres.

PublicRequires Postgres

emailstringrequired

Email address, normalized to lowercase.

namestringoptional

Person or company contact name.

use-casestringoptional

Short description of the intended Nistro AI use case.

GET/v1/auth/config

Returns portal authentication settings, including whether sign-up is enabled for the configured environment type.

Public

200environment_type, signup_enabled, and an optional dev-portal message.

POST/v1/auth/signin

Signs in with Omnistrate customer credentials and returns token, auth, and refresh_token when Omnistrate supplies one.

PublicUses Omnistrate

emailstringrequired

Customer email address.

passwordstringrequired

Customer password.

POST/v1/auth/refresh

Exchanges an Omnistrate refresh token for token, auth, and a replacement refresh_token when Omnistrate supplies one.

PublicUses Omnistrate

refresh_tokenstringrequired

The current Omnistrate refresh token.

200Returns token, auth, and an optional refresh_token.

401SESSION_EXPIRED when the refresh token is invalid or expired.

POST/v1/auth/signup

Creates an Omnistrate customer user. Sign-up is disabled when the server environment type is DEV.

PublicUses Omnistrate

namestringrequired

Customer name.

emailstringrequired

Customer email address.

passwordstringrequired

Customer password.

legalCompanyNamestringrequired

Legal company name.

companyDescription, companyUrlstringoptional

Additional company profile fields forwarded to Omnistrate.

POST/v1/auth/validate-token

Validates the one-time email activation token issued by Omnistrate. No authenticated session is required.

PublicUses Omnistrate

emailstringrequired

Email address from the activation link.

tokenstringrequired

One-time activation token from the email.

POST/v1/auth/password-reset

Asks Omnistrate to email a password reset link. Returns 200 whether or not the email belongs to an account. No authenticated session is required.

PublicUses Omnistrate

emailstringrequired

Email address of the account.

POST/v1/auth/reset-password

Sets a new password with the one-time token from the reset email. No authenticated session is required.

PublicUses Omnistrate

emailstringrequired

Email address from the reset link.

tokenstringrequired

One-time reset token from the email.

passwordstringrequired

The new password.

GET/v1/auth/idp/providers

Renders available Omnistrate identity providers for passwordless or SSO sign-in.

PublicUses Omnistrate

emailquery stringoptional

Login hint forwarded as loginHint.

redirect_urlquery stringoptional

Redirect URL forwarded as redirectUrl.

POST/v1/auth/idp/callback

Completes Omnistrate identity-provider sign-in and returns token, auth, and refresh_token when Omnistrate supplies one.

PublicUses Omnistrate

authorizationCodestringrequired

Code returned by the identity provider.

identityProviderNamestringrequired

Omnistrate identity provider name.

state, redirectUristringoptional

Optional OAuth state and redirect URI.

POST/v1/public/recommendations

Calculates marketing pricing estimates without a customer session. Offers appear only in deployment_options; responses omit recommendations at the top level and inside quantization_options. Base returns only the cheapest offer in the requested location. Scale returns all matching offers in that location, ordered by hourly price. All plans omit the internal instance_price_per_hour_usd while retaining price_per_hour_usd. It considers all sellable regions; deployment-time availability is enforced separately. Public recommendation and quantization requests share a limit of 60 requests per minute per IP. Base offers omit cloud, region, sku, preset, regions, gpu_resource_name, gpu_fraction, and gpu_architecture. Base offers also omit GPU/node/preset counts, fractional_reason, gpu, gpu_vram_gb, vcpu, and ram_gib.

Public

node_countintegeroptional

Scale only: total nodes to price, from 1 through 8; omitted or null defaults to 1. Each offer returns node_count and total price_per_hour_usd = per-node Scale price × node count. GPU and memory sizing remain per node. Base, Enterprise, and BYOA pricing ignore this field.

modelstringconditional

Hugging Face model ID. Required when url is omitted.

urlstringconditional

Hugging Face model URL. Required when model is omitted.

context_length, batch_size, concurrencyintegeroptional

Workload sizing inputs.

quantizationstringoptional

Requested model quantization.

location, cloud, region, instance_typestringoptional

Placement inputs. Base requires location and rejects cloud, region, or instance_type. Explicit location: "ANY" selects the cheapest eligible offer across locations. Scale (pricing_mode: dedicated) requires cloud and region; without instance_type the cheapest machine in that region is used. Scale and Enterprise reject ANY; an omitted or empty location requires both cloud and region and is derived from that placement.

gpu_architecture, gpu_typestringoptional

GPU hardware inputs. Base rejects gpu_type.

dedicatedbooleanoptional

Selects Scale whole-instance allocation with multi-GPU support. Enterprise behavior is unchanged.

pricing_modestringoptional

Pricing tier used for recommendation.

cloud_provider_account_config_idstringoptional

Connected cloud-account context.

200Returns the recommendation response directly.

GET/v1/public/recommendations

Query-string form of the public marketing recommendation endpoint. Public recommendation and quantization requests share a limit of 60 requests per minute per IP.

Public

node_countquery integeroptional

Scale only: total nodes to price, from 1 through 8; omitted defaults to 1. Each offer returns node_count and total price_per_hour_usd = per-node Scale price × node count. GPU and memory sizing remain per node. Base, Enterprise, and BYOA pricing ignore this field.

modelquery stringconditional

Hugging Face model ID. Required when url is omitted.

urlquery stringconditional

Hugging Face model URL. Required when model is omitted.

context_lengthquery integeroptional

Target context window in tokens.

batch_sizequery integeroptional

Target request batch size.

concurrencyquery integeroptional

Target concurrent requests.

quantizationquery stringoptional

Requested model quantization.

locationquery stringoptional

Base requires a location and rejects cloud, region, or instance_type. Scale and Enterprise derive an omitted or empty location from cloud and region; both are required in that case.

cloudquery stringoptional

Cloud-provider override.

regionquery stringoptional

Cloud-region override.

instance_typequery stringoptional

Instance-type override for Scale and Enterprise; rejected on Base.

gpu_architecturequery stringoptional

GPU architecture override.

gpu_typequery stringoptional

GPU type override for Scale and Enterprise; rejected on Base.

dedicatedquery booleanoptional

Selects Scale whole-instance allocation, with multi-GPU support and hourly price C / 0.66. Base hourly price is 0.75 * C * (1 + ((X - 1) / (N - 1))^0.6), where C is hourly instance cloud cost, N is partitions per GPU and X is partitions bought. A one-partition GPU uses the full-allocation price 1.5 * C.

pricing_modequery stringoptional

Pricing tier used for recommendation.

cloud_provider_account_config_idquery stringoptional

Connected cloud-account context.

200Returns the recommendation response directly.

GET/v1/public/vllm/quantizations

Returns model quantization options without a customer session. Public recommendation and quantization requests share a limit of 60 requests per minute per IP. Responses omit recommendations, including within quantization_options.

Public

modelquery stringconditional

Hugging Face model ID. Required when url is omitted.

urlquery stringconditional

Hugging Face model URL. Required when model is omitted.

context_lengthquery integeroptional

Target context window in tokens.

batch_sizequery integeroptional

Target request batch size.

concurrencyquery integeroptional

Target concurrent requests.

quantizationquery stringoptional

Selected quantization input.

locationquery stringoptional

Base defaults an omitted or empty location to ANY and rejects cloud, region, or instance_type. Scale and Enterprise derive an omitted or empty location from cloud and region; both are required in that case.

cloudquery stringoptional

Cloud-provider override.

regionquery stringoptional

Cloud-region override.

instance_typequery stringoptional

Instance-type override for Scale and Enterprise; rejected on Base.

gpu_architecturequery stringoptional

GPU architecture override.

gpu_typequery stringoptional

GPU type override for Scale and Enterprise; rejected on Base.

dedicatedquery booleanoptional

Selects Scale whole-instance allocation with multi-GPU support. Enterprise behavior is unchanged.

pricing_modequery stringoptional

Pricing tier used for recommendation.

cloud_provider_account_config_idquery stringoptional

Connected cloud-account context.

200Returns model_id, model_profile, quantization_options, deployment support fields, and warnings.

POST/v1/public/postgres/offers

Returns public Postgres pricing offers without a customer session. Base and Scale return only the cheapest offer in the requested location across sellable regions, shaped per tier like /v1/postgres/offers: Base omits placement, host sizing, storage type, and price breakdowns. Base requires location and rejects cloud, region, or instance_type; explicit ANY searches across locations. Scale and Enterprise reject ANY; an omitted or empty location requires both cloud and region and is derived from that placement.

PublicRequires price cache

vcpunumberrequired

Requested vCPU amount.

memory_gibnumberrequired

Requested memory in GiB.

storage_gibnumberrequired

Requested storage in GiB.

location, cloud, region, instance_typestringoptional

Placement inputs. Base requires location and rejects cloud, region, or instance_type. Explicit location: "ANY" selects the cheapest eligible offer across locations. Scale (pricing_mode: dedicated) requires cloud and region; without instance_type the cheapest machine in that region is used. Scale and Enterprise reject ANY; an omitted or empty location requires both cloud and region and is derived from that placement.

accept_cheapest, enable_superuserbooleanoptional

Offer-selection and Postgres configuration inputs. enable_superuser is available on Scale and Enterprise only; Base rejects true.

database_name, database_username, database_password, postgres_version, pricing_mode, product_tier_version, instance_id, network_type, cloud_provider_account_config_idstringoptional

Accepted Postgres create and placement inputs.

replicasintegeroptional

Optional for Scale: standby count from 0 to 8, defaulting to zero. Zero leaves one primary and disables its PodDisruptionBudget. Scale estimates compute and storage for the primary plus all standbys: monthly storage is the provider GiB-month rate times requested storage divided by 0.66, multiplied by replicas + 1. Enterprise supports 0 to 8 and defaults to 1.

workload_presetenumoptional

oltp, olap, queuing, or full_text_search. The same presets are available on every tier.

parametersobjectoptional

Custom PostgreSQL parameters are available only on Scale and Enterprise. Base accepts preset selection and an empty object as no overrides, but rejects non-empty parameter objects.

extensionsarrayoptional

PostgreSQL extensions.

200Returns deployment_options and optional warnings.

GET/v1/auth/me

Returns the authenticated Omnistrate identity and resolved Nistro AI tenant session.

Authenticated

POST/v1/auth/signout

Ends the authenticated Omnistrate session.

AuthenticatedUses Omnistrate

200Returns {"ok": true}.

POST/v1/auth/password

Updates the current customer's Omnistrate password using the customer's bearer token.

AuthenticatedUses Omnistrate

current_password or currentPasswordstringrequired

Current password.

password or newPasswordstringrequired

New password.

GET/v1/auth/members

Compatibility alias for GET /v1/access/org-users. Lists Omnistrate users in the current org.

AuthenticatedUses Omnistrate

POST/v1/auth/members

Compatibility alias for POST /v1/access/org-users/invite. Invites a user into the current Omnistrate org, or returns the existing org user when the email is already a member.

Root/AdminUses Omnistrate

emailstringrequired

Email address to invite.

rolestringoptional

Accepted for compatibility; organization invitations do not forward this value.

PATCH/v1/auth/members/{id}

Deprecated local member-role endpoint. It always returns 410; use organization and subscription RBAC through /v1/access/teams and its member endpoints.

AuthenticatedLegacy cleanup

410Local Nistro AI member roles are no longer managed.

GET/v1/access/org-users

Lists users in the current Omnistrate org using the signed-in customer's JWT.

AuthenticatedUses Omnistrate

POST/v1/access/org-users/invite

Invites a user into the current Omnistrate org. Nistro AI checks that the inviter is root or admin, then first checks /org-users. If the email already belongs to the org, this returns already_org_user: true without calling the upstream invite API.

Root/AdminUses Omnistrate

emailstringrequired

Email address to invite into the current org.

rolestringoptional

Accepted for compatibility; organization invitations do not forward this value.

GET/v1/access/teams

Returns Personal plus each shared subscription owner available to the signed-in user. Each team contains friendly product-plan capabilities and an opaque team ID; subscription IDs are never returned.

AuthenticatedUses Omnistrate RBAC

200plans[].key: Self-service keys are postgres.basic, postgres.dedicated, vllm (Base), and vllm.dedicated (Scale) when configured. plans[].requires_approval: True when the Personal team must request and receive approval for the plan before it becomes available. Omitted after approval and for plans that bootstrap lazily.

Personal exposes Postgres Base, Postgres Scale, and vLLM Base before the user's first subscription. vLLM Scale is listed as unavailable with requires_approval: true until its subscription is approved. Shared teams include only active Nistro AI subscriptions visible to the user. Enterprise plans, internal backup, unrelated, inactive, and other-environment subscriptions are excluded from self-service access.

GET/v1/access/teams/{teamID}/members

Lists product-plan access for the selected Personal or shared team. Personal owner grants are returned before their backing subscriptions exist; subscriptions remain lazily created on first deployment or invitation. Grants are grouped by member and never expose subscription IDs.

Plan owner/AdminUses Omnistrate

A shared-team roster includes only plans where the signed-in user has Admin access. Editors and readers cannot view subscription membership.

GET/v1/access/subscription-requests

Lists Omnistrate subscription requests visible to the current user. The optional status query parameter is forwarded to Omnistrate.

AuthenticatedUses Omnistrate

statusquery stringoptional

Subscription-request status filter forwarded to Omnistrate.

POST/v1/access/teams/{teamID}/members

Grants reader, editor, or Admin access to one product plan. Admin is available only when Omnistrate enables subscription Admin RBAC. Nistro AI resolves the backing subscription from the team and access-plan key, creating it on demand for plans that do not require approval.

Plan owner/AdminUses Omnistrate

emailstringrequired

Target user's email address.

access_plan_key or accessPlanKeyenumrequired

postgres.basic, postgres.dedicated, vllm, or vllm.dedicated. Scale without approval returns TEAM_SUBSCRIPTION_REQUIRED; requesting Scale when it already exists returns TEAM_SUBSCRIPTION_EXISTS.

role or role_typeenumrequired

reader, editor, or admin when Admin RBAC is enabled.

The invitation is sent directly through the subscription, matching SaaSBuilder. The same request handles an existing user or a recipient who still needs to sign up; no second grant is required after activation. Shared teams never create missing subscriptions. Before membership changes, historical non-root backup-bucket grants are removed once per bucket. If cleanup cannot finish, the request returns 409 BACKUP_ACCESS_CLEANUP_REQUIRED without changing product access; the subscription owner must retry with an authorized session.

DELETE/v1/access/teams/{teamID}/members

Revokes one exact email, access-plan key, and role grant without changing that user's other product access.

Plan owner/AdminUses Omnistrate

emailstringrequired

Target user's email address.

access_plan_key or accessPlanKeyenumrequired

Exact product plan grant to revoke.

role or role_typeenumrequired

Exact reader, editor, or enabled admin role to revoke.

GET/v1/access/subscriptions

Deprecated raw subscription endpoint. It returns 410 ACCESS_TEAMS_REQUIRED; use GET /v1/access/teams.

AuthenticatedLegacy cleanup

GET/v1/access/subscription-users

Deprecated raw subscription-user endpoint. It returns 410 ACCESS_TEAMS_REQUIRED; use team member endpoints.

AuthenticatedLegacy cleanup

GET/v1/access/subscriptions/{id}/users

Deprecated per-subscription user endpoint. It returns 410 ACCESS_TEAMS_REQUIRED; use GET /v1/access/teams/{teamID}/members.

AuthenticatedLegacy cleanup

POST/v1/access/subscriptions/{id}/users

Deprecated per-subscription grant endpoint. It returns 410 ACCESS_TEAMS_REQUIRED; use POST /v1/access/teams/{teamID}/members.

AuthenticatedLegacy cleanup

DELETE/v1/access/subscriptions/{id}/users

Deprecated per-subscription revoke endpoint. It returns 410 ACCESS_TEAMS_REQUIRED; use DELETE /v1/access/teams/{teamID}/members.

AuthenticatedLegacy cleanup

POST/v1/recommendations

Calculates GPU sizing and cloud placement for a Hugging Face model or URL. Offers appear only in deployment_options; responses omit recommendations at the top level and inside quantization_options. Base returns only the cheapest eligible offer in the requested location. Scale returns all eligible offers in that location, ordered by hourly price, after hosted-region filtering. All plans omit the internal instance_price_per_hour_usd while retaining price_per_hour_usd. The same parameters are also accepted as query parameters with GET. Base offers omit cloud, region, sku, preset, regions, gpu_resource_name, gpu_fraction, and gpu_architecture. Base offers also omit GPU/node/preset counts, fractional_reason, gpu, gpu_vram_gb, vcpu, and ram_gib.

Authenticated

node_countintegeroptional

Scale only: total nodes to price, from 1 through 8; omitted or null defaults to 1. Each offer returns node_count and total price_per_hour_usd = per-node Scale price × node count. GPU and memory sizing remain per node. Base, Enterprise, and BYOA pricing ignore this field.

modelstringconditional

Hugging Face model ID. Required when url is omitted.

urlstringconditional

Hugging Face model URL. Required when model is omitted.

context_lengthintegeroptional

Target context window in tokens.

batch_size, concurrencyintegeroptional

Target batch size and concurrent request count.

quantizationstringoptional

Requested model quantization.

locationenumoptional

US, EU, or ASIA. Base also accepts ANY to select the cheapest eligible offer across locations. Scale and Enterprise reject ANY; an omitted or empty location requires both cloud and region and is derived from that placement.

cloud, region, instance_typestringoptional

Placement overrides for Scale and Enterprise; rejected on Base.

gpu_type, gpu_architecturestringoptional

GPU hardware overrides. Base rejects gpu_type.

dedicatedbooleanoptional

Selects Scale whole-instance allocation with multi-GPU support. Enterprise behavior is unchanged.

pricing_modeenumoptional

Only Base uses GPU time slices, calculated from model memory on a single-GPU instance. Multi-GPU instances are excluded from Base. Scale reserves a whole instance, allows multiple GPUs, and costs cloud cost / 0.66. Base costs 0.75 * C * (1 + ((X - 1) / (N - 1))^0.6), where C is hourly instance cloud cost, N is partitions per GPU and X is partitions bought. Enterprise does not use Base slicing.

cloud_provider_account_config_idstringoptional

Connected cloud-account context; skips hosted-region filtering.

GET/v1/recommendations

Query-string form of the authenticated recommendation endpoint.

Authenticated

node_countquery integeroptional

Scale only: total nodes to price, from 1 through 8; omitted defaults to 1. Each offer returns node_count and total price_per_hour_usd = per-node Scale price × node count. GPU and memory sizing remain per node. Base, Enterprise, and BYOA pricing ignore this field.

modelquery stringconditional

Hugging Face model ID. Required when url is omitted.

urlquery stringconditional

Hugging Face model URL. Required when model is omitted.

context_lengthquery integeroptional

Target context window in tokens.

batch_sizequery integeroptional

Target request batch size.

concurrencyquery integeroptional

Target concurrent requests.

quantizationquery stringoptional

Requested model quantization.

locationquery stringoptional

Base requires a location and rejects cloud, region, or instance_type. Scale and Enterprise derive an omitted or empty location from cloud and region; both are required in that case.

cloudquery stringoptional

Cloud-provider override.

regionquery stringoptional

Cloud-region override.

instance_typequery stringoptional

Instance-type override for Scale and Enterprise; rejected on Base.

gpu_architecturequery stringoptional

GPU architecture override.

gpu_typequery stringoptional

GPU type override for Scale and Enterprise; rejected on Base.

dedicatedquery booleanoptional

Selects Scale whole-instance allocation with multi-GPU support. Enterprise behavior is unchanged.

pricing_modequery stringoptional

Pricing tier used for recommendation.

cloud_provider_account_config_idquery stringoptional

Connected cloud-account context.

GET/v1/vllm/quantizations

Returns server-detected quantization variants for a Hugging Face model or URL. The active KubeAI deployment path serves safetensors/PyTorch weights with vLLM and supported GGUF variants with Ollama. Responses omit recommendations, including within quantization_options.

Authenticated

modelquery stringconditional

Hugging Face model ID. Required when url is omitted.

urlquery stringconditional

Hugging Face model URL. Required when model is omitted.

context_lengthquery integeroptional

Target context window in tokens.

batch_sizequery integeroptional

Target request batch size.

concurrencyquery integeroptional

Target concurrent requests.

quantizationquery stringoptional

Selected quantization input.

locationquery stringoptional

Base defaults an omitted or empty location to ANY and rejects cloud, region, or instance_type. Scale and Enterprise derive an omitted or empty location from cloud and region; both are required in that case.

cloudquery stringoptional

Cloud-provider override.

regionquery stringoptional

Cloud-region override.

instance_typequery stringoptional

Instance-type override for Scale and Enterprise; rejected on Base.

gpu_architecturequery stringoptional

GPU architecture override.

gpu_typequery stringoptional

GPU type override for Scale and Enterprise; rejected on Base.

dedicatedquery booleanoptional

Selects Scale whole-instance allocation with multi-GPU support. Enterprise behavior is unchanged.

pricing_modequery stringoptional

Pricing tier used for recommendation.

cloud_provider_account_config_idquery stringoptional

Connected cloud-account context.

GET/v1/vllm-kubeai/deployments

Lists vLLM/KubeAI deployments readable through the selected team's vLLM subscription. Each deployment includes can_write for its exact subscription and configured min_replicas/max_replicas when its stored KubeAI configuration is available. Deployment responses omit selected_offer. Base deployments also omit cloud and region.

Team reader/editor/admin/rootRequires Postgres

POST/v1/vllm-kubeai/subscriptions

Requests a dedicated vLLM Scale subscription for Personal. Provisioning can begin only after Omnistrate approves the request and the subscription appears in the team.

Root/Admin/MemberUses Omnistrate

pricing_modestringoptional

Defaults to dedicated; dedicated and advanced are accepted.

202status is active with subscription_id, or pending_subscription_approval with subscription_request_id.

409TEAM_PLAN_UNAVAILABLE when a shared team is selected; TEAM_SUBSCRIPTION_EXISTS when Personal already has an active Scale subscription.

POST/v1/vllm-kubeai/deployments

Creates a vLLM or Ollama deployment through KubeAI in the selected team's server-resolved vLLM subscription. Returns only deployment, without selected_offer. Base deployments omit cloud and region.

Team editor/admin/rootRequires PostgresRequires paymentUses Omnistrate

Client-supplied customer, billing, and subscription IDs are not accepted. Personal lazily creates only a missing Base subscription. Scale requires an approved subscription or returns TEAM_SUBSCRIPTION_REQUIRED; requesting Scale again after approval returns TEAM_SUBSCRIPTION_EXISTS. A shared team never creates a subscription. Legacy POST /v1/vllm/deployments returns 410 LEGACY_VLLM_RETIRED.

model_urlstringrequired

Normalized Hugging Face model reference.

model_namestringoptional

Optional model display name.

quantizationstringoptional

Selected quantization variant. The server authoritatively selects vLLM or Ollama from the model format.

enginestringoptional

Accepted as a hint; the recommender selects the authoritative serving engine.

max_model_lenintegeroptional

Requested model context length.

locationstringoptional

Hosted placement for Base and Scale deployments: US, EU, or ASIA. Base requires location and rejects cloud, region, or instance_type. Explicit ANY selects the cheapest eligible placement and returns location: "Nistro Managed"; the database retains ANY in location and stores the selected cloud and region. Scale and Enterprise reject ANY; an omitted or empty location requires both cloud and region and is derived from that placement. An explicit location must match the supplied region, otherwise the request returns HTTP 400. Enterprise deploys into a connected cloud account.

cloud, region, instance_typestringoptional

Placement overrides for Scale and Enterprise; rejected on Base.

gpu_typestringoptional

Requested GPU type for Scale and Enterprise; rejected on Base. The server validates the chosen SKU against recommendation offers.

gpu_count, tensor_parallel_size, min_replicas, max_replicasintegeroptional

Base uses GPU slices and requires gpu_count and tensor_parallel_size to be 1. The server computes gpu_slice_count from model memory and uses gpu:<slice_count> for KubeAI resourceProfile. Scale reserves a whole instance and pins GPU count and tensor parallelism to its physical GPUs. Scale requires both min_replicas and max_replicas explicitly supplied, equal, and between 1 and 8 on creation and updates; autoscaling is not supported. Enterprise behavior is unchanged.

gpu_memory_utilizationnumberoptional

Accepted input; the server calculates the returned value as required model memory divided by assigned pod memory. It is not passed in the vLLM argument block.

enable_prefix_caching, enable_chunked_prefillbooleanoptional

Runtime feature switches.

hf_tokenstringoptional

Hugging Face token for a private model; it is redacted before the request is stored.

pricing_modeenumoptional

basic selects vllm (Base); dedicated or advanced selects vllm.dedicated (Scale); enterprise selects the BYOA plan.

cloud_provider_account_config_idstringoptional

Deploys into a connected customer cloud account when supplied.

The inference API key is generated per deployment and may be read by team readers, editors, admins, and roots after the deployment is ready.

GET/v1/vllm-kubeai/deployments/{id}

Retrieves a deployment after checking both the subscription owner’s organization and selected-team subscription access. Deployment responses omit selected_offer. Base deployments also omit cloud and region.

Team reader/editor/admin/root

PATCH/v1/vllm-kubeai/deployments/{id}

Updates the fixed replica count on an existing Scale deployment. Only min_replicas and max_replicas are accepted. Both must be explicitly supplied, equal, and between 1 and 8. Scale deployments can be created with any fixed count from 1 through 8 and scaled up or down afterward. Autoscaling is not supported.

Team editor/admin/rootScale onlyUses Omnistrate

min_replicasintegerrequired

Between 1 and 8 and equal to max_replicas.

max_replicasintegerrequired

Between 1 and 8 and equal to min_replicas.

202Deployment with status updating and accepted min_replicas/max_replicas. List and detail reads also include configured bounds; the metrics endpoint reports live ready/total replicas while KubeAI reconciles.

400Invalid bounds, unsupported fields, unavailable stored configuration, or a deployment outside the Scale tier.

403TEAM_PLAN_READ_ONLY when the selected team cannot write to this deployment's exact subscription.

404Deployment not found or inaccessible to the selected team.

GET/v1/vllm/deployments

Lists legacy vLLM deployments owned by the authenticated tenant.

Legacy cleanupOrg Root/AdminRequires Postgres

200Returns {"deployments": [...]}.

POST/v1/vllm/deployments

Deprecated legacy create endpoint. It returns 410 LEGACY_VLLM_RETIRED; use POST /v1/vllm-kubeai/deployments.

AuthenticatedLegacy cleanup

GET/v1/vllm/deployments/{id}

Retrieves a legacy vLLM deployment owned by the authenticated tenant.

Legacy cleanupOrg Root/Admin

200Returns the legacy deployment directly.

GET/v1/vllm/deployments/{id}/launch-events

Returns launch sidecar events for a vLLM deployment. Use the backing instance ID returned as the deployment id.

Legacy cleanupOrg Root/Admin

200Returns {"events": [...]}.

GET/v1/vllm/deployments/{id}/launch-events/stream

Streams vLLM launch events as Server-Sent Events using the event name launch_event. Use the backing instance ID returned as the deployment id.

Legacy cleanupOrg Root/AdminSSE

200Streams launch_event events until the client disconnects.

GET/v1/vllm/deployments/{id}/metrics

Returns the latest and recent metrics snapshots for a legacy vLLM deployment.

Legacy cleanupOrg Root/Admin

limitquery integeroptional

Maximum recent samples; defaults to 120. Non-positive or invalid values also use the default.

200Returns deployment_id, latest, and snapshots.

GET/v1/vllm-kubeai/deployments/{id}/metrics

Returns team-scoped runtime state, replica counts, and the latest vLLM/Ollama metrics from the deployment helper.

Team reader/editor/admin/root

POST/v1/internal/vllm/launch-events

Accepts launch lifecycle events from the deployed vLLM progress helper. This route is not authenticated with a customer JWT; it validates the same API key used by the vLLM inference endpoint. The older launch-token credential is still accepted for compatibility.

PublicvLLM API keyInternal callback

Authorizationheaderrequired

Use Bearer <vllm_api_key>.

deployment_idstringrequired

Nistro AI deployment ID or backing instance ID. The server stores events against the internal deployment ID.

event_keystringrequired

Stable event key used for upserts.

phase, level, message, payload, observed_atmixedoptional

Event metadata. Missing phase, level, payload, and observed_at receive server defaults.

202Returns {"status": "accepted"}.

POST/v1/internal/vllm/metrics-snapshots

Accepts periodic runtime metrics from the deployed vLLM metrics helper. The route is protected by the same API key used by the vLLM inference endpoint.

PublicvLLM API keyInternal callback

Authorizationheaderrequired

Use Bearer <vllm_api_key>.

deployment_idstringrequired

Nistro AI deployment ID or backing instance ID. The server stores samples against the internal deployment ID.

sampled_at, timestamp, tokens_per_second, gpu_utilization_percent, kv_cache_usage_percent, vram_used_gb, vram_total_gbmixedoptional

Snapshot fields consumed by the Nistro AI deployment dashboard. timestamp is the fallback sample time when sampled_at is absent.

202Returns {"status": "accepted"}.

DELETE/v1/vllm-kubeai/deployments/{id}

Deletes the backing platform instance after selected-team write authorization.

Team editor/admin/rootUses Omnistrate

DELETE/v1/vllm/deployments/{id}

Deletes a legacy vLLM deployment owned by the authenticated tenant and returns the deployment in deleting state.

Legacy cleanupOrg Root/AdminUses Omnistrate

202Returns the legacy deployment.

GET/v1/postgres/scale/catalog

Lists every supported Scale placement as clouds → regions → instance_types. Requires no request body or sizing inputs. Clouds and regions follow the server's hosted Scale deployment environment; Azure and Base-only pool regions are excluded. Uses the same instance-family rules as Scale offers and includes cached and built-in fallback shapes with positive, finite CPU and memory capacity.

Team reader/editor/admin/rootRequires price cache

Use X-Nistro-Team-ID to select a team. Shared teams require read access to a Scale subscription. Personal can browse before its first subscription.

Each cloud entry has cloud and a regions array. Each region entry has region, location (US, EU, or ASIA), and an instance_types array of strings. Location uses the same mapping as Postgres offers; an unrecognized region has an empty location. All arrays are sorted alphabetically and deduplicated. The response is {"clouds": []} when no hosted placement is available.

Use a returned cloud, region, location, and instance type with pricing_mode: "dedicated" in offers or deployment requests. This catalog lists all choices without selecting a cheapest offer and does not contain prices.

Requested CPU/memory fit, location, replica configuration, payment, and backup readiness are checked by the offers or deployment endpoint. The catalog does not query live cloud capacity.

200Returns the supported Scale catalog.

401A valid customer session is required.

409TEAM_PLAN_UNAVAILABLE: the selected shared team has no readable Scale subscription.

503Postgres deployments or pricing are not configured, or the price cache is unavailable.

GET/v1/postgres/presets

Lists the PostgreSQL workload presets with the parameter values they apply for a CPU/memory allocation, so clients can show them before create or before switching a deployment's preset. Values match what create and PATCH apply for the same vcpu and memory_gib.

Authenticated customer

vcpuquery numberrequired

vCPU allocation, greater than 0 and at most 1024.

memory_gibquery numberrequired

Memory in GiB, greater than 0 and at most 16384.

200Returns {"presets": [{"key": "oltp", "label": "OLTP", "parameters": {"shared_buffers": "2048MB"}}]} with oltp, olap, queuing, and full_text_search in that order. Each key is a valid workload_preset.

400Missing or out-of-range vcpu or memory_gib.

401A valid customer session is required.

POST/v1/postgres/offers

Base uses Azure Epsv5 shared hosts (Standard_E8ps_v5) in centralus for US, and AWS shared hosts (t4g.2xlarge) in eu-west-1 for EU and ap-south-1 for ASIA. Both DEV and PROD deployments support all three locations. Public pricing supports all three locations independently of environment. Base does not fall back to other clouds or regions; Scale and Enterprise placement are unchanged.

Returns Postgres offers for the selected location. Base requires location and rejects cloud, region, or instance_type. Scale and Enterprise derive an omitted or empty location from cloud and region; both are required in that case. An explicit location limits offers even when a region is supplied. Base returns only the deployable offer with the lowest estimated monthly cost in that location, with estimated hourly and monthly prices, source, and requested sizing metadata; it omits placement, host sizing, storage type, price breakdowns, and billing model. Scale returns only the cheapest eligible offer with placement, sizing, and estimated totals, but omits compute and storage price breakdowns and billing model. Enterprise retains full offer details.

Team editor/admin/rootRequires price cache

vcpunumberrequired

Requested vCPU amount, greater than zero. Fractional values are allowed. Base supports up to 8 vCPU.

memory_gibnumberrequired

Requested memory in GiB, greater than zero. Base requires 4 GiB per vCPU and supports up to 32 GiB.

storage_gibnumberrequired

Requested storage in GiB, greater than zero. Base supports up to 1024 GiB (1 TiB).

locationenumoptional

US, EU, or ASIA. Base requires location and rejects cloud, region, or instance_type; explicit ANY selects the cheapest eligible offer across locations. Scale and Enterprise reject ANY and derive an omitted or empty location from cloud and region; both are required in that case.

cloud, region, instance_typestringoptional

Placement overrides for Scale and Enterprise; rejected on Base.

pricing_modeenumoptional

Azure Base compute and storage are temporarily free, with hourly and monthly estimates of zero. AWS Base (basic) compute costs C * M / (0.66 * 32), where C is hourly cloud compute cost and M is purchased memory in GiB. Base estimates use that compute rate plus storage, with 730 hours per month. Scale (dedicated) reserves a whole VM per node and costs C / 0.66 per node per hour. Scale hourly compute is (C / 0.66) * (replicas + 1) (primary plus standbys), with a standby count from 0 to 8, defaulting to zero. Monthly storage is the provider GiB-month rate times requested storage divided by 0.66, multiplied by replicas + 1 for Scale. Base and Enterprise add the storage charge once per deployment. Hourly estimates add total monthly storage divided by 730 to compute; monthly estimates multiply the rounded hourly estimate by 730. Sizing remains per node. Public calculators use the same formulas. Enterprise retains its compute rate.

accept_cheapest, enable_superuserbooleanoptional

Offer-selection and Postgres configuration inputs. enable_superuser is available on Scale and Enterprise only; Base rejects true.

database_name, database_username, database_password, postgres_version, product_tier_version, instance_id, network_type, cloud_provider_account_config_idstringoptional

Accepted Postgres create and placement inputs.

replicasintegeroptional

Optional for Scale: standby count from 0 to 8, defaulting to zero. Zero leaves one primary and disables its PodDisruptionBudget. Scale estimates compute and storage for the primary plus all standbys: monthly storage is the provider GiB-month rate times requested storage divided by 0.66, multiplied by replicas + 1. Enterprise supports 0 to 8 and defaults to 1.

parametersobjectoptional

PostgreSQL parameter map.

extensionsarrayoptional

PostgreSQL extensions.

GET/v1/postgres/deployments

Lists Postgres deployments whose persisted subscription is readable through the selected team. Subscription IDs and stored upstream request/response payloads are not returned. Each deployment includes can_write for the current caller and its exact subscription. Deployment responses omit selected_offer. Base deployments also omit cloud, region, and instance_type. Each deployment includes estimated_price_per_hour_usd and estimated_price_per_month_usd from the latest selected offer, refreshed after accepted storage or replica changes and Base compute resizes; Scale and Enterprise also include storage_type.

Team reader/editor/admin/rootRequires Postgres

POST/v1/postgres/deployments

Creates a CNPG-based Postgres instance in the selected team's server-resolved plan subscription. Returns only deployment, without selected_offer. Base deployments omit cloud, region, and instance_type. Each deployment includes estimated_price_per_hour_usd and estimated_price_per_month_usd from the offer selected at create time. Scale estimates include compute and storage for the primary plus all requested standbys: monthly storage is the provider GiB-month rate times requested storage divided by 0.66, multiplied by replicas + 1; sizing remains per node. Scale and Enterprise also include storage_type.

Team editor/admin/rootRequires PostgresRequires paymentUses Omnistrate

Client-supplied customer, billing, and subscription IDs are not accepted. Personal may lazily create a missing plan subscription; a shared team never creates one. Base deployments do not support backups or snapshots and do not provision backup storage. For Scale and Enterprise, shared members reuse the owner’s ready backup bucket; until the owner finishes initial backup setup, creation returns 409 BACKUP_OWNER_SETUP_REQUIRED.

vcpunumberrequired

Requested vCPU amount, greater than zero. Fractional values are allowed. Base supports up to 8 vCPU.

memory_gibnumberrequired

Requested memory in GiB, greater than zero. Base requires 4 GiB per vCPU and supports up to 32 GiB.

storage_gibnumberrequired

Requested storage in GiB, greater than zero. Base supports up to 1024 GiB (1 TiB).

database_namestringoptional

Database name. Defaults to app.

database_usernamestringoptional

Database username. Defaults to app.

database_passwordstringoptional

Database password. Generated by the server when omitted and returned to authorized team readers, editors, admins, and roots.

postgres_versionstringoptional

PostgreSQL labeled-option value, such as PostgreSQL 16.

replicasintegeroptional

Optional for Scale: standby count from 0 to 8, defaulting to zero. Zero leaves one primary and disables its PodDisruptionBudget. Enterprise supports 0 to 8 and defaults to 1.

enable_superuserbooleanoptional

Enables PostgreSQL superuser access. Scale and Enterprise only; Base rejects true.

workload_presetenumoptional

oltp, olap, queuing, or full_text_search. Case-insensitive display labels such as Queuing are accepted. Omitted means operator defaults. Base presets have read-only parameter values; Scale and Enterprise can override them.

parametersobjectoptional

User-tunable PostgreSQL parameters for Scale and Enterprise; overrides preset values when a preset is supplied. Base accepts an empty object as no overrides but rejects non-empty parameter objects. Without a preset, an empty object retains operator defaults.

extensionsarrayoptional

Create-only extensions. Base rejects non-empty extension lists. Scale accepts only the safe extension allowlist; extended extensions are available only on Enterprise.

location, cloud, region, instance_typestringoptional

Placement inputs. Base requires location and rejects cloud, region, or instance_type. Explicit ANY selects the cheapest eligible placement across locations; deployment responses show location: "Nistro Managed" while the database retains ANY in location and stores the selected cloud and region. Scale (pricing_mode: dedicated) requires cloud and region; without instance_type the cheapest machine in that region is used. Scale and Enterprise reject ANY; an omitted or empty location requires both cloud and region and is derived from that placement.

pricing_modeenumoptional

basic, dedicated, or enterprise.

accept_cheapestbooleanoptional

When true, the server selects the cheapest compatible offer.

cloud_provider_account_config_idstringoptional

Deploys into a connected customer cloud account when supplied.

product_tier_version, instance_id, network_typestringoptional

Optional low-level Omnistrate provisioning inputs accepted by the create schema.

GET/v1/postgres/deployments/{id}

Retrieves a Postgres deployment after checking both the subscription owner’s organization and selected-team subscription access. Deployment responses omit selected_offer. Base deployments also omit cloud, region, and instance_type. Each deployment includes estimated_price_per_hour_usd and estimated_price_per_month_usd from the latest selected offer, refreshed after accepted storage or replica changes and Base compute resizes; Scale and Enterprise also include storage_type.

ready_instances, current_primary, and cluster_status reflect the last observed operator output. Unknown values and health on non-running deployments are omitted. Configured replicas and endpoints do not imply health.

Team reader/editor/admin/root

PATCH/v1/postgres/deployments/{id}

Modifies a Postgres deployment. At least one vCPU, memory, storage, version, superuser, workload preset, parameter, or replica change is required. Base compute can increase or decrease within the create limits; omitted sizing fields retain their current values. Before updating, the server validates and selects a sellable Base offer in the deployment’s location. Base compute resizes retune the selected workload preset. Scale and Enterprise reject vCPU or memory changes with 400. Responses include the selected workload_preset and applied parameters.

Team editor/admin/rootUses Omnistrate

vcpunumberoptional

New vCPU amount for Base only, greater than zero and up to 8. Fractional values are allowed. Can increase or decrease; the resulting memory must equal 4 GiB per vCPU.

memory_gibnumberoptional

New memory size for Base only, greater than zero and up to 32 GiB. Can increase or decrease; must equal 4 GiB per resulting vCPU.

storage_gibnumberoptional

New storage size in GiB. Storage cannot be decreased. Base is capped at 1024 GiB (1 TiB).

postgres_versionstringoptional

Upgrade-only PostgreSQL labeled-option value.

enable_superuserbooleanoptional

Changes superuser access when explicitly supplied. Scale and Enterprise only; Base rejects true.

workload_presetenumoptional

Selects oltp, olap, queuing, or full_text_search, replacing the previous parameter set. Omitted preserves the current preset. Base values are read-only; Scale and Enterprise may supply overrides.

parametersobjectoptional

On Scale and Enterprise, replaces the parameter set unless workload_preset is also supplied, in which case these values override the new preset. Base rejects non-empty parameter objects; an empty object behaves like omission, preserving the current configuration unless a new preset or compute size is supplied.

replicasintegeroptional

Optional on updates; omitted values retain the current count. Scale supports 0 to 8 standbys; zero disables its PodDisruptionBudget and a positive count enables it. Enterprise supports 0 to 8.

202Returns the deployment with accepted sizing, status: updating, and the refreshed hourly and monthly price estimates for a Base compute resize.

400Invalid Base sizing, storage above the Base cap, no sellable offer, compute changes on Scale or Enterprise, or an upstream rejection. Rejected updates do not change stored sizing or prices and do not mark the deployment failed.

POST/v1/postgres/deployments/{id}/start

Starts a stopped Postgres deployment after selected-team write authorization.

Team editor/admin/rootUses Omnistrate

202Returns the updated deployment.

POST/v1/postgres/deployments/{id}/stop

Stops a running Postgres deployment after selected-team write authorization.

Team editor/admin/rootUses Omnistrate

202Returns the updated deployment.

POST/v1/postgres/deployments/{id}/switchover

Requests a CNPG switchover that promotes a specified standby instance as the new primary. Available for Scale and BYOA deployments.

Team editor/admin/rootUses Nistro AI control plane

new_primary or newPrimarystringrequired

CNPG instance name to promote as the new primary.

GET/v1/postgres/snapshots

Lists snapshots readable through the selected team's Scale and Enterprise Postgres subscriptions, including snapshots whose source deployment was deleted. Subscription IDs remain internal. Each snapshot includes can_write for its source subscription. Base snapshots are excluded; teams with only Base subscriptions receive an empty snapshot list.

Team reader/editor/admin/rootRequires PostgresUses Omnistrate

GET/v1/postgres/deployments/{id}/snapshots

Lists snapshots for one Scale or Enterprise Postgres deployment after selected-team read authorization. Base deployments return 403 Forbidden.

Team reader/editor/admin/rootUses Omnistrate

200Returns {"snapshots": [...]}; each snapshot includes can_write.

POST/v1/postgres/deployments/{id}/snapshots

Creates an on-demand snapshot of a Scale or Enterprise Postgres deployment. Base deployments return 403 Forbidden.

Team editor/admin/rootUses Omnistrate

202Returns the accepted snapshot.

POST/v1/postgres/deployments/{id}/snapshots/{snapshotId}/restore

Restores a snapshot as a new tracked Scale or Enterprise Postgres deployment using the source deployment's configuration. Base deployments return 403 Forbidden.

Team editor/admin/rootUses Omnistrate

202Returns the new deployment in restoring state.

DELETE/v1/postgres/deployments/{id}/snapshots/{snapshotId}

Deletes a Scale or Enterprise Postgres snapshot. Base deployments return 403 Forbidden.

Team editor/admin/rootUses Omnistrate

202Returns {snapshot_id, status: "deleting"}.

GET/v1/operations/events

Lists operational events from Omnistrate /2022-09-01-00/fleet/operations/events using the server's configured Fleet API key. The server calls CustomerListResourceInstances with the authenticated customer's token and returns only events with scope: "EndCustomer" for instances in subscriptions readable by the selected team. Send X-Nistro-Team-ID to select a team. Provider events and events with missing or unrecognized scopes are excluded. The scope field is removed from returned events. Events without an accessible instance ID are excluded. The server fixes the environment; environment type, service ID, and service environment ID are not accepted as request filters.

Team reader/editor/admin/rootUses Omnistrate

nextPageTokenquery stringoptional

Opaque upstream pagination cursor. Alias: page_token. Keep the same filters when following a cursor.

pageSizequery integeroptional

Positive target number of visible events; defaults to 20. Alias: page_size. After scope, instance access, and priority filtering, the server reads up to five Fleet pages to fill the response, requesting only the remaining slots on follow-up calls. If Fleet is exhausted or the five-call bound is reached, the response can be short or empty. A continuation cursor is returned when more upstream pages remain.

eventTypesquery string listoptional

Repeatable or comma-separated Fleet event types, for example FailedDeployment,UnhealthyInstance. Forwarded with their original case. Alias: event_types.

instanceIDquery stringoptional

Filter by instance ID. Alias: instance_id. Verified against the selected team's instance inventory before calling Fleet.

startDatequery stringoptional

RFC 3339 lower time bound, forwarded in UTC. Alias: start_date.

endDatequery stringoptional

RFC 3339 upper time bound, forwarded in UTC. Must not precede startDate. Alias: end_date.

productTierIDquery stringoptional

Filter by product tier ID. Alias: product_tier_id.

priorityquery string listoptional

Match any of Critical, High, Medium, or Low, ignoring case. Accepts comma-separated values or repeated parameters: priority=high,critical or priority=high&priority=critical. Duplicates and empty entries are ignored. Applied locally; omitted or entirely empty includes all priorities.

Example: /v1/operations/events?instanceID=instance-123&pageSize=20&priority=high,critical. Scalar parameters accept one value; conflicting aliases are rejected. Other query parameters are ignored.

200Returns {"events": [...], "eventsSummary": {"eventsSummary": {"FailedDeployment": 1}}, "nextPageToken": "..."}. Event fields other than scope are preserved from Fleet: eventID, eventType, eventCategory, eventPayload, alertType, priority, time, expiryTime, and optional instanceID, resourceName, serviceID, serviceName, serviceEnvironmentID, serviceEnvironmentType, servicePlanName, and planVersion. Summary counts are recomputed from the visible page after filtering. nextPageToken is omitted when there is no continuation.

400Invalid query value, date range, or conflicting scalar parameters.

401Missing or invalid customer session.

403Authorization or upstream access denied.

404Requested instance was not found or is not accessible through the selected team, or the selected team was not found.

502Fleet listing, team resolution, or customer access inventory failed. Inventory is bounded to five instance pages; an incomplete inventory returns an error. Upstream 4xx errors retain their status and message.

503Team access, events, or customer access inventory are not configured.

GET/v1/audit-events

Lists account-wide audit events for subscriptions readable by the selected team. Subscription IDs stay internal, the environment is fixed by the server, and cursor paging uses page_token and next_page_token; team filtering means pages may be short or slightly long.

Team reader/editor/admin/rootUses Omnistrate

start_datequery stringoptional

RFC 3339 lower time bound, forwarded in UTC.

end_datequery stringoptional

RFC 3339 upper time bound, forwarded in UTC.

event_typesquery stringoptional

Repeatable or comma-separated event source filter: Customer, Infra, or Maintenance.

productquery stringoptional

Product filter: postgres or vllm.

page_sizequery integeroptional

Requested page size from 1 to 100; defaults to 20.

page_tokenquery stringoptional

Opaque cursor returned as next_page_token by the previous request.

GET/v1/alerts

Lists maintenance upgrade alerts for resource instances in subscriptions readable by the selected team. Send X-Nistro-Team-ID to select a team; the server fixes the environment and follows upstream cursors for up to five pages. An incomplete inventory returns an error. Each valid maintenanceTasks.upgrade_paths entry becomes an alert, reading upgrade_path_status before the legacy upgrade_status. Other maintenance tasks and malformed entries are ignored.

Team reader/editor/admin/rootUses Omnistrate

200Returns {"alerts": [...]}, or an empty array. Each alert includes id (instance ID/upgrade path ID), deployment_id (the console's Omnistrate instance ID), deployment_name (stored database name or model, falling back to the instance ID), product (postgres or vllm), type (maintenance), and raw status. plan is the catalog display name (Base, Scale, or Enterprise), omitted when unknown. scheduled_at is RFC 3339 in UTC, omitted when absent. Alerts are sorted by scheduled time ascending, undated alerts last, then deployment name. Subscription IDs stay internal.

401Missing or invalid customer session.

403Role or upstream access denied.

502Upstream listing, deployment lookup, or the pagination bound prevented a complete result. Upstream 4xx errors retain their status and message.

503Team access or alerts are not configured.

GET/v1/postgres/deployments/{id}/audit-events

Returns Omnistrate audit events after loading the stored deployment and checking selected-team read access.

Team reader/editor/admin/root

DELETE/v1/postgres/deployments/{id}

Deletes the backing platform instance and marks the internal deployment row as deleting. Use the backing instance ID returned as the deployment id.

Team editor/admin/rootUses Omnistrate

GET/v1/usage

Returns priced usage rollups imported from Omnistrate metering. Use /v1/usage/current, /v1/usage/billing-periods, or /v1/usage/billing-periods/{period} for period-specific variants.

Authenticated tenantRequires Postgres

periodquery stringoptional

Billing period in YYYY-MM format.

deployment_idquery stringoptional

Limit usage to one deployment.

GET/v1/usage/current

Returns usage for the current UTC billing period.

Authenticated tenantRequires Postgres

deployment_idquery stringoptional

Limit usage to one deployment.

GET/v1/usage/billing-periods

Returns usage across all billing periods available in the Nistro AI usage store.

Authenticated tenantRequires Postgres

deployment_idquery stringoptional

Limit usage to one deployment.

GET/v1/usage/billing-periods/{period}

Returns usage for a specific billing period.

Authenticated tenantRequires Postgres

periodpath stringrequired

Billing period in YYYY-MM format.

deployment_idquery stringoptional

Limit usage to one deployment.

GET/v1/billing/status

Proxies Omnistrate customer-side billing status for the authenticated customer token.

Authenticated tenantUses Omnistrate

GET/v1/billing/details

Proxies Omnistrate billing details, including payment-method configuration and payment portal URLs.

Authenticated tenantUses Omnistrate

return_urlquery stringoptional

Return URL for Omnistrate payment portal flows. returnUrl is also accepted.

returnUrlquery stringoptional

Camel-case alias for return_url.

subscriptionIDquery stringoptional

Forwarded to Omnistrate.

startDatequery stringoptional

Forwarded to Omnistrate.

endDatequery stringoptional

Forwarded to Omnistrate.

GET/v1/billing/invoices

Proxies Omnistrate invoice data for the authenticated customer token.

Authenticated tenantUses Omnistrate

subscriptionIDquery stringoptional

Forwarded to Omnistrate.

startDatequery stringoptional

Forwarded to Omnistrate.

endDatequery stringoptional

Forwarded to Omnistrate.

GET/v1/billing/usage

Proxies Omnistrate customer-side usage for billing views.

Authenticated tenantUses Omnistrate

subscriptionIDquery stringoptional

Forwarded to Omnistrate.

startDatequery stringoptional

Forwarded to Omnistrate.

endDatequery stringoptional

Forwarded to Omnistrate.

GET/v1/billing/usage-per-day

Proxies Omnistrate daily customer-side usage for billing charts.

Authenticated tenantUses Omnistrate

subscriptionIDquery stringoptional

Forwarded to Omnistrate.

startDatequery stringoptional

Forwarded to Omnistrate.

endDatequery stringoptional

Forwarded to Omnistrate.

GET/v1/deployment-environments

Lists BYOA deployment environments readable through the selected team. Plans and accounts use friendly access_plan_key values; Omnistrate subscription IDs are not returned.

Team reader/editor/admin/rootEnterprise deployments

plansarray

Cataloged BYOA plans available in the selected team, each with an access_plan_key.

subscriptionsarray

Friendly plan entitlement metadata for currently readable subscriptions. This read does not create missing subscriptions.

accountsarray

Connected or offboarding environments in the selected team, including their access_plan_key, setup results, and launch input metadata.

account_config_id, account_config_statusstringoptional

Linked cloud-side account configuration metadata when the environment exposes it.

ready_to_offboardbooleanoptional

Set when server-side cleanup has reached the point where the customer must remove the cloud-side bootstrap resources before final deletion.

account_configobjectoptional

Detailed account-configuration response. The UI uses this to render reconnect or offboard instructions such as a CloudFormation URL or shell command.

Environment deletion is intentionally two-step. The first DELETE starts infrastructure cleanup and the environment can remain visible as DELETING. When ready_to_offboard is true, show the cloud-side offboard instructions from account_config. After the user completes those steps, call DELETE again to remove the environment permanently.

POST/v1/deployment-environments

Connects a cloud account to one friendly product plan. The server resolves the selected team's subscription and submits the account configuration request.

Team editor/admin/rootEnterprise deployments

access_plan_keystringrequired

Friendly plan key from GET /v1/deployment-environments. The server resolves all Omnistrate IDs.

cloud_providerenumrequired

aws, gcp, azure, or nebius. The selected plan must support the cloud.

account_configuration_methodstringoptional

Override for the cloud setup method. Defaults are chosen per cloud.

aws_account_idstringAWS

Required for AWS. aws_bootstrap_role_arn is optional and defaults from the account ID.

aws_bootstrap_role_arnstringAWS

Optional AWS bootstrap role ARN.

aws_regions or awsRegionsarrayAWS

Allowed values are us-east-2, eu-west-1, us-east-1, ap-south-1, and us-west-2. When omitted, all supported AWS regions are enabled.

gcp_project_id, gcp_project_numberstringGCP

Required for GCP. gcp_service_account_email is optional and defaults from the project and tenant when available.

gcp_service_account_emailstringGCP

Optional GCP service-account email.

gcp_regions or gcpRegionsarrayGCP

Allowed values are me-west1, asia-southeast1, us-west1, europe-west1, asia-south1, us-east1, us-east4, europe-west3, australia-southeast1, and us-central1. When omitted, all supported GCP regions are enabled.

azure_subscription_id, azure_tenant_idstringAzure

Required for Azure.

azure_regions or azureRegionsarrayAzure

Allowed values are westus3, westus2, swedencentral, centralus, switzerlandnorth, eastus2, and eastus. When omitted, all supported Azure regions are enabled.

nebius_tenant_idstringNebius

Required for Nebius.

nebius_bindings or nebiusBindingsarrayNebius

At least one binding is required. Each binding requires project_id/projectID, service_account_id/serviceAccountID, public_key_id/publicKeyID, and private_key_pem/privateKeyPEM.

Personal lazily creates a missing subscription on this write. Shared teams never create subscriptions, and reader-only plans return TEAM_PLAN_READ_ONLY.

DELETE/v1/deployment-environments/{id}

Starts or completes deletion for a BYOA deployment environment. The server resolves the plan and subscription for the environment before forwarding the delete request.

Team editor/admin/rootTwo-step offboard

idpath stringrequired

Deployment environment resource instance ID from GET /v1/deployment-environments.

Do not hide environments that return as DELETING. Continue listing them so the user can complete the cloud-side offboard step and then call this endpoint again.

GET/v1/private-connectivity

Lists private network connections configured for the signed-in tenant.

Org Root/Admin

POST/v1/private-connectivity

Creates a private connectivity network for a cloud and region.

Org Root/Admin

namestringrequired

Display name for the private network.

cloudProviderName or cloud_provider_nameenumrequired

aws, gcp, azure, or nebius.

cloudProviderRegion or cloud_provider_regionstringrequired

Cloud region for the private network.

cidrstringrequired

Network CIDR block.

orgId or org_idstringoptional

Organization override when the caller needs to target a specific org context.

PATCH/v1/private-connectivity/{id}

Renames an existing private connectivity network.

Org Root/Admin

idpath stringrequired

Network ID from GET /v1/private-connectivity.

namestringrequired

New display name.

DELETE/v1/private-connectivity/{id}

Deletes a private connectivity network.

Org Root/Admin

idpath stringrequired

Network ID from GET /v1/private-connectivity.

GET/v1/cloud-accounts

Lists connected Omnistrate cloud account configurations for AWS, GCP, Azure, and Nebius.

Org Root/AdminUses Omnistrate

cloudquery stringoptional

Filter to aws, gcp, azure, or nebius. When omitted, all four are queried.

POST/v1/cloud-accounts

Creates an Omnistrate customer cloud account configuration for BYOA deployments.

Org Root/AdminUses Omnistrate

cloud_providerenumrequired

aws, gcp, azure, or nebius.

name, description, cloud_provider_idstringoptional

Display metadata and cloud-provider identifier override.

aws_account_idstringAWS

Required for AWS.

aws_bootstrap_role_arnstringAWS

Defaults from the account ID when omitted.

gcp_project_id, gcp_project_numberstringGCP

Both are required for GCP.

gcp_service_account_emailstringGCP

Optional GCP service-account email.

azure_subscription_id, azure_tenant_idstringAzure

Required for Azure.

nebius_tenant_idstringNebius

Required for Nebius.

POST/v1/billing/stripe/webhook

Receives signed Stripe events and records billing-customer metadata when present. This provider webhook is not intended for ordinary API clients.

AuthenticatedRoot/AdminInternal callback

Stripe-Signatureheaderrequired

Stripe webhook signature accepted within five minutes.

id, type, data.objectmixedprovider payload

Stripe event fields consumed by the handler.

200Returns {"received": "event-id"}.

GET/v1/admin/prices/status

Returns hardware price-cache status.

Root/AdminRequires price cache

POST/v1/admin/prices/refresh

Refreshes cached hardware prices across cloud providers.

Root/AdminRequires price cache

POST/v1/admin/billing/publish

Publishes finalized usage for a billing period through the configured billing publisher.

Root/AdminRequires billing publisher

periodstringoptional

Billing period in YYYY-MM format.

API reference

Authentication

Authorization

Errors