Pickaxe Learn

API Reference

Action

Endpoints for managing actions attached to Pickaxes and Agents.

Related In Learn

Actions

Connect your agents to external tools, APIs, and other agents so they can take real actions.

Open Learn

Action endpoints manage actions attached to Pickaxes and Agents.

Endpoints

GET /studio/action/list?pickaxeId=<pickaxe_id>

List available actions and actions attached to a Pickaxe.

  • Full URL: https://api.pickaxe.co/v1/studio/action/list?pickaxeId=<pickaxe_id>

Request Fields

  • pickaxeId (string, required): The Pickaxe ID to inspect for currently attached and available actions.

Examples

curl -X GET "https://api.pickaxe.co/v1/studio/action/list?pickaxeId=steve-25" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Response Shape

{
  "success": true,
  "data": {
    "available": [
      {
        "actionId": "ACTIONDMU9TKI49FKPOHSJQOKI",
        "name": "get_current_time",
        "displayName": "Get Current Time",
        "description": "Gets the current time if the user asks for it.",
        "visibility": "public",
        "triggerPrompt": "",
        "isAttached": false,
        "isUsingPickaxeCredits": false,
        "variables": []
      }
    ],
    "attached": [],
    "pickaxeId": "steve-25"
  }
}

POST /studio/action/manifest

Create a new reusable Pickaxe Action from a YAML manifest. You can upload the manifest as a multipart file or send the raw manifest text.

  • Full URL: https://api.pickaxe.co/v1/studio/action/manifest

Request Fields

  • file (file, optional): Multipart file upload containing the action manifest in YAML format. Example: @conversation-summary-to-email.pickaxe-action.yaml
  • manifest (string, optional): Raw manifest text. Use this when you are not uploading a file. Either file or manifest is required.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/action/manifest \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "file=@conversation-summary-to-email.pickaxe-action.yaml"

Response Shape

{
  "success": true,
  "data": {
    "actionId": "ACTIONABCDEFGHIJKLMNOPQRST",
    "name": "conversation_summary_to_email",
    "displayName": "Conversation Summary to Email",
    "image": "",
    "description": "Sends a concise summary of the current conversation to a recipient by email.",
    "readme": "# Conversation Summary to Email\n\nThis action sends a short summary of the current conversation by email.",
    "triggerPrompt": "Use this action when the user asks to email or send a summary of the conversation.",
    "rawCode": "def conversation_summary_to_email(recipient_email: str, summary: str):\n    return \"ok\"\n",
    "category": "general",
    "visibility": "private",
    "modules": ["requests"],
    "inputs": [
      {
        "id": "recipient_email",
        "name": "Recipient Email",
        "description": "Email address that should receive the conversation summary.",
        "example": "jane@example.com",
        "type": "string",
        "isRequired": true
      }
    ],
    "variables": [
      {
        "uniqueId": "0b3feef0-7d1d-44a0-9af0-2cbe4f84f3a0",
        "id": "SENDGRID_API_KEY",
        "name": "SendGrid API Key",
        "description": "API key used to authenticate requests to SendGrid.",
        "placeholder": "Paste your SendGrid API key",
        "type": "string",
        "isSpecialDisplay": false,
        "hasValue": false,
        "maskedValue": ""
      }
    ],
    "createdAt": "2026-04-19T16:42:00.000Z",
    "updatedAt": "2026-04-19T16:42:00.000Z"
  }
}

GET /studio/action/manifest?actionId=<action_id>

Export an existing Pickaxe Action as a YAML manifest. Query by actionId or actionName. The response body is YAML, not JSON.

  • Full URL: https://api.pickaxe.co/v1/studio/action/manifest?actionId=<action_id>

Request Fields

  • actionId (string, optional): The action ID to export. Provide this or actionName.
  • actionName (string, optional): The internal action name or display name to export. Provide this or actionId. Example: conversation_summary_to_email

Examples

