API Reference

Agent

Endpoints for managing Pickaxes and agent definitions.

Related In Learn

Agent Builder

Learn how to use the Agent Builder to create and configure AI agents with the AI Helper, Editor, and Preview.

Open Learn

Agent endpoints manage Pickaxes and agent definitions inside a workspace.

Endpoints

GET /studio/pickaxe/list

List Pickaxes in the current workspace.

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

Request Fields

This endpoint does not define request body fields.

Examples

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

Response Shape

{
  "data": [
    {
      "pickaxeId": "fitness-tracker-agent",
      "name": "Fitness Tracker Agent",
      "description": "Tracks workouts, nutrition, goals, recovery, and progress with structured coaching.",
      "type": "chat",
      "privacy": "private",
      "model": "grok-4.20-reasoning-latest",
      "updatedAt": "2026-04-07T19:48:02.631000"
    }
  ]
}

POST /studio/pickaxe/history

Fetch specific Pickaxe chat history.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/history

Request Fields

pickaxeId (string, required): The unique identifier for the Pickaxe whose chat history you want to retrieve.
userId (string, optional): Optional user identifier or email to filter history by user instead of Pickaxe.
skip (number, optional): The number of recent conversations to skip. Defaults to 0.
limit (number, optional): The maximum number of recent conversations to return. Defaults to 10.
lastDays (number, optional): Optional filter for conversations updated within the last N days.
format (string, optional): The desired output format for the chat history. Can be "raw" or "messages". Defaults to "messages".

Examples

curl -X POST https://api.pickaxe.co/v1/studio/pickaxe/history \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "pickaxeId": "MY_FORM_ID",
  "skip": 0,
  "limit": 5,
  "format": "messages"
}'

GET /studio/pickaxe/<pickaxe_id>/documents

List all knowledge-base documents currently attached to a specific Pickaxe.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>/documents

Request Fields

pickaxeId (string, required): The unique identifier for the Pickaxe whose attached documents you want to retrieve.

Examples

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

GET /studio/pickaxe/<pickaxe_id>

Get the full Studio API representation of a Pickaxe, including generic configuration fields and attached documents.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>

Request Fields

pickaxeId (string, required): The unique identifier for the Pickaxe you want to retrieve.

Examples

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

POST /studio/pickaxe/create

Create a new Pickaxe with generic Pickaxe fields and optionally attach existing document IDs. Use type to create chat, form, or form-chat Pickaxes. Actions and MCP server configuration are not supported in the Studio API.

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

Request Fields

pickaxeId (string, optional): Optional custom Pickaxe ID. If omitted, one will be generated automatically.
documentIds (string[], optional): Optional list of existing Studio document IDs to attach when the Pickaxe is created.
data (object, optional): Generic Pickaxe fields to create. Most non-system Pickaxe fields are supported. Common fields are shown below.
- type ("chat" | "form" | "form-chat", optional): Friendly creation mode. chat creates a normal chat Pickaxe, form creates a form-only Pickaxe, and form-chat creates a form with chat responses enabled. Defaults to "chat".
- name (string, optional): Alias for formtitle.
- description (string, optional): Alias for formdescription.
- prompt (string, optional): Alias for role.
- privacy (string, optional): Alias for privacysetting.
- formtitle (string, optional): The Pickaxe title.
- formdescription (string, optional): The Pickaxe description.
- role (string, optional): The Pickaxe system prompt.
- model (string, optional): The model slug to use for the Pickaxe.
- chatflag (boolean, optional): Whether the Pickaxe is a chat Pickaxe.
- promptframe (string, optional): Prompt frame string for form inputs. Embed each input as JSON with an id like userinput:email. The alias promptFrame is also accepted.
  - id (string, required): Input ID embedded in the prompt frame. It should be prefixed with userinput:, for example userinput:email.
  - main (string, required): Visible label for the input field.
  - secondary (string, optional): User Input Placeholder text from the Builder Configure tab. This is the empty-state placeholder, not a default answer.
  - answerlength (number, optional): Input size hint. Short answer inputs commonly use 90, while longer text inputs can use larger values. Defaults to 90.
  - example (string, optional): Prefilled/default answer value. For Multiple Choice and Checkbox fields, join options with S3P32X.
  - type ("Short Answer" | "Long Answer" | "Multiple Choice" | "Checkbox", required): The Builder input type.
  - isRequired (boolean, optional): Whether the user must complete this input before submitting. Defaults to true.
  - isDropdown (boolean, optional): Whether a Multiple Choice field should render as a dropdown instead of another selection UI. Defaults to false.
- promptFrame (string, optional): Alias for promptframe. Use this spelling for CLI-style manifests and API requests.
- placeholdertext (string, optional): Placeholder text shown in the input UI.
- submitText (string | null, optional): Alias for submittext, shown on form submit buttons.
- documentuploadtype (string, optional): Document upload mode for the Pickaxe.
- icebreakers (string[], optional): Optional starter prompts shown to the end user.
- reasoningeffort (string, optional): Optional reasoning effort value for supported reasoning models.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/pickaxe/create \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "pickaxeId": "my-studio-bot",
  "documentIds": ["DOC123", "DOC456"],
  "data": {
    "type": "form-chat",
    "name": "My Studio Bot",
    "description": "Answers questions about our product and docs.",
    "prompt": "You are a helpful product specialist.",
    "model": "gpt-5",
    "promptFrame": "Email: {\"id\":\"userinput:email\",\"main\":\"Email\",\"secondary\":\"Enter your email\",\"answerlength\":90,\"example\":\"\",\"type\":\"Short Answer\",\"isRequired\":true,\"isDropdown\":false}",
    "placeholdertext": "Ask anything...",
    "documentuploadtype": "ownerupload",
    "submitText": "Submit"
  }
}'

