OneOS Docs
Genesis 0.1.12 Console

API reference

Hives

Compute: projects, deployments, functions, secrets, schedules, queues, topics, volumes, metrics and logs.

Operations
175
Base path
https://os.one.ml/api/v1/hives
Scopes
hives:read hives:write
API keys
26 failed with an API key · 27 need a signed-in session · 4 refused to API keys · 53 not yet tested · 65 tested with an API key
SDK
genesis.call('hives_me', …) · helpers under genesis.hives
CLI
genesis hives
MCP
131 tools; the other 44 through genesis_call

Operations

OperationEndpointAPI key
Return the authenticated user.GET/auth/meTested with an API key
List invoices for the authenticated orgGET/billing/invoicesSigned-in session
Get a specific invoiceGET/billing/invoices/{invoice_id}Signed-in session
List available billing plans (public)GET/billing/plansSigned-in session
Create a new subscriptionPOST/billing/subscribeSigned-in session
Get current subscription for the authenticated orgGET/billing/subscriptionSigned-in session
Cancel subscriptionDELETE/billing/subscriptionSigned-in session
Change subscription planPUT/billing/subscription/planSigned-in session
Get usage summary for the authenticated orgGET/billing/usageSigned-in session
hives_get_context_projectGET/context/projectAPI keys refused
hives_set_context_projectPOST/context/projectAPI keys refused
hives_detach_context_projectDELETE/context/projectAPI keys refused
List all fleets known to the controller.GET/fleetsFailed with an API key
Deploy a MAP fleet from a TOML manifest.POST/fleetsTested with an API key
Get detailed status for a single fleet.GET/fleets/{fleet_id}Failed with an API key
Teardown a fleet — stop all instances and remove from discovery.DELETE/fleets/{fleet_id}Failed with an API key
List organizations for the authenticated userGET/organizationsSigned-in session
Create a new organizationPOST/organizationsSigned-in session
Get a single organizationGET/organizations/{org_id}Signed-in session
Delete an organizationDELETE/organizations/{org_id}Signed-in session
Update an organizationPATCH/organizations/{org_id}Signed-in session
List pending invitesGET/organizations/{org_id}/invitesSigned-in session
Invite a member to the organizationPOST/organizations/{org_id}/invitesSigned-in session
Cancel a pending inviteDELETE/organizations/{org_id}/invites/{invite_id}Signed-in session
List organization membersGET/organizations/{org_id}/membersSigned-in session
Remove a member from the organizationDELETE/organizations/{org_id}/members/{member_id}Signed-in session
Update a member's rolePUT/organizations/{org_id}/members/{member_id}/roleSigned-in session
Get SSO configuration for an organizationGET/organizations/{org_id}/ssoSigned-in session
Create a new SSO connectionPOST/organizations/{org_id}/ssoSigned-in session
Delete an SSO connectionDELETE/organizations/{org_id}/sso/{connection_id}Signed-in session
Get organization usage (proxied to Cabbage)GET/organizations/{org_id}/usageSigned-in session
Create a Stripe checkout sessionPOST/payments/checkoutSigned-in session
List payment methods for the authenticated orgGET/payments/methodsSigned-in session
Add a payment methodPOST/payments/methodsSigned-in session
Get Stripe billing portal URLPOST/payments/portalSigned-in session
List all projects for the authenticated tenantGET/projectsTested with an API key
Create a new projectPOST/projectsTested with an API key
Get a project by IDGET/projects/{project_id}Failed with an API key
Delete a projectDELETE/projects/{project_id}Tested with an API key
Update a projectPATCH/projects/{project_id}Tested with an API key
List activity for an authenticated org's projectGET/projects/{project_id}/activityTested with an API key
List all cron jobs for a projectGET/projects/{project_id}/cronTested with an API key
Create a new cron jobPOST/projects/{project_id}/cron—
Get a specific cron jobGET/projects/{project_id}/cron/{cron_id}—
Delete a cron jobDELETE/projects/{project_id}/cron/{cron_id}—
Update a cron jobPATCH/projects/{project_id}/cron/{cron_id}—
Pause a cron jobPOST/projects/{project_id}/cron/{cron_id}/pause—
Resume a cron jobPOST/projects/{project_id}/cron/{cron_id}/resume—
Get run history for a cron jobGET/projects/{project_id}/cron/{cron_id}/runs—
Manually trigger a cron jobPOST/projects/{project_id}/cron/{cron_id}/trigger—
List all deployments for a projectGET/projects/{project_id}/deploymentsTested with an API key
Create a new deploymentPOST/projects/{project_id}/deployments—
Get a specific deploymentGET/projects/{project_id}/deployments/{deployment_id}—
Delete an inactive deploymentDELETE/projects/{project_id}/deployments/{deployment_id}—
Cancel a pending deployment and stop its runtime workPOST/projects/{project_id}/deployments/{deployment_id}/cancel—
Invoke a real running owned deployment and return the raw guest HTTP responsePOST/projects/{project_id}/deployments/{deployment_id}/invoke—
Query logs for a projectGET/projects/{project_id}/deployments/{deployment_id}/logs—
Get deployment metricsGET/projects/{project_id}/deployments/{deployment_id}/metrics—
Promote a deployment to productionPOST/projects/{project_id}/deployments/{deployment_id}/promote—
Roll back to the selected deployment in this projectPOST/projects/{project_id}/deployments/{deployment_id}/rollback—
Stop an active deployment after runtime acknowledgmentPOST/projects/{project_id}/deployments/{deployment_id}/stop—
Upload a real WASM artifact and deploy itPOST/projects/{project_id}/deployments/uploadFailed with an API key
List all domains for a projectGET/projects/{project_id}/domainsTested with an API key
Add a custom domain to a projectPOST/projects/{project_id}/domainsTested with an API key
Provision SSL certificate for a domainPOST/projects/{project_id}/domains/{domain_id}/ssl—
Verify domain DNS configurationPOST/projects/{project_id}/domains/{domain_id}/verify—
Reveal one owned environment value through Genesis KMS with org/project AAD.GET/projects/{project_id}/env/{key}/revealTested with an API key
List persisted environment names, including retained legacy entries.GET/projects/{project_id}/env/metadataTested with an API key
Encrypt and persist a flat map; acknowledge updated names without values.PUT/projects/{project_id}/env/metadataTested with an API key
List all functions for a projectGET/projects/{project_id}/functionsTested with an API key
Create a new functionPOST/projects/{project_id}/functions—
Get a specific functionGET/projects/{project_id}/functions/{function_id}—
Update an owned function and encrypted overridesPUT/projects/{project_id}/functions/{function_id}—
Unregister an owned function before removing metadataDELETE/projects/{project_id}/functions/{function_id}—
Complete a real function invocation and return the raw guest HTTP responsePOST/projects/{project_id}/functions/{function_id}/invoke—
Complete invocation through the compatibility alias (no durable queue)POST/projects/{project_id}/functions/{function_id}/invoke/async—
Get function metricsGET/projects/{project_id}/functions/{function_id}/metrics—
Get function invocations time seriesGET/projects/{project_id}/functions/{function_id}/metrics/invocations—
Read original funding operation status without replaying the guestGET/projects/{project_id}/functions/{function_id}/operations/{operation_id}—
Release an unused reservation only if no guest dispatch occurredPOST/projects/{project_id}/functions/{function_id}/operations/{operation_id}/release—
Query logs for a projectGET/projects/{project_id}/logsTested with an API key
Stream real-time logs for a project via SSEGET/projects/{project_id}/logs/streamTested with an API key
Return existing categories with visibility-scoped actual counts.GET/projects/{project_id}/marketplace/categoriesTested with an API key
Return only persisted featured packages backed by real artifacts.GET/projects/{project_id}/marketplace/featuredTested with an API key
List selected-project installations, preserving unresolved state.GET/projects/{project_id}/marketplace/installedTested with an API key
Read a persisted installation after an interrupted operation.GET/projects/{project_id}/marketplace/installed/{installation_id}—
Persist uninstall intent before stopping every retained workload.DELETE/projects/{project_id}/marketplace/installed/{installation_id}—
Explicitly finish an existing durable operation; this never starts a build.POST/projects/{project_id}/marketplace/installed/{installation_id}/reconcile—
Search the persisted visible catalog.GET/projects/{project_id}/marketplace/packagesTested with an API key
Read the selected package and its actual immutable versions.GET/projects/{project_id}/marketplace/packages/{slug}—
Install a real package. A 202 acknowledges the durable operation, not readiness.POST/projects/{project_id}/marketplace/packages/{slug}/install—
Update through a real successor deployment while retaining the old runtime.POST/projects/{project_id}/marketplace/packages/{slug}/update—
Read every eligible version using bounded pages.GET/projects/{project_id}/marketplace/packages/{slug}/versions—
Publish a verified selected-project artifact; never fetch an arbitrary URL.POST/projects/{project_id}/marketplace/packages/publish—
Get project metrics overviewGET/projects/{project_id}/metricsTested with an API key
Get dashboard metrics for retained completed API invocations.GET/projects/{project_id}/metrics/dashboardTested with an API key
Get error rate metricsGET/projects/{project_id}/metrics/errorsTested with an API key
Get response time metricsGET/projects/{project_id}/metrics/latencyTested with an API key
Get real-time metrics for dashboardGET/projects/{project_id}/metrics/realtimeTested with an API key
Get request metrics time seriesGET/projects/{project_id}/metrics/requestsTested with an API key
Get measured API invocation metadata and real owned resource countsGET/projects/{project_id}/metrics/usageTested with an API key
hives_list_native_queueGET/projects/{project_id}/queuesTested with an API key
hives_create_native_queuePOST/projects/{project_id}/queuesTested with an API key
hives_inspect_native_queueGET/projects/{project_id}/queues/{queue_id}Tested with an API key
hives_delete_native_queueDELETE/projects/{project_id}/queues/{queue_id}Tested with an API key
hives_configure_native_queuePATCH/projects/{project_id}/queues/{queue_id}Failed with an API key
hives_get_native_queue_consumerGET/projects/{project_id}/queues/{queue_id}/consumerTested with an API key
hives_configure_native_queue_consumerPUT/projects/{project_id}/queues/{queue_id}/consumerFailed with an API key
hives_remove_native_queue_consumerDELETE/projects/{project_id}/queues/{queue_id}/consumerTested with an API key
hives_consumers_native_queueGET/projects/{project_id}/queues/{queue_id}/consumersFailed with an API key
hives_dead_letters_native_queueGET/projects/{project_id}/queues/{queue_id}/dlqFailed with an API key
hives_purge_dlq_native_queueDELETE/projects/{project_id}/queues/{queue_id}/dlqFailed with an API key
hives_delete_dlq_native_queueDELETE/projects/{project_id}/queues/{queue_id}/dlq/{message_id}Failed with an API key
hives_replay_native_queuePOST/projects/{project_id}/queues/{queue_id}/dlq/replayFailed with an API key
hives_dlq_stats_native_queueGET/projects/{project_id}/queues/{queue_id}/dlq/statsFailed with an API key
Send one message with an explicit original funding key when requiredPOST/projects/{project_id}/queues/{queue_id}/messagesAPI keys refused
hives_ack_native_queuePOST/projects/{project_id}/queues/{queue_id}/messages/{message_id}/ackFailed with an API key
hives_nack_native_queuePOST/projects/{project_id}/queues/{queue_id}/messages/{message_id}/nackFailed with an API key
hives_receive_native_queuePOST/projects/{project_id}/queues/{queue_id}/messages/receiveTested with an API key
Read the original queue send operation without any queue effectGET/projects/{project_id}/queues/{queue_id}/operations/{operation_id}Failed with an API key
hives_pause_native_queuePOST/projects/{project_id}/queues/{queue_id}/pauseTested with an API key
hives_purge_native_queuePOST/projects/{project_id}/queues/{queue_id}/purgeTested with an API key
hives_resume_native_queuePOST/projects/{project_id}/queues/{queue_id}/resumeTested with an API key
hives_stats_native_queueGET/projects/{project_id}/queues/{queue_id}/statsTested with an API key
Create a debug session for attaching to a running instancePOST/projects/{project_id}/remote/debugFailed with an API key
List active remote sessions for a projectGET/projects/{project_id}/remote/sessionsFailed with an API key
Close an active remote sessionDELETE/projects/{project_id}/remote/sessions/{session_id}—
Delete a file via SFTPDELETE/projects/{project_id}/remote/sftp/{target_id}/deleteFailed with an API key
List files via SFTPGET/projects/{project_id}/remote/sftp/{target_id}/ls—
Read a file via SFTP (returns base64-encoded content)GET/projects/{project_id}/remote/sftp/{target_id}/readFailed with an API key
Write a file via SFTPPOST/projects/{project_id}/remote/sftp/{target_id}/writeFailed with an API key
Create an SSH session for remote accessPOST/projects/{project_id}/remote/sshFailed with an API key
Create a WebSocket terminal sessionPOST/projects/{project_id}/remote/terminalFailed with an API key
Read compiled serving metadata after verified owned project lookupGET/projects/{project_id}/runtimesTested with an API key
List all secrets for a project (names and metadata only, not values)GET/projects/{project_id}/secretsTested with an API key
Create a new secretPOST/projects/{project_id}/secretsTested with an API key
Get a secret's metadata (not its value)GET/projects/{project_id}/secrets/{secret_id}Tested with an API key
Update a secret's value (creates a new version)PUT/projects/{project_id}/secrets/{secret_id}Tested with an API key
Delete a secretDELETE/projects/{project_id}/secrets/{secret_id}Tested with an API key
Explicitly reveal a secret value (sensitive output, audit logged)GET/projects/{project_id}/secrets/{secret_id}/revealTested with an API key
Bulk create or update secretsPUT/projects/{project_id}/secrets/bulkTested with an API key
hives_get_project_settingsGET/projects/{project_id}/settingsTested with an API key
hives_update_project_settingsPATCH/projects/{project_id}/settingsTested with an API key
List all storage buckets for a projectGET/projects/{project_id}/storage/bucketsTested with an API key
Create a new storage bucketPOST/projects/{project_id}/storage/bucketsFailed with an API key
Get a specific bucketGET/projects/{project_id}/storage/buckets/{bucket_id}—
Delete a storage bucketDELETE/projects/{project_id}/storage/buckets/{bucket_id}—
Get CORS rules for a bucketGET/projects/{project_id}/storage/buckets/{bucket_id}/cors—
Set CORS rules for a bucketPUT/projects/{project_id}/storage/buckets/{bucket_id}/cors—
List objects in a bucketGET/projects/{project_id}/storage/buckets/{bucket_id}/objects—
hives_upload_object_by_keyPUT/projects/{project_id}/storage/buckets/{bucket_id}/objects—
hives_delete_object_by_keyDELETE/projects/{project_id}/storage/buckets/{bucket_id}/objects—
Upload an object to a bucket via a server-side proxy.PUT/projects/{project_id}/storage/buckets/{bucket_id}/objects/{key}—
Delete an object from a bucketDELETE/projects/{project_id}/storage/buckets/{bucket_id}/objects/{key}—
hives_download_object_by_keyGET/projects/{project_id}/storage/buckets/{bucket_id}/objects/download—
Generate a presigned URL for object accessPOST/projects/{project_id}/storage/buckets/{bucket_id}/presigned—
Explicit recovery observes provider generations. It never replays an unknownPOST/projects/{project_id}/storage/buckets/{bucket_id}/reconcile—
hives_list_native_topicGET/projects/{project_id}/topicsTested with an API key
hives_create_native_topicPOST/projects/{project_id}/topicsTested with an API key
hives_inspect_native_topicGET/projects/{project_id}/topics/{topic_id}Tested with an API key
hives_delete_native_topicDELETE/projects/{project_id}/topics/{topic_id}Tested with an API key
hives_publish_native_topicPOST/projects/{project_id}/topics/{topic_id}/messagesFailed with an API key
hives_subscriptions_native_topicGET/projects/{project_id}/topics/{topic_id}/subscriptionsTested with an API key
hives_subscribe_native_topicPOST/projects/{project_id}/topics/{topic_id}/subscriptionsTested with an API key
hives_unsubscribe_native_topicDELETE/projects/{project_id}/topics/{topic_id}/subscriptions/{subscription_id}Tested with an API key
List persisted local volumesGET/projects/{project_id}/volumesTested with an API key
Create bounded local persistent storagePOST/projects/{project_id}/volumesTested with an API key
Read persisted volume state and measured usageGET/projects/{project_id}/volumes/{volume_id}Tested with an API key
Delete a detached volume and its dataDELETE/projects/{project_id}/volumes/{volume_id}Tested with an API key
Attach or reconnect the exact existing attachmentPOST/projects/{project_id}/volumes/{volume_id}/mount—
Detach a volume without a request bodyPOST/projects/{project_id}/volumes/{volume_id}/unmountFailed with an API key
List deployment regions available for project creation.GET/regionsTested with an API key
hives_list_runtimesGET/runtimesTested with an API key
hives_get_runtimeGET/runtimes/{name}Tested with an API key
hives_select_runtimeGET/runtimes/selectTested with an API key

Auth

Return the authenticated user.

GET/v1/hives/auth/me

hives:readTested with an API keyhives_me

The handler never calls another service — it shapes the response entirely from the AuthContext that middleware already validated. This means GET /v1/auth/me remains available even if the upstream IAM service is degraded, which is critical for the console's "am I still logged in?" poll.

Responses

  • 200Current authenticated user
    Response fields
    • avatarstring | null

      Optional avatar URL. The Hives API does not currently populate this — it is exposed for forward compatibility with the console type contract.

    • createdAtstringrequired

      ISO 8601 timestamp describing the creation of the response. This is included so the client can cache it; creation-time of the underlying user record lives in the platform IAM service, not Hives.

    • emailstringrequired

      Email address of the authenticated principal. Falls back to the empty string when the upstream identity provider did not populate an email — this happens for machine-to-machine API keys.

    • idstringrequired

      Stable subject identifier (user or service principal). Mirrors AuthContext::subject_id and corresponds to the JWT sub claim when authenticated via a bearer token.

    • namestringrequired

      Human-readable display name. When the JWT does not carry a name, this is derived (in order) from: the local-part of the email, or the subject identifier, so the field is never empty.

    • organizationIdstring | null

      Optional active organization / tenant identifier. Set to None when the authenticated subject is not bound to a tenant (e.g. a newly-signed-in user prior to selecting an organization).

    • rolestringrequired

      Most-privileged organization role carried by the subject. Roles are collapsed using the ordering owner > admin > member > viewer. When no recognized role is present, member is returned as the safe default — matching the console default for authenticated users.

  • 401Unauthorized — no valid JWT or API key
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/auth/me" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Billing

List invoices for the authenticated org

GET/v1/hives/billing/invoices

hives:readSigned-in sessionhives_list_invoices

Parameters

  • limitquery · integer | null (int32)
  • offsetquery · integer | null (int32)

Responses

  • 200Invoices for the authenticated organization
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503Billing service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/billing/invoices" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Get a specific invoice

GET/v1/hives/billing/invoices/{invoice_id}

hives:readSigned-in sessionhives_get_invoice

Parameters

  • invoice_idpath · stringrequired

    Invoice ID

Responses

  • 200Invoice details
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Invoice not found
  • 503Billing service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/billing/invoices/$INVOICE_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

List available billing plans (public)

GET/v1/hives/billing/plans

hives:readSigned-in sessionhives_list_plans

Responses

  • 200Available billing plans
    Response fields

    A JSON object.

  • 503Billing service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/billing/plans" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Create a new subscription

POST/v1/hives/billing/subscribe

hives:writeSigned-in sessionhives_create_subscription

Request body application/json

  • plan_idstringrequired

Responses

  • 200Subscription created
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503Billing service unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/billing/subscribe" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "string"
  }'

Get current subscription for the authenticated org

GET/v1/hives/billing/subscription

hives:readSigned-in sessionhives_get_subscription

Responses

  • 200Current subscription
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503Billing service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/billing/subscription" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Cancel subscription

DELETE/v1/hives/billing/subscription

hives:writeSigned-in sessionhives_cancel_subscription

Responses

  • 200Subscription cancelled
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503Billing service unavailable
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/billing/subscription" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Change subscription plan

PUT/v1/hives/billing/subscription/plan

hives:writeSigned-in sessionhives_change_plan

Request body application/json

  • plan_idstringrequired

Responses

  • 200Subscription plan changed
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503Billing service unavailable
  • 4xx 5xxThe error envelope.
curl -X PUT "https://os.one.ml/api/v1/hives/billing/subscription/plan" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "string"
  }'

Get usage summary for the authenticated org

GET/v1/hives/billing/usage

hives:readSigned-in sessionhives_get_usage

Parameters

  • periodquery · string | null

Responses

  • 200Usage summary
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503Billing service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/billing/usage" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Context

hives_get_context_project

GET/v1/hives/context/project

hives:readAPI keys refusedhives_get_context_project

Responses

  • 200Owned Hives project for verified native selection
    Response fields
    • bindingobjectrequired
    • binding.createdAtstring (date-time)required
    • binding.hivesProjectIdstringrequired
    • projectobjectrequired

      Persisted metadata only: no secret values or invented runtime counters.

    • project.active_deployment_idstring | null
    • project.created_atstring (date-time)required
    • project.descriptionstring | null
    • project.idstringrequired
    • project.kindstringrequired
    • project.namestringrequired
    • project.slugstringrequired
    • project.statusstringrequired
    • project.tenant_idstringrequired
    • project.updated_atstring (date-time)required
    • selectedContextobjectrequired

      Field declaration order is the producer's canonical JSON order.

    • selectedContext.expiresAtMsinteger (int64)required

      min 0

    • selectedContext.fleetIdstring | null
    • selectedContext.organizationIdstringrequired
    • selectedContext.platformIdstringrequired
    • selectedContext.projectIdstringrequired
    • selectedContext.resourceEnvironmentstringrequired
    • selectedContext.schemaVersioninteger (int32)required

      min 0

    • selectedContext.workspaceIdstringrequired
  • 401Invalid or expired signed identity or selection
  • 404Selection has no Hives binding
  • 409Selection required or linked project unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/context/project" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_set_context_project

POST/v1/hives/context/project

hives:writeAPI keys refusedhives_set_context_project

Request body application/json

  • createnull | object
  • linknull | object

Responses

  • 200Existing or explicitly linked owned project
    Response fields
    • bindingobjectrequired
    • binding.createdAtstring (date-time)required
    • binding.hivesProjectIdstringrequired
    • projectobjectrequired

      Persisted metadata only: no secret values or invented runtime counters.

    • project.active_deployment_idstring | null
    • project.created_atstring (date-time)required
    • project.descriptionstring | null
    • project.idstringrequired
    • project.kindstringrequired
    • project.namestringrequired
    • project.slugstringrequired
    • project.statusstringrequired
    • project.tenant_idstringrequired
    • project.updated_atstring (date-time)required
    • selectedContextobjectrequired

      Field declaration order is the producer's canonical JSON order.

    • selectedContext.expiresAtMsinteger (int64)required

      min 0

    • selectedContext.fleetIdstring | null
    • selectedContext.organizationIdstringrequired
    • selectedContext.platformIdstringrequired
    • selectedContext.projectIdstringrequired
    • selectedContext.resourceEnvironmentstringrequired
    • selectedContext.schemaVersioninteger (int32)required

      min 0

    • selectedContext.workspaceIdstringrequired
  • 201Created project and binding committed atomically
    Response fields
    • bindingobjectrequired
    • binding.createdAtstring (date-time)required
    • binding.hivesProjectIdstringrequired
    • projectobjectrequired

      Persisted metadata only: no secret values or invented runtime counters.

    • project.active_deployment_idstring | null
    • project.created_atstring (date-time)required
    • project.descriptionstring | null
    • project.idstringrequired
    • project.kindstringrequired
    • project.namestringrequired
    • project.slugstringrequired
    • project.statusstringrequired
    • project.tenant_idstringrequired
    • project.updated_atstring (date-time)required
    • selectedContextobjectrequired

      Field declaration order is the producer's canonical JSON order.

    • selectedContext.expiresAtMsinteger (int64)required

      min 0

    • selectedContext.fleetIdstring | null
    • selectedContext.organizationIdstringrequired
    • selectedContext.platformIdstringrequired
    • selectedContext.projectIdstringrequired
    • selectedContext.resourceEnvironmentstringrequired
    • selectedContext.schemaVersioninteger (int32)required

      min 0

    • selectedContext.workspaceIdstringrequired
  • 400Provide exactly create or link
  • 401Invalid or expired signed identity or selection
  • 404Link target does not belong to verified org
  • 409Conflicting binding or project
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/context/project" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

