> ## Documentation Index > Fetch the complete documentation index at: https://docs.hivenet.com/llms.txt > Use this file to discover all available pages before exploring further. # Stop an instance > Stops a running instance. The call returns as soon as the request is accepted; the instance moves `STOPPING → STOPPED` in the background. Storage is retained and the instance can be started again. Billing for compute stops; storage may still be charged. ## OpenAPI ````yaml /public-v1.yaml post /instances/{id}/stop openapi: 3.0.3 info: title: Hive Compute Public API description: | The Hive Compute public API lets you manage compute instances and SSH keys programmatically, and browse the hardware presets and regions available to you. **Base URL:** `https://api.hivenet.com/v1` ## Authentication Every endpoint requires an API key, sent as a Bearer token: ``` Authorization: Bearer ``` API keys are issued manually at this release. Email [support@hivenet.com](mailto:support@hivenet.com) to request one. There is no self-service endpoint or console page for creating, listing or rotating keys yet; both will arrive in a later release. Treat the key as a password. It carries the full permissions of your account, does not expire on its own, and can only be replaced by contacting support. ## Scope Requests are scoped to the account the key belongs to. You can only see and act on your own instances and SSH keys. Regions and presets are the shared public catalogue and look the same to everyone. ## Errors Every error shares one envelope: ```json { "error": { "code": "NOT_FOUND", "message": "Instance 7f3c... not found", "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ``` Quote `request_id` when contacting support: it identifies the exact request in our logs. ## Rate limiting Requests are rate limited per key. Exceeding the limit returns `429` with a `Retry-After` header giving the number of seconds to wait. Treat the limit as subject to change and back off on `429` rather than pacing to a fixed number. ## Pagination List endpoints are cursor-paginated and return the same envelope: ```json { "data": [], "pagination": { "next": "opaque-cursor", "size": 50 } } ``` Pass `pagination.next` back as the `cursor` query parameter to fetch the following page. When it is `null` you have reached the last page. Cursors are opaque; do not construct or parse them. version: 1.0.0 contact: name: Hive Compute Support email: support@hivenet.com url: https://hivenet.com servers: - url: https://api.hivenet.com/v1 description: Production security: - bearerAuth: [] tags: - name: Instances description: > Compute instances are the core resource of the platform. Each instance runs a GPU-backed workload on a hardware preset in a region, and moves through this lifecycle: `CREATED → DEPLOYED → STARTING → RUNNING → STOPPING → STOPPED → TERMINATING → TERMINATED` A stopped instance can be started again and keeps its storage. A terminated instance is gone permanently and cannot be recovered. - name: SSH keys description: | Public keys used to reach your instances over SSH. A key you register is owned by your account and is not visible to anyone else. - name: Catalogue description: | The regions and hardware presets available to launch instances on. This is shared public reference data, identical for every caller. paths: /instances/{id}/stop: post: tags: - Instances summary: Stop an instance description: | Stops a running instance. The call returns as soon as the request is accepted; the instance moves `STOPPING → STOPPED` in the background. Storage is retained and the instance can be started again. Billing for compute stops; storage may still be charged. operationId: stopInstance parameters: - $ref: '#/components/parameters/InstanceId' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/InstanceAction' responses: '201': description: The request was accepted; the instance's current state is returned. content: application/json: schema: $ref: '#/components/schemas/Instance' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: parameters: InstanceId: name: id in: path required: true description: The instance's unique identifier. schema: type: string format: uuid schemas: InstanceAction: type: object description: Optional context recorded in the audit trail for this action. properties: reason_note: type: string maxLength: 10000 description: Free-text note explaining why the action was taken. example: scaling down overnight Instance: type: object properties: instance_id: type: string format: uuid description: Unique identifier. name: type: string description: Display name. example: training-run-4 status: type: string enum: - CREATED - DEPLOYED - STARTING - RUNNING - ERRORED - TERMINATING - TERMINATED - STOPPING - STOPPED description: Current lifecycle state. region: type: string description: Region the instance runs in. example: eu-west gpu_type: type: string description: GPU model. example: RTX 4090 size: type: string description: SKU name of the preset the instance runs on. example: 8x-RTX-4090 cpu_count: type: integer description: Virtual CPUs allocated. resources: type: string description: Human-readable summary of the allocated hardware. bandwidth: type: number description: Allocated bandwidth, in Mbps. storage_used_gb: type: number description: Storage currently in use, in GB. hourly_rate: type: number description: Price charged per hour while running, in credits. current_cost: type: number description: Cost accrued during the current run, in credits. total_cost_incurred: type: number description: Total cost over the instance's whole life, in credits. total_runtime_hours: type: number description: Total hours the instance has spent running. ttl_remaining_hours: type: number description: Hours remaining before the instance is stopped automatically. started_at: type: string format: date-time nullable: true description: When the instance last entered `RUNNING`. terminated_at: type: string format: date-time nullable: true description: When the instance was terminated, if it has been. termination_reason: type: string nullable: true description: Why the instance was terminated, if it has been. guest_ready: type: string description: Whether the guest OS has finished booting and is reachable. guest_ready_reason: type: string nullable: true description: Explanation when the guest is not ready. Error: type: object properties: error: type: object properties: code: type: string enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - VALIDATION_ERROR - TOO_MANY_REQUESTS - INTERNAL_ERROR description: Stable, machine-readable error code. message: type: string description: Human-readable explanation. Do not match on this text. request_id: type: string description: Identifies this request in our logs. Quote it to support. responses: ValidationError: description: The request was malformed or a parameter was invalid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: VALIDATION_ERROR message: size must not be greater than 200 request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Unauthorized: description: The API key is missing, malformed or not valid. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Missing API token request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 Forbidden: description: The resource exists but does not belong to your account. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: FORBIDDEN message: instance does not belong to the caller request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 NotFound: description: No such resource. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Instance 7f3c8f22-1f4e-4a5e-9b7a-0c1d2e3f4a5b not found request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 RateLimited: description: | Too many requests. Wait the number of seconds given in `Retry-After` before retrying. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: TOO_MANY_REQUESTS message: Too Many Requests request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 InternalError: description: >- Something went wrong on our side. Retry, then contact support with the `request_id`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: Internal server error request_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 securitySchemes: bearerAuth: type: http scheme: bearer description: | An API key issued by Hive Compute support. See **Authentication** above for how to request one. ````