> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/stormkit-io/stormkit-io/llms.txt
> Use this file to discover all available pages before exploring further.

# Snippets

> Inject custom code snippets into your deployed pages

The Snippets API allows you to inject custom HTML, JavaScript, or CSS into your deployed pages. This is useful for analytics, tracking pixels, custom scripts, and more.

## List Snippets

<ParamField path="GET /v1/snippets" type="endpoint">
  Retrieve all snippets for an environment.
</ParamField>

### Query Parameters

<ParamField query="afterId" type="string">
  Pagination cursor for retrieving the next page
</ParamField>

<ParamField query="hosts" type="string">
  Filter by comma-separated hostnames
</ParamField>

<ParamField query="title" type="string">
  Filter by snippet title (URL-encoded)
</ParamField>

### Response

<ResponseField name="snippets" type="array">
  Array of snippet objects

  <Expandable title="Snippet Object">
    <ResponseField name="id" type="string">
      Unique snippet identifier
    </ResponseField>

    <ResponseField name="title" type="string">
      Snippet title for internal reference
    </ResponseField>

    <ResponseField name="content" type="string">
      HTML/JavaScript/CSS content to inject
    </ResponseField>

    <ResponseField name="enabled" type="boolean">
      Whether the snippet is active
    </ResponseField>

    <ResponseField name="location" type="string">
      Injection location: "head" or "body"
    </ResponseField>

    <ResponseField name="prepend" type="boolean">
      If true, inject as first child; otherwise as last child
    </ResponseField>

    <ResponseField name="rules" type="object" optional>
      Conditional injection rules

      <Expandable title="Rules Object">
        <ResponseField name="hosts" type="array">
          Hostnames to inject on (supports wildcards like "\*.dev")
        </ResponseField>

        <ResponseField name="path" type="string">
          Path pattern to match for injection
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination">
    <ResponseField name="hasNextPage" type="boolean">
      Whether more results are available
    </ResponseField>

    <ResponseField name="afterId" type="string" optional>
      Cursor for next page
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET \
    -H 'Authorization: <api_key>' \
    -H 'Content-Type: application/json' \
    'https://api.stormkit.io/v1/snippets'
  ```

  ```json Response theme={null}
  {
    "snippets": [
      {
        "id": "1501",
        "title": "Google Analytics",
        "content": "<script async src='https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID'></script>",
        "enabled": true,
        "prepend": false,
        "location": "head",
        "rules": {
          "hosts": ["example.org", "*.dev"],
          "path": "/"
        }
      }
    ],
    "pagination": {
      "hasNextPage": false
    }
  }
  ```
</CodeGroup>

***

## Create Snippet

<ParamField path="POST /v1/snippets" type="endpoint">
  Add one or more snippets to an environment.
</ParamField>

### Request Body

<ParamField body="snippets" type="array" required>
  Array of snippet objects to create

  <Expandable title="Snippet Object">
    <ParamField body="title" type="string" required>
      Descriptive title for internal use
    </ParamField>

    <ParamField body="content" type="string" required>
      HTML/JavaScript/CSS content to inject
    </ParamField>

    <ParamField body="enabled" type="boolean" required>
      Whether the snippet should be active
    </ParamField>

    <ParamField body="location" type="string" required>
      Injection point: "head" or "body"
    </ParamField>

    <ParamField body="prepend" type="boolean" required>
      If true, inject as first child; otherwise as last child
    </ParamField>

    <ParamField body="rules" type="object">
      Conditional injection rules

      <Expandable title="Rules Object">
        <ParamField body="hosts" type="array">
          Hostnames to inject on
        </ParamField>

        <ParamField body="path" type="string">
          Path pattern to match
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="snippets" type="array">
  Array of created snippet objects with IDs
</ResponseField>

### Status Codes

* **201**: Snippet created successfully
* **400**: Invalid snippet parameters
* **409**: Duplicate snippet content in environment

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST \
    -H 'Authorization: <api_key>' \
    -H 'Content-Type: application/json' \
    'https://api.stormkit.io/v1/snippets' \
    -d '{
      "snippets": [
        {
          "title": "Google Analytics",
          "content": "<script>console.log('Analytics loaded')</script>",
          "enabled": true,
          "prepend": false,
          "location": "head",
          "rules": {
            "hosts": ["example.org", "*.dev"],
            "path": "/"
          }
        }
      ]
    }'
  ```

  ```json Response theme={null}
  {
    "snippets": [
      {
        "id": "1501",
        "title": "Google Analytics",
        "content": "<script>console.log('Analytics loaded')</script>",
        "enabled": true,
        "prepend": false,
        "location": "head",
        "rules": {
          "hosts": ["example.org", "*.dev"],
          "path": "/"
        }
      }
    ]
  }
  ```
