> ## Documentation Index > Fetch the complete documentation index at: https://docs.baseten.co/llms.txt > Use this file to discover all available pages before exploring further. # Create a sandbox preview > Exposes a sandbox port through a public or token-protected HTTPS URL. ## OpenAPI ````yaml post /v1/sandboxes/instances/{sandbox_name}/previews openapi: 3.1.0 info: description: REST API for management of Baseten resources title: Baseten management API version: 1.0.0 servers: - url: https://api.baseten.co security: - BearerAuth: [] paths: /v1/sandboxes/instances/{sandbox_name}/previews: parameters: - $ref: '#/components/parameters/SandboxName' post: tags: - Previews summary: Create a sandbox preview description: >- Expose a port of the sandbox on an HTTPS URL. A public preview is reachable by anyone with the URL. A private preview requires a preview token, created with the tokens endpoint and sent as the bl_preview_token query parameter; the first request sets a bl_preview_token cookie so a browser can keep navigating without it. Port 80 and the sandbox's reserved system ports are rejected, and port 443 must stay private. Without a name, the name is generated from the sandbox name and port, or is public- or private- when create_if_not_exists is true. operationId: CreateSandboxPreview parameters: - $ref: '#/components/parameters/TeamId' - $ref: '#/components/parameters/TeamIdHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSandboxPreviewRequestV1' examples: public: $ref: '#/components/examples/CreateSandboxPreviewPublic' private: $ref: '#/components/examples/CreateSandboxPreviewPrivate' responses: '201': description: Preview created. content: application/json: schema: $ref: '#/components/schemas/SandboxPreviewV1' examples: complete: $ref: '#/components/examples/SandboxPreviewReady' '400': $ref: '#/components/responses/SandboxError400' '401': $ref: '#/components/responses/SandboxError401' '403': $ref: '#/components/responses/SandboxError403' '404': $ref: '#/components/responses/SandboxError404' '409': $ref: '#/components/responses/SandboxError409' '429': $ref: '#/components/responses/SandboxError429' '500': $ref: '#/components/responses/SandboxError500' components: parameters: SandboxName: name: sandbox_name in: path required: true description: Immutable sandbox name returned by creation. schema: type: string minLength: 1 example: baseten-api-review-0916 TeamId: name: team_id in: query required: false description: >- Optional team ID. Must match X-Team-Id when both are supplied. If neither selector is supplied, defaults to the caller's only accessible team. Callers with multiple accessible teams must select a team. Requests without access to any team are forbidden. schema: minLength: 1 type: string TeamIdHeader: name: X-Team-Id in: header required: false description: >- Optional team ID. Must match the team_id query parameter when both are supplied. If neither selector is supplied, defaults to the caller's only accessible team. Callers with multiple accessible teams must select a team. Requests without access to any team are forbidden. schema: minLength: 1 type: string schemas: CreateSandboxPreviewRequestV1: description: Preview to create. Only port is required. allOf: - $ref: '#/components/schemas/SandboxPreviewConfigurationV1' - type: object properties: create_if_not_exists: type: boolean description: >- When true, return the existing preview with this name instead of failing with a conflict. Without name, the name is public- or private-, so the same port and visibility return the same preview. Existing configuration is preserved. Defaults to false when omitted. name: type: string description: >- Preview name, unique within the sandbox. When omitted, generated from the sandbox name and port, or public- or private- when create_if_not_exists is true. minLength: 1 maxLength: 49 pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$ example: web port: type: integer description: Sandbox port to expose. minimum: 1 maximum: 65535 example: 3000 required: - port SandboxPreviewV1: description: >- Sandbox preview with configuration and server-managed fields at the root. allOf: - $ref: '#/components/schemas/SandboxPreviewConfigurationV1' - type: object properties: name: type: string description: Preview name, used in preview_name path parameters. readOnly: true example: web port: type: integer description: Exposed sandbox port. readOnly: true example: 3000 url: type: string format: uri description: >- HTTPS URL serving the port, including the region label. Use this exact URL. Requests to a private preview need a token. readOnly: true example: https://a1b2c3d4e5f6g7h8.us-pdx-1.preview.b10.co status: $ref: '#/components/schemas/SandboxPreviewStatusV1' region: type: string description: Region serving the preview, the sandbox's region. readOnly: true example: us-pdx-1 created_at: type: string format: date-time readOnly: true example: '2026-10-12T12:00:00Z' updated_at: type: string format: date-time readOnly: true example: '2026-10-12T12:00:00Z' created_by: type: string readOnly: true example: sandbox-automation updated_by: type: string readOnly: true example: sandbox-automation required: - name - port - url - status - public SandboxPreviewConfigurationV1: type: object description: >- Mutable preview configuration. ttl and expires_at are mutually exclusive; supplying both returns 400. properties: public: type: boolean description: >- Whether the URL is reachable without a preview token. Defaults to false. default: false example: true response_headers: description: >- Headers added to every response served by the preview, for example CORS headers. allOf: - $ref: '#/components/schemas/SandboxPreviewHeadersV1' request_headers: description: >- Headers added to every request forwarded to the sandbox, for example an Authorization header expected by the application. Responses return each name with the value "****", except a GET with show_secrets=true by a workspace administrator. Sending "****" back as a value returns 400. A PATCH replaces the whole set. allOf: - $ref: '#/components/schemas/SandboxPreviewHeadersV1' example: Authorization: Bearer app-internal-token ttl: $ref: '#/components/schemas/SandboxPreviewTtlV1' expires_at: type: string format: date-time description: Time at which the preview is deleted. Must be in the future. example: '2026-10-19T12:00:00Z' SandboxPreviewStatusV1: type: string description: Preview status, always uppercase. enum: - DEPLOYING - DEPLOYED - FAILED - DELETING - TERMINATED readOnly: true example: DEPLOYED SandboxPreviewHeadersV1: type: object description: HTTP headers as name-value pairs. additionalProperties: type: string example: Access-Control-Allow-Origin: '*' SandboxPreviewTtlV1: type: string description: >- Lifetime counted from the request, using seconds, minutes, hours or composite durations such as 1h30m. Whole days are also supported, for example 7d; days cannot be combined with other units. The preview is deleted when it elapses. pattern: ^([0-9]+d|(([0-9]+(\.[0-9]*)?|\.[0-9]+)(ns|us|µs|μs|ms|s|m|h))+)$ example: 24h examples: CreateSandboxPreviewPublic: summary: Public preview of a web server value: name: web port: 3000 public: true response_headers: Access-Control-Allow-Origin: '*' CreateSandboxPreviewPrivate: summary: Private preview deleted after one day value: port: 8080 ttl: 24h SandboxPreviewReady: summary: Public preview value: name: web port: 3000 public: true url: https://a1b2c3d4e5f6g7h8.us-pdx-1.preview.b10.co status: DEPLOYED region: us-pdx-1 response_headers: Access-Control-Allow-Origin: '*' created_at: '2026-10-12T12:00:00Z' updated_at: '2026-10-12T12:00:00Z' created_by: sandbox-automation updated_by: sandbox-automation responses: SandboxError400: description: >- Invalid request. Returns a JSON error with code, message, and optional details. content: application/json: example: code: INVALID_REQUEST message: One or more request parameters are invalid. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError401: description: >- Missing or invalid authentication. Returns a JSON error with code, message, and optional details. content: application/json: example: code: UNAUTHORIZED message: Provide a valid authentication token in the Authorization header. details: header: Authorization SandboxError403: description: >- Insufficient permissions. Returns a JSON error with code, message, and optional details. content: application/json: example: code: FORBIDDEN message: >- This authentication token does not grant permission to perform this operation. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError404: description: >- Resource not found. Returns a JSON error with code, message, and optional details. content: application/json: example: code: NOT_FOUND message: The requested resource was not found. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError409: description: >- Resource is currently in use or conflicts with the requested operation. Returns a JSON error with code, message, and optional details. content: application/json: example: code: RESOURCE_IN_USE message: >- The resource is currently in use or conflicts with the requested operation. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 SandboxError429: description: >- Request limit exceeded. Returns a JSON error with code, message, and optional details. content: application/json: example: code: RATE_LIMITED message: Too many requests. Try again in 30 seconds. details: retry_after_seconds: 30 SandboxError500: description: >- Internal server error. Returns a JSON error with code, message, and optional details. content: application/json: example: code: INTERNAL_ERROR message: The request could not be completed. Try again later. details: request_id: a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043 securitySchemes: BearerAuth: type: http scheme: bearer description: >- Send `Authorization: Bearer `. The legacy `Authorization: Api-Key ` scheme is also accepted. ````