API Reference

Deployment

Endpoints for API deployments and deployment-level sharing settings.

Related In Learn

Deployments Overview

Learn about the different ways to deploy and share your agents with the world.

Open Learn

Deployment endpoints manage API deployments and deployment-level sharing settings.

Endpoints

GET /studio/deployment/list

List deployments in the current workspace.

Full URL: https://api.pickaxe.co/v1/studio/deployment/list

Request Fields

This endpoint does not define request body fields.

Examples

curl -X GET https://api.pickaxe.co/v1/studio/deployment/list \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Response Shape

{
  "success": true,
  "data": [
    {
      "deploymentId": "deployment-6cdc2c26-2a9b-4f7d-8126-fd58913ab5a4",
      "name": "billing-bot (Direct Link)",
      "type": "direct-link",
      "visibility": "public",
      "formId": "billing-bot",
      "pickaxeName": "billing-bot",
      "path": "deployment-6cdc2c26-2a9b-4f7d-8126-fd58913ab5a4",
      "headerScript": "<script>window.analyticsReady = true;</script>",
      "footerScript": "<script src=\"https://cdn.example.com/widget.js\"></script>",
      "createdAt": "2026-04-15T00:41:00.000000",
      "updatedAt": "2026-04-15T00:52:00.000000"
    }
  ]
}

POST /studio/deployment/create

Create a new public deployment for an existing Pickaxe in the caller's workspace.

Full URL: https://api.pickaxe.co/v1/studio/deployment/create

Request Fields

formId (string, required): The Pickaxe ID to deploy. You can also send this as formid or pickaxeId.
deploymentType (string, required): The deployment type to create. Accepted canonical types are embed-script-inline, embed-iframe-inline, embed-script-fab, embed-script-popup, and direct-link.
deploymentId (string, optional): Provide your own deployment ID instead of letting Pickaxe generate one.
headerScript (string, optional): Custom HTML or JavaScript injected before the embed or direct-link body. Supported only for embed and direct-link deployments.
footerScript (string, optional): Custom HTML or JavaScript injected after the embed or direct-link body. Supported only for embed and direct-link deployments.

Type Aliases

For convenience, deploymentType also accepts these aliases:

inline -> embed-script-inline
iframe -> embed-iframe-inline
fab -> embed-script-fab
popup -> embed-script-popup
direct-link -> direct-link

Notes

headerScript and footerScript are stored directly on the deployment.
Embed deployments automatically include default dimensions in the saved deployment document.
headerScript and footerScript are rejected for unsupported deployment types.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/deployment/create \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "formId": "billing-bot",
  "deploymentType": "embed-script-inline",
  "headerScript": "<script>window.billingBotHeader = true;</script>",
  "footerScript": "<script src=\"https://cdn.example.com/billing-bot-footer.js\"></script>"
}'

Response Shape

{
  "success": true,
  "data": {
    "deploymentId": "deployment-4d3e4762-d1b7-4a78-b2b3-0d94047bafab",
    "name": "billing-bot (Inline Embed)",
    "type": "embed-script-inline",
    "visibility": "public",
    "formId": "billing-bot",
    "path": "",
    "headerScript": "<script>window.billingBotHeader = true;</script>",
    "footerScript": "<script src=\"https://cdn.example.com/billing-bot-footer.js\"></script>",
    "dimensions": {
      "width": {
        "value": 100,
        "unit": "%"
      },
      "height": {
        "value": 500,
        "unit": "px"
      },
      "minHeight": 500,
      "maxWidth": 700,
      "maxHeight": 500
    },
    "createdAt": "2026-04-15T00:41:00.000000",
    "updatedAt": "2026-04-15T00:41:00.000000"
  }
}

POST /studio/deployment/update

Update the custom header and footer injection code for an existing deployment.

Full URL: https://api.pickaxe.co/v1/studio/deployment/update

Request Fields

deploymentId (string, required): The deployment to update.
headerScript (string | null, optional): Replace the deployment header script. Send null to clear it.
footerScript (string | null, optional): Replace the deployment footer script. Send null to clear it.

Notes

