> ## Documentation Index > Fetch the complete documentation index at: https://www.ravion.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Pause an app > Pause an app: its sandbox's disk is kept and the microVM stops. A request to one of its URLs wakes it. Returns 202 with the app as it is now. ## OpenAPI ````yaml https://api.ravion.com/openapi.yaml post /apps/{id}/pause openapi: 3.0.0 info: title: Ravion version: 0.0.0 servers: - url: https://api.ravion.com security: - BearerAuth: [] tags: - name: Projects - name: Environments - name: FeatureFlags - name: Pipelines - name: PipelineRuns - name: TerraformResources - name: TerraformExecutionSummaries - name: PipelineStepExecutions - name: AwsCloudWatch - name: AwsAmp - name: PipelineVersions - name: Organizations - name: Stacks - name: StackWorkspaces - name: Auth - name: OAuth - name: User - name: Health - name: Memberships - name: ServiceAccounts - name: Integrations - name: AwsDefaultNetworks - name: AwsAccounts - name: ApiKeys - name: EksPrometheus - name: EksLoki - name: ExecutionEnvironments - name: ModuleDefinitions - name: ModuleCategories - name: ModuleVersions - name: ModuleInstances - name: DefaultValueDefinitions - name: DefaultValues - name: CodeSources - name: Github - name: GitHub Actions - name: Alerts - name: Gitlab - name: Slack - name: Git - name: MergeQueues - name: Values - name: Deployments - name: DeploymentResources - name: InfrastructureEvents - name: WebSocket - name: Domains - name: AcmCertificates - name: NotificationDestinations - name: NotificationDispatches - name: NotificationEvents - name: NotificationRules - name: Activity - name: Describe - name: Reports - name: BillingPlans - name: BillingAccounts - name: BillingCycles - name: BillingUsageSummaries - name: BillingAddOns - name: BillingInvoices - name: Authorization - name: Sandboxes - name: SandboxCommands - name: SandboxPorts - name: Apps paths: /apps/{id}/pause: post: tags: - Apps summary: Pause an app description: >- Pause an app: its sandbox's disk is kept and the microVM stops. A request to one of its URLs wakes it. Returns 202 with the app as it is now. Fails with 409 `NO_SANDBOX` when no sandbox runs the app, and with 409 when its sandbox is not running. operationId: PauseApp parameters: - in: path name: id required: true schema: type: string responses: '202': content: application/json: schema: additionalProperties: false properties: data: $ref: '#/components/schemas/App' required: - data type: object description: >- The request has been accepted for processing, but processing has not yet completed. '400': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The request is invalid or malformed. '401': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You are not authenticated '403': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You do not have permission to access this resource. '404': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The server cannot find the requested resource. '409': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The request conflicts with the current state of the server. '500': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: Server error components: schemas: App: additionalProperties: false description: 'An app: a named microVM on an App Cluster, served at its URLs.' properties: branch: description: >- The git branch of a branch app: the app deployed from a branch other than its default one, served at its app's URLs with `--` and the branch after the first label, such as `https://--.`. Absent for the app of the default branch. type: string cpu: description: vCPUs the app runs with. format: int32 type: integer createdAt: allOf: - $ref: '#/components/schemas/UtcDateTime' readOnly: true createdById: description: User or service account who created the app. type: string defaultBranch: description: >- For the app of the default branch, the branch its first deploy that named one was taken from. `ravion deploy` from that branch deploys this app, and from any other branch the branch app of that branch. Absent before then, and for a branch app. type: string definition: allOf: - $ref: '#/components/schemas/AppDefinitionSummary' description: >- The app's definition as its last successful deploy set it. Absent before the first successful deploy. diskGib: description: Disk the app runs with, in GiB. format: int32 type: integer domains: description: >- The domains of the app's own its exposed ports list, in the order its last deploy listed them. Empty for an app that lists none, and for a branch app: the domains serve the app of the default branch. items: $ref: '#/components/schemas/AppDomain' type: array environmentId: description: Environment (`env_*`) of the App Cluster. type: string id: readOnly: true type: string lastDeploy: allOf: - $ref: '#/components/schemas/AppDeploy' description: >- The app's most recent deploy, whatever became of it. Absent before the first deploy. memoryMib: description: Memory the app runs with, in MiB. format: int32 type: integer moduleInstanceId: description: App Cluster module instance (`minst_*`) the app is deployed onto. type: string name: description: >- The app's name: 1 to 32 lowercase letters, digits or hyphens, starting and ending with a letter or digit, with no two hyphens in a row. It is part of every URL the app is served at. The app and its branch apps share it. type: string organizationId: readOnly: true type: string projectId: description: Project (`proj_*`) of the App Cluster. type: string sandboxId: description: >- Sandbox (`sbx_*`) that runs the app. Absent while no sandbox runs it: before its first deploy, and after its disk was deleted. type: string sandboxStatus: allOf: - $ref: '#/components/schemas/Sandbox.Status' description: >- Where the app's sandbox is in its life, for clients that wait for it to run. Absent while no sandbox runs the app. status: allOf: - $ref: '#/components/schemas/App.Status' description: Where the app is. updatedAt: allOf: - $ref: '#/components/schemas/UtcDateTime' readOnly: true urls: description: >- The URLs the app is served at, one per exposed port, in the order of its definition. Empty for an app that exposes no port or has not been deployed. items: $ref: '#/components/schemas/AppUrl' type: array required: - id - createdAt - updatedAt - organizationId - name - moduleInstanceId - projectId - environmentId - status - urls - domains - cpu - memoryMib - diskGib type: object Errors.UserFacingErrorData: additionalProperties: false description: |- User-facing error presentation data. This is what the API returns to the frontend after formatting ErrorData using CEL templates from the error registry. Used for both: - Error fields on domain models (e.g., PipelineRun.error) - API error response bodies (HTTP 4xx/5xx responses) properties: action: allOf: - $ref: '#/components/schemas/Errors.Action' description: Optional action to help resolve the error code: description: Full error code, e.g., "Ravion:Pipeline:NOT_FOUND" type: string description: description: Additional description with more details type: string details: description: Structured details rendered as user-facing sections. items: $ref: '#/components/schemas/Errors.UserFacingErrorDetailSection' type: array isInternal: description: >- Indicates whether this error is internal (only set when ShowInternal=true). This allows SUPERADMINs to identify internal errors while viewing full details. type: boolean message: description: Main error message (required) type: string metadata: additionalProperties: {} description: >- Error params/metadata. Stripped for internal errors unless superadmin. type: object requestId: description: Request ID for correlating errors with server logs. type: string required: - code - message type: object UtcDateTime: description: UTC RFC3339 timestamp with a required Z suffix format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$ type: string x-go-type: apitypes.UTCDateTime x-go-type-import: name: apitypes path: ravion/api-go/pkg/apitypes AppDefinitionSummary: additionalProperties: false description: >- An app's definition as its current deploy set it, with the environment variables named and their values left out. properties: compose: allOf: - $ref: '#/components/schemas/App.AppCompose' description: The Docker Compose project. Set when `kind` is `compose`. cpu: description: vCPUs. Defaults to the cluster's default. format: int32 minimum: 1 type: integer x-go-name: CPU description: description: >- What the app is, from `description` in `ravion-app.yaml`. Shown on the app's overview. maxLength: 500 type: string diskGib: description: Disk in GiB. Defaults to the cluster's default. format: int32 minimum: 1 type: integer x-go-name: DiskGiB envNames: description: >- Names of the environment variables the deploy set, those of `ravion-app.yaml` and those passed with the deploy, in order. Their values are never returned. items: type: string type: array expose: description: >- HTTP ports served at the app's URLs, in order. Empty for an app that serves no port. items: $ref: '#/components/schemas/App.AppExposure' type: array idleTimeoutSeconds: description: >- Seconds without a request or a running command before the app is paused: 0 never pauses it, otherwise at least 60. Defaults to the cluster's default. format: int32 minimum: 0 type: integer kind: allOf: - $ref: '#/components/schemas/App.AppKind' description: Whether `compose` or `run` builds and starts the app. memoryMib: description: Memory in MiB. Defaults to the cluster's default. format: int32 minimum: 1 type: integer x-go-name: MemoryMiB run: allOf: - $ref: '#/components/schemas/App.AppRun' description: The build and start commands. Set when `kind` is `run`. workdir: description: >- Folder that holds `ravion-app.yaml`, relative to the root of the uploaded files, or `.` for the root. Commands run in it. minLength: 1 type: string required: - kind - workdir - expose - envNames type: object AppDomain: additionalProperties: false description: >- A domain of an app's own, as an exposed port of its `ravion-app.yaml` lists it, with its certificate's state and the DNS records to add for it. properties: domainId: description: >- Id of the domain as the App Cluster's domains list it; the domain DNS status operation names its records by it. type: string error: description: >- Why the domain's certificate could not be issued or attached. Set when `status` is `FAILED`. type: string exposure: description: Name of the exposed port the domain serves. type: string name: description: The domain name. type: string records: description: >- The DNS records to add at your DNS provider: the certificate's validation records, then the routing record that points the domain at the App Cluster's load balancer. items: $ref: '#/components/schemas/AppDomainRecord' type: array status: allOf: - $ref: '#/components/schemas/AppDomainStatus' description: Where the domain is. required: - name - exposure - domainId - status - records type: object AppDeploy: additionalProperties: false description: >- One deploy of an app: the pipeline run that carried it out, and what it deployed. properties: branch: description: >- Branch the deployed files were taken from. Absent when they were not on a branch. type: string commit: description: >- Commit the deployed files were taken from. Absent when they were not taken from a git commit. type: string commitUrl: description: >- The URL that serves this deploy's commit from the snapshot taken when it turned healthy. Absent when no snapshot was taken. type: string createdAt: allOf: - $ref: '#/components/schemas/UtcDateTime' description: When the deploy was requested. createdById: description: User or service account who requested the deploy. type: string dirty: description: True when the deployed files had changes that were not committed. type: boolean finishedAt: allOf: - $ref: '#/components/schemas/UtcDateTime' description: When the deploy's pipeline run ended. Absent while it runs. pipelineRunId: description: >- Pipeline run (`prun_*`) that carries out the deploy. Read it for the deploy's steps and their logs, or cancel it. type: string status: allOf: - $ref: '#/components/schemas/PipelineRun.Status' description: Where the deploy's pipeline run is. required: - pipelineRunId - status - dirty - createdAt type: object Sandbox.Status: description: >- Where a sandbox is in its life. `PENDING`: created, waiting for a host. `STARTING`: a host is booting it. `RUNNING`: ready for commands. `PAUSING`: its disk is being snapshotted. `PAUSED`: stopped with a snapshot to resume from. `RESUMING`: booting from its snapshot. `STOPPING`/`STOPPED`: stopped by you or by the loss of its host; a stopped sandbox with a snapshot can be resumed. `EXPIRED`: its retention period ended and its snapshot was deleted. `DELETED`: deleted on request. `FAILED`: it could not be started; see `statusReason`. enum: - PENDING - STARTING - RUNNING - PAUSING - PAUSED - RESUMING - STOPPING - STOPPED - EXPIRED - DELETED - FAILED type: string App.Status: description: >- Where an app is. `DEPLOYING`: a deploy of the app is running. `RUNNING`: the app's sandbox is running, or is starting or waking; requests to its URLs are held until it is up. `PAUSED`: the app is paused, or pausing, with its disk kept; a request to one of its URLs wakes it. `STOPPED`: no sandbox runs the app: it has not been deployed yet, its sandbox was stopped, or its disk was deleted after it stayed paused longer than its App Cluster keeps paused apps. The next deploy starts it. `FAILED`: the last deploy failed, or the app's sandbox could not be started. `DELETING`: the app is being deleted. enum: - DEPLOYING - RUNNING - PAUSED - STOPPED - FAILED - DELETING type: string AppUrl: additionalProperties: false description: Where an exposed port of an app is served. properties: alternateUrls: description: >- The port's URLs under the App Cluster's custom wildcard domains, in the App Cluster's order, always `https://`. Empty when the App Cluster has none. The port's own domains are listed in the app's `domains`. items: type: string type: array name: description: Name of the exposed port, as `ravion-app.yaml` names it. type: string url: description: >- The port's URL under the App Cluster's Ravion domain, always `https://`. type: string required: - name - url - alternateUrls type: object Errors.Action: additionalProperties: false description: Action to help user resolve the error properties: label: description: Button/link label text type: string url: description: URL to navigate to for resolution type: string required: - label - url type: object Errors.UserFacingErrorDetailSection: additionalProperties: false description: Structured user-facing error detail section. properties: items: description: List of detail values for this section. items: type: string type: array object: additionalProperties: {} description: Structured detail payload for object rendering. type: object render: description: Rendering hint for clients. Valid values are list or object. type: string title: description: Detail section title shown in the UI. type: string required: - title - render type: object App.AppCompose: additionalProperties: false description: A Docker Compose project Ravion builds and starts. properties: file: description: Compose file, relative to the app's folder. minLength: 1 type: string x-templateable: true profiles: description: Compose profiles to enable. May be empty. items: type: string type: array x-templateable: true services: description: >- Services to build and start. Empty builds and starts every service the enabled profiles include. items: type: string type: array x-templateable: true required: - file - profiles - services type: object x-go-type: app.Compose x-go-type-import: name: app path: ravion/schemas/app App.AppExposure: additionalProperties: false description: >- An HTTP port an app serves. The first exposure is served at the app's primary URL. properties: domains: description: >- Domains of your own the port is also served at, in order. An app has at most 10 domains across its exposures, no two exposures list the same domain, and at least one of the app's domains is at most 64 characters long, to name its certificate. Absent or empty for a port served only at the App Cluster's domains. items: $ref: '#/components/schemas/App.AppDomainName' maxItems: 10 type: array x-go-type-skip-optional-pointer: true x-templateable: true healthCheckPath: description: HTTP path requested to tell whether the port is ready. pattern: ^/ type: string x-templateable: true name: description: >- 1 to 20 lowercase letters, digits or hyphens, starting and ending with a letter or digit, with no two hyphens in a row, unique within the app. maxLength: 20 pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$ type: string x-templateable: true port: description: Port inside the app. format: int32 maximum: 65535 minimum: 1 type: integer x-templateable: true required: - name - port - healthCheckPath type: object x-go-type: app.Exposure x-go-type-import: name: app path: ravion/schemas/app App.AppKind: description: How an app is built and started. enum: - compose - run type: string x-go-type: app.Kind x-go-type-import: name: app path: ravion/schemas/app App.AppRun: additionalProperties: false description: An app's own build and start commands. properties: build: description: Commands run in order on every deploy, before `start`. May be empty. items: type: string type: array x-templateable: true start: description: >- Commands run in order on every deploy, after `build`, and every time the app wakes. items: type: string minItems: 1 type: array x-templateable: true required: - build - start type: object x-go-type: app.Run x-go-type-import: name: app path: ravion/schemas/app AppDomainRecord: additionalProperties: false description: A DNS record to add at your DNS provider for a domain of an app's own. properties: name: description: Name of the record. type: string purpose: allOf: - $ref: '#/components/schemas/AppDomainRecordPurpose' description: What the record is for. type: description: DNS record type, such as `CNAME`. type: string value: description: Value the record must hold. type: string required: - purpose - type - name - value type: object AppDomainStatus: description: >- Where a domain of an app's own is. `PENDING`: Ravion requested the domain's certificate and waits for its validation records to be added at your DNS provider, or is attaching it to the App Cluster's load balancer. `ACTIVE`: the certificate is issued and on the load balancer; requests reach the app once the domain's routing record points at the load balancer. `FAILED`: the certificate could not be issued or attached, and `error` says why; deploy the app again to retry. enum: - PENDING - ACTIVE - FAILED type: string PipelineRun.Status: enum: - QUEUED - IN_PROGRESS - PENDING_APPROVAL - CANCELLING - SUCCESS - ERROR - CANCELLED - SKIPPED - TIMEOUT type: string App.AppDomainName: description: >- A domain name in a DNS zone you control, such as `shop.example.com`: two or more lowercase labels of letters, digits and hyphens, with no `*.` and no trailing dot. maxLength: 253 pattern: >- ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$ type: string AppDomainRecordPurpose: description: >- What a DNS record of an app's domain is for. `VALIDATION`: proves to AWS that you control the domain, so its certificate is issued. `ROUTING`: points the domain at the App Cluster's load balancer. enum: - VALIDATION - ROUTING type: string securitySchemes: BearerAuth: scheme: Bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.