POST /studio/pickaxe/build

Ask the experimental AI builder to propose or apply Pickaxe configuration changes. This route can materialize formFields into a prompt frame, but deterministic create/update calls should send promptFrame directly.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/build

Request Fields

pickaxeId (string, required): The existing Pickaxe ID to modify.
prompt (string, required): Natural-language build request. The alias message is also accepted.
apply (boolean, optional): When false, the response returns a review/change set only. When true, accepted changes are written to the Pickaxe. Defaults to false.
formFields (object[], optional): Can appear inside the AI-generated change set when the builder decides to create form inputs. Fields are normalized into promptFrame before being saved.
- id (string, required): Input ID embedded in the prompt frame. It should be prefixed with userinput:, for example userinput:email.
- main (string, required): Visible label for the input field.
- secondary (string, optional): User Input Placeholder text from the Builder Configure tab. This is the empty-state placeholder, not a default answer.
- answerlength (number, optional): Input size hint. Short answer inputs commonly use 90, while longer text inputs can use larger values. Defaults to 90.
- example (string, optional): Prefilled/default answer value. For Multiple Choice and Checkbox fields, join options with S3P32X.
- type ("Short Answer" | "Long Answer" | "Multiple Choice" | "Checkbox", required): The Builder input type.
- isRequired (boolean, optional): Whether the user must complete this input before submitting. Defaults to true.
- isDropdown (boolean, optional): Whether a Multiple Choice field should render as a dropdown instead of another selection UI. Defaults to false.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/pickaxe/build \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "pickaxeId": "my-studio-bot",
  "prompt": "Turn this into a form-chat intake with Email and Details fields.",
  "apply": false
}'

Response Shape

{
  "success": true,
  "data": {
    "experimental": true,
    "mode": "build",
    "pickaxeId": "my-studio-bot",
    "summary": "Adds form intake fields.",
    "changeSet": {
      "pickaxePatch": {
        "type": "form-chat",
        "formFields": [
          {
            "id": "userinput:email",
            "main": "Email",
            "secondary": "Enter your email",
            "answerlength": 90,
            "example": "",
            "type": "Short Answer",
            "isRequired": true,
            "isDropdown": false
          }
        ]
      }
    },
    "applied": false
  }
}

PATCH /studio/pickaxe/<pickaxe_id>

Update generic Pickaxe configuration fields and optionally replace, add, or remove attached document IDs. Actions and MCP server configuration are not supported in the Studio API.

Full URL: https://api.pickaxe.co/v1/studio/pickaxe/<pickaxe_id>

Request Fields

pickaxeId (string, required): The unique identifier for the Pickaxe you want to update.
documentIds (string[], optional): If provided, replaces the Pickaxe's attached documents with exactly this set.
addDocumentIds (string[], optional): Optional list of document IDs to add without replacing the existing attachments.
removeDocumentIds (string[], optional): Optional list of document IDs to remove without replacing the entire attachment set.
data (object, optional): The generic Pickaxe fields to update. You can use raw Pickaxe field names such as formtitle/formdescription, or the aliases name/description.
- type ("chat" | "form" | "form-chat", optional): Friendly type update. Updates chatflag and enablechatresponses to match the requested mode.
- name (string, optional): Alias for formtitle.
- description (string, optional): Alias for formdescription.
- prompt (string, optional): Alias for role.
- privacy (string, optional): Alias for privacysetting.
- formtitle (string, optional): The Pickaxe title.
- formdescription (string, optional): The Pickaxe description.
- role (string, optional): The system prompt for the Pickaxe.
- model (string, optional): The model slug to use for the Pickaxe.
- chatflag (boolean, optional): Whether the Pickaxe is a chat Pickaxe.
- placeholdertext (string, optional): Placeholder text shown in the input UI.
- promptFrame (string, optional): Alias for promptframe. Use this to update form inputs by sending a prompt frame string with embedded userinput JSON.
  - id (string, required): Input ID embedded in the prompt frame. It should be prefixed with userinput:, for example userinput:email.
  - main (string, required): Visible label for the input field.
  - secondary (string, optional): User Input Placeholder text from the Builder Configure tab. This is the empty-state placeholder, not a default answer.
  - answerlength (number, optional): Input size hint. Short answer inputs commonly use 90, while longer text inputs can use larger values. Defaults to 90.
  - example (string, optional): Prefilled/default answer value. For Multiple Choice and Checkbox fields, join options with S3P32X.
  - type ("Short Answer" | "Long Answer" | "Multiple Choice" | "Checkbox", required): The Builder input type.
  - isRequired (boolean, optional): Whether the user must complete this input before submitting. Defaults to true.
  - isDropdown (boolean, optional): Whether a Multiple Choice field should render as a dropdown instead of another selection UI. Defaults to false.
- submitText (string | null, optional): Alias for submittext, shown on form submit buttons.
- documentuploadtype (string, optional): Document upload mode for the Pickaxe.

Examples

curl -X PATCH https://api.pickaxe.co/v1/studio/pickaxe/EXAMPLEPICKAXEID \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "addDocumentIds": ["DOC789"],
  "removeDocumentIds": ["DOC123"],
  "data": {
    "formtitle": "My Updated Pickaxe",
    "formdescription": "Now covers support and onboarding questions.",
    "role": "You are a helpful assistant who gives concise answers.",
    "model": "gpt-5"
  }
}'

Completions

Action