hives_detach_context_project

DELETE/v1/hives/context/project

hives:writeAPI keys refusedhives_detach_context_project

Responses

  • 200Explicitly detached binding; Hives project retained
    Response fields
    • hivesProjectIdstringrequired
    • removedbooleanrequired
  • 401Invalid or expired signed selection
  • 404Selection has no binding
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/context/project" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Fleets

List all fleets known to the controller.

GET/v1/hives/fleets

hives:readFailed with an API keyhives_list_fleets

Responses

  • 200Fleet list
    Response fields
    • fleetsobject[]required

      Fleets currently known to the controller.

    • fleets[].[].fleetIdstringrequired

      Unique fleet identifier (e.g. fleet_map-production).

    • fleets[].[].gatewaynull | object
    • fleets[].[].healthyInstancesinteger (int32)required

      Total healthy instances. min 0

    • fleets[].[].namestringrequired

      Human-readable fleet name from the manifest.

    • fleets[].[].protocolsobject[]required

      Protocols in this fleet.

    • fleets[].[].protocols[].[].endpointsstring[]required

      Endpoint strings in host:port form.

    • fleets[].[].protocols[].[].healthyInstancesinteger (int32)required

      Instances passing health checks. min 0

    • fleets[].[].protocols[].[].namestringrequired

      Human-readable name.

    • fleets[].[].protocols[].[].protocolIdstringrequired

      Protocol identifier (e.g. "marc", "mind").

    • fleets[].[].protocols[].[].runningInstancesinteger (int32)required

      Currently running instances. min 0

    • fleets[].[].protocols[].[].targetInstancesinteger (int32)required

      Target instance count. min 0

    • fleets[].[].statestringrequired

      Current lifecycle state (Deploying, Running, Degraded, Updating, TearingDown, Terminated).

    • fleets[].[].totalInstancesinteger (int32)required

      Total instances across all protocols + gateway. min 0

  • 401Unauthorized
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/fleets" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Deploy a MAP fleet from a TOML manifest.

POST/v1/hives/fleets

hives:writeTested with an API keyhives_deploy_fleet

Request body application/json

  • manifestTomlstringrequired

    Contents of the map-fleet.toml manifest.

Responses

  • 201Fleet deployed
    Response fields
    • fleetIdstringrequired

      Assigned fleet id.

    • gatewayEndpointstring | null

      Gateway endpoint if present (e.g. 0.0.0.0:8080).

    • totalInstancesinteger (int32)required

      Total instances that were instantiated. min 0

  • 400Invalid manifest
  • 401Unauthorized
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/fleets" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "manifestToml": "string"
  }'

Get detailed status for a single fleet.

GET/v1/hives/fleets/{fleet_id}

hives:readFailed with an API keyhives_get_fleet_status

Parameters

  • fleet_idpath · stringrequired

    Fleet identifier

Responses

  • 200Fleet status
    Response fields
    • fleetIdstringrequired

      Unique fleet identifier (e.g. fleet_map-production).

    • gatewaynull | object
    • healthyInstancesinteger (int32)required

      Total healthy instances. min 0

    • namestringrequired

      Human-readable fleet name from the manifest.

    • protocolsobject[]required

      Protocols in this fleet.

    • protocols[].[].endpointsstring[]required

      Endpoint strings in host:port form.

    • protocols[].[].healthyInstancesinteger (int32)required

      Instances passing health checks. min 0

    • protocols[].[].namestringrequired

      Human-readable name.

    • protocols[].[].protocolIdstringrequired

      Protocol identifier (e.g. "marc", "mind").

    • protocols[].[].runningInstancesinteger (int32)required

      Currently running instances. min 0

    • protocols[].[].targetInstancesinteger (int32)required

      Target instance count. min 0

    • statestringrequired

      Current lifecycle state (Deploying, Running, Degraded, Updating, TearingDown, Terminated).

    • totalInstancesinteger (int32)required

      Total instances across all protocols + gateway. min 0

  • 401Unauthorized
  • 404Fleet not found
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/fleets/$FLEET_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Teardown a fleet — stop all instances and remove from discovery.

DELETE/v1/hives/fleets/{fleet_id}

hives:writeFailed with an API keyhives_teardown_fleet

Parameters

  • fleet_idpath · stringrequired

    Fleet identifier

Responses

  • 204Fleet torn down
  • 401Unauthorized
  • 404Fleet not found
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/fleets/$FLEET_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Organizations

List organizations for the authenticated user

GET/v1/hives/organizations

hives:readSigned-in sessionhives_list_organizations

Responses

  • 200Organizations visible to the authenticated user
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503IAM service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/organizations" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Create a new organization

POST/v1/hives/organizations

hives:writeSigned-in sessionhives_create_organization

Request body application/json

A JSON object; see the description above.

Responses

  • 200Organization created
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503IAM service unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/organizations" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Get a single organization

GET/v1/hives/organizations/{org_id}

hives:readSigned-in sessionhives_get_organization

Parameters

  • org_idpath · stringrequired

    Organization ID

Responses

  • 200Organization details
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization not found
  • 503IAM service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/organizations/$ORG_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Delete an organization

DELETE/v1/hives/organizations/{org_id}

hives:writeSigned-in sessionhives_delete_organization

Parameters

  • org_idpath · stringrequired

    Organization ID

Responses

  • 200Organization deleted
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization not found
  • 503IAM service unavailable
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/organizations/$ORG_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Update an organization

PATCH/v1/hives/organizations/{org_id}

hives:writeSigned-in sessionhives_update_organization

Parameters

  • org_idpath · stringrequired

    Organization ID

Request body application/json

A JSON object; see the description above.

Responses

  • 200Organization updated
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization not found
  • 503IAM service unavailable
  • 4xx 5xxThe error envelope.
curl -X PATCH "https://os.one.ml/api/v1/hives/organizations/$ORG_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Invites

List pending invites

GET/v1/hives/organizations/{org_id}/invites

hives:readSigned-in sessionhives_list_invites

Parameters

  • org_idpath · stringrequired

    Organization ID

Responses

  • 200Pending invites
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization not found
  • 503IAM service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/organizations/$ORG_ID/invites" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Invite a member to the organization

POST/v1/hives/organizations/{org_id}/invites

hives:writeSigned-in sessionhives_invite_member

Parameters

  • org_idpath · stringrequired

    Organization ID

Request body application/json

  • emailstringrequired
  • rolestringrequired

Responses

  • 200Invitation created
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization not found
  • 503IAM service unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/organizations/$ORG_ID/invites" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "string",
    "role": "string"
  }'

Cancel a pending invite

DELETE/v1/hives/organizations/{org_id}/invites/{invite_id}

hives:writeSigned-in sessionhives_cancel_invite

Parameters

  • org_idpath · stringrequired

    Organization ID

  • invite_idpath · stringrequired

    Invite ID

Responses

  • 200Invite cancelled
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization or invite not found
  • 503IAM service unavailable
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/organizations/$ORG_ID/invites/$INVITE_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Members

List organization members

GET/v1/hives/organizations/{org_id}/members

hives:readSigned-in sessionhives_list_members

Parameters

  • org_idpath · stringrequired

    Organization ID

Responses

  • 200Organization members
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization not found
  • 503IAM service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/organizations/$ORG_ID/members" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Remove a member from the organization

DELETE/v1/hives/organizations/{org_id}/members/{member_id}

hives:writeSigned-in sessionhives_remove_member

Parameters

  • org_idpath · stringrequired

    Organization ID

  • member_idpath · stringrequired

    Member ID

Responses

  • 200Member removed
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization or member not found
  • 503IAM service unavailable
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/organizations/$ORG_ID/members/$MEMBER_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Update a member's role

PUT/v1/hives/organizations/{org_id}/members/{member_id}/role

hives:writeSigned-in sessionhives_update_member_role

Parameters

  • org_idpath · stringrequired

    Organization ID

  • member_idpath · stringrequired

    Member ID

Request body application/json

  • rolestringrequired

Responses

  • 200Member role updated
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization or member not found
  • 503IAM service unavailable
  • 4xx 5xxThe error envelope.
curl -X PUT "https://os.one.ml/api/v1/hives/organizations/$ORG_ID/members/$MEMBER_ID/role" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "string"
  }'

Sso

Get SSO configuration for an organization

GET/v1/hives/organizations/{org_id}/sso

hives:readSigned-in sessionhives_get_sso_config

Parameters

  • org_idpath · stringrequired

    Organization ID

Responses

  • 200SSO configuration
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization not found
  • 503SSO service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/organizations/$ORG_ID/sso" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Create a new SSO connection

POST/v1/hives/organizations/{org_id}/sso

hives:writeSigned-in sessionhives_create_sso_connection

Parameters

  • org_idpath · stringrequired

    Organization ID

Request body application/json

  • idp_typestring | null

    IdP type hint

  • metadata_rawstring | null

    Raw IdP metadata XML (alternative to URL)

  • metadata_urlstring | null

    IdP metadata URL (e.g. Okta, Azure AD metadata endpoint)

  • namestringrequired

    Connection name/label

Responses

  • 200SSO connection created
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization not found
  • 503SSO service unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/organizations/$ORG_ID/sso" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'

Delete an SSO connection

DELETE/v1/hives/organizations/{org_id}/sso/{connection_id}

hives:writeSigned-in sessionhives_delete_sso_connection

Parameters

  • org_idpath · stringrequired

    Organization ID

  • connection_idpath · stringrequired

    SSO connection ID

Responses

  • 200SSO connection deleted
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization or connection not found
  • 503SSO service unavailable
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/organizations/$ORG_ID/sso/$CONNECTION_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Usage

Get organization usage (proxied to Cabbage)

GET/v1/hives/organizations/{org_id}/usage

hives:readSigned-in sessionhives_get_org_usage

Parameters

  • org_idpath · stringrequired

    Organization ID

Responses

  • 200Organization usage summary
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Organization not found
  • 503Billing service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/organizations/$ORG_ID/usage" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Payments

Create a Stripe checkout session

POST/v1/hives/payments/checkout

hives:writeSigned-in sessionhives_create_checkout

Request body application/json

  • cancel_urlstring | null
  • plan_idstringrequired
  • success_urlstring | null

Responses

  • 200Checkout session created
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503Payments service unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/payments/checkout" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "string"
  }'

List payment methods for the authenticated org

GET/v1/hives/payments/methods

hives:readSigned-in sessionhives_list_payment_methods

Responses

  • 200Payment methods
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503Payments service unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/payments/methods" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Add a payment method

POST/v1/hives/payments/methods

hives:writeSigned-in sessionhives_add_payment_method

Request body application/json

  • payment_method_idstringrequired
  • set_defaultboolean | null

Responses

  • 200Payment method added
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503Payments service unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/payments/methods" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "string"
  }'

Get Stripe billing portal URL

POST/v1/hives/payments/portal

hives:writeSigned-in sessionhives_get_billing_portal

Responses

  • 200Billing portal URL
    Response fields

    A JSON object.

  • 401Unauthorized
  • 503Payments service unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/payments/portal" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Projects

List all projects for the authenticated tenant

GET/v1/hives/projects

hives:readTested with an API keyhives_list_projects

Parameters

  • kindquery · string | null

    Filter by project kind

  • statusquery · string | null

    Filter by status

  • searchquery · string | null

    Search by name

  • sort_byquery · "name" | "created_at" | "updated_at"

    Sort field

  • sort_orderquery · "asc" | "desc"

    Sort order

  • pagequery · integer (int32)

    Page number (1-indexed)

  • per_pagequery · integer (int32)

    Items per page

Responses

  • 200List of projects
    Response fields
    • dataobject[]required

      Response data

    • data[].[].active_instancesinteger | null (int64)

      No project-worker inventory is connected; never substitute a fabricated zero. min 0

    • data[].[].current_versioninteger | null (int64)

      Current deployment version min 0

    • data[].[].observationnull | object
    • data[].[].requests_24hinteger | null (int64)

      Retained completed API invocation observations in the explicit 24-hour window. min 0

    • data[].[].summary_state"available" | "unavailable"required

      Whether the derived summary was available; mutation acknowledgements preserve committed data.

    • data[].[].total_deploymentsinteger | null (int64)

      Actual owned deployment count; unavailable only on a committed mutation acknowledgement. min 0

    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Whether there is a next page

    • pagination.has_prevbooleanrequired

      Whether there is a previous page

    • pagination.pageinteger (int32)required

      Current page number min 0

    • pagination.per_pageinteger (int32)required

      Items per page min 0

    • pagination.totalinteger (int64)required

      Total number of items min 0

    • pagination.total_pagesinteger (int32)required

      Total number of pages min 0

  • 401Unauthorized
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Create a new project

POST/v1/hives/projects

hives:writeTested with an API keyhives_create_project

Request body application/json

  • descriptionstring | null

    Project description

  • domainsstring[]

    Initial custom domains

  • envobject

    Initial environment variables

  • kindstringrequired

    Project type

  • namestringrequired

    Project name (3-64 characters, alphanumeric with hyphens)

Responses

  • 201Project created
    Response fields
    • active_instancesinteger | null (int64)

      No project-worker inventory is connected; never substitute a fabricated zero. min 0

    • current_versioninteger | null (int64)

      Current deployment version min 0

    • observationnull | object
    • requests_24hinteger | null (int64)

      Retained completed API invocation observations in the explicit 24-hour window. min 0

    • summary_state"available" | "unavailable"required

      Whether the derived summary was available; mutation acknowledgements preserve committed data.

    • total_deploymentsinteger | null (int64)

      Actual owned deployment count; unavailable only on a committed mutation acknowledgement. min 0

  • 400Invalid request
  • 401Unauthorized
  • 409Project already exists
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "kind": "string"
  }'

Get a project by ID

GET/v1/hives/projects/{project_id}

hives:readFailed with an API keyhives_get_project

Parameters

  • project_idpath · stringrequired

    Project ID

Responses

  • 200Project details
    Response fields
    • active_instancesinteger | null (int64)

      No project-worker inventory is connected; never substitute a fabricated zero. min 0

    • current_versioninteger | null (int64)

      Current deployment version min 0

    • observationnull | object
    • requests_24hinteger | null (int64)

      Retained completed API invocation observations in the explicit 24-hour window. min 0

    • summary_state"available" | "unavailable"required

      Whether the derived summary was available; mutation acknowledgements preserve committed data.

    • total_deploymentsinteger | null (int64)

      Actual owned deployment count; unavailable only on a committed mutation acknowledgement. min 0

  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Delete a project

DELETE/v1/hives/projects/{project_id}

hives:writeTested with an API keyhives_delete_project

Parameters

  • project_idpath · stringrequired

    Project ID

Responses

  • 200Project deleted
    Response fields
    • idstringrequired

      Deleted resource ID

    • messagestringrequired

      Message

    • successbooleanrequired

      Success flag

  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Update a project

PATCH/v1/hives/projects/{project_id}

hives:writeTested with an API keyhives_update_project

Parameters

  • project_idpath · stringrequired

    Project ID

Request body application/json

  • descriptionstring | null

    New description

  • envobject

    Environment variables to add/update

  • namestring | null

    New project name

  • remove_envstring[]

    Environment variable names to remove

Responses

  • 200Project updated
    Response fields
    • active_instancesinteger | null (int64)

      No project-worker inventory is connected; never substitute a fabricated zero. min 0

    • current_versioninteger | null (int64)

      Current deployment version min 0

    • observationnull | object
    • requests_24hinteger | null (int64)

      Retained completed API invocation observations in the explicit 24-hour window. min 0

    • summary_state"available" | "unavailable"required

      Whether the derived summary was available; mutation acknowledgements preserve committed data.

    • total_deploymentsinteger | null (int64)

      Actual owned deployment count; unavailable only on a committed mutation acknowledgement. min 0

  • 400Invalid request
  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X PATCH "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Activity

List activity for an authenticated org's project

GET/v1/hives/projects/{project_id}/activity

hives:readTested with an API keyhives_get_project_activity

Requires hives:read. The backend verifies that the project belongs to the signed org before reading its activity; an unknown or foreign-org project returns 404.

Parameters

  • project_idpath · stringrequired

    Project ID belonging to the authenticated org

  • actionquery · string

    Filter by action, such as project.updated

  • actor_typequery · string

    Filter by actor type, such as user, api_key or system

  • resource_typequery · string

    Filter by resource type

  • sincequery · string (date-time)

    Inclusive start timestamp

  • untilquery · string (date-time)

    Inclusive end timestamp

  • pagequery · integer

    Page number (1-indexed)

  • per_pagequery · integer

    Items per page

Responses

  • 200Project activity for the authenticated org
    Response fields
    • dataobject[]required
    • data[].[].idstringrequired
    • data[].[].actor_idstringrequired
    • data[].[].actor_typestringrequired
    • data[].[].actor_namestring | null
    • data[].[].actionstringrequired
    • data[].[].resource_typestringrequired
    • data[].[].resource_idstring | null
    • data[].[].resource_namestring | null
    • data[].[].metadataany

      Additional JSON metadata, or null

    • data[].[].ip_addressstring | null
    • data[].[].user_agentstring | null
    • data[].[].created_atstring (date-time)required
    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Whether there is a next page

    • pagination.has_prevbooleanrequired

      Whether there is a previous page

    • pagination.pageinteger (int32)required

      Current page number min 0

    • pagination.per_pageinteger (int32)required

      Items per page min 0

    • pagination.totalinteger (int64)required

      Total number of items min 0

    • pagination.total_pagesinteger (int32)required

      Total number of pages min 0

  • 400Invalid filter or pagination
  • 401Missing or invalid signed identity
  • 403Missing hives:read scope
  • 404Project not found in the authenticated org
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/activity" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Cron

List all cron jobs for a project

GET/v1/hives/projects/{project_id}/cron

hives:readTested with an API keyhives_list_crons

Parameters

  • project_idpath · stringrequired

    Project ID

  • pagequery · integer (int32)

    Page number (1-indexed)

  • per_pagequery · integer (int32)

    Items per page

Responses

  • 200List of cron jobs
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 503Cron engine unavailable or unconfirmed control result
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/cron" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Create a new cron job

POST/v1/hives/projects/{project_id}/cron

hives:writehives_create_cron

Parameters

  • project_idpath · stringrequired

    Project ID

Request body application/json

  • enabledboolean

    Whether the job is enabled

  • handlerstringrequired

    Handler function ID or name

  • namestringrequired

    Job name

  • schedulestringrequired

    Cron schedule expression

  • timezonestring

    Timezone (IANA format)

Responses

  • 201Cron job created
    Response fields

    A JSON object.

  • 400Invalid request
  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 503Cron engine unavailable or unconfirmed control result
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/cron" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "schedule": "string",
    "handler": "string"
  }'

Get a specific cron job

GET/v1/hives/projects/{project_id}/cron/{cron_id}

hives:readhives_get_cron

Parameters

  • project_idpath · stringrequired

    Project ID

  • cron_idpath · stringrequired

    Cron job ID

Responses

  • 200Cron job details
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Cron job not found
  • 500Internal server error
  • 503Cron engine unavailable or unconfirmed control result
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/cron/$CRON_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Delete a cron job

DELETE/v1/hives/projects/{project_id}/cron/{cron_id}

hives:writehives_delete_cron

Parameters

  • project_idpath · stringrequired

    Project ID

  • cron_idpath · stringrequired

    Cron job ID

Responses

  • 200Cron job deleted
    Response fields
    • idstringrequired

      Deleted resource ID

    • messagestringrequired

      Message

    • successbooleanrequired

      Success flag

  • 401Unauthorized
  • 404Cron job not found
  • 500Internal server error
  • 503Cron engine unavailable or unconfirmed control result
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/cron/$CRON_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Update a cron job

PATCH/v1/hives/projects/{project_id}/cron/{cron_id}

hives:writehives_update_cron

Parameters

  • project_idpath · stringrequired

    Project ID

  • cron_idpath · stringrequired

    Cron job ID

Request body application/json

  • enabledboolean | null

    Whether the job is enabled

  • handlerstring | null

    Handler function

  • namestring | null

    Job name

  • schedulestring | null

    Cron schedule expression

  • timezonestring | null

    Timezone

Responses

  • 200Cron job updated
    Response fields

    A JSON object.

  • 400Invalid request
  • 401Unauthorized
  • 404Cron job not found
  • 500Internal server error
  • 503Cron engine unavailable or unconfirmed control result
  • 4xx 5xxThe error envelope.
curl -X PATCH "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/cron/$CRON_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Pause a cron job

POST/v1/hives/projects/{project_id}/cron/{cron_id}/pause

hives:writehives_pause_cron

Parameters

  • project_idpath · stringrequired

    Project ID

  • cron_idpath · stringrequired

    Cron job ID

Responses

  • 200Cron job paused
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Cron job not found
  • 500Internal server error
  • 503Cron engine unavailable or unconfirmed control result
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/cron/$CRON_ID/pause" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Resume a cron job

POST/v1/hives/projects/{project_id}/cron/{cron_id}/resume

hives:writehives_resume_cron

Parameters

  • project_idpath · stringrequired

    Project ID

  • cron_idpath · stringrequired

    Cron job ID

Responses

  • 200Cron job resumed
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Cron job not found
  • 500Internal server error
  • 503Cron engine unavailable or unconfirmed control result
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/cron/$CRON_ID/resume" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Get run history for a cron job

GET/v1/hives/projects/{project_id}/cron/{cron_id}/runs

hives:readhives_get_cron_runs

Parameters

  • project_idpath · stringrequired

    Project ID

  • cron_idpath · stringrequired

    Cron job ID

  • statusquery · string | null

    Filter by status

  • sincequery · string | null (date-time)

    Start date filter

  • untilquery · string | null (date-time)

    End date filter

  • pagequery · integer (int32)

    Page number (1-indexed)

  • per_pagequery · integer (int32)

    Items per page

Responses

  • 200Cron run history
    Response fields
    • dataobject[]required

      Response data

    • data[].[].duration_msinteger | null (int64)

      Duration in ms min 0

    • data[].[].ended_atstring | null (date-time)

      End timestamp

    • data[].[].errorstring | null

      Error message if failed

    • data[].[].idstringrequired

      Run ID

    • data[].[].logs_urlstring | null

      Logs URL

    • data[].[].started_atstring (date-time)required

      Start timestamp

    • data[].[].statusstringrequired

      Run status

    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Whether there is a next page

    • pagination.has_prevbooleanrequired

      Whether there is a previous page

    • pagination.pageinteger (int32)required

      Current page number min 0

    • pagination.per_pageinteger (int32)required

      Items per page min 0

    • pagination.totalinteger (int64)required

      Total number of items min 0

    • pagination.total_pagesinteger (int32)required

      Total number of pages min 0

  • 401Unauthorized
  • 404Cron job not found
  • 500Internal server error
  • 503Cron engine unavailable or unconfirmed control result
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/cron/$CRON_ID/runs" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Manually trigger a cron job