You must send at least one of headerScript or footerScript.
This endpoint only supports embed deployments and direct-link deployments.
Whitespace-only script values are treated as empty and stored as null.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/deployment/update \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "deploymentId": "deployment-4d3e4762-d1b7-4a78-b2b3-0d94047bafab",
  "headerScript": "<script>window.billingBotHeader = \"v2\";</script>",
  "footerScript": null
}'

Response Shape

{
  "success": true,
  "data": {
    "deploymentId": "deployment-4d3e4762-d1b7-4a78-b2b3-0d94047bafab",
    "name": "billing-bot (Inline Embed)",
    "type": "embed-script-inline",
    "visibility": "public",
    "formId": "billing-bot",
    "path": "",
    "headerScript": "<script>window.billingBotHeader = \"v2\";</script>",
    "footerScript": null,
    "dimensions": {
      "width": {
        "value": 100,
        "unit": "%"
      },
      "height": {
        "value": 500,
        "unit": "px"
      },
      "minHeight": 500,
      "maxWidth": 700,
      "maxHeight": 500
    },
    "createdAt": "2026-04-15T00:41:00.000000",
    "updatedAt": "2026-04-15T00:52:00.000000"
  }
}

GET /studio/deployment/{deploymentId}/rendered-html

Render an embed deployment in a headless browser and return the resulting DOM.

Full URL: https://api.pickaxe.co/v1/studio/deployment/{deploymentId}/rendered-html

Request Fields

deploymentId (string, required): The deployment ID in the path. Only embed deployments can be rendered.
timeoutMs (number, optional): Maximum render time in milliseconds. Defaults to 20000.
viewportWidth (number, optional): Browser viewport width used for rendering. Defaults to 1280.
viewportHeight (number, optional): Browser viewport height used for rendering. Defaults to 900.
includeGeometry (boolean, optional): Include element bounding boxes and computed layout metadata. Defaults to true.

Notes

Only embed deployments can be rendered.
Inline embed types return one preOpen state.
Multi-state embed types return both preOpen and postOpen states when possible. This includes FAB, pop-up, and chat-input deployments.
postOpen is captured after the renderer clicks the visible launch control.
The response includes the full document HTML, the deployment root HTML, iframe/frame HTML, browser console messages, request failures, and optional geometry data.

Examples

curl -X GET "https://api.pickaxe.co/v1/studio/deployment/deployment-d0fbdda9-6d3e-4865-b17d-da4d80da9025/rendered-html?includeGeometry=true&viewportWidth=1280&viewportHeight=900" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Response Shape

{
  "success": true,
  "data": {
    "deploymentId": "deployment-d0fbdda9-6d3e-4865-b17d-da4d80da9025",
    "type": "embed-script-fab",
    "html": "<html>...</html>",
    "deploymentHtml": "<div id=\"deployment-d0fbdda9-6d3e-4865-b17d-da4d80da9025\" class=\"pickaxe-embed\">...</div>",
    "states": [
      {
        "name": "preOpen",
        "html": "<html>...</html>",
        "deploymentHtml": "<div id=\"deployment-d0fbdda9-6d3e-4865-b17d-da4d80da9025\">...</div>",
        "snapshot": {},
        "frames": []
      },
      {
        "name": "postOpen",
        "html": "<html>...</html>",
        "deploymentHtml": "<div id=\"deployment-d0fbdda9-6d3e-4865-b17d-da4d80da9025\">...</div>",
        "snapshot": {},
        "frames": []
      }
    ],
    "consoleMessages": [],
    "requestFailures": [],
    "pageErrors": []
  }
}

CLI Workflow

If you are using the Pickaxe CLI, the same deployment functionality is available without hand-writing these requests.

Create a deployment with injected scripts

pickaxe deploy create \
  --key website \
  --header-script-file embeds/header.html \
  --footer-script-file embeds/footer.html

Update an existing deployment's injected scripts

pickaxe deploy update \
  --key website \
  --header-script-file embeds/header.html \
  --footer-script-file embeds/footer.html

Render the final local embed snippet

pickaxe deploy snippet --key website

Manifest Example

deployments:
  - key: website
    type: embed-script-inline
    headerScriptFile: embeds/header.html
    footerScriptFile: embeds/footer.html

Document

Portal