Pickaxe Learn

API Reference

Workspace

Authenticated workspace context and workspace-level metadata endpoints.

Workspace endpoints manage authenticated workspace context and workspace-level metadata.

Endpoints

PATCH /studio/update

Partially update workspace-level Studio usage settings. Usage fields are merged into the existing usage object, while each supplied package array replaces that array in full. Use usage.availableUses for a uses-based Studio and usage.availableCredits for a credits-based Studio.

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

Request Fields

  • data (object, required): Studio fields to update. The same fields may also be sent at the top level.
    • usage (object, required): Partial Studio usage configuration. Include at least one supported usage field.
      • availableUses (object[], optional): The complete list of buy-more packages when usage.isCredits is false. Each package uses { price, uses }. Supplying this field replaces the current availableUses list.
        • price (number, required): Package price. Must be finite and at least 0.
        • uses (number, required): Number of uses in the package. Must be finite and greater than 0.
      • availableCredits (object[], optional): The complete list of buy-more packages when usage.isCredits is true. Each package uses { price, credits }. Supplying this field replaces the current availableCredits list.
        • price (number, required): Package price. Must be finite and at least 0.
        • credits (number, required): Number of credits in the package. Must be finite and greater than 0.
      • isCredits (boolean, optional): The Studio billing mode. This endpoint accepts the current value but cannot change it because switching modes requires conversion of user balances and access-group limits. An attempted change returns usage_conversion_required.
      • usesPerCurrency (number | null, optional): Positive conversion multiplier used by Studio pricing controls, or null to clear it.
      • creditsPerCurrency (number | null, optional): Positive conversion multiplier used by Studio pricing controls, or null to clear it.
      • currency (string, optional): Non-empty currency code associated with the usage configuration. It is normalized to lowercase.

Examples

curl -X PATCH https://api.pickaxe.co/v1/studio/update \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "data": {
    "usage": {
      "availableUses": [
        { "price": 5, "uses": 250 },
        { "price": 10, "uses": 600 }
      ],
      "availableCredits": [
        { "price": 10, "credits": 100000 }
      ]
    }
  }
}'

Response Shape

{
  "success": true,
  "data": {
    "studioId": "studio-1NsG6mQxT4Pv",
    "usage": {
      "isCredits": false,
      "currency": "usd",
      "availableUses": [
        { "price": 5, "uses": 250 },
        { "price": 10, "uses": 600 }
      ],
      "availableCredits": [{ "price": 10, "credits": 100000 }]
    },
    "updatedAt": "2026-08-12T18:30:00Z"
  }
}

GET /studio/whoami

Return the authenticated workspace API key context.

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

Request Fields

This endpoint does not define request body fields.

Examples

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

Response Shape

{
  "data": {
    "authMode": "workspace_api_key",
    "user": {
      "email": "carson@pickaxeproject.com",
      "name": null
    },
    "workspace": {
      "workspaceId": "5f90404a-f736-48c4-95df-d84cf886759b",
      "name": "WaveWatch"
    },
    "workspaceScope": "fixed",
    "capabilities": {
      "pickaxes": true,
      "deployments": true,
      "actions": true,
      "mcps": true,
      "accessGroups": true,
      "products": true,
      "aiBuild": true
    }
  }
}

GET /studio/workspace/list

List workspaces visible to the current API key.

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

Request Fields

This endpoint does not define request body fields.

Examples

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

Response Shape

{
  "data": [
    {
      "workspaceId": "5f90404a-f736-48c4-95df-d84cf886759b",
      "name": "WaveWatch",
      "selected": true,
      "visibility": "public",
      "creator": "carson@pickaxeproject.com"
    }
  ]
}

POST /studio/workspace/history

Fetch conversation history across the authenticated workspace.

For very large exports, do not request the full workspace in one response. A single response that hydrates thousands of conversations can exceed HTTP function timeouts. For the most reliable giant export, use a coding agent or script to list Pickaxes, page through each Pickaxe's history, and write each record to JSONL as it arrives.

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

Request Fields

  • pickaxeIds (string[], optional): Optional list of Pickaxe IDs to include. If omitted, history is fetched across all active Pickaxes in the authenticated workspace. The field pickaxes is also accepted as an alias.
  • skip (number, optional): The number of recent conversations to skip. Defaults to 0.
  • limit (number, optional): The maximum number of recent conversations to return for this request. 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.
  • sortBy (string, optional): Sort order for returned conversations. Supported values include "created-desc", "created-asc", "updated-desc", "updated-asc", "cost-desc", and "cost-asc". Defaults to created-desc.
  • users (string[], optional): Optional user IDs or emails to filter history by conversation sender.
  • originTypes (string[], optional): Optional source filters such as PICKAXE, BUILDER, STUDIO, EMBED, EMAIL, WHATSAPP, API, SLACK, or MAKE.
  • search (string, optional): Optional search string matched against session ID, Pickaxe ID, sender, and summary fields.
  • createdAfter (string, optional): Optional ISO datetime lower bound for conversation creation time.
  • createdBefore (string, optional): Optional ISO datetime upper bound for conversation creation time.
  • updatedAfter (string, optional): Optional ISO datetime lower bound for conversation update time.
  • updatedBefore (string, optional): Optional ISO datetime upper bound for conversation update time.
  • hasUploadedDocuments (boolean, optional): If true, only returns conversations that used uploaded documents.
  • hasMemories (boolean, optional): If true, only returns conversations that created or used user memories.
  • userMemoryIds (string[], optional): Optional memory IDs to filter matching conversations.
  • minCost (number, optional): Optional minimum total conversation cost filter.
  • maxCost (number, optional): Optional maximum total conversation cost filter.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/workspace/history \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "skip": 0,
  "limit": 100,
  "format": "raw",
  "sortBy": "created-desc"
}'

Response Shape

{
  "success": true,
  "data": [
    {
      "responseId": "SESSION123",
      "formId": "MY_FORM_ID",
      "type": "chat",
      "messages": [],
      "userId": "user@example.com",
      "model": "gpt-5",
      "historyId": "665f4f1d2f1b9c0012345678",
      "userMemoryIds": [],
      "createdAt": "2026-05-08T18:10:00.000Z",
      "updatedAt": "2026-05-08T18:10:10.000Z"
    }
  ]
}

GET /studio/models

List model slugs and capabilities for the authenticated workspace plan. Use this before setting the model field on a Pickaxe so agents can choose a supported slug.

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

Request Fields

  • all (boolean, optional): Include hidden models in the response when true. Hidden models are omitted by default. Defaults to false.
  • availableOnly (boolean, optional): Return only models available to the authenticated workspace plan. Defaults to false.

Examples

curl -X GET "https://api.pickaxe.co/v1/studio/models?availableOnly=true" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN"

Response Shape

{
  "success": true,
  "data": [
    {
      "slug": "gpt-5",
      "maxContextTokens": 400000,
      "maxOutputTokens": 128000,
      "available": true,
      "reasoning": true,
      "supportsActions": true,
      "supportsImageInput": true
    }
  ],
  "meta": {
    "plan": "pro",
    "includeHidden": false,
    "availableOnly": true
  }
}

Previous

Authenticated Embeds

Next

Completions