POST/v1/hives/projects/{project_id}/cron/{cron_id}/trigger

hives:writehives_trigger_cron

Parameters

  • project_idpath · stringrequired

    Project ID

  • cron_idpath · stringrequired

    Cron job ID

Responses

  • 202Cron job triggered
  • 401Unauthorized
  • 404Cron job not found
  • 500Internal server error
  • 503Cron engine unavailable or unconfirmed control result
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/cron/$CRON_ID/trigger" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Deployments

List all deployments for a project

GET/v1/hives/projects/{project_id}/deployments

hives:readTested with an API keyhives_list_deployments

Parameters

  • project_idpath · stringrequired

    Project ID

  • statusquery · string | null

    Filter by status

  • environmentquery · string | null

    Filter by environment

  • authorquery · string | null

    Filter by author

  • sort_orderquery · "asc" | "desc"

    Sort order

  • pagequery · integer (int32)

    Page number (1-indexed)

  • per_pagequery · integer (int32)

    Items per page

Responses

  • 200List of deployments
    Response fields
    • dataobject[]required

      Response data

    • data[].[].logs_urlstring | null

      Build logs URL

    • data[].[].urlstring | null

      Deployment URL

    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Whether there is a next page

    • pagination.has_prevbooleanrequired

      Whether there is a previous page

    • pagination.pageinteger (int32)required

      Current page number min 0

    • pagination.per_pageinteger (int32)required

      Items per page min 0

    • pagination.totalinteger (int64)required

      Total number of items min 0

    • pagination.total_pagesinteger (int32)required

      Total number of pages min 0

  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Create a new deployment

POST/v1/hives/projects/{project_id}/deployments

hives:writehives_create_deployment

Parameters

  • project_idpath · stringrequired

    Project ID

Request body application/json

  • module_hashstringrequired

    SHA-256 returned by a real upload in this same org and project pattern ^[a-f0-9]{64}$

  • auto_promoteboolean

    Whether to promote immediately to production

  • env_overridesobject

    Environment overrides for this deployment

  • git_branchstring | null

    Git branch name

  • git_messagestring | null

    Git commit message

  • git_shastring | null

    Git commit SHA (optional)

  • regionsstring[]

    Target regions (defaults to all)

Responses

  • 201Deployment created
    Response fields
    • idstringrequired
    • project_idstringrequired
    • tenant_idstringrequired
    • module_idstringrequired
    • module_hashstring | null

      Owned persisted artifact digest; null for a legacy deployment without an artifact pattern ^[a-f0-9]{64}$

    • versionintegerrequired

      min 1

    • statusstringrequired
    • git_shastring | null
    • git_branchstring | null
    • created_bystringrequired
    • created_atstring (date-time)required
    • promoted_atstring | null (date-time)
    • logs_urlstring | null
    • urlstring | null
  • 400Invalid request
  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "module_hash": "string"
  }'

Get a specific deployment

GET/v1/hives/projects/{project_id}/deployments/{deployment_id}

hives:readhives_get_deployment

Parameters

  • project_idpath · stringrequired

    Project ID

  • deployment_idpath · stringrequired

    Deployment ID

Responses

  • 200Deployment details
    Response fields
    • idstringrequired
    • project_idstringrequired
    • tenant_idstringrequired
    • module_idstringrequired
    • module_hashstring | null

      Owned persisted artifact digest; null for a legacy deployment without an artifact pattern ^[a-f0-9]{64}$

    • versionintegerrequired

      min 1

    • statusstringrequired
    • git_shastring | null
    • git_branchstring | null
    • created_bystringrequired
    • created_atstring (date-time)required
    • promoted_atstring | null (date-time)
    • logs_urlstring | null
    • urlstring | null
  • 401Unauthorized
  • 404Deployment not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Delete an inactive deployment

DELETE/v1/hives/projects/{project_id}/deployments/{deployment_id}

hives:writehives_delete_deployment

Parameters

  • project_idpath · stringrequired
  • deployment_idpath · stringrequired

Responses

  • 200Action completed
    Response fields
    • idstringrequired

      Deleted resource ID

    • messagestringrequired

      Message

    • successbooleanrequired

      Success flag

  • 401Unauthorized
  • 403Missing Hives scope
  • 404Project or deployment is not owned by the authenticated org and project
  • 409Deployment status does not permit this action
  • 502Runtime operation failed
  • 503Runtime unavailable
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Cancel a pending deployment and stop its runtime work

POST/v1/hives/projects/{project_id}/deployments/{deployment_id}/cancel

hives:writehives_cancel_deployment

Parameters

  • project_idpath · stringrequired
  • deployment_idpath · stringrequired

Responses

  • 200Action completed
    Response fields
    • idstringrequired
    • project_idstringrequired
    • tenant_idstringrequired
    • module_idstringrequired
    • module_hashstring | null

      Owned persisted artifact digest; null for a legacy deployment without an artifact pattern ^[a-f0-9]{64}$

    • versionintegerrequired

      min 1

    • statusstringrequired
    • git_shastring | null
    • git_branchstring | null
    • created_bystringrequired
    • created_atstring (date-time)required
    • promoted_atstring | null (date-time)
    • logs_urlstring | null
    • urlstring | null
  • 401Unauthorized
  • 403Missing Hives scope
  • 404Project or deployment is not owned by the authenticated org and project
  • 409Deployment status does not permit this action
  • 502Runtime operation failed
  • 503Runtime unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID/cancel" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Invoke a real running owned deployment and return the raw guest HTTP response

POST/v1/hives/projects/{project_id}/deployments/{deployment_id}/invoke

hives:writehives_invoke_deployment

Returns actual guest status, safe headers and exact binary bytes, including executed error statuses. An authoritative x-execution-id distinguishes a completed guest response from an API failure. Unmarked WASI stdout is raw 200 octets. No JSON result wrapper or queue acknowledgement.

Parameters

  • project_idpath · stringrequired
  • deployment_idpath · stringrequired

Request body application/json

  • bodyany

    Strings become UTF-8; other non-null values serialize as JSON; null is empty

  • body_base64string

    Standard base64 for exact binary bytes, decoded at most 10 MiB; guest envelope may reach its cap earlier max length 13981016

  • headersobject

    At most 64 KiB of UTF-8 key/value bytes. Platform identity/status, auth, cookie, Host, framing, origin, referer and forwarding headers are forbidden. Guest headers cannot establish ownership.

  • methodstring

    Valid ASCII HTTP method token at most 64 bytes max length 64 · default "POST"

  • pathstring

    Origin-relative guest URI path including query, at most 8192 UTF-8 bytes. Begins with /, forbids // origins and # fragments. default "/"

Responses

curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID/invoke" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Query logs for a project

GET/v1/hives/projects/{project_id}/deployments/{deployment_id}/logs

hives:readhives_query_deployment_logs

Parameters

  • deployment_idpath · stringrequired
  • project_idpath · stringrequired

    Project ID

  • levelquery · string | null

    Filter by minimum log level

  • sourcequery · string | null

    Filter by source (function, deployment, etc.)

  • searchquery · string | null

    Search query

  • startquery · string | null (date-time)

    Start time (defaults to 1 hour ago)

  • endquery · string | null (date-time)

    End time (defaults to now)

  • request_idquery · string | null

    Request ID for correlation

  • pagequery · integer (int32)

    Page number (1-indexed)

  • per_pagequery · integer (int32)

    Items per page

Responses

  • 200Log entries
    Response fields
    • logsobject[]required

      Log entries

    • logs[].[].duration_msinteger | null (int64)

      Execution duration in milliseconds

    • logs[].[].idstringrequired

      Log entry ID

    • logs[].[].level"trace" | "debug" | "info" | "warn" | "error" | "fatal"required

      Log level enumeration

    • logs[].[].messagestringrequired

      Log message

    • logs[].[].metadataany

      Structured metadata

    • logs[].[].request_idstring | null

      Request ID for correlation

    • logs[].[].sourcestringrequired

      Source (function name, deployment ID, etc.)

    • logs[].[].timestampstring (date-time)required

      Timestamp

    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Whether there is a next page

    • pagination.has_prevbooleanrequired

      Whether there is a previous page

    • pagination.pageinteger (int32)required

      Current page number min 0

    • pagination.per_pageinteger (int32)required

      Items per page min 0

    • pagination.totalinteger (int64)required

      Total number of items min 0

    • pagination.total_pagesinteger (int32)required

      Total number of pages min 0

    • time_rangeobjectrequired

      Time range for metrics

    • time_range.endstring (date-time)required
    • time_range.startstring (date-time)required
  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID/logs" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Get deployment metrics

GET/v1/hives/projects/{project_id}/deployments/{deployment_id}/metrics

hives:readhives_get_deployment_metrics

Parameters

  • project_idpath · stringrequired

    Project ID

  • deployment_idpath · stringrequired

    Deployment ID

  • startquery · string | null (date-time)

    Start time (defaults based on resolution)

  • endquery · string | null (date-time)

    End time (defaults to now)

  • aggregationquery · "sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"

    Aggregation type

  • resolutionquery · "minute" | "fiveminutes" | "fifteenminutes" | "hour" | "day"

    Resolution

Responses

  • 200Deployment metrics
    Response fields
    • active_instancesinteger | null (int32)

      Unavailable: no per-resource runtime inventory samples.

    • avg_api_http_duration_msnumber | null (double)

      Average monotonic API duration for retained completed invocations (milliseconds).

    • avg_cpu_percentnumber | null (double)

      Unavailable: no measured per-resource CPU producer.

    • avg_memory_mbnumber | null (double)

      Unavailable: no measured resident-memory producer.

    • avg_response_time_msnumber | null (double)

      Compatibility alias for monotonic API HTTP duration (milliseconds).

    • deployment_idstringrequired

      Deployment ID

    • error_countinteger (int64)required

      Error count

    • error_ratenumber | null (double)

      Error rate

    • max_instancesinteger | null (int32)

      Unavailable: no historical instance-count samples.

    • min_instancesinteger | null (int32)

      Unavailable: no historical instance-count samples.

    • network_in_bytesinteger | null (int64)

      Unavailable: decoded payload lengths are not wire-network measurements.

    • network_out_bytesinteger | null (int64)

      Unavailable: decoded payload lengths are not wire-network measurements.

    • observationobjectrequired

      Retained observations only; an empty ledger is not proof of zero runtime traffic.

    • observation.duration_measurementstringrequired
    • observation.first_observed_atstring | null (date-time)
    • observation.payload_measurementstringrequired
    • observation.sample_countinteger (int64)required
    • observation.scopestringrequired
    • observed_request_payload_bytesinteger (int64)required

      Decoded HTTP payload bytes; these are not wire traffic or billing bandwidth.

    • observed_response_payload_bytesinteger (int64)required
    • p95_response_time_msnumber | null (double)

      P95 monotonic API HTTP duration (milliseconds).

    • time_rangeobjectrequired

      Time range for metrics

    • time_range.endstring (date-time)required
    • time_range.startstring (date-time)required
    • total_requestsinteger (int64)required

      Total requests

  • 401Unauthorized
  • 403Permission denied
  • 404Deployment not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID/metrics" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Promote a deployment to production

POST/v1/hives/projects/{project_id}/deployments/{deployment_id}/promote

hives:writehives_promote_deployment

Parameters

  • project_idpath · stringrequired

    Project ID

  • deployment_idpath · stringrequired

    Deployment ID

Responses

  • 200Deployment promoted
    Response fields
    • idstringrequired
    • project_idstringrequired
    • tenant_idstringrequired
    • module_idstringrequired
    • module_hashstring | null

      Owned persisted artifact digest; null for a legacy deployment without an artifact pattern ^[a-f0-9]{64}$

    • versionintegerrequired

      min 1

    • statusstringrequired
    • git_shastring | null
    • git_branchstring | null
    • created_bystringrequired
    • created_atstring (date-time)required
    • promoted_atstring | null (date-time)
    • logs_urlstring | null
    • urlstring | null
  • 401Unauthorized
  • 404Deployment not found
  • 409Cannot promote deployment
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID/promote" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Roll back to the selected deployment in this project

POST/v1/hives/projects/{project_id}/deployments/{deployment_id}/rollback

hives:writehives_rollback_deployment

Parameters

  • project_idpath · stringrequired

    Project ID

  • deployment_idpath · stringrequired

    Owned target deployment ID

Request body application/json

  • reasonstring | null

    Reason for rollback

  • target_versioninteger | null (int64)

    Target version to rollback to (defaults to previous) min 0

Responses

  • 200Rollback completed
    Response fields
    • idstringrequired
    • project_idstringrequired
    • tenant_idstringrequired
    • module_idstringrequired
    • module_hashstring | null

      Owned persisted artifact digest; null for a legacy deployment without an artifact pattern ^[a-f0-9]{64}$

    • versionintegerrequired

      min 1

    • statusstringrequired
    • git_shastring | null
    • git_branchstring | null
    • created_bystringrequired
    • created_atstring (date-time)required
    • promoted_atstring | null (date-time)
    • logs_urlstring | null
    • urlstring | null
  • 401Unauthorized
  • 404Project or target version not found
  • 409Target deployment cannot be activated
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID/rollback" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Stop an active deployment after runtime acknowledgment

POST/v1/hives/projects/{project_id}/deployments/{deployment_id}/stop

hives:writehives_stop_deployment

Bodyless explicit stop of an owned deployment. A successful response confirms cancelled after runtime stop acknowledgment. An uncertain stop remains stopping; read the same deployment before explicitly reconciling with another stop request. Clients never automatically replay this mutation.

Parameters

  • project_idpath · stringrequired
  • deployment_idpath · stringrequired

Responses

  • 200Runtime stop acknowledged; deployment is cancelled
    Response fields
    • idstringrequired
    • project_idstringrequired
    • tenant_idstringrequired
    • module_idstringrequired
    • module_hashstring | null

      Owned persisted artifact digest; null for a legacy deployment without an artifact pattern ^[a-f0-9]{64}$

    • versionintegerrequired

      min 1

    • statusstringrequired
    • git_shastring | null
    • git_branchstring | null
    • created_bystringrequired
    • created_atstring (date-time)required
    • promoted_atstring | null (date-time)
    • logs_urlstring | null
    • urlstring | null
  • 401Unauthorized
  • 403Missing Hives scope
  • 404Project or deployment is not owned by the authenticated org and project
  • 409Deployment status does not permit this action
  • 502Runtime operation failed
  • 503Runtime unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments/$DEPLOYMENT_ID/stop" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Upload a real WASM artifact and deploy it

POST/v1/hives/projects/{project_id}/deployments/upload

hives:writeFailed with an API keyhives_upload_deployment

Multipart upload with one file, at most 10 MiB decoded bytes. Git fields are labels, not a Git build source. The backend owns org/project identity and computes the SHA-256 module_hash.

Request bodies sent through https://os.one.ml/api are limited to 2 MiB.

Parameters

  • project_idpath · stringrequired

Request body multipart/form-data

  • filestring (binary)required

    WebAssembly binary up to 10 MiB

  • git_shastring

    min length 7 · max length 40

  • git_branchstring

    max length 255

  • git_messagestring

    max length 1000

Responses

  • 201Real artifact persisted and build accepted
    Response fields
    • idstringrequired
    • project_idstringrequired
    • tenant_idstringrequired
    • module_idstringrequired
    • module_hashstring | null

      Owned persisted artifact digest; null for a legacy deployment without an artifact pattern ^[a-f0-9]{64}$

    • versionintegerrequired

      min 1

    • statusstringrequired
    • git_shastring | null
    • git_branchstring | null
    • created_bystringrequired
    • created_atstring (date-time)required
    • promoted_atstring | null (date-time)
    • logs_urlstring | null
    • urlstring | null
  • 400Missing or invalid WASM binary or metadata
  • 401Unauthorized
  • 403Missing Hives write scope
  • 404Project not owned by authenticated org
  • 413Upload exceeds the bounded limit
  • 502Build dispatch failed
  • 503Build service unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/deployments/upload" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  --data-binary @body.bin

Domains

List all domains for a project

GET/v1/hives/projects/{project_id}/domains

hives:readTested with an API keyhives_list_domains

Parameters

  • project_idpath · stringrequired

    Project ID

  • pagequery · integer (int32)

    Page number (1-indexed)

  • per_pagequery · integer (int32)

    Items per page

Responses

  • 200List of domains
    Response fields
    • dataobject[]required

      Response data

    • data[].[].created_atstring (date-time)required

      Created timestamp

    • data[].[].dns_statusstringrequired

      DNS verification status

    • data[].[].domainstringrequired

      Domain name

    • data[].[].domain_type"subdomain" | "custom" | "apex"required

      Domain type

    • data[].[].idstringrequired

      Domain ID

    • data[].[].ssl_expires_atstring | null (date-time)

      SSL expiration

    • data[].[].ssl_statusstringrequired

      SSL status

    • data[].[].verification_recordnull | object
    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Whether there is a next page

    • pagination.has_prevbooleanrequired

      Whether there is a previous page

    • pagination.pageinteger (int32)required

      Current page number min 0

    • pagination.per_pageinteger (int32)required

      Items per page min 0

    • pagination.totalinteger (int64)required

      Total number of items min 0

    • pagination.total_pagesinteger (int32)required

      Total number of pages min 0

  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/domains" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Add a custom domain to a project

POST/v1/hives/projects/{project_id}/domains

hives:writeTested with an API keyhives_add_domain

Parameters

  • project_idpath · stringrequired

    Project ID

Request body application/json

  • domainstringrequired

    Domain name

Responses

  • 201Domain added
    Response fields
    • created_atstring (date-time)required

      Created timestamp

    • dns_statusstringrequired

      DNS verification status

    • domainstringrequired

      Domain name

    • domain_type"subdomain" | "custom" | "apex"required

      Domain type

    • idstringrequired

      Domain ID

    • ssl_expires_atstring | null (date-time)

      SSL expiration

    • ssl_statusstringrequired

      SSL status

    • verification_recordnull | object
  • 400Invalid request
  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 409Domain already exists
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/domains" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "string"
  }'

Provision SSL certificate for a domain

POST/v1/hives/projects/{project_id}/domains/{domain_id}/ssl

hives:writehives_provision_ssl

Parameters

  • project_idpath · stringrequired

    Project ID

  • domain_idpath · stringrequired

    Domain ID

Responses

  • 200SSL provisioning result
    Response fields
    • errorstring | null

      Error message if failed

    • expires_atstring | null (date-time)

      Certificate expiration

    • ssl_statusstringrequired

      Updated SSL status

    • startedbooleanrequired

      Provisioning started

  • 400Domain not verified
  • 401Unauthorized
  • 403Permission denied
  • 404Domain not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/domains/$DOMAIN_ID/ssl" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Verify domain DNS configuration

POST/v1/hives/projects/{project_id}/domains/{domain_id}/verify

hives:writehives_verify_domain

Parameters

  • project_idpath · stringrequired

    Project ID

  • domain_idpath · stringrequired

    Domain ID

Responses

  • 200Verification result
    Response fields
    • checked_atstring (date-time)required

      Check timestamp

    • dns_statusstringrequired

      Updated DNS status

    • errorstring | null

      Error message if failed

    • verifiedbooleanrequired

      Verification success

  • 401Unauthorized
  • 403Permission denied
  • 404Domain not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/domains/$DOMAIN_ID/verify" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Env

Reveal one owned environment value through Genesis KMS with org/project AAD.

GET/v1/hives/projects/{project_id}/env/{key}/reveal

hives:readTested with an API keyhives_reveal_project_environment

Parameters

  • project_idpath · stringrequired

    Owned Hives project ID

  • keypath · stringrequired

    Environment variable name

Responses

  • 200Explicit environment value reveal; no-store
    Response fields
    • namestringrequired
    • valuestringrequired
  • 401Unauthorized
  • 403Permission denied
  • 404Project or environment name not found
  • 503KMS, protected migration or audit unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/env/$KEY/reveal" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

List persisted environment names, including retained legacy entries.

GET/v1/hives/projects/{project_id}/env/metadata

hives:readTested with an API keyhives_list_project_environment

Parameters

  • project_idpath · stringrequired

    Owned Hives project ID

  • pagequery · integer (int32)

    Page number (1-indexed)

  • per_pagequery · integer (int32)

    Items per page

Responses

  • 200Environment names only
    Response fields
    • dataobject[]required
    • data[].[].namestringrequired
    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Whether there is a next page

    • pagination.has_prevbooleanrequired

      Whether there is a previous page

    • pagination.pageinteger (int32)required

      Current page number min 0

    • pagination.per_pageinteger (int32)required

      Items per page min 0

    • pagination.totalinteger (int64)required

      Total number of items min 0

    • pagination.total_pagesinteger (int32)required

      Total number of pages min 0

    • project_idstringrequired
  • 400Invalid pagination
  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/env/metadata" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Encrypt and persist a flat map; acknowledge updated names without values.

PUT/v1/hives/projects/{project_id}/env/metadata

hives:writeTested with an API keyhives_update_project_environment

Parameters

  • project_idpath · stringrequired

    Owned Hives project ID

Request body application/json

A JSON object; see the description above.

Responses

  • 200Persisted updated names only
    Response fields
    • project_idstringrequired
    • updatedobject[]required
    • updated[].[].namestringrequired
  • 400Invalid names, values or batch size
  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 503KMS or protected migration unavailable
  • 4xx 5xxThe error envelope.
curl -X PUT "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/env/metadata" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Functions

List all functions for a project

GET/v1/hives/projects/{project_id}/functions

hives:readTested with an API keyhives_list_functions

Parameters

  • project_idpath · stringrequired

    Project ID

  • statusquery · string | null

    Filter by status

  • searchquery · string | null

    Search by name

  • pagequery · integer (int32)

    Page number (1-indexed)

  • per_pagequery · integer (int32)

    Items per page

Responses

  • 200List of functions
    Response fields
    • dataobject[]required
    • data[].[].idstringrequired
    • data[].[].tenant_idstringrequired
    • data[].[].project_idstringrequired
    • data[].[].namestringrequired
    • data[].[].descriptionstring | null
    • data[].[].handlerstringrequired

      Persisted handler reference; disabled retained legacy references remain inspectable. New or replacement handlers require an owned canonical WASM artifact.

    • data[].[].routestring | null
    • data[].[].memory_mbintegerrequired

      min 64 · max 1024

    • data[].[].timeout_msintegerrequired

      min 100 · max 30000

    • data[].[].statusstringrequired
    • data[].[].invocationsintegerrequired

      min 0

    • data[].[].avg_duration_msnumberrequired

      min 0

    • data[].[].created_atstring (date-time)required
    • data[].[].updated_atstring (date-time)required
    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Whether there is a next page

    • pagination.has_prevbooleanrequired

      Whether there is a previous page

    • pagination.pageinteger (int32)required

      Current page number min 0

    • pagination.per_pageinteger (int32)required

      Items per page min 0

    • pagination.totalinteger (int64)required

      Total number of items min 0

    • pagination.total_pagesinteger (int32)required

      Total number of pages min 0

  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/functions" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Create a new function

POST/v1/hives/projects/{project_id}/functions

hives:writehives_create_function

Parameters

  • project_idpath · stringrequired

    Project ID

