Agent

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. 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.
  • 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 / starter messages JSON string for the Pickaxe.
  • placeholdertext (string, optional): Placeholder text shown in the input UI.
  • 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": {
    "formtitle": "My Studio Bot",
    "formdescription": "Answers questions about our product and docs.",
    "role": "You are a helpful product specialist.",
    "model": "gpt-5",
    "chatflag": true,
    "promptframe": "[]",
    "placeholdertext": "Ask anything...",
    "documentuploadtype": "ownerupload"
  }
}'

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.
  • name (string, optional): Alias for formtitle.
  • description (string, optional): Alias for formdescription.
  • 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.
  • 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"
  }
}'