Pickaxe Learn

API Reference

Portal

Endpoints for portals, portal display settings, and styling options.

Related In Learn

Portals

Create branded, multi-agent hubs where users can access your agents in one place.

Open Learn

Portal endpoints manage portal containers, portal display settings, and the supported portal styling contract.

Portal creation starts with an empty nav: items: []. Add custom coded pages to portal navigation separately with the Page API.

Endpoints

GET /studio/portal/styling/list

List all portal styling fields supported by the API.

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

Request Fields

This endpoint does not define request body fields.

Response Includes

  • style.defaults: Default portal style values.
  • Enum values for glassTheme, imageSize, and textSize.
  • Numeric ranges for glassOpacity and roundness.
  • Boolean styling fields.
  • Display fields: name, image, previewImage, isWhitelabel.
  • Lockout fields: lockoutTitle, lockoutMessage, lockoutCTA.
  • Reserved portal path values.

Examples

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

GET /studio/portal/list

List portals in the current workspace studio.

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

Request Fields

This endpoint does not define request body fields.

Examples

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

Response Shape

{
  "success": true,
  "data": [
    {
      "portalId": "portal-123",
      "name": "Landing Portal",
      "path": "landing",
      "image": "",
      "previewImage": "",
      "isWhitelabel": false,
      "style": {
        "glassTheme": "light",
        "glassOpacity": 0.1,
        "roundness": 24,
        "imageSize": "md",
        "textSize": "md",
        "isShowSidebarImages": true,
        "isShowPortalImage": true
      },
      "items": [],
      "createdAt": "2026-04-28T16:20:00.000000",
      "updatedAt": "2026-04-28T16:20:00.000000"
    }
  ]
}

POST /studio/portal/create

Create an empty portal.

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

Request Fields

  • name (string, required): Portal name.
  • path (string, optional): Portal path.
  • image (string, optional): Portal image URL. Defaults to "".
  • previewImage (string, optional): Portal preview image URL. Defaults to "".
  • isWhitelabel (boolean, optional): White-label portal display flag. Defaults to false.
  • style (object, optional): Portal style settings.
    • glassTheme (string, optional): Glass theme. Run GET /studio/portal/styling/list for supported values.
    • glassOpacity (number, optional): Glass opacity. Run GET /studio/portal/styling/list for the supported range.
    • roundness (number, optional): Portal roundness. Run GET /studio/portal/styling/list for the supported range.
    • imageSize (string, optional): Portal image size. Run GET /studio/portal/styling/list for supported values.
    • textSize (string, optional): Portal text size. Run GET /studio/portal/styling/list for supported values.
    • isShowSidebarImages (boolean, optional): Whether sidebar item images are visible.
    • isShowPortalImage (boolean, optional): Whether the portal image is visible.
  • lockoutTitle (string, optional): Title shown when a user lacks access.
  • lockoutMessage (string, optional): Message shown when a user lacks access.
  • lockoutCTA (string, optional): CTA text shown when a user lacks access.
  • portalId (string, optional): Advanced field for explicitly setting the portal ID. If omitted, Pickaxe generates one.

Notes

  • Unsupported portal fields are rejected.
  • Create rejects an existing portalId with 409 portal_id_conflict.
  • Create rejects an existing path with 409 portal_path_conflict.
  • Create always starts with items: [].
  • This endpoint does not create or link pages. Add pages separately with POST /studio/page/{pageId}/portal-links.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/portal/create \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "name": "Landing Portal",
  "path": "landing",
  "image": "",
  "previewImage": "",
  "isWhitelabel": false,
  "style": {
    "glassTheme": "light",
    "glassOpacity": 0.1,
    "roundness": 24,
    "imageSize": "md",
    "textSize": "md",
    "isShowSidebarImages": true,
    "isShowPortalImage": true
  },
  "lockoutTitle": "Access Restricted",
  "lockoutMessage": "You do not have access to this portal.",
  "lockoutCTA": "Upgrade to continue"
}'

Response Shape

{
  "success": true,
  "data": {
    "portalId": "portal-123",
    "name": "Landing Portal",
    "path": "landing",
    "image": "",
    "previewImage": "",
    "isWhitelabel": false,
    "style": {
      "glassTheme": "light",
      "glassOpacity": 0.1,
      "roundness": 24,
      "imageSize": "md",
      "textSize": "md",
      "isShowSidebarImages": true,
      "isShowPortalImage": true
    },
    "items": [],
    "createdAt": "2026-04-28T16:20:00.000000",
    "updatedAt": "2026-04-28T16:20:00.000000"
  }
}

GET /studio/portal/{portalId}

Fetch one portal.

  • Full URL: https://api.pickaxe.co/v1/studio/portal/{portalId}

Request Fields

  • portalId (string, required): The portal ID in the path.

Examples

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

PATCH /studio/portal/{portalId}

Update portal display, path, lockout copy, or style fields.

  • Full URL: https://api.pickaxe.co/v1/studio/portal/{portalId}

