Skip to main content
API Documentation

API reference

Create sandboxes with code
API

Here you can learn how to use CodeSandbox programmatically

Import Local projects via CLI

You can import a local project in to CodeSandbox by using our CLI.

You can install our CLI by running npm install -g codesandbox. Then import a project by running codesandbox {directory}.

Example usage

$ npm install -g codesandbox
$ codesandbox ./

Define API

We offer an API that allows you to programmatically create a sandbox. This is useful for documentation, enabling you to generate a sandbox on the fly from code examples. You can call the endpoint https://codesandbox.stream/api/v1/sandboxes/define both with a GET and with a POST request.

Supported Parameters

We currently support three extra parameters. The query accepts the same options as the embed options.

Query Parameter Description Example Input
parameters Parameters used to define how the sandbox should be created. Example below
query The query that will be used in the redirect url. view=preview&runonclick=1
embed Whether we should redirect to the embed instead of the editor. 1
json Instead of redirecting we will send a JSON reponse with {"sandbox_id": sandboxId}. 1

How it works

The API only needs one argument: files. This argument contains the files that will be in the sandbox, an example body would be:

{
  "files": {
    "index.js": {
      "content": "console.log('hello!')",
      "isBinary": false
    },
    "package.json": {
      "content": {
        "dependencies": {}
      }
    }
  }
}

You can import binary files by setting isBinary to true and content as a URL to the file hosted externally. For example:

{
  "isBinary": true,
  "content": "https://..."
}

Every request requires a package.json. This file can either be a string or an object. We determine all information of the sandbox from the files, like we do with the GitHub import.

GET Request

It's very hard to send the JSON parameters with a GET request, there is a chance of unescaped characters and the URL hits its limit of ~2000 characters quickly. That's why we first compress the files to a compressed lz-string. We offer a utility function in the codesandbox dependency for this. The implementation looks like this:

import { getParameters } from 'codesandbox/lib/api/define';

const parameters = getParameters({
  files: {
    'index.js': {
      content: "console.log('hello')",
    },
    'package.json': {
      content: { dependencies: {} },
    },
  },
});

const url = `https://codesandbox.stream/api/v1/sandboxes/define?parameters=${parameters}`;

Example Sandbox

POST Form

You can do the exact same steps for a POST request, but instead of a URL you'd show a form. With a POST request you can create bigger sandboxes.

Example Sandbox

Define without render

If you want to define a new sandbox without getting it rendered, you can add ?json=1 to the request. For instance https://codesandbox.stream/api/v1/sandboxes/define?json=1. Instead of the render, the result will be json data providing you with the sandbox_id of the new sandbox.

This is useful, for instance, if you need to create a new sandbox programmatically, so you can then embed it on your site (See Embed documentation).

Both get and post requests are supported.

XHR Request

You can also create a sandbox using an XHR request, like using fetch. An example sandbox of that is here:

Import Single Components

You can import a local component in to CodeSandbox by using our other CLI.

You can install our CLI by running npm install -g codesandboxer-fs. Then you can export a project by running codesandboxer {filePath}.

$ npm install -g codesandboxer-fs
$ codesandboxer docs/examples/my-single-component.js

This will print out the id of a sandbox that does nothing but render the targeted component, along with a link to that sandbox. This will also bundle in other local files used by the component to ensure render.

Setting inference

When importting, we infer sandbox settings based on several files in a repository.

Sandbox Setting Inferred from
Title name field in package.json
Description description field in package.json
Tags keywords field in package.json
Template Based on this logic

If the correct template isn't automatically being used when importing, then you may specify a template property in your ./sandbox.config.json file to override the detected template.

{
  "template": "node"
}