curl -X GET "https://api.pickaxe.co/v1/studio/action/manifest?actionId=ACTIONABCDEFGHIJKLMNOPQRST" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Response Shape

schema_version: "1.0"
kind: "pickaxe-action"
provenance:
  created_at: "2026-04-19T16:42:00+00:00"
  generated_by: "pickaxe-studio-api-export"
  author: "owner@example.com"
metadata:
  name: "conversation_summary_to_email"
  display_name: "Conversation Summary to Email"
  description: "Sends a concise summary of the current conversation to a recipient by email."
  category: "general"
  visibility: "private"
  is_cloneable: true
activation:
  default_trigger_prompt: "Use this action when the user asks to email or send a summary of the conversation."
interface:
  inputs:
    - id: "recipient_email"
      name: "Recipient Email"
      description: "Email address that should receive the conversation summary."
      example: "jane@example.com"
      type: "string"
      is_required: true
  environment_variables:
    - id: "SENDGRID_API_KEY"
      name: "SendGrid API Key"
      description: "API key used to authenticate requests to SendGrid."
      type: "string"
      is_required: true
      placeholder: "Paste your SendGrid API key"
      is_special_display: false
      provisioning: "user-provided"
implementation:
  runtime:
    language: "python"
    version: "3"
  entrypoint: "conversation_summary_to_email"
  source: |
    def conversation_summary_to_email(recipient_email: str, summary: str):
        return "ok"
  dependencies:
    python_packages:
      - "requests"
docs:
  readme_markdown: "# Conversation Summary to Email\n\nThis action sends a short summary of the current conversation by email."

PUT /studio/action/manifest?actionId=<action_id>

Update an existing Pickaxe Action from a YAML manifest. Query by actionId or actionName, then upload the replacement manifest as a multipart file or send the raw manifest text.

  • Full URL: https://api.pickaxe.co/v1/studio/action/manifest?actionId=<action_id>

Request Fields

  • actionId (string, optional): The action ID to update. Provide this or actionName.
  • actionName (string, optional): The internal action name or display name to update. Provide this or actionId. Example: conversation_summary_to_email
  • file (file, optional): Multipart file upload containing the replacement action manifest in YAML format. Example: @conversation-summary-to-email.pickaxe-action.yaml
  • manifest (string, optional): Raw manifest text. Use this when you are not uploading a file. Either file or manifest is required.

Examples

curl -X PUT "https://api.pickaxe.co/v1/studio/action/manifest?actionId=ACTIONABCDEFGHIJKLMNOPQRST" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "file=@conversation-summary-to-email.pickaxe-action.yaml"

Response Shape

{
  "success": true,
  "data": {
    "actionId": "ACTIONABCDEFGHIJKLMNOPQRST",
    "name": "conversation_summary_to_email",
    "displayName": "Conversation Summary to Email",
    "image": "",
    "description": "Sends a concise summary of the current conversation to a recipient by email.",
    "readme": "# Conversation Summary to Email\n\nThis action sends a short summary of the current conversation by email.",
    "triggerPrompt": "Use this action when the user asks to email or send a summary of the conversation.",
    "rawCode": "def conversation_summary_to_email(recipient_email: str, summary: str):\n    return \"ok\"\n",
    "category": "general",
    "visibility": "private",
    "modules": ["requests"],
    "inputs": [
      {
        "id": "recipient_email",
        "name": "Recipient Email",
        "description": "Email address that should receive the conversation summary.",
        "example": "jane@example.com",
        "type": "string",
        "isRequired": true
      }
    ],
    "variables": [
      {
        "uniqueId": "0b3feef0-7d1d-44a0-9af0-2cbe4f84f3a0",
        "id": "SENDGRID_API_KEY",
        "name": "SendGrid API Key",
        "description": "API key used to authenticate requests to SendGrid.",
        "placeholder": "Paste your SendGrid API key",
        "type": "string",
        "isSpecialDisplay": false,
        "hasValue": true,
        "maskedValue": "****************abcd"
      }
    ],
    "createdAt": "2026-04-19T16:42:00.000Z",
    "updatedAt": "2026-04-19T16:55:00.000Z"
  }
}

