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.

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 page-to-portal links.

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
  }
}'

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 page create --file pages/landing.html --link portal-123

Deployment

Page