</CodeGroup>

***

## Update Snippet

<ParamField path="PUT /v1/snippets" type="endpoint">
  Update an existing snippet.
</ParamField>

### Request Body

<ParamField body="snippet" type="object" required>
  Snippet object with updated values

  <Expandable title="Snippet Object">
    <ParamField body="id" type="string" required>
      ID of the snippet to update
    </ParamField>

    <ParamField body="title" type="string" required>
      Updated title
    </ParamField>

    <ParamField body="content" type="string" required>
      Updated content
    </ParamField>

    <ParamField body="enabled" type="boolean" required>
      Whether the snippet is active
    </ParamField>

    <ParamField body="location" type="string" required>
      Injection location
    </ParamField>

    <ParamField body="prepend" type="boolean" required>
      Prepend or append
    </ParamField>

    <ParamField body="rules" type="object">
      Updated rules
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="ok" type="boolean">
  Whether the update was successful
</ResponseField>

### Status Codes

* **200**: Snippet updated successfully
* **400**: Invalid snippet parameters
* **409**: Duplicate snippet content in environment

<CodeGroup>
  ```bash Request theme={null}
  curl -X PUT \
    -H 'Authorization: <api_key>' \
    -H 'Content-Type: application/json' \
    'https://api.stormkit.io/v1/snippets' \
    -d '{
      "snippet": {
        "id": "1501",
        "title": "Updated Analytics",
        "content": "<script>console.log('Updated')</script>",
        "enabled": true,
        "prepend": false,
        "location": "head",
        "rules": {
          "hosts": ["example.org"],
          "path": "/"
        }
      }
    }'
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

***

## Delete Snippets

<ParamField path="DELETE /v1/snippets" type="endpoint">
  Delete one or more snippets by ID.
</ParamField>

<Warning>
  You can delete a maximum of 100 snippets at a time.
</Warning>

### Query Parameters

<ParamField query="ids" type="string" required>
  Comma-separated snippet IDs to delete
</ParamField>

### Response

<ResponseField name="ok" type="boolean">
  Whether the deletion was successful
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE \
    -H 'Authorization: <api_key>' \
    -H 'Content-Type: application/json' \
    'https://api.stormkit.io/v1/snippets?ids=1501,5061'
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

***

## Snippet Configuration

### Injection Locations

* **head**: Inject into the `<head>` element
* **body**: Inject into the `<body>` element

### Prepend vs Append

* **prepend: true**: Inject as the first child of the location element
* **prepend: false**: Inject as the last child of the location element

### Rules

Snippets can be conditionally injected based on:

* **hosts**: Specific domain names or wildcard patterns
* **path**: URL path pattern matching

### Development Endpoints

To inject snippets on all development/preview deployments, use the wildcard pattern:

```json theme={null}
{
  "rules": {
    "hosts": ["*.dev"]
  }
}
```

<Note>
  Specifying an individual deployment endpoint will enable the snippet for all development endpoints.
</Note>

***

## Common Use Cases

### Google Analytics

```json theme={null}
{
  "title": "Google Analytics",
  "content": "<script async src='https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID'></script><script>window.dataLayer = window.dataLayer || [];function gtag(){dataLayer.push(arguments);}gtag('js', new Date());gtag('config', 'GA_MEASUREMENT_ID');</script>",
  "enabled": true,
  "location": "head",
  "prepend": false,
  "rules": {
    "hosts": ["example.org"]
  }
}
```

### Custom CSS

```json theme={null}
{
  "title": "Custom Styles",
  "content": "<style>.custom-banner { background: #8B5CF6; color: white; }</style>",
  "enabled": true,
  "location": "head",
  "prepend": true
}
```

### Tracking Pixel

```json theme={null}
{
  "title": "Facebook Pixel",
  "content": "<script>!function(f,b,e,v,n,t,s){...}(window,document,'script','https://connect.facebook.net/en_US/fbevents.js');</script>",
  "enabled": true,
  "location": "head",
  "prepend": false,
  "rules": {
    "path": "/landing"
  }
}
```

### Chat Widget

```json theme={null}
{
  "title": "Support Chat",
  "content": "<script src='https://chat.example.com/widget.js'></script>",
  "enabled": true,
  "location": "body",
  "prepend": false
}
```