Create a sandbox preview

POST

sandboxes

instances

{sandbox_name}

previews

curl --request POST \
  --url https://api.baseten.co/v1/sandboxes/instances/{sandbox_name}/previews \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "web",
  "port": 3000,
  "public": true,
  "response_headers": {
    "Access-Control-Allow-Origin": "*"
  }
}
'

{
  "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"
}

{
  "code": "INVALID_REQUEST",
  "message": "One or more request parameters are invalid.",
  "details": {
    "request_id": "a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043"
  }
}

{
  "code": "UNAUTHORIZED",
  "message": "Provide a valid authentication token in the Authorization header.",
  "details": {
    "header": "Authorization"
  }
}

{
  "code": "FORBIDDEN",
  "message": "This authentication token does not grant permission to perform this operation.",
  "details": {
    "request_id": "a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043"
  }
}

{
  "code": "NOT_FOUND",
  "message": "The requested resource was not found.",
  "details": {
    "request_id": "a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043"
  }
}

{
  "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"
  }
}

{
  "code": "RATE_LIMITED",
  "message": "Too many requests. Try again in 30 seconds.",
  "details": {
    "retry_after_seconds": 30
  }
}

{
  "code": "INTERNAL_ERROR",
  "message": "The request could not be completed. Try again later.",
  "details": {
    "request_id": "a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043"
  }
}

Authorizations

Authorization

string

header

required

Send Authorization: Bearer <api_key>. The legacy Authorization: Api-Key <api_key> scheme is also accepted.

Headers

X-Team-Id

string

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.

Minimum string length: 1

Path Parameters

sandbox_name

string

required

Immutable sandbox name returned by creation.

Minimum string length: 1

Example:

"baseten-api-review-0916"

Query Parameters

team_id

string

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.

Minimum string length: 1

Body

application/json

Preview to create. Only port is required.

port

integer

required

Sandbox port to expose.

Required range: 1 <= x <= 65535

Example:

3000

public

boolean

default:false

Whether the URL is reachable without a preview token. Defaults to false.

Example:

true

response_headers

object

Headers added to every response served by the preview, for example CORS headers.

Show child attributes

Example:

{ "Access-Control-Allow-Origin": "*" }

request_headers

object

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.

Show child attributes

Example:

{
  "Access-Control-Allow-Origin": "*",
  "Authorization": "Bearer app-internal-token"
}

ttl

string

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"

expires_at

string<date-time>

Time at which the preview is deleted. Must be in the future.

Example:

"2026-10-19T12:00:00Z"

create_if_not_exists

boolean

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

string

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.

Required string length: 1 - 49

Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$

Example:

"web"

Response

Preview created.

Sandbox preview with configuration and server-managed fields at the root.

public

boolean

default:false

required

Whether the URL is reachable without a preview token. Defaults to false.

Example:

true

name

string

required

read-only

Preview name, used in preview_name path parameters.

Example:

"web"

port

integer

required

read-only

Exposed sandbox port.

Example:

3000

url

string<uri>

required

read-only

HTTPS URL serving the port, including the region label. Use this exact URL. Requests to a private preview need a token.

Example:

"https://a1b2c3d4e5f6g7h8.us-pdx-1.preview.b10.co"

status

enum<string>

required

read-only

Preview status, always uppercase.

Available options:

DEPLOYING,

DEPLOYED,

FAILED,

DELETING,

TERMINATED

Example:

"DEPLOYED"

response_headers

object

Headers added to every response served by the preview, for example CORS headers.

Show child attributes

Example:

{ "Access-Control-Allow-Origin": "*" }

request_headers

object

Show child attributes

Example:

{
  "Access-Control-Allow-Origin": "*",
  "Authorization": "Bearer app-internal-token"
}

ttl

string

Pattern: ^([0-9]+d|(([0-9]+(\.[0-9]*)?|\.[0-9]+)(ns|us|µs|μs|ms|s|m|h))+)$

Example:

"24h"

expires_at

string<date-time>

Time at which the preview is deleted. Must be in the future.

Example:

"2026-10-19T12:00:00Z"

region

string

read-only

Region serving the preview, the sandbox's region.

Example:

"us-pdx-1"

created_at

string<date-time>

read-only

Example:

"2026-10-12T12:00:00Z"

updated_at

string<date-time>

read-only

Example:

"2026-10-12T12:00:00Z"

created_by

string

read-only

Example:

"sandbox-automation"

updated_by

string

read-only

Example:

"sandbox-automation"

⌘I

curl --request POST \
  --url https://api.baseten.co/v1/sandboxes/instances/{sandbox_name}/previews \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "web",
  "port": 3000,
  "public": true,
  "response_headers": {
    "Access-Control-Allow-Origin": "*"
  }
}
'

{
  "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"
}

{
  "code": "INVALID_REQUEST",
  "message": "One or more request parameters are invalid.",
  "details": {
    "request_id": "a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043"
  }
}

{
  "code": "UNAUTHORIZED",
  "message": "Provide a valid authentication token in the Authorization header.",
  "details": {
    "header": "Authorization"
  }
}

{
  "code": "FORBIDDEN",
  "message": "This authentication token does not grant permission to perform this operation.",
  "details": {
    "request_id": "a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043"
  }
}

{
  "code": "NOT_FOUND",
  "message": "The requested resource was not found.",
  "details": {
    "request_id": "a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043"
  }
}

{
  "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"
  }
}

{
  "code": "RATE_LIMITED",
  "message": "Too many requests. Try again in 30 seconds.",
  "details": {
    "retry_after_seconds": 30
  }
}

{
  "code": "INTERNAL_ERROR",
  "message": "The request could not be completed. Try again later.",
  "details": {
    "request_id": "a3b7c4d2-91e6-4f08-9b5a-2c6d7e8f1043"
  }
}

Reference

Inference API

Management API

Loops API

Training API

Frontier Gateway API

CLI reference

SDKs and clients

Configuration

Metrics

Integrations

Create a sandbox preview

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response