> For the complete documentation index, see [llms.txt](https://docs.tonic.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tonic.ai/fabricate/data-agent-tools/project-api/sandboxes.md).

# Using sandboxes

{% hint style="info" %}
The sandboxes feature requires an Enterprise license.
{% endhint %}

A sandbox is a temporary copy of local project data that you can interact with. The actual project data remains unchanged.

One use case for a sandbox is for test suites. A sandbox allows you to begin each test run with the same data.

Sandboxes automatically expire and are deleted after an hour of inactivity. The expiration resets every time the sandbox is used.

Each account is limited to 10 active sandboxes across all workspaces and projects. To request an increase to that number, contact Tonic.ai. 

## Displaying your sandboxes <a href="#sandboxes-display" id="sandboxes-display"></a>

To display the list of active sandboxes, under **API**, click **Sandboxes**.

<figure><img src="https://4109733485-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmoU4gTR9LxlzHeWmQCUZ%2Fuploads%2FhFpGOcedgcLB2JA85hyB%2FDataAgent_SandboxesLink.png?alt=media&amp;token=fcfd0f08-1f21-452f-80c0-cde034020a3c" alt=""><figcaption><p>API menu with the Sandboxes link to display the active sandboxes</p></figcaption></figure>

For each sandbox, the list includes:

* Sandbox name.
* When the sandbox was most recently used.
* When the sandbox expires and will be deleted. The expiration is based on inactivity. The inactivity timer resets whenever you use the sandbox.

<figure><img src="https://4109733485-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FmoU4gTR9LxlzHeWmQCUZ%2Fuploads%2FkOj46C78bthdw4rjAe8B%2FProject_Sandboxes.png?alt=media&amp;token=9c511102-42c2-4759-a04e-92ee8bf9c703" alt=""><figcaption><p>Sandboxes page with the list of active sandboxes</p></figcaption></figure>

## About the sandbox URL <a href="#sandbox-url" id="sandbox-url"></a>

The **Sandboxes** page displays a template sandbox URL for the current project. To copy the template URL, click the copy icon.

At a high level, the structure of a sandbox URL is:

`https://<fabricate URL>/api/v1/workspaces/<workspace name>/projects/<project name>/versions/<project version>/sandboxes/<sandbox>/api`

Where:

* `<fabricate URL>` is the main URL for the Fabricate instance. For Fabricate Cloud, this is fabricate.tonic.ai.
* `<workspace name>` is the name of the workspace. In the workspace name, replace any spaces with `%20`. For example, the workspace name `First workspace` becomes `First%20workspace`.
* `<project name>` is the name of the project. In the project name, replace any spaces with `%20`. For example, the project name `First project` becomes `First%20project`.
* `<project version>` is the version of the project to use.
* `<sandbox>` is the identifier of the sandbox.

## Connecting to a sandbox <a href="#sandbox-connect-to" id="sandbox-connect-to"></a>

To connect to a sandbox, you call the sandbox URL.

The request must include a Fabricate API key as a bearer token in the Authorization header. The API key must have edit access to the project.

For example:

`curl -H "Authorization: Bearer NIDgKxMs2tPzdeF5PRrayr28" "https://fabricate.tonic.ai/api/v1/workspaces/workspace1/projects/project1/versions/v1/sandboxes/sandbox1/api/patients"`

## Creating a sandbox <a href="#sandbox-create" id="sandbox-create"></a>

To create a sandbox, you connect to the sandbox URL with a new sandbox name.

When Fabricate detects the new name, it creates a sandbox with that name.

If your account already has the maximum allowed number of active sandboxes, then the request returns an error indicating that the sandbox cannot be created because of the limit.

If the call uses the name of an active sandbox, then Fabricate connects to that sandbox.

## Deleting an active sandbox <a href="#sandbox-delete" id="sandbox-delete"></a>

Sandboxes expire and are deleted automatically after an hour.

Before that, to delete an active sandbox, on the **Sandboxes** page, click the delete icon for the sandbox.

## Using REST API endpoints to manage sandboxes <a href="#sandbox-rest-api" id="sandbox-rest-api"></a>

You can also use REST API endpoints to create and manage sandboxes.

### Base path

The base path for REST API requests is:

`/api/v1/workspaces/{workspace}/projects/{project}[/versions/{version_label}]/sandboxes/`

To refer to a specific sandbox:

`/api/v1/workspaces/{workspace}/projects/{project}[/versions/{version_label}]/sandboxes/{sandbox_id}`

### Endpoints

The REST API includes the following endpoints:

| `GET .../sandboxes`                     | Returns the list of active sandboxes.                                                                                                                                       |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PUT .../sandboxes/{sandbox_id}`        | <p>If the sandbox identifier matches an active sandbox, returns the sandbox.</p><p><br>If the sandbox identifier does not match an active sandbox, creates the sandbox.</p> |
| `POST .../sandboxes/{sandbox_id}/reset` | Resets the data in the sandbox.                                                                                                                                             |
| `DELETE .../sandboxes/{sandbox_id}`     | Deletes the sandbox.                                                                                                                                                        |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tonic.ai/fabricate/data-agent-tools/project-api/sandboxes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.