Request body application/json

  • descriptionstring | null

    Function description

  • envobject

    Environment variables

  • handlerstringrequired

    Owned uploaded artifact wasm://sha256/<64 lowercase hex>; foreign org/project artifacts return 404 pattern ^wasm://sha256/[a-f0-9]{64}$

  • module_base64string | null

    Optional canonical standard-base64 WASM bytes (8 to65536 decoded bytes) matching handler. Requires enabled finite staging policy and signed human Genesis sandbox FunctionWrite. Bytes remain on this function only; creation registers without a deployment, DNS or guest invocation. Omit to use an owned uploaded deployment artifact. Reconcile uncertain creation by owned name/ID; no POST replay contract. min length 12 · max length 87384 · pattern ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$

  • memory_mbinteger (int64)

    Memory limit in MB (64-1024) min 64 · max 1024 · default 128

  • namestringrequired

    Function name

  • routestring | null

    HTTP route pattern (optional)

  • timeout_msinteger (int64)

    Timeout in milliseconds (100-30000) min 100 · max 30000 · default 30000

Responses

  • 201Function created
    Response fields
    • idstringrequired
    • tenant_idstringrequired
    • project_idstringrequired
    • namestringrequired
    • descriptionstring | null
    • handlerstringrequired

      Persisted handler reference; disabled retained legacy references remain inspectable. New or replacement handlers require an owned canonical WASM artifact.

    • routestring | null
    • memory_mbintegerrequired

      min 64 · max 1024

    • timeout_msintegerrequired

      min 100 · max 30000

    • statusstringrequired
    • invocationsintegerrequired

      min 0

    • avg_duration_msnumberrequired

      min 0

    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • 400Invalid request
  • 401Unauthorized
  • 404Project not found
  • 409Function already exists
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/functions" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "handler": "string"
  }'

Get a specific function

GET/v1/hives/projects/{project_id}/functions/{function_id}

hives:readhives_get_function

Parameters

  • project_idpath · stringrequired

    Project ID

  • function_idpath · stringrequired

    Function ID

Responses

  • 200Function details
    Response fields
    • idstringrequired
    • tenant_idstringrequired
    • project_idstringrequired
    • namestringrequired
    • descriptionstring | null
    • handlerstringrequired

      Persisted handler reference; disabled retained legacy references remain inspectable. New or replacement handlers require an owned canonical WASM artifact.

    • routestring | null
    • memory_mbintegerrequired

      min 64 · max 1024

    • timeout_msintegerrequired

      min 100 · max 30000

    • statusstringrequired
    • invocationsintegerrequired

      min 0

    • avg_duration_msnumberrequired

      min 0

    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • 401Unauthorized
  • 404Function not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/functions/$FUNCTION_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Update an owned function and encrypted overrides

PUT/v1/hives/projects/{project_id}/functions/{function_id}

hives:writehives_update_function

Parameters

  • project_idpath · stringrequired
  • function_idpath · stringrequired

Request body application/json

  • descriptionstring | null

    max length 500

  • handlerstring

    pattern ^wasm://sha256/[a-f0-9]{64}$

  • remove_routeboolean

    Remove the current HTTP route. Cannot be combined with a route value. Omitting this field or sending a null route preserves the current route.

  • routestring | null

    max length 255

  • memory_mbinteger

    min 64 · max 1024

  • timeout_msinteger

    min 100 · max 30000

  • envobject

    Values encrypted by Genesis KMS; omitted from metadata

  • remove_envstring[]

    Override names to remove

Responses

  • 200Updated metadata; environment values are omitted
    Response fields
    • idstringrequired
    • tenant_idstringrequired
    • project_idstringrequired
    • namestringrequired
    • descriptionstring | null
    • handlerstringrequired

      Persisted handler reference; disabled retained legacy references remain inspectable. New or replacement handlers require an owned canonical WASM artifact.

    • routestring | null
    • memory_mbintegerrequired

      min 64 · max 1024

    • timeout_msintegerrequired

      min 100 · max 30000

    • statusstringrequired
    • invocationsintegerrequired

      min 0

    • avg_duration_msnumberrequired

      min 0

    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • 400Invalid request
  • 403Missing authorized scope
  • 404Function or artifact not found in the signed org and path project
  • 409Mutation conflict; refresh and retry
  • 502Runtime replacement failed; previous healthy function is retained
  • 503Runtime or KMS unavailable
  • 4xx 5xxThe error envelope.
curl -X PUT "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/functions/$FUNCTION_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Unregister an owned function before removing metadata

DELETE/v1/hives/projects/{project_id}/functions/{function_id}

hives:writehives_delete_function

Parameters

  • project_idpath · stringrequired
  • function_idpath · stringrequired

Responses

  • 200Runtime unregister and metadata deletion completed
    Response fields
    • idstringrequired

      Deleted resource ID

    • messagestringrequired

      Message

    • successbooleanrequired

      Success flag

  • 403Missing authorized scope
  • 404Function not found in signed org and path project
  • 409Mutation conflict; refresh and retry
  • 502Runtime unregister failed; metadata is retained
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/functions/$FUNCTION_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Complete a real function invocation and return the raw guest HTTP response

POST/v1/hives/projects/{project_id}/functions/{function_id}/invoke

hives:writeIdempotency-Key optionalhives_invoke_function

Returns actual guest status, safe headers and exact binary bytes, including executed error statuses. An authoritative x-execution-id distinguishes a completed guest response from an API failure. Unmarked WASI stdout is raw 200 octets. No JSON result wrapper or queue acknowledgement.

Parameters

  • project_idpath · stringrequired
  • function_idpath · stringrequired
  • Idempotency-Keyheader · string

    Persist the original key. Required when Genesis funding is enabled; retries reconcile the original operation without replaying the guest.

Request body application/json

  • bodyany

    Strings become UTF-8; other non-null values serialize as JSON; null is empty

  • body_base64string

    Standard base64 for exact binary bytes, decoded at most 10 MiB; guest envelope may reach its cap earlier max length 13981016

  • headersobject

    At most 64 KiB of UTF-8 key/value bytes. Platform identity/status, auth, cookie, Host, framing, origin, referer and forwarding headers are forbidden. Guest headers cannot establish ownership.

  • methodstring

    Valid ASCII HTTP method token at most 64 bytes max length 64 · default "POST"

  • pathstring

    Origin-relative guest URI path including query, at most 8192 UTF-8 bytes. Begins with /, forbids // origins and # fragments. default "/"

Responses

curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/functions/$FUNCTION_ID/invoke" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Complete invocation through the compatibility alias (no durable queue)

POST/v1/hives/projects/{project_id}/functions/{function_id}/invoke/async

hives:writeIdempotency-Key optionalhives_invoke_function_async

Parameters

  • project_idpath · stringrequired
  • function_idpath · stringrequired
  • Idempotency-Keyheader · string

    Persist the original key. Required when Genesis funding is enabled; retries reconcile the original operation without replaying the guest.

Request body application/json

  • bodyany

    Strings become UTF-8; other non-null values serialize as JSON; null is empty

  • body_base64string

    Standard base64 for exact binary bytes, decoded at most 10 MiB; guest envelope may reach its cap earlier max length 13981016

  • headersobject

    At most 64 KiB of UTF-8 key/value bytes. Platform identity/status, auth, cookie, Host, framing, origin, referer and forwarding headers are forbidden. Guest headers cannot establish ownership.

  • methodstring

    Valid ASCII HTTP method token at most 64 bytes max length 64 · default "POST"

  • pathstring

    Origin-relative guest URI path including query, at most 8192 UTF-8 bytes. Begins with /, forbids // origins and # fragments. default "/"

Responses

curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/functions/$FUNCTION_ID/invoke/async" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Get function metrics

GET/v1/hives/projects/{project_id}/functions/{function_id}/metrics

hives:readhives_get_function_metrics

Parameters

  • project_idpath · stringrequired

    Project ID

  • function_idpath · stringrequired

    Function ID

  • startquery · string | null (date-time)

    Start time (defaults based on resolution)

  • endquery · string | null (date-time)

    End time (defaults to now)

  • aggregationquery · "sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"

    Aggregation type

  • resolutionquery · "minute" | "fiveminutes" | "fifteenminutes" | "hour" | "day"

    Resolution

Responses

  • 200Function metrics
    Response fields
    • avg_api_http_duration_msnumber | null (double)

      Average monotonic API duration for retained completed invocations (milliseconds).

    • avg_duration_msnumber | null (double)

      Compatibility alias for monotonic API HTTP duration (milliseconds).

    • billed_gb_secondsnumber | null (double)

      Unavailable: observations are not compute billing.

    • cold_startsinteger | null (int64)

      Unavailable: no persisted cold-start measurement.

    • configured_memory_limit_mbinteger (int64)required

      Persisted configuration limit, not a measured memory sample.

    • failed_invocationsinteger (int64)required

      Failed invocations

    • function_idstringrequired

      Function ID

    • function_namestringrequired

      Function name

    • memory_mbinteger | null (int32)

      Unavailable: no measured resident-memory producer.

    • observationobjectrequired

      Retained observations only; an empty ledger is not proof of zero runtime traffic.

    • observation.duration_measurementstringrequired
    • observation.first_observed_atstring | null (date-time)
    • observation.payload_measurementstringrequired
    • observation.sample_countinteger (int64)required
    • observation.scopestringrequired
    • observed_request_payload_bytesinteger (int64)required

      Decoded HTTP payload bytes; these are not wire traffic or billing bandwidth.

    • observed_response_payload_bytesinteger (int64)required
    • p50_duration_msnumber | null (double)

      P50 monotonic API HTTP duration (milliseconds).

    • p95_duration_msnumber | null (double)

      P95 monotonic API HTTP duration (milliseconds).

    • p99_duration_msnumber | null (double)

      P99 monotonic API HTTP duration (milliseconds).

    • success_ratenumber | null (double)

      Success rate (percentage)

    • successful_invocationsinteger (int64)required

      Successful invocations

    • time_rangeobjectrequired

      Time range for metrics

    • time_range.endstring (date-time)required
    • time_range.startstring (date-time)required
    • timeoutsinteger | null (int64)

      Unavailable: ambiguous transport timeouts are not guest completion samples.

    • total_invocationsinteger (int64)required

      Total invocations

  • 401Unauthorized
  • 403Permission denied
  • 404Function not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/functions/$FUNCTION_ID/metrics" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Get function invocations time series

GET/v1/hives/projects/{project_id}/functions/{function_id}/metrics/invocations

hives:readhives_get_function_invocations_series

Parameters

  • project_idpath · stringrequired

    Project ID

  • function_idpath · stringrequired

    Function ID

  • startquery · string | null (date-time)

    Start time (defaults based on resolution)

  • endquery · string | null (date-time)

    End time (defaults to now)

  • aggregationquery · "sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"

    Aggregation type

  • resolutionquery · "minute" | "fiveminutes" | "fifteenminutes" | "hour" | "day"

    Resolution

Responses

  • 200Invocation metrics time series
    Response fields
    • aggregation"sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"required

      Metric aggregation type

    • dataobject[]required

      Data points

    • data[].[].labelsobject | null

      Optional labels

    • data[].[].timestampstring (date-time)required

      Timestamp

    • data[].[].valuenumber (double)required

      Metric value

    • namestringrequired

      Metric name

    • observationobjectrequired

      Retained observations only; an empty ledger is not proof of zero runtime traffic.

    • observation.duration_measurementstringrequired
    • observation.first_observed_atstring | null (date-time)
    • observation.payload_measurementstringrequired
    • observation.sample_countinteger (int64)required
    • observation.scopestringrequired
    • resolution_secondsinteger (int64)required

      Resolution (bucket size in seconds)

    • time_rangeobjectrequired

      Time range for metrics

    • time_range.endstring (date-time)required
    • time_range.startstring (date-time)required
  • 401Unauthorized
  • 403Permission denied
  • 404Function not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/functions/$FUNCTION_ID/metrics/invocations" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Read original funding operation status without replaying the guest

GET/v1/hives/projects/{project_id}/functions/{function_id}/operations/{operation_id}

hives:readhives_get_function_operation

Parameters

  • project_idpath · stringrequired
  • function_idpath · stringrequired
  • operation_idpath · stringrequired

Responses

  • 200Original operation status; this does not replay the guest response
    Response fields
    • operation_idstringrequired

      pattern ^exec_[a-f0-9]{32}$

    • state"prepared" | "reserve_unknown" | "reserved" | "dispatch_unknown" | "dispatch_authorized" | "dispatched" | "settle_unknown" | "settled" | "release_pending" | "released"required
    • codestringrequired
    • funding_source"sandbox_allowance" | "stripe_test_metered" | nullrequired
    • reservation_idstring | nullrequired
    • retry_executionfalserequired
  • 202Original operation remains unresolved; retain its key
    Response fields
    • operation_idstringrequired

      pattern ^exec_[a-f0-9]{32}$

    • state"prepared" | "reserve_unknown" | "reserved" | "dispatch_unknown" | "dispatch_authorized" | "dispatched" | "settle_unknown" | "settled" | "release_pending" | "released"required
    • codestringrequired
    • funding_source"sandbox_allowance" | "stripe_test_metered" | nullrequired
    • reservation_idstring | nullrequired
    • retry_executionfalserequired
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/functions/$FUNCTION_ID/operations/$OPERATION_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Release an unused reservation only if no guest dispatch occurred

POST/v1/hives/projects/{project_id}/functions/{function_id}/operations/{operation_id}/release

hives:writehives_release_function_operation

Parameters

  • project_idpath · stringrequired
  • function_idpath · stringrequired
  • operation_idpath · stringrequired

Responses

  • 200Original operation status; this does not replay the guest response
    Response fields
    • operation_idstringrequired

      pattern ^exec_[a-f0-9]{32}$

    • state"prepared" | "reserve_unknown" | "reserved" | "dispatch_unknown" | "dispatch_authorized" | "dispatched" | "settle_unknown" | "settled" | "release_pending" | "released"required
    • codestringrequired
    • funding_source"sandbox_allowance" | "stripe_test_metered" | nullrequired
    • reservation_idstring | nullrequired
    • retry_executionfalserequired
  • 202Original operation remains unresolved; retain its key
    Response fields
    • operation_idstringrequired

      pattern ^exec_[a-f0-9]{32}$

    • state"prepared" | "reserve_unknown" | "reserved" | "dispatch_unknown" | "dispatch_authorized" | "dispatched" | "settle_unknown" | "settled" | "release_pending" | "released"required
    • codestringrequired
    • funding_source"sandbox_allowance" | "stripe_test_metered" | nullrequired
    • reservation_idstring | nullrequired
    • retry_executionfalserequired
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/functions/$FUNCTION_ID/operations/$OPERATION_ID/release" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Logs

Query logs for a project

GET/v1/hives/projects/{project_id}/logs

hives:readTested with an API keyhives_query_logs

Parameters

  • project_idpath · stringrequired

    Project ID

  • levelquery · string | null

    Filter by minimum log level

  • sourcequery · string | null

    Filter by source (function, deployment, etc.)

  • searchquery · string | null

    Search query

  • startquery · string | null (date-time)

    Start time (defaults to 1 hour ago)

  • endquery · string | null (date-time)

    End time (defaults to now)

  • request_idquery · string | null

    Request ID for correlation

  • pagequery · integer (int32)

    Page number (1-indexed)

  • per_pagequery · integer (int32)

    Items per page

Responses

  • 200Log entries
    Response fields
    • logsobject[]required

      Log entries

    • logs[].[].duration_msinteger | null (int64)

      Execution duration in milliseconds

    • logs[].[].idstringrequired

      Log entry ID

    • logs[].[].level"trace" | "debug" | "info" | "warn" | "error" | "fatal"required

      Log level enumeration

    • logs[].[].messagestringrequired

      Log message

    • logs[].[].metadataany

      Structured metadata

    • logs[].[].request_idstring | null

      Request ID for correlation

    • logs[].[].sourcestringrequired

      Source (function name, deployment ID, etc.)

    • logs[].[].timestampstring (date-time)required

      Timestamp

    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Whether there is a next page

    • pagination.has_prevbooleanrequired

      Whether there is a previous page

    • pagination.pageinteger (int32)required

      Current page number min 0

    • pagination.per_pageinteger (int32)required

      Items per page min 0

    • pagination.totalinteger (int64)required

      Total number of items min 0

    • pagination.total_pagesinteger (int32)required

      Total number of pages min 0

    • time_rangeobjectrequired

      Time range for metrics

    • time_range.endstring (date-time)required
    • time_range.startstring (date-time)required
  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/logs" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Stream real-time logs for a project via SSE

GET/v1/hives/projects/{project_id}/logs/stream

hives:readTested with an API keyhives_stream_logs

Parameters

  • project_idpath · stringrequired

    Project ID

  • levelquery · string | null

    Filter by minimum log level

  • sourcequery · string | null

    Filter by source

  • heartbeatquery · boolean

    Include heartbeat events

Responses

  • 200Log stream
  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/logs/stream" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Marketplace

Return existing categories with visibility-scoped actual counts.

GET/v1/hives/projects/{project_id}/marketplace/categories

hives:readTested with an API keyhives_marketplace_categories

Parameters

  • project_idpath · stringrequired

    Verified owned Hives project

Responses

  • 200Persisted Marketplace state
    Response fields
    • descriptionstring | null

      Category description

    • icon_urlstring | null

      Icon URL

    • idstring (uuid)required

      Category ID

    • namestringrequired

      Category name

    • package_countinteger (int32)required

      Package count

    • slugstringrequired

      Category slug

    • sort_orderinteger (int32)required

      Sort order

  • 404Resource outside verified organization/project or unavailable
  • 409Existing operation requires reconciliation
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/marketplace/categories" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

List selected-project installations, preserving unresolved state.

GET/v1/hives/projects/{project_id}/marketplace/installed

hives:readTested with an API keyhives_marketplace_installed

Parameters

  • project_idpath · stringrequired

    Verified owned Hives project

  • pagequery · integer (int32)

    One-based page.

  • page_sizequery · integer (int32)

    Maximum rows per page.

Responses

  • 200Persisted Marketplace state
    Response fields
    • dataobject[]required

      Data items

    • data[].[].deployment_idstring | null

      Current actual deployment, retained until a successor is ready.

    • data[].[].deployment_statusstring | null

      Current deployment state.

    • data[].[].idstring (uuid)required

      Durable installation id.

    • data[].[].installed_atstring (date-time)required

      Installation timestamp.

    • data[].[].latest_versionstring | null

      Latest eligible catalog version.

    • data[].[].namestringrequired

      Package name.

    • data[].[].operationstring | null

      Durable operation (install/update/cleanup/uninstall) or null.

    • data[].[].package_idstring (uuid)required

      Package id.

    • data[].[].pending_deployment_idstring | null

      Pending actual deployment.

    • data[].[].pending_deployment_statusstring | null

      Pending deployment state.

    • data[].[].pending_versionstring | null

      Pending target version.

    • data[].[].project_idstringrequired

      Verified selected project.

    • data[].[].slugstringrequired

      Package slug.

    • data[].[].statusstringrequired

      Last persisted installation state.

    • data[].[].versionstring | null

      Current completed version, if one exists.

    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Has next page

    • pagination.has_prevbooleanrequired

      Has previous page

    • pagination.pageinteger (int32)required

      Current page min 0

    • pagination.page_sizeinteger (int32)required

      Page size min 0

    • pagination.totalinteger (int64)required

      Total items

    • pagination.total_pagesinteger (int32)required

      Total pages min 0

  • 404Resource outside verified organization/project or unavailable
  • 409Existing operation requires reconciliation
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/marketplace/installed" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Read a persisted installation after an interrupted operation.

GET/v1/hives/projects/{project_id}/marketplace/installed/{installation_id}

hives:readhives_marketplace_get_installation

Parameters

  • project_idpath · stringrequired

    Verified owned Hives project

  • installation_idpath · string (uuid)required

    Owned persisted installation

Responses

  • 200Persisted Marketplace state
    Response fields
    • deployment_idstring | null

      Current actual deployment, retained until a successor is ready.

    • deployment_statusstring | null

      Current deployment state.

    • idstring (uuid)required

      Durable installation id.

    • installed_atstring (date-time)required

      Installation timestamp.

    • latest_versionstring | null

      Latest eligible catalog version.

    • namestringrequired

      Package name.

    • operationstring | null

      Durable operation (install/update/cleanup/uninstall) or null.

    • package_idstring (uuid)required

      Package id.

    • pending_deployment_idstring | null

      Pending actual deployment.

    • pending_deployment_statusstring | null

      Pending deployment state.

    • pending_versionstring | null

      Pending target version.

    • project_idstringrequired

      Verified selected project.

    • slugstringrequired

      Package slug.

    • statusstringrequired

      Last persisted installation state.

    • versionstring | null

      Current completed version, if one exists.

  • 404Resource outside verified organization/project or unavailable
  • 409Existing operation requires reconciliation
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/marketplace/installed/$INSTALLATION_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Persist uninstall intent before stopping every retained workload.

DELETE/v1/hives/projects/{project_id}/marketplace/installed/{installation_id}

hives:writehives_marketplace_uninstall

Parameters

  • project_idpath · stringrequired

    Verified owned Hives project

  • installation_idpath · string (uuid)required

    Owned persisted installation

Responses

  • 200Persisted Marketplace state
    Response fields
    • deployment_idstring | null

      Current actual deployment, retained until a successor is ready.

    • deployment_statusstring | null

      Current deployment state.

    • idstring (uuid)required

      Durable installation id.

    • installed_atstring (date-time)required

      Installation timestamp.

    • latest_versionstring | null

      Latest eligible catalog version.

    • namestringrequired

      Package name.

    • operationstring | null

      Durable operation (install/update/cleanup/uninstall) or null.

    • package_idstring (uuid)required

      Package id.

    • pending_deployment_idstring | null

      Pending actual deployment.

    • pending_deployment_statusstring | null

      Pending deployment state.

    • pending_versionstring | null

      Pending target version.

    • project_idstringrequired

      Verified selected project.

    • slugstringrequired

      Package slug.

    • statusstringrequired

      Last persisted installation state.

    • versionstring | null

      Current completed version, if one exists.

  • 404Resource outside verified organization/project or unavailable
  • 409Existing operation requires reconciliation
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/marketplace/installed/$INSTALLATION_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Explicitly finish an existing durable operation; this never starts a build.

POST/v1/hives/projects/{project_id}/marketplace/installed/{installation_id}/reconcile

hives:writehives_marketplace_reconcile

Parameters

  • project_idpath · stringrequired

    Verified owned Hives project

  • installation_idpath · string (uuid)required

    Owned persisted installation

Responses

  • 200Persisted Marketplace state
    Response fields
    • deployment_idstring | null

      Current actual deployment, retained until a successor is ready.

    • deployment_statusstring | null

      Current deployment state.

    • idstring (uuid)required

      Durable installation id.

    • installed_atstring (date-time)required

      Installation timestamp.

    • latest_versionstring | null

      Latest eligible catalog version.

    • namestringrequired

      Package name.

    • operationstring | null

      Durable operation (install/update/cleanup/uninstall) or null.

    • package_idstring (uuid)required

      Package id.

    • pending_deployment_idstring | null

      Pending actual deployment.

    • pending_deployment_statusstring | null

      Pending deployment state.

    • pending_versionstring | null

      Pending target version.

    • project_idstringrequired

      Verified selected project.

    • slugstringrequired

      Package slug.

    • statusstringrequired

      Last persisted installation state.

    • versionstring | null

      Current completed version, if one exists.

  • 404Resource outside verified organization/project or unavailable
  • 409Existing operation requires reconciliation
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/marketplace/installed/$INSTALLATION_ID/reconcile" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Search the persisted visible catalog.

GET/v1/hives/projects/{project_id}/marketplace/packages

hives:readTested with an API keyhives_marketplace_list_packages

