Sandbox Custom

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
POST
GET
PATCH
DELETE
POST
POST

List all sandbox custom images

API for custom sandbox base images, built on top of the VM sandbox base via an image-builder agent.

Custom images only run on the Modal VM runtime, so every action is gated on the tasks-modal-vm-sandbox flag (org-enabled with user_created in its origin_products payload).

Required API key scopes

task:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/sandbox_custom_images
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/sandbox_custom_images/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "repository": "string",
      "private": true,
      "status": "string",
      "version": 0,
      "modal_image_name": "string",
      "spec": {},
      "spec_yaml": "string",
      "scan_result": {},
      "build_log": "string",
      "error": "string",
      "builder_task_id": "b82e5e36-095b-4d0c-93b2-7e77faa9edcc",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "string",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "string"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create sandbox custom images

Create a draft custom image and start its interactive image-builder agent task. The returned builder_task_id points at the conversation.

Required API key scopes

task:write

Request parameters

  • name
    string
  • description
    string
    Default:
  • repository
    stringnull
  • private
    boolean
    Default: false

Response


Example request

POST /api/projects/:project_id/sandbox_custom_images
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/sandbox_custom_images/\
	-d name="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "repository": "string",
  "private": true,
  "status": "string",
  "version": 0,
  "modal_image_name": "string",
  "spec": {},
  "spec_yaml": "string",
  "scan_result": {},
  "build_log": "string",
  "error": "string",
  "builder_task_id": "b82e5e36-095b-4d0c-93b2-7e77faa9edcc",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve sandbox custom images

API for custom sandbox base images, built on top of the VM sandbox base via an image-builder agent.

Custom images only run on the Modal VM runtime, so every action is gated on the tasks-modal-vm-sandbox flag (org-enabled with user_created in its origin_products payload).

Required API key scopes

task:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/sandbox_custom_images/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/sandbox_custom_images/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "repository": "string",
  "private": true,
  "status": "string",
  "version": 0,
  "modal_image_name": "string",
  "spec": {},
  "spec_yaml": "string",
  "scan_result": {},
  "build_log": "string",
  "error": "string",
  "builder_task_id": "b82e5e36-095b-4d0c-93b2-7e77faa9edcc",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Update sandbox custom images

Rename or update the description of a custom image. Only mutable metadata (name, description) is editable; the build spec and status are managed by the build flow.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • name
    string
  • description
    string

Response


Example request

PATCH /api/projects/:project_id/sandbox_custom_images/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/sandbox_custom_images/:id/\
	-d name="string"

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "repository": "string",
  "private": true,
  "status": "string",
  "version": 0,
  "modal_image_name": "string",
  "spec": {},
  "spec_yaml": "string",
  "scan_result": {},
  "build_log": "string",
  "error": "string",
  "builder_task_id": "b82e5e36-095b-4d0c-93b2-7e77faa9edcc",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Delete sandbox custom images

API for custom sandbox base images, built on top of the VM sandbox base via an image-builder agent.

Custom images only run on the Modal VM runtime, so every action is gated on the tasks-modal-vm-sandbox flag (org-enabled with user_created in its origin_products payload).

Required API key scopes

task:write

Path parameters

  • id
    string

Example request

DELETE /api/projects/:project_id/sandbox_custom_images/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/sandbox_custom_images/:id/

Example response

Status 204 No response body

Create sandbox custom images build

Persist the image spec (from the request body or the builder agent's sandbox), run the security scan, and on pass build and publish the image.

Required API key scopes

task:write

Path parameters

  • id
    string

Request parameters

  • spec_yaml
    stringnull

Response


Example request

POST /api/projects/:project_id/sandbox_custom_images/:id/build
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/sandbox_custom_images/:id/build/\
	-d spec_yaml=["string","null"]

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "repository": "string",
  "private": true,
  "status": "string",
  "version": 0,
  "modal_image_name": "string",
  "spec": {},
  "spec_yaml": "string",
  "scan_result": {},
  "build_log": "string",
  "error": "string",
  "builder_task_id": "b82e5e36-095b-4d0c-93b2-7e77faa9edcc",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create sandbox custom images builder task

Revive (or reuse) the image's builder agent session. When the previous session has ended, a fresh one is started seeded with the stored spec — use this to update an existing image.

Required API key scopes

task:write

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/sandbox_custom_images/:id/builder_task
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/sandbox_custom_images/:id/builder_task/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "repository": "string",
  "private": true,
  "status": "string",
  "version": 0,
  "modal_image_name": "string",
  "spec": {},
  "spec_yaml": "string",
  "scan_result": {},
  "build_log": "string",
  "error": "string",
  "builder_task_id": "b82e5e36-095b-4d0c-93b2-7e77faa9edcc",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "string"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Community questions