Pickaxe Learn

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"
  }
}

POST /deployment/email/weekly-summary/bootstrap

Start a private Wingman email session for a workspace member. This specialized endpoint uses an invisible trigger and also prepares the email thread, workspace credential context, and recurring summary schedule. Use POST /v1/triggers for general invisible API-deployment turns. The synthetic user turn is hidden from conversation history and deployment webhooks; only the generated report is emailed. Authenticate with a workspace API key, not the deployment ID. The request returns with status: "starting" while generation and scheduling continue asynchronously.

  • Full URL: https://pickaxe-api2.pickaxe.co/deployment/email/weekly-summary/bootstrap

Request Fields

  • deploymentId (string, required): The public Wingman email deployment to use for the report and subsequent email thread.
  • recipientEmail (string, required): The workspace owner or member who receives the report. The email must belong to the workspace identified by the Bearer API key.
  • timezone (string, optional): An IANA timezone used when the agent creates and describes the recurring schedule, for example America/New_York. Defaults to UTC.
  • reportInstructions (string, optional): Workspace-owner preferences for what each report should emphasize. The value is treated only as report-content guidance and is limited to 2,000 characters.
  • subject (string, optional): Optional subject for the initial email thread. A cadence-aware workspace summary subject is generated when omitted.
  • force (boolean, optional): Start a new bootstrap attempt even when a session already exists. Normally leave this false so active sessions are reused and concurrent setup attempts return 409. Defaults to false.

Examples

curl -X POST https://pickaxe-api2.pickaxe.co/deployment/email/weekly-summary/bootstrap \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_WORKSPACE_API_KEY" \
-d '{
  "deploymentId": "deployment-b651428f-32f0-4094-b86e-d17768bc9af5",
  "recipientEmail": "owner@example.com",
  "timezone": "America/New_York",
  "reportInstructions": "Prioritize adoption, errors, and cost trends."
}'

Response Shape

{
  "success": true,
  "alreadyActive": false,
  "status": "starting",
  "cadence": "daily",
  "sessionId": "deployment-example-workspace-example-owner@example.com",
  "recipientEmail": "owner@example.com",
  "reportInstructions": "Prioritize adoption, errors, and cost trends."
}

POST /deployment/email/weekly-summary/disable

Cancel the recurring workspace summary in the same Wingman email session. The endpoint sends a private cancellation turn on the caller's behalf, so no synthetic user message or internal scheduling command appears in the email thread. Authenticate with the same workspace API key used to start the summary. A disabling response means cancellation has started asynchronously; disabled means no active schedule remains.

  • Full URL: https://pickaxe-api2.pickaxe.co/deployment/email/weekly-summary/disable

Request Fields

  • deploymentId (string, required): The Wingman email deployment associated with the existing summary session.
  • recipientEmail (string, required): The workspace owner or member whose recurring summary should be cancelled.

Examples

curl -X POST https://pickaxe-api2.pickaxe.co/deployment/email/weekly-summary/disable \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_WORKSPACE_API_KEY" \
-d '{
  "deploymentId": "deployment-b651428f-32f0-4094-b86e-d17768bc9af5",
  "recipientEmail": "owner@example.com"
}'

Response Shape

{
  "success": true,
  "alreadyDisabled": false,
  "status": "disabling",
  "sessionId": "deployment-example-workspace-example-owner@example.com",
  "recipientEmail": "owner@example.com"
}

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

Previous

Document

Next

Portal