Parameters

  • project_idpath · stringrequired

    Verified owned Hives project

  • qquery · string | null

    Search query

  • categoryquery · string | null

    Category filter

  • free_onlyquery · boolean

    Only free packages

  • verified_onlyquery · boolean

    Only verified packages

  • sortquery · "name" | "installs" | "stars" | "created" | "updated"

    Sort field

  • orderquery · "asc" | "desc"

    Sort order

  • pagequery · integer (int32)

    Page number

  • page_sizequery · integer (int32)

    Page size

Responses

  • 200Persisted Marketplace state
    Response fields
    • dataobject[]required

      Data items

    • data[].[].author_namestringrequired

      Verified publisher display name captured at publication.

    • data[].[].categoriesstring[]required

      Existing categories.

    • data[].[].created_atstring (date-time)required

      Persisted creation timestamp.

    • data[].[].descriptionstringrequired

      Description.

    • data[].[].featuredbooleanrequired

      Persisted featured marker.

    • data[].[].freebooleanrequired

      Paid packages require a real Foundry entitlement before installation.

    • data[].[].idstring (uuid)required

      Package id.

    • data[].[].installsinteger (int64)required

      Actual completed native installations, excluding seeded counters.

    • data[].[].keywordsstring[]required

      Search keywords.

    • data[].[].latest_versionstringrequired

      Latest eligible version.

    • data[].[].licensestringrequired

      License.

    • data[].[].namestringrequired

      Display name.

    • data[].[].ownedbooleanrequired

      Can the signed organization publish another version?

    • data[].[].slugstringrequired

      Stable slug.

    • data[].[].starsinteger (int64)required

      Actual persisted stars, excluding seeded counters.

    • data[].[].updated_atstring (date-time)required

      Persisted update timestamp.

    • data[].[].verifiedbooleanrequired

      Persisted verification marker.

    • data[].[].version_countinteger (int64)required

      Exact number of eligible versions.

    • data[].[].visibilitystringrequired

      Public/private/unlisted visibility.

    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Has next page

    • pagination.has_prevbooleanrequired

      Has previous page

    • pagination.pageinteger (int32)required

      Current page min 0

    • pagination.page_sizeinteger (int32)required

      Page size min 0

    • pagination.totalinteger (int64)required

      Total items

    • pagination.total_pagesinteger (int32)required

      Total pages min 0

  • 404Resource outside verified organization/project or unavailable
  • 409Existing operation requires reconciliation
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/marketplace/packages" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Read the selected package and its actual immutable versions.

GET/v1/hives/projects/{project_id}/marketplace/packages/{slug}

hives:readhives_marketplace_get_package

Parameters

  • project_idpath · stringrequired

    Verified owned Hives project

  • slugpath · stringrequired

    Existing package slug

  • versionquery · string | null

    Optional exact semantic version; absence returns the newest bounded page.

Responses

  • 200Persisted Marketplace state
    Response fields
    • author_namestringrequired

      Verified publisher display name captured at publication.

    • categoriesstring[]required

      Existing categories.

    • created_atstring (date-time)required

      Persisted creation timestamp.

    • descriptionstringrequired

      Description.

    • featuredbooleanrequired

      Persisted featured marker.

    • freebooleanrequired

      Paid packages require a real Foundry entitlement before installation.

    • idstring (uuid)required

      Package id.

    • installsinteger (int64)required

      Actual completed native installations, excluding seeded counters.

    • keywordsstring[]required

      Search keywords.

    • latest_versionstringrequired

      Latest eligible version.

    • licensestringrequired

      License.

    • namestringrequired

      Display name.

    • ownedbooleanrequired

      Can the signed organization publish another version?

    • slugstringrequired

      Stable slug.

    • starsinteger (int64)required

      Actual persisted stars, excluding seeded counters.

    • updated_atstring (date-time)required

      Persisted update timestamp.

    • verifiedbooleanrequired

      Persisted verification marker.

    • version_countinteger (int64)required

      Exact number of eligible versions.

    • visibilitystringrequired

      Public/private/unlisted visibility.

    • versionsobject[]required

      Eligible immutable versions.

    • versions[].[].changelogstringrequired

      Version changes.

    • versions[].[].deprecatedbooleanrequired

      Persisted deprecation flag.

    • versions[].[].downloadsinteger (int64)required

      Actual persisted installation attempts for this new artifact version.

    • versions[].[].idstring (uuid)required

      Version id.

    • versions[].[].module_hashstringrequired

      Content digest.

    • versions[].[].package_idstring (uuid)required

      Owning package.

    • versions[].[].published_atstring (date-time)required

      Persisted publish timestamp.

    • versions[].[].readmestringrequired

      Readme text.

    • versions[].[].required_envstring[]required

      Required environment names.

    • versions[].[].size_bytesinteger (int64)required

      Actual stored size.

    • versions[].[].versionstringrequired

      Semantic version.

  • 404Resource outside verified organization/project or unavailable
  • 409Existing operation requires reconciliation
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/marketplace/packages/$SLUG" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Install a real package. A 202 acknowledges the durable operation, not readiness.

POST/v1/hives/projects/{project_id}/marketplace/packages/{slug}/install

hives:writehives_marketplace_install

Parameters

  • project_idpath · stringrequired

    Verified owned Hives project

  • slugpath · stringrequired

    Existing package slug

Request body application/json

  • env_overridesobject

    Values are encrypted through the existing deployment KMS path.

  • versionstring | null

    Latest eligible version is selected when omitted.

Responses

  • 202Persisted Marketplace state
    Response fields
    • deployment_idstring | null

      Current actual deployment, retained until a successor is ready.

    • deployment_statusstring | null

      Current deployment state.

    • idstring (uuid)required

      Durable installation id.

    • installed_atstring (date-time)required

      Installation timestamp.

    • latest_versionstring | null

      Latest eligible catalog version.

    • namestringrequired

      Package name.

    • operationstring | null

      Durable operation (install/update/cleanup/uninstall) or null.

    • package_idstring (uuid)required

      Package id.

    • pending_deployment_idstring | null

      Pending actual deployment.

    • pending_deployment_statusstring | null

      Pending deployment state.

    • pending_versionstring | null

      Pending target version.

    • project_idstringrequired

      Verified selected project.

    • slugstringrequired

      Package slug.

    • statusstringrequired

      Last persisted installation state.

    • versionstring | null

      Current completed version, if one exists.

  • 404Resource outside verified organization/project or unavailable
  • 409Existing operation requires reconciliation
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/marketplace/packages/$SLUG/install" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Update through a real successor deployment while retaining the old runtime.

POST/v1/hives/projects/{project_id}/marketplace/packages/{slug}/update

hives:writehives_marketplace_update

Parameters

  • project_idpath · stringrequired

    Verified owned Hives project

  • slugpath · stringrequired

    Existing package slug

Request body application/json

  • env_overridesobject

    Values are encrypted through the existing deployment KMS path.

  • versionstring | null

    Latest eligible version is selected when omitted.

Responses

  • 202Persisted Marketplace state
    Response fields
    • deployment_idstring | null

      Current actual deployment, retained until a successor is ready.

    • deployment_statusstring | null

      Current deployment state.

    • idstring (uuid)required

      Durable installation id.

    • installed_atstring (date-time)required

      Installation timestamp.

    • latest_versionstring | null

      Latest eligible catalog version.

    • namestringrequired

      Package name.

    • operationstring | null

      Durable operation (install/update/cleanup/uninstall) or null.

    • package_idstring (uuid)required

      Package id.

    • pending_deployment_idstring | null

      Pending actual deployment.

    • pending_deployment_statusstring | null

      Pending deployment state.

    • pending_versionstring | null

      Pending target version.

    • project_idstringrequired

      Verified selected project.

    • slugstringrequired

      Package slug.

    • statusstringrequired

      Last persisted installation state.

    • versionstring | null

      Current completed version, if one exists.

  • 404Resource outside verified organization/project or unavailable
  • 409Existing operation requires reconciliation
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/marketplace/packages/$SLUG/update" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Read every eligible version using bounded pages.

GET/v1/hives/projects/{project_id}/marketplace/packages/{slug}/versions

hives:readhives_marketplace_list_versions

Parameters

  • project_idpath · stringrequired

    Verified owned Hives project

  • slugpath · stringrequired

    Existing package slug

  • pagequery · integer (int32)

    One-based page.

  • page_sizequery · integer (int32)

    At most five full versions keep escaped JSON beneath the Console limit.

Responses

  • 200Persisted Marketplace state
    Response fields
    • dataobject[]required

      Data items

    • data[].[].changelogstringrequired

      Version changes.

    • data[].[].deprecatedbooleanrequired

      Persisted deprecation flag.

    • data[].[].downloadsinteger (int64)required

      Actual persisted installation attempts for this new artifact version.

    • data[].[].idstring (uuid)required

      Version id.

    • data[].[].module_hashstringrequired

      Content digest.

    • data[].[].package_idstring (uuid)required

      Owning package.

    • data[].[].published_atstring (date-time)required

      Persisted publish timestamp.

    • data[].[].readmestringrequired

      Readme text.

    • data[].[].required_envstring[]required

      Required environment names.

    • data[].[].size_bytesinteger (int64)required

      Actual stored size.

    • data[].[].versionstringrequired

      Semantic version.

    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Has next page

    • pagination.has_prevbooleanrequired

      Has previous page

    • pagination.pageinteger (int32)required

      Current page min 0

    • pagination.page_sizeinteger (int32)required

      Page size min 0

    • pagination.totalinteger (int64)required

      Total items

    • pagination.total_pagesinteger (int32)required

      Total pages min 0

  • 404Resource outside verified organization/project or unavailable
  • 409Existing operation requires reconciliation
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/marketplace/packages/$SLUG/versions" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Publish a verified selected-project artifact; never fetch an arbitrary URL.

POST/v1/hives/projects/{project_id}/marketplace/packages/publish

hives:writehives_marketplace_publish

Parameters

  • project_idpath · stringrequired

    Verified owned Hives project

Request body application/json

  • categoriesstring[]

    Existing category slugs.

  • changelogstring

    Version changes.

  • descriptionstring

    Short description.

  • keywordsstring[]

    Search keywords.

  • licensestring

    Package license.

  • module_hashstringrequired

    Source artifact already owned by the selected project.

  • namestringrequired

    Human-readable package name.

  • readmestring

    Plain-text readme.

  • required_envstring[]

    Environment names required when installing; never values.

  • slugstringrequired

    Stable package slug.

  • versionstringrequired

    Immutable semantic version.

  • visibility"public" | "private" | "unlisted"

    Package visibility

Responses

  • 201Persisted Marketplace state
    Response fields
    • author_namestringrequired

      Verified publisher display name captured at publication.

    • categoriesstring[]required

      Existing categories.

    • created_atstring (date-time)required

      Persisted creation timestamp.

    • descriptionstringrequired

      Description.

    • featuredbooleanrequired

      Persisted featured marker.

    • freebooleanrequired

      Paid packages require a real Foundry entitlement before installation.

    • idstring (uuid)required

      Package id.

    • installsinteger (int64)required

      Actual completed native installations, excluding seeded counters.

    • keywordsstring[]required

      Search keywords.

    • latest_versionstringrequired

      Latest eligible version.

    • licensestringrequired

      License.

    • namestringrequired

      Display name.

    • ownedbooleanrequired

      Can the signed organization publish another version?

    • slugstringrequired

      Stable slug.

    • starsinteger (int64)required

      Actual persisted stars, excluding seeded counters.

    • updated_atstring (date-time)required

      Persisted update timestamp.

    • verifiedbooleanrequired

      Persisted verification marker.

    • version_countinteger (int64)required

      Exact number of eligible versions.

    • visibilitystringrequired

      Public/private/unlisted visibility.

    • versionsobject[]required

      Eligible immutable versions.

    • versions[].[].changelogstringrequired

      Version changes.

    • versions[].[].deprecatedbooleanrequired

      Persisted deprecation flag.

    • versions[].[].downloadsinteger (int64)required

      Actual persisted installation attempts for this new artifact version.

    • versions[].[].idstring (uuid)required

      Version id.

    • versions[].[].module_hashstringrequired

      Content digest.

    • versions[].[].package_idstring (uuid)required

      Owning package.

    • versions[].[].published_atstring (date-time)required

      Persisted publish timestamp.

    • versions[].[].readmestringrequired

      Readme text.

    • versions[].[].required_envstring[]required

      Required environment names.

    • versions[].[].size_bytesinteger (int64)required

      Actual stored size.

    • versions[].[].versionstringrequired

      Semantic version.

  • 404Resource outside verified organization/project or unavailable
  • 409Existing operation requires reconciliation
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/marketplace/packages/publish" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "string",
    "name": "string",
    "module_hash": "string",
    "version": "string"
  }'

Metrics

Get project metrics overview

GET/v1/hives/projects/{project_id}/metrics

hives:readTested with an API keyhives_get_project_metrics

Parameters

  • project_idpath · stringrequired

    Project ID

  • startquery · string | null (date-time)

    Start time (defaults based on resolution)

  • endquery · string | null (date-time)

    End time (defaults to now)

  • aggregationquery · "sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"

    Aggregation type

  • resolutionquery · "minute" | "fiveminutes" | "fifteenminutes" | "hour" | "day"

    Resolution

Responses

  • 200Project metrics
    Response fields
    • active_deploymentsinteger (int32)required

      Active deployments

    • avg_api_http_duration_msnumber | null (double)

      Average monotonic API duration for retained completed invocations (milliseconds).

    • avg_response_time_msnumber | null (double)

      Compatibility alias for monotonic API HTTP duration (milliseconds).

    • cron_executionsinteger | null (int64)

      Unavailable: this ledger does not observe scheduler execution history.

    • data_transfer_bytesinteger (int64)required

      Compatibility alias for observed decoded request + response payload bytes.

    • error_countinteger (int64)required

      Error count

    • error_ratenumber | null (double)

      Error rate (percentage)

    • function_invocationsinteger (int64)required

      Function invocations

    • observationobjectrequired

      Retained observations only; an empty ledger is not proof of zero runtime traffic.

    • observation.duration_measurementstringrequired
    • observation.first_observed_atstring | null (date-time)
    • observation.payload_measurementstringrequired
    • observation.sample_countinteger (int64)required
    • observation.scopestringrequired
    • observed_request_payload_bytesinteger (int64)required

      Decoded HTTP payload bytes; these are not wire traffic or billing bandwidth.

    • observed_response_payload_bytesinteger (int64)required
    • p95_response_time_msnumber | null (double)

      P95 monotonic API HTTP duration (milliseconds).

    • p99_response_time_msnumber | null (double)

      P99 monotonic API HTTP duration (milliseconds).

    • project_idstringrequired

      Project ID

    • storage_bytesinteger | null (int64)

      Unavailable: no attested storage-usage producer.

    • time_rangeobjectrequired

      Time range for metrics

    • time_range.endstring (date-time)required
    • time_range.startstring (date-time)required
    • total_requestsinteger (int64)required

      Total requests

    • unique_visitorsinteger | null (int64)

      Unavailable: no visitor identity collection.

  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/metrics" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Get dashboard metrics for retained completed API invocations.

GET/v1/hives/projects/{project_id}/metrics/dashboard

hives:readTested with an API keyhives_get_dashboard_metrics

Parameters

  • project_idpath · stringrequired

    Owned project ID

  • periodquery · string | null

    Relative period: 1h, 24h, 7d, or 30d.

Responses

  • 200Retained completed API invocation metrics; unavailable values are null
    Response fields
    • activeDeploymentsinteger (int32)required
    • avgApiHttpDurationMsnumber | null (double)

      Average monotonic API duration for retained completed invocations (milliseconds).

    • avgLatencyMsnumber | null (double)
    • deploymentsChangenumber | null (double)
    • errorRatenumber | null (double)
    • errorRateChangenumber | null (double)
    • errorTimeSeriesobject[]required
    • errorTimeSeries[].[].labelsobject | null

      Optional labels

    • errorTimeSeries[].[].timestampstring (date-time)required

      Timestamp

    • errorTimeSeries[].[].valuenumber (double)required

      Metric value

    • latencyChangenumber | null (double)
    • latencyTimeSeriesobject[]required
    • latencyTimeSeries[].[].labelsobject | null

      Optional labels

    • latencyTimeSeries[].[].timestampstring (date-time)required

      Timestamp

    • latencyTimeSeries[].[].valuenumber (double)required

      Metric value

    • observationobjectrequired

      Retained observations only; an empty ledger is not proof of zero runtime traffic.

    • observation.duration_measurementstringrequired
    • observation.first_observed_atstring | null (date-time)
    • observation.payload_measurementstringrequired
    • observation.sample_countinteger (int64)required
    • observation.scopestringrequired
    • observedRequestPayloadBytesinteger (int64)required

      Decoded HTTP payload bytes; these are not wire traffic or billing bandwidth.

    • observedResponsePayloadBytesinteger (int64)required
    • requestsChangenumber | null (double)
    • requestsTimeSeriesobject[]required
    • requestsTimeSeries[].[].labelsobject | null

      Optional labels

    • requestsTimeSeries[].[].timestampstring (date-time)required

      Timestamp

    • requestsTimeSeries[].[].valuenumber (double)required

      Metric value

    • totalRequestsinteger (int64)required
  • 400Invalid metric window
  • 401Unauthorized
  • 404Project not found
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/metrics/dashboard" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Get error rate metrics

GET/v1/hives/projects/{project_id}/metrics/errors

hives:readTested with an API keyhives_get_error_metrics

Parameters

  • project_idpath · stringrequired

    Project ID

  • startquery · string | null (date-time)

    Start time (defaults based on resolution)

  • endquery · string | null (date-time)

    End time (defaults to now)

  • aggregationquery · "sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"

    Aggregation type

  • resolutionquery · "minute" | "fiveminutes" | "fifteenminutes" | "hour" | "day"

    Resolution

Responses

  • 200Error metrics time series
    Response fields
    • aggregation"sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"required

      Metric aggregation type

    • dataobject[]required

      Data points

    • data[].[].labelsobject | null

      Optional labels

    • data[].[].timestampstring (date-time)required

      Timestamp

    • data[].[].valuenumber (double)required

      Metric value

    • namestringrequired

      Metric name

    • observationobjectrequired

      Retained observations only; an empty ledger is not proof of zero runtime traffic.

    • observation.duration_measurementstringrequired
    • observation.first_observed_atstring | null (date-time)
    • observation.payload_measurementstringrequired
    • observation.sample_countinteger (int64)required
    • observation.scopestringrequired
    • resolution_secondsinteger (int64)required

      Resolution (bucket size in seconds)

    • time_rangeobjectrequired

      Time range for metrics

    • time_range.endstring (date-time)required
    • time_range.startstring (date-time)required
  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/metrics/errors" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Get response time metrics

GET/v1/hives/projects/{project_id}/metrics/latency

hives:readTested with an API keyhives_get_latency_metrics

Parameters

  • project_idpath · stringrequired

    Project ID

  • startquery · string | null (date-time)

    Start time (defaults based on resolution)

  • endquery · string | null (date-time)

    End time (defaults to now)

  • aggregationquery · "sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"

    Aggregation type

  • resolutionquery · "minute" | "fiveminutes" | "fifteenminutes" | "hour" | "day"

    Resolution

Responses

  • 200Latency metrics time series
    Response fields
    • aggregation"sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"required

      Metric aggregation type

    • dataobject[]required

      Data points

    • data[].[].labelsobject | null

      Optional labels

    • data[].[].timestampstring (date-time)required

      Timestamp

    • data[].[].valuenumber (double)required

      Metric value

    • namestringrequired

      Metric name

    • observationobjectrequired

      Retained observations only; an empty ledger is not proof of zero runtime traffic.

    • observation.duration_measurementstringrequired
    • observation.first_observed_atstring | null (date-time)
    • observation.payload_measurementstringrequired
    • observation.sample_countinteger (int64)required
    • observation.scopestringrequired
    • resolution_secondsinteger (int64)required

      Resolution (bucket size in seconds)

    • time_rangeobjectrequired

      Time range for metrics

    • time_range.endstring (date-time)required
    • time_range.startstring (date-time)required
  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/metrics/latency" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Get real-time metrics for dashboard

GET/v1/hives/projects/{project_id}/metrics/realtime

hives:readTested with an API keyhives_get_realtime_metrics

Parameters

  • project_idpath · stringrequired

    Project ID

Responses

  • 200Real-time metrics
    Response fields
    • active_connectionsinteger | null (int64)

      Unavailable: process-global connections are not project measurements.

    • avg_api_http_duration_msnumber | null (double)

      Average monotonic API duration for retained completed invocations (milliseconds).

    • avg_response_time_msnumber | null (double)

      Compatibility alias for monotonic API HTTP duration (milliseconds). - last 5 minutes

    • cpu_percentnumber | null (double)

      Unavailable: no measured per-resource CPU producer.

    • error_ratenumber | null (double)

      Current error rate (percentage)

    • memory_percentnumber | null (double)

      Unavailable: no measured per-resource memory producer.

    • observationobjectrequired

      Retained observations only; an empty ledger is not proof of zero runtime traffic.

    • observation.duration_measurementstringrequired
    • observation.first_observed_atstring | null (date-time)
    • observation.payload_measurementstringrequired
    • observation.sample_countinteger (int64)required
    • observation.scopestringrequired
    • observed_request_payload_bytesinteger (int64)required

      Decoded HTTP payload bytes; these are not wire traffic or billing bandwidth.

    • observed_response_payload_bytesinteger (int64)required
    • requests_per_secondnumber (double)required

      Current requests per second

    • updated_atstring (date-time)required

      Last updated timestamp

  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/metrics/realtime" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Get request metrics time series

GET/v1/hives/projects/{project_id}/metrics/requests

hives:readTested with an API keyhives_get_request_metrics

Parameters

  • project_idpath · stringrequired

    Project ID

  • startquery · string | null (date-time)

    Start time (defaults based on resolution)

  • endquery · string | null (date-time)

    End time (defaults to now)

  • aggregationquery · "sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"

    Aggregation type

  • resolutionquery · "minute" | "fiveminutes" | "fifteenminutes" | "hour" | "day"

    Resolution

Responses

  • 200Request metrics time series
    Response fields
    • aggregation"sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"required

      Metric aggregation type

    • dataobject[]required

      Data points

    • data[].[].labelsobject | null

      Optional labels

    • data[].[].timestampstring (date-time)required

      Timestamp

    • data[].[].valuenumber (double)required

      Metric value

    • namestringrequired

      Metric name

    • observationobjectrequired

      Retained observations only; an empty ledger is not proof of zero runtime traffic.

    • observation.duration_measurementstringrequired
    • observation.first_observed_atstring | null (date-time)
    • observation.payload_measurementstringrequired
    • observation.sample_countinteger (int64)required
    • observation.scopestringrequired
    • resolution_secondsinteger (int64)required

      Resolution (bucket size in seconds)

    • time_rangeobjectrequired

      Time range for metrics

    • time_range.endstring (date-time)required
    • time_range.startstring (date-time)required
  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/metrics/requests" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Get measured API invocation metadata and real owned resource counts

GET/v1/hives/projects/{project_id}/metrics/usage

hives:readTested with an API keyhives_get_resource_usage

Parameters

  • project_idpath · stringrequired

    Project ID

  • startquery · string | null (date-time)

    Start time (defaults based on resolution)

  • endquery · string | null (date-time)

    End time (defaults to now)

  • aggregationquery · "sum" | "avg" | "min" | "max" | "count" | "p50" | "p90" | "p95" | "p99"

    Aggregation type

  • resolutionquery · "minute" | "fiveminutes" | "fifteenminutes" | "hour" | "day"

    Resolution