Request Fields

  • portalId (string, required): The portal ID in the path.
  • name (string, optional): Portal name.
  • path (string, optional): Portal path.
  • image (string, optional): Portal image URL.
  • previewImage (string, optional): Portal preview image URL.
  • isWhitelabel (boolean, optional): White-label portal display flag.
  • style (object, optional): Partial portal style settings. Run GET /studio/portal/styling/list for supported fields and values.
  • lockoutTitle (string, optional): Lockout title.
  • lockoutMessage (string, optional): Lockout message.
  • lockoutCTA (string, optional): Lockout CTA text.

Notes

  • Unsupported portal fields are rejected.
  • Update rejects path conflicts with 409 portal_path_conflict.
  • Nav item and page-link mutation is not performed here. Use the Page API for custom page-to-portal links, or POST /studio/portal/{portalId}/pickaxe-pages to add an existing Pickaxe to a portal.

Examples

curl -X PATCH https://api.pickaxe.co/v1/studio/portal/portal-123 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "name": "Updated Landing Portal",
  "style": {
    "glassTheme": "light",
    "roundness": 24,
    "isShowPortalImage": true
  }
}'

POST /studio/portal/{portalId}/pickaxe-pages

Add an existing Pickaxe to a portal as a Pickaxe page. This is the API equivalent of adding an agent to a portal.

  • Full URL: https://api.pickaxe.co/v1/studio/portal/{portalId}/pickaxe-pages

Request Fields

  • portalId (string, required): The portal ID in the path.
  • pickaxeId (string, required): Existing Pickaxe ID to add to the portal.
  • parentId (string, optional): Optional existing portal folder item ID.
  • displayName (string, optional): Portal page title. Defaults to the Pickaxe title when omitted.
  • displayDescription (string, optional): Portal page description. Defaults to the Pickaxe description when omitted.
  • displayIcon (string, optional): Portal page icon/image. Defaults to the Pickaxe cover photo when omitted.
  • design (object, optional): Initial Pickaxe page design object.
  • headerScript (string, optional): Custom header script applied to the Pickaxe page.
  • footerScript (string, optional): Custom footer script applied to the Pickaxe page.

Notes

  • The request body may be sent directly or under a data object.
  • If the Pickaxe is already linked to the portal, the API returns the existing portal item.
  • portalId must belong to the authenticated workspace, and pickaxeId must reference a Pickaxe in the same workspace.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/portal/portal-123/pickaxe-pages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "pickaxeId": "my-studio-bot",
  "displayName": "Support Bot"
}'

GET /studio/portal/pickaxe-pages/design/list

List accepted design fields, enum values, defaults, and custom-code fields for portal Pickaxe pages.

  • Full URL: https://api.pickaxe.co/v1/studio/portal/pickaxe-pages/design/list

Request Fields

This endpoint does not define request body fields.

Examples

CURL

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

GET /studio/portal/{portalId}/pickaxe-pages/design

Fetch the current shared Pickaxe page design for a portal. The response includes a sample Pickaxe/page ID from the portal.

  • Full URL: https://api.pickaxe.co/v1/studio/portal/{portalId}/pickaxe-pages/design

Request Fields

  • portalId (string, required): The portal ID in the path.

Examples

CURL

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

PATCH /studio/portal/{portalId}/pickaxe-pages/design

Update the shared Pickaxe page design and custom scripts for every Pickaxe page in a portal.

  • Full URL: https://api.pickaxe.co/v1/studio/portal/{portalId}/pickaxe-pages/design

Request Fields

  • portalId (string, required): The portal ID in the path.
  • design (object, optional): Design object. Fields may also be sent directly at the top level.
  • theme ("light" | "dark" | "draper" | "pulse", optional): Pickaxe page theme.
  • style (object, optional): Page style fields such as font, fontSize, inputType, buttonType, and roundness.
  • colors (object, optional): Color fields for background, foreground, secondary, secondaryForeground, accent, and accentForeground.
  • visibility (object, optional): Boolean visibility toggles for title, description, and image.
  • headerScript (string, optional): Custom header script applied to portal Pickaxe pages.
  • footerScript (string, optional): Custom footer script applied to portal Pickaxe pages.

Examples

CURL

curl -X PATCH https://api.pickaxe.co/v1/studio/portal/portal-123/pickaxe-pages/design \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "theme": "light",
  "visibility": {
    "title": true,
    "description": true,
    "image": true
  }
}'

CLI Notes

If you are using the Pickaxe CLI, inspect the supported style contract before creating or updating a portal:

pickaxe portal styling list
pickaxe portal create --name "Landing Portal" --path landing --glass-theme light
pickaxe portal update portal-123 --roundness 24 --show-portal-image true
pickaxe portal add-agent portal-123 my-studio-bot --name "Support Bot"
pickaxe page create --file pages/landing.html --link portal-123

Previous

Deployment

Next

Page