GET /studio/action/runs?actionId=<action_id>

List recorded action runs and logs for a custom action. You can query by actionId or actionName, filter to a specific sessionId, and page through results with cursor pagination.

  • Full URL: https://api.pickaxe.co/v1/studio/action/runs?actionId=<action_id>

Request Fields

  • actionId (string, optional): The action ID to inspect. Provide this or actionName.
  • actionName (string, optional): The internal action name or display name to inspect. Provide this or actionId. Example: conversation_summary_to_email
  • sessionId (string, optional): Optional session ID filter. Use this to return logs from one specific run session.
  • limit (number, optional): Maximum number of runs to return per page. The current maximum is 100. Defaults to 20.
  • cursor (string, optional): Pagination cursor returned as nextCursor from a previous response.

Examples

curl -X GET "https://api.pickaxe.co/v1/studio/action/runs?actionName=Conversation%20Summary%20to%20Email&sessionId=session_abc123&limit=20" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Response Shape

{
  "success": true,
  "data": {
    "actionId": "ACTIONabcdefghijklmnop1234",
    "name": "conversation_summary_to_email",
    "displayName": "Conversation Summary to Email",
    "sessionId": "session_abc123",
    "limit": 20,
    "returnedCount": 1,
    "nextCursor": null,
    "hasMore": false,
    "runs": [
      {
        "id": "6800d6d4d8d3f4b0a9d8f123",
        "actionId": "ACTIONabcdefghijklmnop1234",
        "sessionId": "session_abc123",
        "type": "action",
        "status": "success",
        "args": "{\"transcript\":\"Alice: We should ship Friday...\"}",
        "parsedArgs": {
          "transcript": "Alice: We should ship Friday..."
        },
        "content": "Summary generated successfully...",
        "createdAt": "2026-04-17T10:22:31.000Z",
        "updatedAt": "2026-04-17T10:22:31.000Z"
      }
    ]
  }
}

POST /studio/action/connect

Attach an action to a Pickaxe.

  • Full URL: https://api.pickaxe.co/v1/studio/action/connect

Request Fields

  • pickaxeId (string, required): The Pickaxe ID to attach the action to.
  • actionId (string, required): The action ID to attach.
  • triggerPrompt (string, optional): Optional trigger prompt for when the action should run.
  • isUsingPickaxeCredits (boolean, optional): Whether action execution should consume Pickaxe credits when applicable. Defaults to false.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/action/connect \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "pickaxeId": "steve-25",
  "actionId": "ACTIONDMU9TKI49FKPOHSJQOKI",
  "triggerPrompt": "optional",
  "isUsingPickaxeCredits": false
}'

Response Shape

{
  "actionId": "ACTIONDMU9TKI49FKPOHSJQOKI",
  "name": "get_current_time",
  "displayName": "Get Current Time",
  "description": "Gets the current time if the user asks for it.",
  "visibility": "public",
  "triggerPrompt": "",
  "isAttached": true,
  "isUsingPickaxeCredits": false,
  "variables": []
}

POST /studio/action/disconnect

Remove an action from a Pickaxe.

  • Full URL: https://api.pickaxe.co/v1/studio/action/disconnect

Request Fields

  • pickaxeId (string, required): The Pickaxe ID to disconnect the action from.
  • actionId (string, required): The action ID to disconnect.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/action/disconnect \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "pickaxeId": "steve-25",
  "actionId": "ACTIONDMU9TKI49FKPOHSJQOKI"
}'

Response Shape

{
  "pickaxeId": "steve-25",
  "actionId": "ACTIONDMU9TKI49FKPOHSJQOKI"
}

Previous

Agent

Next

MCP