Responses

  • 200Resource usage
    Response fields
    • active_deploymentsinteger (int32)required

      Active deployments

    • avg_api_http_duration_msnumber | null (double)

      Average monotonic API duration for retained completed invocations (milliseconds).

    • bandwidth_gbnumber | null (double)

      Unavailable: decoded payload bytes are not billed bandwidth.

    • build_minutesinteger | null (int64)

      Unavailable: no retained build-duration producer.

    • compute_gb_secondsnumber | null (double)

      Unavailable: this is not a billing ledger.

    • custom_domainsinteger (int32)required

      Custom domains

    • function_invocationsinteger (int64)required

      Function invocations

    • observationobjectrequired

      Retained observations only; an empty ledger is not proof of zero runtime traffic.

    • observation.duration_measurementstringrequired
    • observation.first_observed_atstring | null (date-time)
    • observation.payload_measurementstringrequired
    • observation.sample_countinteger (int64)required
    • observation.scopestringrequired
    • observed_request_payload_bytesinteger (int64)required

      Decoded HTTP payload bytes; these are not wire traffic or billing bandwidth.

    • observed_response_payload_bytesinteger (int64)required
    • scheduled_jobsinteger (int32)required

      Enabled canonical Waggle definitions; not proof of scheduler execution.

    • ssl_certificatesinteger (int32)required

      SSL certificates

    • storage_gbnumber | null (double)

      Unavailable: no attested storage-usage producer.

    • time_rangeobjectrequired

      Time range for metrics

    • time_range.endstring (date-time)required
    • time_range.startstring (date-time)required
  • 401Unauthorized
  • 403Permission denied
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/metrics/usage" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Queues

hives_list_native_queue

GET/v1/hives/projects/{project_id}/queues

hives:readTested with an API keyhives_list_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

Responses

  • 200Actual persisted queue result
    Response fields

    A JSON object.

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_create_native_queue

POST/v1/hives/projects/{project_id}/queues

hives:writeTested with an API keyhives_create_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

Request body application/json

  • deadLetterQueueIdstring | null
  • maxReceiveCountinteger (int32)

    min 0

  • namestringrequired
  • retentionPeriodinteger (int32)

    min 0

  • type"standard" | "fifo" | "dead_letter"

    Queue type determining delivery semantics

  • visibilityTimeoutinteger (int32)

    min 0

Responses

  • 201Actual persisted queue result
    Response fields
    • avgProcessingTimeMsnumber | null (double)
    • consumerCountinteger | null (int64)

      min 0

    • createdAtstringrequired
    • deadLetterQueueIdstring | null
    • delayedMessagesinteger (int64)required
    • deliveryAvailablebooleanrequired
    • idstringrequired
    • maxMessageSizeintegerrequired

      min 0

    • maxReceiveCountinteger (int32)required

      min 0

    • messageCountinteger (int64)required
    • messagesProcessinginteger (int64)required
    • namestringrequired
    • projectIdstringrequired
    • retainedMessagesinteger (int64)required
    • retainedPayloadBytesinteger (int64)required
    • retentionPeriodinteger (int32)required

      min 0

    • statusstringrequired
    • throughputPerSecondnumber | null (double)
    • typestringrequired
    • updatedAtstringrequired
    • visibilityTimeoutinteger (int32)required

      min 0

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'

hives_inspect_native_queue

GET/v1/hives/projects/{project_id}/queues/{queue_id}

hives:readTested with an API keyhives_inspect_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Responses

  • 200Actual persisted queue result
    Response fields
    • avgProcessingTimeMsnumber | null (double)
    • consumerCountinteger | null (int64)

      min 0

    • createdAtstringrequired
    • deadLetterQueueIdstring | null
    • delayedMessagesinteger (int64)required
    • deliveryAvailablebooleanrequired
    • idstringrequired
    • maxMessageSizeintegerrequired

      min 0

    • maxReceiveCountinteger (int32)required

      min 0

    • messageCountinteger (int64)required
    • messagesProcessinginteger (int64)required
    • namestringrequired
    • projectIdstringrequired
    • retainedMessagesinteger (int64)required
    • retainedPayloadBytesinteger (int64)required
    • retentionPeriodinteger (int32)required

      min 0

    • statusstringrequired
    • throughputPerSecondnumber | null (double)
    • typestringrequired
    • updatedAtstringrequired
    • visibilityTimeoutinteger (int32)required

      min 0

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_delete_native_queue

DELETE/v1/hives/projects/{project_id}/queues/{queue_id}

hives:writeTested with an API keyhives_delete_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Responses

  • 200Actual persisted queue result
    Response fields

    A JSON object.

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_configure_native_queue

PATCH/v1/hives/projects/{project_id}/queues/{queue_id}

hives:writeFailed with an API keyhives_configure_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Request body application/json

  • deadLetterQueueIdstring | null
  • maxReceiveCountinteger (int32)required

    min 0

  • retentionPeriodinteger (int32)required

    min 0

  • visibilityTimeoutinteger (int32)required

    min 0

Responses

  • 200Actual persisted queue result
    Response fields
    • avgProcessingTimeMsnumber | null (double)
    • consumerCountinteger | null (int64)

      min 0

    • createdAtstringrequired
    • deadLetterQueueIdstring | null
    • delayedMessagesinteger (int64)required
    • deliveryAvailablebooleanrequired
    • idstringrequired
    • maxMessageSizeintegerrequired

      min 0

    • maxReceiveCountinteger (int32)required

      min 0

    • messageCountinteger (int64)required
    • messagesProcessinginteger (int64)required
    • namestringrequired
    • projectIdstringrequired
    • retainedMessagesinteger (int64)required
    • retainedPayloadBytesinteger (int64)required
    • retentionPeriodinteger (int32)required

      min 0

    • statusstringrequired
    • throughputPerSecondnumber | null (double)
    • typestringrequired
    • updatedAtstringrequired
    • visibilityTimeoutinteger (int32)required

      min 0

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X PATCH "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "retentionPeriod": 0,
    "visibilityTimeout": 0,
    "maxReceiveCount": 0
  }'

hives_get_native_queue_consumer

GET/v1/hives/projects/{project_id}/queues/{queue_id}/consumer

hives:readTested with an API keyhives_get_native_queue_consumer

Parameters

  • project_idpath · stringrequired
  • queue_idpath · stringrequired

Responses

  • 200Persisted binding and latest attempt
    Response fields
    • autoAckbooleanrequired
    • batchSizeinteger (int32)required

      min 0

    • consumerobjectrequired
    • consumer.bindingnull | object
    • consumer.exhaustedMessagesinteger (int64)required
    • consumer.latestAttemptnull | object
    • maxConcurrentinteger (int32)required

      min 0

    • runtimeEnabledbooleanrequired
  • 401Verified identity required
  • 403Hives read scope required
  • 404Owned queue not found
  • 503Persistence unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/consumer" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_configure_native_queue_consumer

PUT/v1/hives/projects/{project_id}/queues/{queue_id}/consumer

hives:writeFailed with an API keyhives_configure_native_queue_consumer

Parameters

  • project_idpath · stringrequired
  • queue_idpath · stringrequired

Request body application/json

  • autoAckbooleanrequired
  • batchSizeinteger (int32)required

    min 0

  • deadLetterQueuestring | null
  • enabledbooleanrequired
  • functionIdstringrequired
  • maxConcurrentinteger (int32)required

    min 0

  • maxRetriesinteger (int32)required

    min 0

  • queueNamestringrequired
  • visibilityTimeoutSecsinteger (int32)required

    min 0

Responses

  • 200Persisted consumer binding
    Response fields
    • createdAtstring (date-time)required
    • enabledbooleanrequired
    • functionIdstringrequired
    • projectIdstringrequired
    • queueIdstringrequired
    • revisioninteger (int64)required
    • updatedAtstring (date-time)required
  • 400Invalid trigger configuration
  • 401Verified identity required
  • 403Queue write and function invoke scope required
  • 404Owned queue or active function not found
  • 409Delivery configuration mismatch or attempt in flight
  • 503Unsupported trigger mode or persistence unavailable
  • 4xx 5xxThe error envelope.
curl -X PUT "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/consumer" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "functionId": "string",
    "queueName": "string",
    "batchSize": 0,
    "maxConcurrent": 0,
    "visibilityTimeoutSecs": 0,
    "maxRetries": 0,
    "autoAck": true,
    "enabled": true
  }'

hives_remove_native_queue_consumer

DELETE/v1/hives/projects/{project_id}/queues/{queue_id}/consumer

hives:writeTested with an API keyhives_remove_native_queue_consumer

Parameters

  • project_idpath · stringrequired
  • queue_idpath · stringrequired

Responses

  • 200Binding removed; messages and invocation logs retained
    Response fields
    • queueIdstringrequired
    • successbooleanrequired
  • 401Verified identity required
  • 403Hives write scope required
  • 404Owned queue not found
  • 409Attempt in flight
  • 503Persistence unavailable
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/consumer" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_consumers_native_queue

GET/v1/hives/projects/{project_id}/queues/{queue_id}/consumers

hives:readFailed with an API keyhives_consumers_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Responses

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/consumers" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_dead_letters_native_queue

GET/v1/hives/projects/{project_id}/queues/{queue_id}/dlq

hives:readFailed with an API keyhives_dead_letters_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Responses

  • 200Actual persisted queue result
    Response fields

    A JSON object.

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/dlq" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_purge_dlq_native_queue

DELETE/v1/hives/projects/{project_id}/queues/{queue_id}/dlq

hives:writeFailed with an API keyhives_purge_dlq_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Responses

  • 200Actual persisted queue result
    Response fields

    A JSON object.

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/dlq" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_delete_dlq_native_queue

DELETE/v1/hives/projects/{project_id}/queues/{queue_id}/dlq/{message_id}

hives:writeFailed with an API keyhives_delete_dlq_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

  • message_idpath · stringrequired

    Owned message

Responses

  • 200Actual persisted queue result
    Response fields

    A JSON object.

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/dlq/$MESSAGE_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_replay_native_queue

POST/v1/hives/projects/{project_id}/queues/{queue_id}/dlq/replay

hives:writeFailed with an API keyhives_replay_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Request body application/json

  • message_idstringrequired

Responses

  • 200Actual persisted queue result
    Response fields

    A JSON object.

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/dlq/replay" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": "string"
  }'

hives_dlq_stats_native_queue

GET/v1/hives/projects/{project_id}/queues/{queue_id}/dlq/stats

hives:readFailed with an API keyhives_dlq_stats_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Responses

  • 200Actual persisted queue result
    Response fields

    A JSON object.

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/dlq/stats" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Send one message with an explicit original funding key when required

POST/v1/hives/projects/{project_id}/queues/{queue_id}/messages

hives:writeAPI keys refusedIdempotency-Key optionalhives_send_native_queue

Funded standard sends require a persisted Idempotency-Key and return the original queue operation. Do not retry an unknown send with a new key. Legacy nonrequired and FIFO sends retain their message receipt; keyed FIFO is unsupported.

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

  • Idempotency-Keyheader · string

    Required in Genesis-required mode for standard queues. Printable ASCII1–128 bytes; preserve exactly. Unsupported for FIFO.

Request body application/json

  • attributesobject
  • bodyany
  • body_base64string | null
  • deduplication_idstring | null

    Required for FIFO: queue-scoped identity retained for 300 seconds, including after ACK.

  • message_group_idstring | null

    Required for FIFO: printable ASCII, 1–128 bytes. Omit for standard queues.

Responses

  • 200Original terminal queue operation; no repeated send
    Response fields
    • object"queue_send_operation"required
    • operation_idstringrequired

      pattern ^qop_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$

    • state"prepared" | "reserve_unknown" | "reserved" | "dispatch_unknown" | "dispatch_authorized" | "commit_unknown" | "settle_unknown" | "settled" | "denied" | "released"required
    • codestringrequired

      pattern ^[a-z_]{1,80}$

    • message_idstring | nullrequired

      pattern ^msg_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$

    • funding_source"sandbox_allowance" | nullrequired
    • reservation_idstring | nullrequired
    • native_meter"hives.queue_operations"required
    • quantity_basestring | nullrequired

      pattern ^[1-5]$

    • upper_bound_quantity_basestringrequired

      pattern ^[1-5]$

    • retry_sendfalserequired
  • 201Newly settled funded send, or original legacy message receipt
    Response fields

    Type: object | object

  • 202Original operation pending or unknown; use GET, never replay send
    Response fields
    • object"queue_send_operation"required
    • operation_idstringrequired

      pattern ^qop_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$

    • state"prepared" | "reserve_unknown" | "reserved" | "dispatch_unknown" | "dispatch_authorized" | "commit_unknown" | "settle_unknown" | "settled" | "denied" | "released"required
    • codestringrequired

      pattern ^[a-z_]{1,80}$

    • message_idstring | nullrequired

      pattern ^msg_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$

    • funding_source"sandbox_allowance" | nullrequired
    • reservation_idstring | nullrequired
    • native_meter"hives.queue_operations"required
    • quantity_basestring | nullrequired

      pattern ^[1-5]$

    • upper_bound_quantity_basestringrequired

      pattern ^[1-5]$

    • retry_sendfalserequired
  • 400Static invalid request
  • 401Verified identity required
  • 402Required funding denied; no message effect
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/messages" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

hives_ack_native_queue

POST/v1/hives/projects/{project_id}/queues/{queue_id}/messages/{message_id}/ack

hives:writeFailed with an API keyhives_ack_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

  • message_idpath · stringrequired

    Owned message

Request body application/json

  • receiptHandlestringrequired

Responses

  • 200Actual persisted queue result
    Response fields

    A JSON object.

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/messages/$MESSAGE_ID/ack" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "receiptHandle": "string"
  }'

hives_nack_native_queue

POST/v1/hives/projects/{project_id}/queues/{queue_id}/messages/{message_id}/nack

hives:writeFailed with an API keyhives_nack_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

  • message_idpath · stringrequired

    Owned message

Request body application/json

  • receiptHandlestringrequired

Responses

  • 200Actual persisted queue result
    Response fields

    A JSON object.

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/messages/$MESSAGE_ID/nack" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "receiptHandle": "string"
  }'

hives_receive_native_queue

POST/v1/hives/projects/{project_id}/queues/{queue_id}/messages/receive

hives:writeTested with an API keyhives_receive_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Request body application/json

  • maxMessagesinteger (int32)

    min 0

  • waitSecondsinteger (int32)

    min 0

Responses

  • 200Actual persisted queue result
    Response fields

    A JSON object.

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/messages/receive" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Read the original queue send operation without any queue effect

GET/v1/hives/projects/{project_id}/queues/{queue_id}/operations/{operation_id}

hives:readFailed with an API keyhives_get_operation_native_queue

Requires fresh native read authorization and original actor/binding. No send, receive, ACK, new reservation or automatic settlement replay.

Parameters

  • project_idpath · stringrequired
  • queue_idpath · stringrequired
  • operation_idpath · stringrequired

Responses

  • 200Original settled, denied or released operation
    Response fields
    • object"queue_send_operation"required
    • operation_idstringrequired

      pattern ^qop_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$

    • state"prepared" | "reserve_unknown" | "reserved" | "dispatch_unknown" | "dispatch_authorized" | "commit_unknown" | "settle_unknown" | "settled" | "denied" | "released"required
    • codestringrequired

      pattern ^[a-z_]{1,80}$

    • message_idstring | nullrequired

      pattern ^msg_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$

    • funding_source"sandbox_allowance" | nullrequired
    • reservation_idstring | nullrequired
    • native_meter"hives.queue_operations"required
    • quantity_basestring | nullrequired

      pattern ^[1-5]$

    • upper_bound_quantity_basestringrequired

      pattern ^[1-5]$

    • retry_sendfalserequired
  • 202Original operation remains pending or unknown
    Response fields
    • object"queue_send_operation"required
    • operation_idstringrequired

      pattern ^qop_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$

    • state"prepared" | "reserve_unknown" | "reserved" | "dispatch_unknown" | "dispatch_authorized" | "commit_unknown" | "settle_unknown" | "settled" | "denied" | "released"required
    • codestringrequired

      pattern ^[a-z_]{1,80}$

    • message_idstring | nullrequired

      pattern ^msg_[0-9a-f]{12}7[0-9a-f]{3}[89ab][0-9a-f]{15}$

    • funding_source"sandbox_allowance" | nullrequired
    • reservation_idstring | nullrequired
    • native_meter"hives.queue_operations"required
    • quantity_basestring | nullrequired

      pattern ^[1-5]$

    • upper_bound_quantity_basestringrequired

      pattern ^[1-5]$

    • retry_sendfalserequired
  • 404Missing or wrong owner
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/operations/$OPERATION_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_pause_native_queue

POST/v1/hives/projects/{project_id}/queues/{queue_id}/pause

hives:writeTested with an API keyhives_pause_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Responses

  • 200Actual persisted queue result
    Response fields
    • avgProcessingTimeMsnumber | null (double)
    • consumerCountinteger | null (int64)

      min 0

    • createdAtstringrequired
    • deadLetterQueueIdstring | null
    • delayedMessagesinteger (int64)required
    • deliveryAvailablebooleanrequired
    • idstringrequired
    • maxMessageSizeintegerrequired

      min 0

    • maxReceiveCountinteger (int32)required

      min 0

    • messageCountinteger (int64)required
    • messagesProcessinginteger (int64)required
    • namestringrequired
    • projectIdstringrequired
    • retainedMessagesinteger (int64)required
    • retainedPayloadBytesinteger (int64)required
    • retentionPeriodinteger (int32)required

      min 0

    • statusstringrequired
    • throughputPerSecondnumber | null (double)
    • typestringrequired
    • updatedAtstringrequired
    • visibilityTimeoutinteger (int32)required

      min 0

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/pause" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_purge_native_queue

POST/v1/hives/projects/{project_id}/queues/{queue_id}/purge

hives:writeTested with an API keyhives_purge_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Responses

  • 200Actual persisted queue result
    Response fields

    A JSON object.

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/purge" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_resume_native_queue

POST/v1/hives/projects/{project_id}/queues/{queue_id}/resume

hives:writeTested with an API keyhives_resume_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Responses

  • 200Actual persisted queue result
    Response fields
    • avgProcessingTimeMsnumber | null (double)
    • consumerCountinteger | null (int64)

      min 0

    • createdAtstringrequired
    • deadLetterQueueIdstring | null
    • delayedMessagesinteger (int64)required
    • deliveryAvailablebooleanrequired
    • idstringrequired
    • maxMessageSizeintegerrequired

      min 0

    • maxReceiveCountinteger (int32)required

      min 0

    • messageCountinteger (int64)required
    • messagesProcessinginteger (int64)required
    • namestringrequired
    • projectIdstringrequired
    • retainedMessagesinteger (int64)required
    • retainedPayloadBytesinteger (int64)required
    • retentionPeriodinteger (int32)required

      min 0

    • statusstringrequired
    • throughputPerSecondnumber | null (double)
    • typestringrequired
    • updatedAtstringrequired
    • visibilityTimeoutinteger (int32)required

      min 0

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/resume" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_stats_native_queue

GET/v1/hives/projects/{project_id}/queues/{queue_id}/stats

hives:readTested with an API keyhives_stats_native_queue

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • queue_idpath · stringrequired

    Owned Buzz queue

Responses

  • 200Actual persisted queue result
    Response fields
    • avgProcessingTimeMsnumber | null (double)
    • consumerCountinteger | null (int64)

      min 0

    • createdAtstringrequired
    • deadLetterQueueIdstring | null
    • delayedMessagesinteger (int64)required
    • deliveryAvailablebooleanrequired
    • idstringrequired
    • maxMessageSizeintegerrequired

      min 0

    • maxReceiveCountinteger (int32)required

      min 0

    • messageCountinteger (int64)required
    • messagesProcessinginteger (int64)required
    • namestringrequired
    • projectIdstringrequired
    • retainedMessagesinteger (int64)required
    • retainedPayloadBytesinteger (int64)required
    • retentionPeriodinteger (int32)required

      min 0

    • statusstringrequired
    • throughputPerSecondnumber | null (double)
    • typestringrequired
    • updatedAtstringrequired
    • visibilityTimeoutinteger (int32)required

      min 0

  • 400Static invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409State or receipt conflict
  • 429Stored queue capacity reached
  • 503Engine or measurement unavailable; no confirmed acknowledgement
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/queues/$QUEUE_ID/stats" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Remote

Create a debug session for attaching to a running instance

POST/v1/hives/projects/{project_id}/remote/debug

hives:writeFailed with an API keyhives_create_debug_session

Parameters

  • project_idpath · stringrequired

    Project ID

Request body application/json

  • protocolstring

    Debug adapter protocol (dap, chrome-devtools)

  • target_idstringrequired

    Target deployment or instance ID

Responses

  • 201Debug session created
    Response fields
    • debug_urlstringrequired
    • expires_atstringrequired
    • protocolstringrequired
    • session_idstringrequired
    • tokenstringrequired
  • 400Invalid request
  • 401Unauthorized
  • 404Target not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/remote/debug" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "string"
  }'

List active remote sessions for a project

GET/v1/hives/projects/{project_id}/remote/sessions

hives:readFailed with an API keyhives_list_remote_sessions

Parameters

  • project_idpath · stringrequired

    Project ID

  • session_typequery · string | null

    Filter by session type (ssh, terminal, sftp, debug)

  • target_idquery · string | null

    Filter by target ID

Responses

  • 200List of remote sessions
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/remote/sessions" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Close an active remote session

DELETE/v1/hives/projects/{project_id}/remote/sessions/{session_id}

hives:writehives_close_remote_session

Parameters

  • project_idpath · stringrequired

    Project ID

  • session_idpath · stringrequired

    Session ID

Responses

  • 200Session closed
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Session not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/remote/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Delete a file via SFTP

DELETE/v1/hives/projects/{project_id}/remote/sftp/{target_id}/delete

hives:writeFailed with an API keyhives_sftp_delete

Parameters

  • project_idpath · stringrequired

    Project ID

  • target_idpath · stringrequired

    Target deployment/instance ID

Request body application/json

  • pathstringrequired

    Target file or directory path

Responses

  • 200File deleted
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404File not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/remote/sftp/$TARGET_ID/delete" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "string"
  }'

List files via SFTP

GET/v1/hives/projects/{project_id}/remote/sftp/{target_id}/ls

hives:readhives_sftp_list

Parameters

  • project_idpath · stringrequired

    Project ID

  • target_idpath · stringrequired

    Target deployment/instance ID

  • pathquery · string

    Directory path to list

Responses

  • 200Directory listing
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Target not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/remote/sftp/$TARGET_ID/ls" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Read a file via SFTP (returns base64-encoded content)

GET/v1/hives/projects/{project_id}/remote/sftp/{target_id}/read

hives:readFailed with an API keyhives_sftp_read

Parameters

  • project_idpath · stringrequired

    Project ID

  • target_idpath · stringrequired

    Target deployment/instance ID

  • pathquery · string

    Directory path to list

Responses

  • 200File content
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404File not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/remote/sftp/$TARGET_ID/read" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Write a file via SFTP

POST/v1/hives/projects/{project_id}/remote/sftp/{target_id}/write

hives:writeFailed with an API keyhives_sftp_write

Parameters

  • project_idpath · stringrequired

    Project ID

  • target_idpath · stringrequired

    Target deployment/instance ID

Request body application/json

  • content_base64stringrequired

    Base64-encoded file content

  • pathstringrequired

    Target file path

Responses

  • 200File written
    Response fields

    A JSON object.

  • 401Unauthorized
  • 404Target not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/remote/sftp/$TARGET_ID/write" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "string",
    "content_base64": "string"
  }'

Create an SSH session for remote access

POST/v1/hives/projects/{project_id}/remote/ssh

hives:writeFailed with an API keyhives_create_ssh_session

Parameters

  • project_idpath · stringrequired

    Project ID

