> ## Documentation Index > Fetch the complete documentation index at: https://docs.hiloop.ai/llms.txt > Use this file to discover all available pages before exploring further. # Post v1workloads > Register a workload in the caller's organization. The name must be unique within the organization; the new workload starts with the default launch ACL (any org member may launch). ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/workloads openapi: 3.0.3 info: title: '' version: 0.0.1 servers: [] security: - bearerAuth: [] tags: - name: AnnotationSchemaService description: |- Org-scoped annotation-schema registry CRUD. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. Registration runs a backward-compatibility check against the latest live version and REJECTS an incompatible change (FAILED_PRECONDITION). These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: AnnotationService description: >- Typed annotation surface over the telemetry store: the annotate writes plus the one served annotation read every consumer shares. Organization scoping is enforced from request identity, not from the request body. Ingest of ordinary telemetry lives in TelemetryIngestService (telemetry.proto); the general event read surface lives in TelemetryQueryService (query.proto). - name: FeedbackService description: |- Product-feedback intake. The organization is derived from the caller's credential, never from the request body; a request with no org scope is UNAUTHENTICATED. Any org-scoped caller — a user session, a service key, or a sandbox-scoped credential — may submit feedback. - name: IdentityService description: Identity/health surface for the control-plane API. - name: MetaService description: Unauthenticated discovery surface for client-visible sibling service URLs. - name: ProjectService description: |- Org-scoped project CRUD. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: RunService description: |- Org-scoped access to runs and their lineage. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: SandboxService description: |- Org-scoped sandbox runtime API. The organization comes from the caller's credential. Org-scoped human and service credentials may use every route in their organization. A sandbox-scoped, lineage-confined credential may read its own sandbox and snapshot lineage and may exec or snapshot only that sandbox; it may not create, update, or delete sandboxes, delete snapshots, or exec into a sibling sandbox. State and verb rules are closed. Get and list serve every visible state. Failed and terminated rows remain available through GetSandbox for a server retention window, then return 404 not_found. Update to stopped is accepted from ready or running and is idempotent from stopped; update to running wakes stopped and is idempotent from running. A wake racing an in-flight stop waits for stop to win before wake proceeds. Workspace growth is accepted only for a stable durable sandbox and is idempotent for the same target; lifecycle mutation and growth never overlap. An undurable snapshot, including one whose request timed out, fences growth and cannot be deleted because its seal may still publish a late receipt; repeat the same snapshot request (and idempotency key, if supplied) to resolve its outcome. Delete is accepted once for a nonterminal sandbox; a second delete returns 404 not_found. Exec requires running and never wakes implicitly; any other non-quarantined state returns 409 sandbox_not_running. Snapshot is accepted from ready, running, or stopped; other non-quarantined states return 409 sandbox_not_ready. Every mutating verb on a quarantined sandbox returns 409 quarantined. A concurrent snapshot returns 409 snapshot_in_progress. Every error uses the flat {code, message, request_id} envelope. Stable route codes are invalid_argument (400), not_found (404), idempotency_conflict, name_conflict, sandbox_not_running, sandbox_not_ready, quarantined, snapshot_in_progress, snapshot_in_use, and snapshot_not_restorable, workspace_shrink_unsupported, and operation_conflict (409), unsupported_capability (422), quota_exceeded (429; details.quota.metric names the limit — sandboxes.running, sandboxes.total, or sandboxes.workspace_capacity_gib), and unavailable (503). Exec transport failures use spawn_failed or sandbox_stopped and discard any partial output; both mean the command did not run. A command that WAS dispatched but whose outcome could not be read is never an error: it returns 200 with the indeterminate outcome, alongside whatever partial output was collected, as a timeout does. Capability-receipt observation has no route in this version and is explicitly NOTIMPL; it is not inferred from Sandbox fields. - name: SecretService description: |- Org-scoped sandbox-secret management. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. Create/revoke/rotate require an owner/admin in the organization; these management RPCs never return the secret value. - name: TelemetryViewService description: >- Typed data-view surface over the telemetry store. Organization scoping is enforced from request identity, not from the request body. A data view's spec is the engine's `DataViewSpec` — a raw `Sql` `SELECT` — re-validated and compiled fresh on every run under the forced-organization safe-SQL gateway. The untrusted raw-SQL escape hatch is a separate `POST /v1/telemetry/sql` endpoint, intentionally kept off this typed wire. - name: UsageService description: Org-scoped product quota reads. - name: VolumeService description: |- Org-scoped volume CRUD. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: WorkloadService description: |- Org-scoped workload registry management. The organization is derived from the caller's credential; a request with no org scope is UNAUTHENTICATED. Registering and reading workloads is open to any org member. Setting a launch ACL and deleting a workload are operator actions and require an owner or admin in the organization. A sandbox-scoped credential may not register, delete, or manage workloads. paths: /v1/workloads: post: tags: - WorkloadService description: >- Register a workload in the caller's organization. The name must be unique within the organization; the new workload starts with the default launch ACL (any org member may launch). operationId: WorkloadService_CreateWorkload requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateWorkloadRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateWorkloadResponse' '429': $ref: '#/components/responses/RateLimited' default: $ref: '#/components/responses/Error' components: schemas: CreateWorkloadRequest: type: object properties: name: type: string description: >- The workload name to register — unique within the organization. Lowercase letters, digits, `.`, `_`, and `-`; must start and end with a letter or digit; at most 100 characters. description: type: string description: A free-text description of what the workload is for. Optional. CreateWorkloadResponse: type: object properties: workload: allOf: - $ref: '#/components/schemas/Workload' description: >- The registered workload, carrying the default launch ACL (any org member may launch). Workload: type: object properties: id: type: string description: The workload's stable id. name: type: string description: >- The workload's registered name — unique within the organization, and how the workload is displayed in attribution everywhere. Lowercase letters, digits, `.`, `_`, and `-`; must start and end with a letter or digit; at most 100 characters. description: type: string description: A free-text description of what the workload is for. May be empty. launch_acl: allOf: - $ref: '#/components/schemas/WorkloadLaunchAcl' description: Who may launch as this workload. created_by: type: string description: >- Stable id of the principal that registered the workload, when recorded. created_at: type: string description: When the workload was registered (RFC 3339). updated_at: type: string description: When the workload's registration or ACL was last changed (RFC 3339). federation_configs: type: array items: $ref: '#/components/schemas/WorkloadFederationConfig' description: >- Live cloud-federation registrations owned by this workload, in creation order. description: A registered workload identity, scoped to the caller's organization. ErrorBody: type: object required: - code - message properties: code: type: string description: Stable machine-readable error code in snake_case. message: type: string description: Human-readable description; clients must not parse it. details: $ref: '#/components/schemas/ErrorDetails' request_id: type: string description: Correlation id present on server faults. WorkloadLaunchAcl: type: object properties: policy: enum: - WORKLOAD_LAUNCH_POLICY_UNSPECIFIED - WORKLOAD_LAUNCH_POLICY_MEMBERS - WORKLOAD_LAUNCH_POLICY_RESTRICTED type: string description: >- The launch policy: open to all org members, or restricted to the listed launchers. format: enum launchers: type: array items: $ref: '#/components/schemas/WorkloadLauncher' description: >- The principals allowed to launch as this workload. Meaningful only when the policy is WORKLOAD_LAUNCH_POLICY_RESTRICTED; empty otherwise. description: >- A per-workload launch ACL: which principals may launch a run or sandbox as the workload. WorkloadFederationConfig: type: object properties: id: type: string description: Stable handle used by federation list, remove, and setup. workload_id: type: string description: Stable id of the workload that owns this registration. cloud: type: string description: 'Cloud provider: aws, gcp, or azure.' audience: type: string description: Exact provider audience admitted for this workload. descriptor: allOf: - $ref: '#/components/schemas/WorkloadFederationDescriptor' description: Strict parameters for the selected cloud. created_by: type: string description: >- Stable id of the principal that created the registration, when recorded. created_at: type: string description: When the registration was created (RFC 3339). description: >- One live cloud-federation registration owned by a workload. The audience is provider-canonical and server-derived from cloud and descriptor; it is the exact value the workload may request from the workload-identity issuer. ErrorDetails: type: object properties: quota: $ref: '#/components/schemas/QuotaDetails' WorkloadLauncher: type: object properties: kind: type: string description: >- The kind of principal this entry names: `user` (an org member, named by user id — also the meaning of an unset kind) or `service_account` (a service-account API key, named by key id). Any other value is rejected. principal_id: type: string description: >- The principal's stable id: a user id for `user`, a service-account key id for `service_account`. description: 'One launch-ACL entry: a principal allowed to launch as the workload.' WorkloadFederationDescriptor: type: object properties: role_arn: type: string description: AWS IAM role trusted by this workload. region: type: string description: >- AWS region used by the generated SDK configuration. Defaults to us-east-1. project_id: type: string description: Google Cloud project id. project_number: type: string description: Google Cloud project number. pool_id: type: string description: Google Cloud workload identity pool id. provider_id: type: string description: Google Cloud workload identity provider id. service_account_email: type: string description: Optional Google Cloud service account to impersonate. application_id: type: string description: Microsoft Entra application (client) id. entra_tenant_id: type: string description: Microsoft Entra tenant id. description: >- Cloud-specific parameters for one workload federation registration. Only the fields belonging to the selected cloud may be set. AWS requires role_arn and defaults an empty region to us-east-1. Google Cloud requires project_id, project_number, pool_id, and provider_id; service_account_email is optional. Microsoft Entra requires application_id and entra_tenant_id. QuotaDetails: type: object required: - metric - limit properties: metric: type: string limit: type: integer format: uint64 current: type: integer format: uint64 reserved: type: integer format: uint64 retry_after_seconds: type: integer format: uint64 responses: RateLimited: description: A quota or rate-limit rejection. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer format: uint64 content: application/json: schema: $ref: '#/components/schemas/ErrorBody' Error: description: An error using the standard hiloop error envelope. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer format: uint64 content: application/json: schema: $ref: '#/components/schemas/ErrorBody' securitySchemes: bearerAuth: type: http scheme: bearer description: Hiloop API key sent as an HTTP Bearer token. ````