Request body application/json

  • public_keystringrequired

    SSH public key for authentication

  • target_idstringrequired

    Target deployment or instance ID

  • ttl_secsinteger (int64)

    Session TTL in seconds (default 3600) min 0

Responses

  • 201SSH session created
    Response fields
    • expires_atstringrequired
    • fingerprintstringrequired
    • hoststringrequired
    • portinteger (int32)required

      min 0

    • session_idstringrequired
    • usernamestringrequired
  • 400Invalid request
  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/remote/ssh" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "string",
    "public_key": "string"
  }'

Create a WebSocket terminal session

POST/v1/hives/projects/{project_id}/remote/terminal

hives:writeFailed with an API keyhives_create_terminal_session

Parameters

  • project_idpath · stringrequired

    Project ID

Request body application/json

  • colsinteger (int32)

    Terminal columns min 0

  • rowsinteger (int32)

    Terminal rows min 0

  • shellstring

    Shell to use (default: /bin/sh)

  • target_idstringrequired

    Target deployment or instance ID

Responses

  • 201Terminal session created
    Response fields
    • expires_atstringrequired
    • session_idstringrequired
    • tokenstringrequired
    • websocket_urlstringrequired
  • 400Invalid request
  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/remote/terminal" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "string"
  }'

Runtimes

Read compiled serving metadata after verified owned project lookup

GET/v1/hives/projects/{project_id}/runtimes

hives:readTested with an API keyhives_list_project_runtimes

Parameters

  • project_idpath · stringrequired

Responses

  • 200Implemented serving runtime catalog; not live capacity
    Response fields
    • runtimesobject[]required
    • runtimes[].[].artifactKindsstring[]required

      Accepted serving artifacts; optional library presence does not imply execution.

    • runtimes[].[].capabilityScopestringrequired

      This catalog is implementation metadata, not observed node availability.

    • runtimes[].[].compiledFeaturesstring[]required

      Actual Cargo feature flags, separately from serving admission.

    • runtimes[].[].featuresstring[]required
    • runtimes[].[].namestringrequired
    • runtimes[].[].runnersstring[]required
    • runtimes[].[].useCasesstring[]required
    • runtimes[].[].versionstringrequired

      Exact locked dependency version embedded by the Nectar build script.

    • runtimes[].[].wasiVersionsstring[]required

      WASI interfaces accepted by the real serving path.

  • 401Unauthorized
  • 404Project not found in the verified organization
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/runtimes" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_list_runtimes

GET/v1/hives/runtimes

hives:readTested with an API keyhives_list_runtimes

Responses

  • 200Implemented serving runtime catalog; not live capacity
    Response fields
    • runtimesobject[]required
    • runtimes[].[].artifactKindsstring[]required

      Accepted serving artifacts; optional library presence does not imply execution.

    • runtimes[].[].capabilityScopestringrequired

      This catalog is implementation metadata, not observed node availability.

    • runtimes[].[].compiledFeaturesstring[]required

      Actual Cargo feature flags, separately from serving admission.

    • runtimes[].[].featuresstring[]required
    • runtimes[].[].namestringrequired
    • runtimes[].[].runnersstring[]required
    • runtimes[].[].useCasesstring[]required
    • runtimes[].[].versionstringrequired

      Exact locked dependency version embedded by the Nectar build script.

    • runtimes[].[].wasiVersionsstring[]required

      WASI interfaces accepted by the real serving path.

  • 401Unauthorized
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/runtimes" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_get_runtime

GET/v1/hives/runtimes/{name}

hives:readTested with an API keyhives_get_runtime

Parameters

  • namepath · stringrequired

    Implemented serving runtime name

Responses

  • 200Serving runtime details
    Response fields
    • artifactKindsstring[]required

      Accepted serving artifacts; optional library presence does not imply execution.

    • capabilityScopestringrequired

      This catalog is implementation metadata, not observed node availability.

    • compiledFeaturesstring[]required

      Actual Cargo feature flags, separately from serving admission.

    • featuresstring[]required
    • namestringrequired
    • runnersstring[]required
    • useCasesstring[]required
    • versionstringrequired

      Exact locked dependency version embedded by the Nectar build script.

    • wasiVersionsstring[]required

      WASI interfaces accepted by the real serving path.

  • 401Unauthorized
  • 404Runtime not implemented
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/runtimes/$NAME" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_select_runtime

GET/v1/hives/runtimes/select

hives:readTested with an API keyhives_select_runtime

Parameters

  • wasiquery · stringrequired

    Serving WASI interface: preview1 (p1/wasi-preview1 aliases accepted).

  • runnerquery · stringrequired

    Serving runner: http.

  • artifactquery · stringrequired

    Serving artifact: core-module (core alias accepted).

Responses

  • 200Implemented serving selection; not deployment admission
    Response fields
    • artifactstringrequired
    • reasonstringrequired
    • runnerstringrequired
    • selectedstringrequired
    • wasistringrequired
  • 400Unsupported or invalid serving workload shape
  • 401Unauthorized
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/runtimes/select?wasi=$WASI&runner=$RUNNER&artifact=$ARTIFACT" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Secrets

List all secrets for a project (names and metadata only, not values)

GET/v1/hives/projects/{project_id}/secrets

hives:readTested with an API keyhives_list_secrets

The backend verifies the signed org owns the project and secret. Unknown, foreign-org or wrong-project resources return 404. Values remain encrypted in Genesis KMS; only explicit reveal returns plaintext.

Parameters

  • project_idpath · stringrequired

    Project ID

  • pagequery · integer (int32)

    Page number (1-indexed, up to 10000)

  • per_pagequery · integer (int32)

    Items per page

Responses

  • 200List of secrets
    Response fields
    • dataobject[]required

      Response data

    • data[].[].created_atstring (date-time)required

      Created timestamp

    • data[].[].descriptionstring | null

      Description

    • data[].[].namestringrequired

      Secret name

    • data[].[].updated_atstring (date-time)required

      Updated timestamp

    • data[].[].versioninteger (int32)required

      Current version min 0

    • paginationobjectrequired

      Pagination metadata

    • pagination.has_nextbooleanrequired

      Whether there is a next page

    • pagination.has_prevbooleanrequired

      Whether there is a previous page

    • pagination.pageinteger (int32)required

      Current page number min 0

    • pagination.per_pageinteger (int32)required

      Items per page min 0

    • pagination.totalinteger (int64)required

      Total number of items min 0

    • pagination.total_pagesinteger (int32)required

      Total number of pages min 0

  • 401Unauthorized
  • 403Missing the required hives read or write scope
  • 404Project not found
  • 500Internal server error
  • 503Customer encryption unavailable or legacy ciphertext requires protected migration
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/secrets" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Create a new secret

POST/v1/hives/projects/{project_id}/secrets

hives:writeTested with an API keyhives_create_secret

The backend verifies the signed org owns the project and secret. Unknown, foreign-org or wrong-project resources return 404. Values remain encrypted in Genesis KMS; only explicit reveal returns plaintext.

Parameters

  • project_idpath · stringrequired

    Project ID

Request body application/json

  • descriptionstring | null

    Description max length 500

  • namestringrequired

    Secret name min length 1 · max length 255 · pattern ^[A-Za-z][A-Za-z0-9_]*$

  • valuestringrequired

    Secret value, limited to 65,536 UTF-8 bytes by Genesis KMS min length 1 · max length 65536

Responses

  • 201Secret created
    Response fields
    • idstringrequired

      Persisted secret ID for metadata, update, delete and reveal routes

    • created_atstring (date-time)required

      Created timestamp

    • descriptionstring | null

      Description

    • namestringrequired

      Secret name

    • updated_atstring (date-time)required

      Updated timestamp

    • versioninteger (int32)required

      Current version min 0

  • 400Invalid request
  • 401Unauthorized
  • 403Missing the required hives read or write scope
  • 404Project not found
  • 409Secret already exists
  • 500Internal server error
  • 503Customer encryption unavailable or legacy ciphertext requires protected migration
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/secrets" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "value": "string"
  }'

Get a secret's metadata (not its value)

GET/v1/hives/projects/{project_id}/secrets/{secret_id}

hives:readTested with an API keyhives_get_secret

The backend verifies the signed org owns the project and secret. Unknown, foreign-org or wrong-project resources return 404. Values remain encrypted in Genesis KMS; only explicit reveal returns plaintext.

Parameters

  • project_idpath · stringrequired

    Project ID

  • secret_idpath · stringrequired

    Secret ID

Responses

  • 200Secret metadata
    Response fields
    • idstringrequired

      Persisted secret ID for metadata, update, delete and reveal routes

    • created_atstring (date-time)required

      Created timestamp

    • descriptionstring | null

      Description

    • namestringrequired

      Secret name

    • updated_atstring (date-time)required

      Updated timestamp

    • versioninteger (int32)required

      Current version min 0

  • 401Unauthorized
  • 403Missing the required hives read or write scope
  • 404Secret not found
  • 500Internal server error
  • 503Customer encryption unavailable or legacy ciphertext requires protected migration
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/secrets/$SECRET_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Update a secret's value (creates a new version)

PUT/v1/hives/projects/{project_id}/secrets/{secret_id}

hives:writeTested with an API keyhives_update_secret

The backend verifies the signed org owns the project and secret. Unknown, foreign-org or wrong-project resources return 404. Values remain encrypted in Genesis KMS; only explicit reveal returns plaintext.

Parameters

  • project_idpath · stringrequired

    Project ID

  • secret_idpath · stringrequired

    Secret ID

Request body application/json

  • valuestringrequired

    New secret value, limited to 65,536 UTF-8 bytes by Genesis KMS min length 1 · max length 65536

Responses

  • 200Secret updated
    Response fields
    • idstringrequired

      Persisted secret ID for metadata, update, delete and reveal routes

    • created_atstring (date-time)required

      Created timestamp

    • descriptionstring | null

      Description

    • namestringrequired

      Secret name

    • updated_atstring (date-time)required

      Updated timestamp

    • versioninteger (int32)required

      Current version min 0

  • 400Invalid request
  • 401Unauthorized
  • 403Missing the required hives read or write scope
  • 404Secret not found
  • 500Internal server error
  • 503Customer encryption unavailable or legacy ciphertext requires protected migration
  • 4xx 5xxThe error envelope.
curl -X PUT "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/secrets/$SECRET_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "string"
  }'

Delete a secret

DELETE/v1/hives/projects/{project_id}/secrets/{secret_id}

hives:writeTested with an API keyhives_delete_secret

The backend verifies the signed org owns the project and secret. Unknown, foreign-org or wrong-project resources return 404. Values remain encrypted in Genesis KMS; only explicit reveal returns plaintext.

Parameters

  • project_idpath · stringrequired

    Project ID

  • secret_idpath · stringrequired

    Secret ID

Responses

  • 200Secret deleted
    Response fields
    • idstringrequired

      Deleted resource ID

    • messagestringrequired

      Message

    • successbooleanrequired

      Success flag

  • 401Unauthorized
  • 403Missing the required hives read or write scope
  • 404Secret not found
  • 500Internal server error
  • 503Customer encryption unavailable or legacy ciphertext requires protected migration
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/secrets/$SECRET_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Explicitly reveal a secret value (sensitive output, audit logged)

GET/v1/hives/projects/{project_id}/secrets/{secret_id}/reveal

hives:readTested with an API keyhives_reveal_secret

The backend verifies the signed org owns the project and secret. Unknown, foreign-org or wrong-project resources return 404. Values remain encrypted in Genesis KMS; only explicit reveal returns plaintext.

Parameters

  • project_idpath · stringrequired

    Project ID

  • secret_idpath · stringrequired

    Secret ID

Responses

  • 200Secret value revealed
    Response fields
    • valuestringrequired
  • 401Unauthorized
  • 403Missing the required hives read or write scope
  • 404Secret not found
  • 500Decryption failed
  • 503Customer encryption unavailable or legacy ciphertext requires protected migration
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/secrets/$SECRET_ID/reveal" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Bulk create or update secrets

PUT/v1/hives/projects/{project_id}/secrets/bulk

hives:writeTested with an API keyhives_bulk_upsert_secrets

The backend verifies the signed org owns the project and secret. Unknown, foreign-org or wrong-project resources return 404. Values remain encrypted in Genesis KMS; only explicit reveal returns plaintext.

Parameters

  • project_idpath · stringrequired

    Project ID

Request body application/json

  • descriptionstring | null

    Description max length 500

  • namestringrequired

    Secret name min length 1 · max length 255 · pattern ^[A-Za-z][A-Za-z0-9_]*$

  • valuestringrequired

    Secret value, limited to 65,536 UTF-8 bytes by Genesis KMS min length 1 · max length 65536

Responses

  • 200Secrets created/updated
    Response fields
    • successbooleanrequired
    • secretsobject[]required
    • secrets[].[].idstringrequired

      Persisted secret ID for metadata, update, delete and reveal routes

    • secrets[].[].created_atstring (date-time)required

      Created timestamp

    • secrets[].[].descriptionstring | null

      Description

    • secrets[].[].namestringrequired

      Secret name

    • secrets[].[].updated_atstring (date-time)required

      Updated timestamp

    • secrets[].[].versioninteger (int32)required

      Current version min 0

  • 400Invalid request
  • 401Unauthorized
  • 403Missing the required hives read or write scope
  • 404Project not found
  • 500Internal server error
  • 503Customer encryption unavailable or legacy ciphertext requires protected migration
  • 4xx 5xxThe error envelope.
curl -X PUT "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/secrets/bulk" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[]'

Settings

hives_get_project_settings

GET/v1/hives/projects/{project_id}/settings

hives:readTested with an API keyhives_get_project_settings

Parameters

  • project_idpath · stringrequired

    Owned project ID

Responses

  • 200Stored and effective project settings
    Response fields
    • autoDeployEnabledbooleanrequired
    • buildCommandstring | null
    • defaultRegionstringrequired
    • installCommandstring | null
    • outputDirectorystring | null
    • previewDeploymentsEnabledbooleanrequired
    • capabilitiesobjectrequired
    • capabilities.autoDeployobjectrequired
    • capabilities.autoDeploy.availablebooleanrequired
    • capabilities.autoDeploy.reasonCodestringrequired
    • capabilities.buildCommandsobjectrequired
    • capabilities.buildCommands.availablebooleanrequired
    • capabilities.buildCommands.reasonCodestringrequired
    • capabilities.previewDeploymentsobjectrequired
    • capabilities.previewDeployments.availablebooleanrequired
    • capabilities.previewDeployments.reasonCodestringrequired
    • effectiveobjectrequired
    • effective.autoDeployEnabledbooleanrequired
    • effective.defaultRegionstringrequired

      The only supported deployment target, not a guarantee of live capacity.

    • effective.previewDeploymentsEnabledbooleanrequired
  • 401Unauthorized
  • 403Read scope required
  • 404Project not found
  • 500Settings unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/settings" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_update_project_settings

PATCH/v1/hives/projects/{project_id}/settings

hives:writeTested with an API keyhives_update_project_settings

Parameters

  • project_idpath · stringrequired

    Owned project ID

Request body application/json

  • autoDeployEnabledboolean | null
  • buildCommandstring | null

    Blank clears a stored command. Source-build commands are not operational in Genesis.

  • defaultRegionstring | null
  • installCommandstring | null
  • outputDirectorystring | null
  • previewDeploymentsEnabledboolean | null

Responses

  • 200Persisted stored settings and actual capabilities
    Response fields
    • autoDeployEnabledbooleanrequired
    • buildCommandstring | null
    • defaultRegionstringrequired
    • installCommandstring | null
    • outputDirectorystring | null
    • previewDeploymentsEnabledbooleanrequired
    • capabilitiesobjectrequired
    • capabilities.autoDeployobjectrequired
    • capabilities.autoDeploy.availablebooleanrequired
    • capabilities.autoDeploy.reasonCodestringrequired
    • capabilities.buildCommandsobjectrequired
    • capabilities.buildCommands.availablebooleanrequired
    • capabilities.buildCommands.reasonCodestringrequired
    • capabilities.previewDeploymentsobjectrequired
    • capabilities.previewDeployments.availablebooleanrequired
    • capabilities.previewDeployments.reasonCodestringrequired
    • effectiveobjectrequired
    • effective.autoDeployEnabledbooleanrequired
    • effective.defaultRegionstringrequired

      The only supported deployment target, not a guarantee of live capacity.

    • effective.previewDeploymentsEnabledbooleanrequired
  • 400Invalid region or bounded settings
  • 401Unauthorized
  • 403Write scope required
  • 404Project not found
  • 409Stored settings owner conflict
  • 503Requested Git or source-build engine is not connected
  • 4xx 5xxThe error envelope.
curl -X PATCH "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/settings" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Storage

List all storage buckets for a project

GET/v1/hives/projects/{project_id}/storage/buckets

hives:readTested with an API keyhives_list_buckets

Parameters

  • project_idpath · stringrequired

    Project ID

  • pagequery · integer (int32)

    Page number (1-indexed)

  • per_pagequery · integer (int32)

    Items per page

Responses

  • 200List of buckets
    Response fields
    • dataobject[]required
    • data[].[].idstringrequired
    • data[].[].tenant_idstringrequired
    • data[].[].project_idstringrequired
    • data[].[].namestringrequired
    • data[].[].regionstringrequired
    • data[].[].visibilitystringrequired
    • data[].[].statusstringrequired
    • data[].[].created_atstringrequired
    • data[].[].object_countinteger | nullrequired

      min 0

    • data[].[].size_bytesinteger | nullrequired

      min 0

    • data[].[].statistics_scope"unmeasured_provider_inventory" | "retained_legacy_metadata"required
    • data[].[].provider_bindingobject | nullrequired
    • data[].[].provider_binding.provider"gcs"required
    • data[].[].provider_binding.regionstringrequired
    • data[].[].provider_binding.statestringrequired
    • data[].[].provider_binding.requires_reconciliationbooleanrequired
    • data[].[].operation_statestring | nullrequired
    • paginationobjectrequired
    • pagination.pageintegerrequired

      min 0

    • pagination.per_pageintegerrequired

      min 0

    • pagination.totalintegerrequired

      min 0

    • pagination.total_pagesintegerrequired

      min 0

    • pagination.has_nextbooleanrequired
    • pagination.has_prevbooleanrequired
  • 401Unauthorized
  • 404Project not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Create a new storage bucket

POST/v1/hives/projects/{project_id}/storage/buckets

hives:writeFailed with an API keyhives_create_bucket

Parameters

  • project_idpath · stringrequired

    Project ID

Request body application/json

  • cors_rulesobject[]
  • cors_rules[].[].allowed_originsstring[]required
  • cors_rules[].[].allowed_methodsstring[]required
  • cors_rules[].[].allowed_headers["*"]required
  • cors_rules[].[].exposed_headersstring[]required
  • cors_rules[].[].max_age_secsintegerrequired

    min 0

  • namestringrequired

    Bucket name

  • region"us-central1"

    default "us-central1"

  • visibility"private" | "publicread"

    default "private"

Responses

  • 201Bucket created and access policy confirmed
    Response fields
    • idstringrequired
    • tenant_idstringrequired
    • project_idstringrequired
    • namestringrequired
    • regionstringrequired
    • visibilitystringrequired
    • statusstringrequired
    • created_atstringrequired
    • object_countinteger | nullrequired

      min 0

    • size_bytesinteger | nullrequired

      min 0

    • statistics_scope"unmeasured_provider_inventory" | "retained_legacy_metadata"required
    • provider_bindingobject | nullrequired
    • provider_binding.provider"gcs"required
    • provider_binding.regionstringrequired
    • provider_binding.statestringrequired
    • provider_binding.requires_reconciliationbooleanrequired
    • operation_statestring | nullrequired
  • 202Durable pending provider outcome; explicit readback/reconciliation required
    Response fields
    • idstringrequired
    • tenant_idstringrequired
    • project_idstringrequired
    • namestringrequired
    • regionstringrequired
    • visibilitystringrequired
    • statusstringrequired
    • created_atstringrequired
    • object_countinteger | nullrequired

      min 0

    • size_bytesinteger | nullrequired

      min 0

    • statistics_scope"unmeasured_provider_inventory" | "retained_legacy_metadata"required
    • provider_bindingobject | nullrequired
    • provider_binding.provider"gcs"required
    • provider_binding.regionstringrequired
    • provider_binding.statestringrequired
    • provider_binding.requires_reconciliationbooleanrequired
    • operation_statestring | nullrequired
  • 400Invalid request
  • 401Unauthorized
  • 404Project not found
  • 409Bucket already exists
  • 500Internal server error
  • 503Object storage provider is unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'

Get a specific bucket

GET/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}

hives:readhives_get_bucket

Parameters

  • project_idpath · stringrequired

    Project ID

  • bucket_idpath · stringrequired

    Bucket ID

Responses

  • 200Bucket details
    Response fields
    • idstringrequired
    • tenant_idstringrequired
    • project_idstringrequired
    • namestringrequired
    • regionstringrequired
    • visibilitystringrequired
    • statusstringrequired
    • created_atstringrequired
    • object_countinteger | nullrequired

      min 0

    • size_bytesinteger | nullrequired

      min 0

    • statistics_scope"unmeasured_provider_inventory" | "retained_legacy_metadata"required
    • provider_bindingobject | nullrequired
    • provider_binding.provider"gcs"required
    • provider_binding.regionstringrequired
    • provider_binding.statestringrequired
    • provider_binding.requires_reconciliationbooleanrequired
    • operation_statestring | nullrequired
  • 401Unauthorized
  • 404Bucket not found
  • 500Internal server error
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Delete a storage bucket

DELETE/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}

hives:writehives_delete_bucket

Parameters

  • project_idpath · stringrequired

    Project ID

  • bucket_idpath · stringrequired

    Bucket ID

Responses

  • 200Bucket deleted
    Response fields
    • idstringrequired

      Deleted resource ID

    • messagestringrequired

      Message

    • successbooleanrequired

      Success flag

  • 400Bucket not empty
  • 401Unauthorized
  • 404Bucket not found
  • 500Internal server error
  • 503Object storage provider is unavailable
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Get CORS rules for a bucket

GET/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}/cors

hives:readhives_get_cors_config

Parameters

  • project_idpath · stringrequired

    Project ID

  • bucket_idpath · stringrequired

    Bucket ID

Responses

  • 200CORS configuration
    Response fields
    • allowed_originsstring[]required
    • allowed_methodsstring[]required
    • allowed_headers["*"]required
    • exposed_headersstring[]required
    • max_age_secsintegerrequired

      min 0

  • 401Unauthorized
  • 404Bucket not found
  • 500Internal server error
  • 503Object storage provider is unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID/cors" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Set CORS rules for a bucket

PUT/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}/cors

hives:writehives_set_cors_config

Parameters

  • project_idpath · stringrequired

    Project ID

  • bucket_idpath · stringrequired

    Bucket ID

Request body application/json

  • rulesobject[]required
  • rules[].[].allowed_originsstring[]required
  • rules[].[].allowed_methodsstring[]required
  • rules[].[].allowed_headers["*"]required
  • rules[].[].exposed_headersstring[]required
  • rules[].[].max_age_secsintegerrequired

    min 0

Responses

  • 200CORS configuration updated
    Response fields
    • allowed_originsstring[]required
    • allowed_methodsstring[]required
    • allowed_headers["*"]required
    • exposed_headersstring[]required
    • max_age_secsintegerrequired

      min 0

  • 401Unauthorized
  • 404Bucket not found
  • 422Validation error
  • 500Internal server error
  • 503Object storage provider is unavailable
  • 4xx 5xxThe error envelope.
curl -X PUT "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID/cors" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rules": []
  }'

List objects in a bucket

GET/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}/objects

hives:readhives_list_objects

Parameters

  • project_idpath · stringrequired

    Project ID

  • bucket_idpath · stringrequired

    Bucket ID

  • prefixquery · string | null

    Prefix filter

  • delimiterquery · string | null

    Delimiter for hierarchical listing

  • continuation_tokenquery · string | null

    Continuation token for pagination

  • max_keysquery · integer (int32)

    Maximum keys to return

Responses

  • 200Provider object list; content_type and metadata may be null when not returned by listing; total is unknown
    Response fields
    • objectsobject[]required
    • objects[].[].keystringrequired
    • objects[].[].bucket_idstringrequired
    • objects[].[].size_bytesintegerrequired

      min 0

    • objects[].[].etagstringrequired
    • objects[].[].generationstringrequired
    • objects[].[].content_typestring | nullrequired
    • objects[].[].last_modifiedstringrequired
    • objects[].[].metadataobject | nullrequired
    • objects[].[].metadata_scope"provider_list_metadata"required
    • common_prefixesstring[]required
    • is_truncatedbooleanrequired
    • next_continuation_tokenstring | nullrequired
    • totalnullrequired
  • 401Unauthorized
  • 404Bucket not found
  • 500Internal server error
  • 503Object storage provider is unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID/objects" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_upload_object_by_key

PUT/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}/objects

hives:writehives_upload_object_by_key

Request bodies sent through https://os.one.ml/api are limited to 2 MiB.

Parameters

  • project_idpath · stringrequired
  • bucket_idpath · stringrequired
  • key_base64urlquery · stringrequired

    Unpadded base64url UTF-8 key, 1..1366 characters and <=1024 decoded bytes.

Request body application/octet-stream

Type: string

Responses

  • 200Actual provider upload metadata
    Response fields
    • keystringrequired
    • bucket_idstringrequired
    • size_bytesintegerrequired

      min 0 · max 10485760

    • etagstringrequired
    • generationstringrequired
    • content_typestring | nullrequired
  • 400Invalid encoded key
  • 404Owned bucket not found
  • 409Operation pending or generation changed
  • 413Object exceeds 10 MiB
  • 503Provider outcome unavailable
  • 4xx 5xxThe error envelope.
curl -X PUT "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID/objects?key_base64url=$KEY_BASE64URL" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @body.bin

hives_delete_object_by_key

DELETE/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}/objects

hives:writehives_delete_object_by_key

Parameters

  • project_idpath · stringrequired
  • bucket_idpath · stringrequired
  • key_base64urlquery · stringrequired

    Unpadded base64url UTF-8 key, 1..1366 characters and <=1024 decoded bytes.

Responses

  • 200Exact empty acknowledgement
  • 204Empty compatible acknowledgement
  • 400Invalid encoded key
  • 404Owned bucket not found
  • 409Operation pending or generation changed
  • 503Provider outcome unavailable
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID/objects?key_base64url=$KEY_BASE64URL" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Upload an object to a bucket via a server-side proxy.

PUT/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}/objects/{key}

hives:writehives_upload_object

Accepts the raw request body and streams it to the S3-compatible backend. For large uploads, clients should prefer presigned URLs via POST .../presigned to avoid routing traffic through the API server.

Request bodies sent through https://os.one.ml/api are limited to 2 MiB.

Parameters

  • project_idpath · stringrequired

    Project ID

  • bucket_idpath · stringrequired

    Bucket ID

  • keypath · stringrequired

    Object key

Request body application/octet-stream

Type: string

Responses

  • 200Object uploaded
    Response fields
    • keystringrequired
    • bucket_idstringrequired
    • size_bytesintegerrequired

      min 0 · max 10485760

    • etagstringrequired
    • generationstringrequired
    • content_typestring | nullrequired
  • 401Unauthorized
  • 404Bucket not found
  • 413Payload too large
  • 500Internal server error
  • 503Object storage provider is unavailable
  • 4xx 5xxThe error envelope.
curl -X PUT "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID/objects/$KEY" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @body.bin

Delete an object from a bucket

DELETE/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}/objects/{key}

hives:writehives_delete_object

Parameters

  • project_idpath · stringrequired

    Project ID

  • bucket_idpath · stringrequired

    Bucket ID

  • keypath · stringrequired

    Object key

Responses

  • 200Exact empty acknowledgement
  • 204Empty compatible acknowledgement
  • 401Unauthorized
  • 404Object not found
  • 500Internal server error
  • 503Object storage provider is unavailable
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID/objects/$KEY" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_download_object_by_key

GET/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}/objects/download

hives:readhives_download_object_by_key

Parameters

  • project_idpath · stringrequired
  • bucket_idpath · stringrequired
  • key_base64urlquery · stringrequired

    Unpadded base64url UTF-8 key, 1..1366 characters and <=1024 decoded bytes.

Responses

  • 200Actual raw stored bytes with no-store attachment; at most 10 MiB
    Response fields

    Type: string

  • 400Invalid encoded key
  • 404Owned object not found
  • 409Bucket operation pending
  • 413Object exceeds 10 MiB
  • 503Provider unavailable
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID/objects/download?key_base64url=$KEY_BASE64URL" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Generate a presigned URL for object access

POST/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}/presigned

hives:writehives_generate_presigned_url

Parameters

  • project_idpath · stringrequired

    Project ID

  • bucket_idpath · stringrequired

    Bucket ID

Request body application/json

  • content_lengthinteger | null

    min 0 · max 10485760

  • content_typestring | null

    Content type (for PUT requests)

  • expires_in_secsinteger (int64)

    URL expiration in seconds (60-604800) min 60 · max 900

  • keystringrequired

    Object key

  • method"GET" | "PUT"

    default "GET"

Responses

  • 200Presigned URL generated
    Response fields
    • expires_atstring (date-time)required

      Expiration timestamp

    • methodstringrequired

      Method

    • required_headersobject

      Required headers (for PUT requests)

    • urlstringrequired

      Presigned URL

  • 400Invalid request
  • 401Unauthorized
  • 404Bucket not found
  • 500Internal server error
  • 503Object storage provider is unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID/presigned" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "string"
  }'

Explicit recovery observes provider generations. It never replays an unknown

POST/v1/hives/projects/{project_id}/storage/buckets/{bucket_id}/reconcile

hives:writehives_reconcile

Parameters

  • project_idpath · stringrequired
  • bucket_idpath · stringrequired

Responses

  • 200Observed reconciliation outcome, with actual bucket metadata
    Response fields
    • outcomestringrequired
    • bucketobjectrequired

      Actual Cells005 BucketView JSON. Bound inventory counters are null; legacy counts are recorded metadata. Pending provider state is not completed creation.

    • bucket.idstringrequired
    • bucket.tenant_idstringrequired
    • bucket.project_idstringrequired
    • bucket.namestringrequired
    • bucket.regionstringrequired
    • bucket.visibilitystringrequired
    • bucket.statusstringrequired
    • bucket.created_atstringrequired
    • bucket.object_countinteger | nullrequired

      min 0

    • bucket.size_bytesinteger | nullrequired

      min 0

    • bucket.statistics_scope"unmeasured_provider_inventory" | "retained_legacy_metadata"required
    • bucket.provider_bindingobject | nullrequired
    • bucket.provider_binding.provider"gcs"required
    • bucket.provider_binding.regionstringrequired
    • bucket.provider_binding.statestringrequired
    • bucket.provider_binding.requires_reconciliationbooleanrequired
    • bucket.operation_statestring | nullrequired
  • 404Owned bucket not found
  • 409Provider outcome remains uncertain
  • 503Provider unavailable
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/storage/buckets/$BUCKET_ID/reconcile" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Topics

hives_list_native_topic

GET/v1/hives/projects/{project_id}/topics

hives:readTested with an API keyhives_list_native_topic

Parameters

  • project_idpath · stringrequired

    Owned Hives project

Responses

  • 200Persisted owned pub/sub result
    Response fields

    A JSON object.

  • 400Invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409Retained state conflict
  • 429Stored queue or topic capacity reached
  • 503Persistence unavailable or commit not confirmed
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/topics" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_create_native_topic

POST/v1/hives/projects/{project_id}/topics

hives:writeTested with an API keyhives_create_native_topic

Parameters

  • project_idpath · stringrequired

    Owned Hives project

Request body application/json

  • namestringrequired

Responses

  • 201Persisted owned pub/sub result
    Response fields
    • createdAtstring (date-time)required
    • idstringrequired
    • namestringrequired
    • projectIdstringrequired
  • 400Invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409Retained state conflict
  • 429Stored queue or topic capacity reached
  • 503Persistence unavailable or commit not confirmed
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/topics" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string"
  }'

hives_inspect_native_topic

GET/v1/hives/projects/{project_id}/topics/{topic_id}

hives:readTested with an API keyhives_inspect_native_topic

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • topic_idpath · stringrequired

    Owned Buzz topic

Responses

  • 200Persisted owned pub/sub result
    Response fields
    • createdAtstring (date-time)required
    • idstringrequired
    • namestringrequired
    • projectIdstringrequired
  • 400Invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409Retained state conflict
  • 429Stored queue or topic capacity reached
  • 503Persistence unavailable or commit not confirmed
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/topics/$TOPIC_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_delete_native_topic

DELETE/v1/hives/projects/{project_id}/topics/{topic_id}

hives:writeTested with an API keyhives_delete_native_topic

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • topic_idpath · stringrequired

    Owned Buzz topic

Responses

  • 200Persisted owned pub/sub result
    Response fields

    A JSON object.

  • 400Invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409Retained state conflict
  • 429Stored queue or topic capacity reached
  • 503Persistence unavailable or commit not confirmed
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/topics/$TOPIC_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_publish_native_topic

POST/v1/hives/projects/{project_id}/topics/{topic_id}/messages

hives:writeFailed with an API keyhives_publish_native_topic

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • topic_idpath · stringrequired

    Owned Buzz topic

Request body application/json

  • attributesobject
  • bodyany
  • body_base64string | null

Responses

  • 201Persisted owned pub/sub result
    Response fields
    • deliveriesobject[]required
    • deliveries[].[].message_idstringrequired
    • deliveries[].[].queue_idstringrequired
    • deliveries[].[].subscription_idstringrequired
    • publication_idstringrequired
  • 400Invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409Retained state conflict
  • 429Stored queue or topic capacity reached
  • 503Persistence unavailable or commit not confirmed
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/topics/$TOPIC_ID/messages" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

hives_subscriptions_native_topic

GET/v1/hives/projects/{project_id}/topics/{topic_id}/subscriptions

hives:readTested with an API keyhives_subscriptions_native_topic

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • topic_idpath · stringrequired

    Owned Buzz topic

Responses

  • 200Persisted owned pub/sub result
    Response fields

    A JSON object.

  • 400Invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409Retained state conflict
  • 429Stored queue or topic capacity reached
  • 503Persistence unavailable or commit not confirmed
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/topics/$TOPIC_ID/subscriptions" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

hives_subscribe_native_topic

POST/v1/hives/projects/{project_id}/topics/{topic_id}/subscriptions

hives:writeTested with an API keyhives_subscribe_native_topic

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • topic_idpath · stringrequired

    Owned Buzz topic

Request body application/json

  • queueIdstringrequired

Responses

  • 201Persisted owned pub/sub result
    Response fields
    • createdAtstring (date-time)required
    • idstringrequired
    • projectIdstringrequired
    • queueIdstringrequired
    • topicIdstringrequired
  • 400Invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409Retained state conflict
  • 429Stored queue or topic capacity reached
  • 503Persistence unavailable or commit not confirmed
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/topics/$TOPIC_ID/subscriptions" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queueId": "string"
  }'

hives_unsubscribe_native_topic

DELETE/v1/hives/projects/{project_id}/topics/{topic_id}/subscriptions/{subscription_id}

hives:writeTested with an API keyhives_unsubscribe_native_topic

Parameters

  • project_idpath · stringrequired

    Owned Hives project

  • topic_idpath · stringrequired

    Owned Buzz topic

  • subscription_idpath · stringrequired

    Subscription of the owned topic

Responses

  • 200Persisted owned pub/sub result
    Response fields

    A JSON object.

  • 400Invalid request
  • 401Verified identity required
  • 403Hives scope required
  • 404Owned resource not found
  • 409Retained state conflict
  • 429Stored queue or topic capacity reached
  • 503Persistence unavailable or commit not confirmed
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/topics/$TOPIC_ID/subscriptions/$SUBSCRIPTION_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Volumes

List persisted local volumes

GET/v1/hives/projects/{project_id}/volumes

hives:readTested with an API keyhives_list_volumes

Backend enforces organization and project ownership. Mutation acknowledgements may be uncertain; read persisted state before another write. No automatic replay.

Parameters

  • project_idpath · stringrequired

    Project owned by the verified organization

  • pagequery · integer
  • per_pagequery · integer

Responses

  • 200Actual persisted volume result
    Response fields
    • volumesobject[]required
    • volumes[].[].idstring (uuid)required
    • volumes[].[].project_idstringrequired

      min length 1 · max length 128 · pattern ^[A-Za-z0-9_-]+$

    • volumes[].[].namestringrequired

      min length 1 · max length 64

    • volumes[].[].size_gibnumberrequired

      min 0.03125 · max 1

    • volumes[].[].backing_bytesintegerrequired

      min 33554432 · max 1073741824

    • volumes[].[].capacity_bytesinteger | nullrequired

      min 0

    • volumes[].[].used_bytesinteger | nullrequired

      min 0

    • volumes[].[].used_gibnumber | nullrequired

      min 0

    • volumes[].[].storage_class"local"required
    • volumes[].[].access_mode"read_write_once"required
    • volumes[].[].state"creating" | "available" | "attaching" | "attached" | "detaching" | "deleting" | "failed"required
    • volumes[].[].operation_pendingbooleanrequired
    • volumes[].[].generationintegerrequired

      min 1

    • volumes[].[].mount_pathstring | nullrequired

      max length 128

    • volumes[].[].attached_tostring | nullrequired

      max length 128

    • volumes[].[].read_onlyboolean | nullrequired
    • volumes[].[].created_atstring (date-time)required
    • volumes[].[].updated_atstring (date-time)required
    • paginationobjectrequired
    • pagination.pageintegerrequired

      min 1

    • pagination.per_pageintegerrequired

      min 1

    • pagination.totalintegerrequired

      min 0

    • pagination.total_pagesintegerrequired

      min 0

  • 400Invalid bounded request
  • 401Verified identity required
  • 403Required Hives scope missing
  • 404Resource not found in authenticated organization and project
  • 409Persisted lifecycle conflict
  • 503Storage acknowledgement unavailable; read persisted state
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/volumes" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Create bounded local persistent storage

POST/v1/hives/projects/{project_id}/volumes

hives:writeTested with an API keyhives_create_volume

Backend enforces organization and project ownership. Mutation acknowledgements may be uncertain; read persisted state before another write. No automatic replay.

Parameters

  • project_idpath · stringrequired

    Project owned by the verified organization

Request body application/json

  • namestringrequired

    min length 1 · max length 64

  • size_mibinteger

    min 32 · max 1024

  • size_gib1
  • storage_class"local"

    default "local"

  • access_mode"read_write_once"

    default "read_write_once"

Responses

  • 201Actual persisted volume result
    Response fields
    • idstring (uuid)required
    • project_idstringrequired

      min length 1 · max length 128 · pattern ^[A-Za-z0-9_-]+$

    • namestringrequired

      min length 1 · max length 64

    • size_gibnumberrequired

      min 0.03125 · max 1

    • backing_bytesintegerrequired

      min 33554432 · max 1073741824

    • capacity_bytesinteger | nullrequired

      min 0

    • used_bytesinteger | nullrequired

      min 0

    • used_gibnumber | nullrequired

      min 0

    • storage_class"local"required
    • access_mode"read_write_once"required
    • state"creating" | "available" | "attaching" | "attached" | "detaching" | "deleting" | "failed"required
    • operation_pendingbooleanrequired
    • generationintegerrequired

      min 1

    • mount_pathstring | nullrequired

      max length 128

    • attached_tostring | nullrequired

      max length 128

    • read_onlyboolean | nullrequired
    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • 400Invalid bounded request
  • 401Verified identity required
  • 403Required Hives scope missing
  • 404Resource not found in authenticated organization and project
  • 409Persisted lifecycle conflict
  • 503Storage acknowledgement unavailable; read persisted state
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/volumes" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '"string"'

Read persisted volume state and measured usage

GET/v1/hives/projects/{project_id}/volumes/{volume_id}

hives:readTested with an API keyhives_get_volume

Backend enforces organization and project ownership. Mutation acknowledgements may be uncertain; read persisted state before another write. No automatic replay.

Parameters

  • project_idpath · stringrequired

    Project owned by the verified organization

  • volume_idpath · string (uuid)required

    Volume owned by this project

Responses

  • 200Actual persisted volume result
    Response fields
    • idstring (uuid)required
    • project_idstringrequired

      min length 1 · max length 128 · pattern ^[A-Za-z0-9_-]+$

    • namestringrequired

      min length 1 · max length 64

    • size_gibnumberrequired

      min 0.03125 · max 1

    • backing_bytesintegerrequired

      min 33554432 · max 1073741824

    • capacity_bytesinteger | nullrequired

      min 0

    • used_bytesinteger | nullrequired

      min 0

    • used_gibnumber | nullrequired

      min 0

    • storage_class"local"required
    • access_mode"read_write_once"required
    • state"creating" | "available" | "attaching" | "attached" | "detaching" | "deleting" | "failed"required
    • operation_pendingbooleanrequired
    • generationintegerrequired

      min 1

    • mount_pathstring | nullrequired

      max length 128

    • attached_tostring | nullrequired

      max length 128

    • read_onlyboolean | nullrequired
    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • 400Invalid bounded request
  • 401Verified identity required
  • 403Required Hives scope missing
  • 404Resource not found in authenticated organization and project
  • 409Persisted lifecycle conflict
  • 503Storage acknowledgement unavailable; read persisted state
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/volumes/$VOLUME_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Delete a detached volume and its data

DELETE/v1/hives/projects/{project_id}/volumes/{volume_id}

hives:writeTested with an API keyhives_delete_volume

Backend enforces organization and project ownership. Mutation acknowledgements may be uncertain; read persisted state before another write. No automatic replay.

Parameters

  • project_idpath · stringrequired

    Project owned by the verified organization

  • volume_idpath · string (uuid)required

    Volume owned by this project

Responses

  • 200Actual persisted volume result
    Response fields
    • successtruerequired
    • idstring (uuid)required
    • messagestringrequired

      max length 256

  • 400Invalid bounded request
  • 401Verified identity required
  • 403Required Hives scope missing
  • 404Resource not found in authenticated organization and project
  • 409Persisted lifecycle conflict
  • 503Storage acknowledgement unavailable; read persisted state
  • 4xx 5xxThe error envelope.
curl -X DELETE "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/volumes/$VOLUME_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Attach or reconnect the exact existing attachment

POST/v1/hives/projects/{project_id}/volumes/{volume_id}/mount

hives:writehives_mount_volume

Backend enforces organization and project ownership. Mutation acknowledgements may be uncertain; read persisted state before another write. No automatic replay.

Parameters

  • project_idpath · stringrequired

    Project owned by the verified organization

  • volume_idpath · string (uuid)required

    Volume owned by this project

Request body application/json

  • target_idstringrequired

    min length 1 · max length 128 · pattern ^[A-Za-z0-9_-]+$

  • mount_pathstringrequired

    max length 128 · pattern ^/[A-Za-z0-9_-]+(/[A-Za-z0-9_-]+)*$

  • read_onlybooleanrequired

Responses

  • 200Actual persisted volume result
    Response fields
    • idstring (uuid)required
    • project_idstringrequired

      min length 1 · max length 128 · pattern ^[A-Za-z0-9_-]+$

    • namestringrequired

      min length 1 · max length 64

    • size_gibnumberrequired

      min 0.03125 · max 1

    • backing_bytesintegerrequired

      min 33554432 · max 1073741824

    • capacity_bytesinteger | nullrequired

      min 0

    • used_bytesinteger | nullrequired

      min 0

    • used_gibnumber | nullrequired

      min 0

    • storage_class"local"required
    • access_mode"read_write_once"required
    • state"creating" | "available" | "attaching" | "attached" | "detaching" | "deleting" | "failed"required
    • operation_pendingbooleanrequired
    • generationintegerrequired

      min 1

    • mount_pathstring | nullrequired

      max length 128

    • attached_tostring | nullrequired

      max length 128

    • read_onlyboolean | nullrequired
    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • 400Invalid bounded request
  • 401Verified identity required
  • 403Required Hives scope missing
  • 404Resource not found in authenticated organization and project
  • 409Persisted lifecycle conflict
  • 503Storage acknowledgement unavailable; read persisted state
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/volumes/$VOLUME_ID/mount" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "string",
    "mount_path": "string",
    "read_only": true
  }'

Detach a volume without a request body

POST/v1/hives/projects/{project_id}/volumes/{volume_id}/unmount

hives:writeFailed with an API keyhives_unmount_volume

Backend enforces organization and project ownership. Mutation acknowledgements may be uncertain; read persisted state before another write. No automatic replay.

Parameters

  • project_idpath · stringrequired

    Project owned by the verified organization

  • volume_idpath · string (uuid)required

    Volume owned by this project

Responses

  • 200Actual persisted volume result
    Response fields
    • idstring (uuid)required
    • project_idstringrequired

      min length 1 · max length 128 · pattern ^[A-Za-z0-9_-]+$

    • namestringrequired

      min length 1 · max length 64

    • size_gibnumberrequired

      min 0.03125 · max 1

    • backing_bytesintegerrequired

      min 33554432 · max 1073741824

    • capacity_bytesinteger | nullrequired

      min 0

    • used_bytesinteger | nullrequired

      min 0

    • used_gibnumber | nullrequired

      min 0

    • storage_class"local"required
    • access_mode"read_write_once"required
    • state"creating" | "available" | "attaching" | "attached" | "detaching" | "deleting" | "failed"required
    • operation_pendingbooleanrequired
    • generationintegerrequired

      min 1

    • mount_pathstring | nullrequired

      max length 128

    • attached_tostring | nullrequired

      max length 128

    • read_onlyboolean | nullrequired
    • created_atstring (date-time)required
    • updated_atstring (date-time)required
  • 400Invalid bounded request
  • 401Verified identity required
  • 403Required Hives scope missing
  • 404Resource not found in authenticated organization and project
  • 409Persisted lifecycle conflict
  • 503Storage acknowledgement unavailable; read persisted state
  • 4xx 5xxThe error envelope.
curl -X POST "https://os.one.ml/api/v1/hives/projects/$PROJECT_ID/volumes/$VOLUME_ID/unmount" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

Regions

List deployment regions available for project creation.

GET/v1/hives/regions

hives:readTested with an API keyhives_list_regions

Authentication is required: any valid JWT or API key is accepted. We do not gate by scope because the region list is not sensitive and is needed by every authenticated console user to render the project-create flow.

Responses

  • 200Deployment regions
    Response fields
    • regionsobject[]required
    • regions[].[].availablebooleanrequired

      Recent worker admission capacity; the worker still admits atomically.

    • regions[].[].codestringrequired
    • regions[].[].edgeLocationsinteger (int32)required

      Actual active, recently healthy workers in this deployed region. min 0

    • regions[].[].idstringrequired
    • regions[].[].locationstringrequired
    • regions[].[].namestringrequired
    • regions[].[].providerstringrequired
  • 401Unauthorized — no valid JWT or API key
  • 4xx 5xxThe error envelope.
curl "https://os.one.ml/api/v1/hives/regions" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

One Superintelligence, Inc. · Built from Genesis 0.1.12 and the live gateway on 2026-10-20. Support