Pickaxe Learn

API Reference

Access Group

Endpoints for public and member access groups and related access settings.

Related In Learn

Access Overview

Control who can use your tools with public and member access groups.

Open Learn

Access group endpoints manage public and member access groups and related access settings.

Endpoints

GET /studio/access-group/list

List every access group in the current studio using the workspace tied to your API key.

  • Full URL: https://api.pickaxe.co/v1/studio/access-group/list

Request Fields

This endpoint does not define request body fields.

Examples

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

GET /studio/product/list

Legacy access-group listing endpoint retained for backwards compatibility.

  • Full URL: https://api.pickaxe.co/v1/studio/product/list
  • Status: Deprecated

Request Fields

This endpoint does not define request body fields.

Examples

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

POST /studio/access-group/create

Create a new access group with limit, upgrade-flow, and card-display configuration.

  • Full URL: https://api.pickaxe.co/v1/studio/access-group/create

Request Fields

  • data (object, required): The access-group payload to create. The API also accepts the same fields at the top level, but using data keeps the request format consistent with the rest of the Studio API.
    • type ("public" | "members", required): The access-group type. Public groups are meant for non-members, while members groups are intended for signed-in or paid members.
    • name (string, optional): Internal group name used in the workspace UI and administrative flows. Must be 1 to 60 characters when supplied. Defaults to "My New Access Group".
    • description (string, optional): Internal description for the access group. Limited to 100 characters. Defaults to "".
    • image (string | null, optional): Optional image URL used when the group card displays an image. Defaults to null.
    • displayName (string | null, optional): Optional public-facing card title. If omitted, clients typically fall back to name. Defaults to null.
    • displayDescription (string | null, optional): Optional public-facing card description. If omitted, clients typically fall back to description. Defaults to null.
    • limit (number, optional): Usage limit for the group. Use -1337 for unlimited access. Finite limits are typically paired with limitInterval. Defaults to -1337.
    • limitInterval ("day" | "week" | "month" | "year" | "one_time" | null, optional): The reset period for a finite limit. Use one_time for a non-recurring wallet or usage allocation. Defaults to null.
    • upgrade (object, optional): Controls the experience shown after a user reaches their usage limit. Defaults to {...default upgrade payload}.
      • limitMessage (string, optional): The message shown when a user reaches the access limit for this group. Defaults to "Please upgrade to continue".
      • limitCTA (string, optional): The CTA label used when the upgrade flow displays a button. Defaults to "Continue".
      • limitLink (string, optional): The URL to open when the limit flow is configured to link users to a custom destination. Defaults to "".
      • accessGroupIds (string[], optional): Member Access Group IDs that users can upgrade into from this group. Every ID must belong to the same studio and must reference a member group. Defaults to [].
      • isCTAButton (boolean, optional): Whether the limit experience should render a CTA button using limitCTA. Defaults to true.
      • isBuyMoreUses (boolean, optional): Whether users should be allowed to buy additional usage after reaching the limit. Defaults to false.
      • isUpgradeToAnotherGroup (boolean, optional): Whether the limit experience should offer upgrades into other member access groups. Defaults to false.
      • isLinkToCustomURL (boolean, optional): Whether the CTA should send the user to limitLink instead of an internal upgrade flow. Defaults to false.
    • currency (string | null, optional): Currency code used for paid groups, such as usd. This is ignored for free groups. Defaults to null.
    • ctaButtonText (string, optional): Text shown on the access-group card CTA in upgrade flows. Limited to 100 characters. Defaults to "Get".
    • isDisplayImage (boolean, optional): Whether the access-group card should render its image in upgrade flows. Defaults to false.
    • isArchived (boolean, optional): Whether the group should be marked as archived without deleting it. Defaults to false.
    • derivedFromProductIds (string[], optional): Advanced/internal linkage to upstream product IDs that produced this access group. Defaults to [].

Examples

curl -X POST https://api.pickaxe.co/v1/studio/access-group/create \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "data": {
    "type": "members",
    "name": "Pro Members",
    "description": "Access to premium tools",
    "displayName": "Pro",
    "displayDescription": "Unlock our premium tools and higher limits.",
    "limit": 500,
    "limitInterval": "month",
    "ctaButtonText": "Upgrade",
    "isDisplayImage": true,
    "upgrade": {
      "limitMessage": "Upgrade to keep going",
      "limitCTA": "See plans",
      "accessGroupIds": ["access-2MsL0vQeR8Ty"],
      "isCTAButton": true,
      "isBuyMoreUses": true,
      "isUpgradeToAnotherGroup": true,
      "isLinkToCustomURL": false
    }
  }
}'

POST /studio/access-group/assign

Create associations between access groups and deployments or portals, either from the resource side or from the access-group side.

  • Full URL: https://api.pickaxe.co/v1/studio/access-group/assign

Request Fields

  • data (object, required): Assignment payload. Provide exactly one scope: accessGroupId, deploymentId, or portalId.
    • mode ("append" | "replace", optional): append adds missing links while preserving existing ones. replace makes the provided set the exact final state for the chosen scope. Defaults to "append".
    • accessGroupId (string, optional): Use this when assigning deployments and/or portals to one access group.
    • deploymentId (string, optional): Use this when assigning one or more access groups to a single deployment.
    • portalId (string, optional): Use this when assigning one or more access groups to a single portal.
    • accessGroupIds (string[], optional): Required when deploymentId or portalId is provided. These are the groups that should be linked to that resource.
    • deploymentIds (string[], optional): Required when accessGroupId is provided and you want to connect deployments to that access group.
    • portalIds (string[], optional): Required when accessGroupId is provided and you want to connect portals to that access group.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/access-group/assign \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "data": {
    "mode": "append",
    "deploymentId": "deploy-1NsG6mQxT4Pv",
    "accessGroupIds": [
      "access-7VjA3sX2pQ9L",
      "access-2MsL0vQeR8Ty"
    ]
  }
}'

POST /studio/access-group/remove

Remove associations between access groups and deployments or portals using the same scope rules as the assign endpoint.

  • Full URL: https://api.pickaxe.co/v1/studio/access-group/remove

Request Fields

  • data (object, required): Removal payload. Provide exactly one scope: accessGroupId, deploymentId, or portalId.
    • accessGroupId (string, optional): Use this when removing deployments and/or portals from one access group.
    • deploymentId (string, optional): Use this when removing one or more access groups from a single deployment.
    • portalId (string, optional): Use this when removing one or more access groups from a single portal.
    • accessGroupIds (string[], optional): Required when deploymentId or portalId is provided. These are the groups to disconnect from that resource.
    • deploymentIds (string[], optional): Required when accessGroupId is provided and you want to disconnect deployments from that access group.
    • portalIds (string[], optional): Required when accessGroupId is provided and you want to disconnect portals from that access group.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/access-group/remove \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "data": {
    "portalId": "portal-4LsP0kNaW2Yd",
    "accessGroupIds": ["access-7VjA3sX2pQ9L"]
  }
}'

GET /studio/access-group/<access_group_id>

Fetch one access group with computed counts and related deployment, portal, and parent-upgrade references.

  • Full URL: https://api.pickaxe.co/v1/studio/access-group/<access_group_id>

Request Fields

  • accessGroupId (string, required): The access-group ID to retrieve.

Examples

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

PATCH /studio/access-group/<access_group_id>

Partially update an access group. Only the fields you send are changed.

  • Full URL: https://api.pickaxe.co/v1/studio/access-group/<access_group_id>

Request Fields

  • accessGroupId (string, required): The access-group ID to update.
  • data (object, required): Partial access-group payload. At least one real change is required.
    • name (string, optional): Internal group name used in the workspace UI and administrative flows. Must be 1 to 60 characters when supplied. Defaults to "My New Access Group".
    • description (string, optional): Internal description for the access group. Limited to 100 characters. Defaults to "".
    • image (string | null, optional): Optional image URL used when the group card displays an image. Defaults to null.
    • displayName (string | null, optional): Optional public-facing card title. If omitted, clients typically fall back to name. Defaults to null.
    • displayDescription (string | null, optional): Optional public-facing card description. If omitted, clients typically fall back to description. Defaults to null.
    • limit (number, optional): Usage limit for the group. Use -1337 for unlimited access. Finite limits are typically paired with limitInterval. Defaults to -1337.
    • limitInterval ("day" | "week" | "month" | "year" | "one_time" | null, optional): The reset period for a finite limit. Use one_time for a non-recurring wallet or usage allocation. Defaults to null.
    • upgrade (object, optional): Controls the experience shown after a user reaches their usage limit. Defaults to {...default upgrade payload}.
      • limitMessage (string, optional): The message shown when a user reaches the access limit for this group. Defaults to "Please upgrade to continue".
      • limitCTA (string, optional): The CTA label used when the upgrade flow displays a button. Defaults to "Continue".
      • limitLink (string, optional): The URL to open when the limit flow is configured to link users to a custom destination. Defaults to "".
      • accessGroupIds (string[], optional): Member Access Group IDs that users can upgrade into from this group. Every ID must belong to the same studio and must reference a member group. Defaults to [].
      • isCTAButton (boolean, optional): Whether the limit experience should render a CTA button using limitCTA. Defaults to true.
      • isBuyMoreUses (boolean, optional): Whether users should be allowed to buy additional usage after reaching the limit. Defaults to false.
      • isUpgradeToAnotherGroup (boolean, optional): Whether the limit experience should offer upgrades into other member access groups. Defaults to false.
      • isLinkToCustomURL (boolean, optional): Whether the CTA should send the user to limitLink instead of an internal upgrade flow. Defaults to false.
    • currency (string | null, optional): Currency code used for paid groups, such as usd. This is ignored for free groups. Defaults to null.
    • ctaButtonText (string, optional): Text shown on the access-group card CTA in upgrade flows. Limited to 100 characters. Defaults to "Get".
    • isDisplayImage (boolean, optional): Whether the access-group card should render its image in upgrade flows. Defaults to false.
    • isArchived (boolean, optional): Whether the group should be marked as archived without deleting it. Defaults to false.
    • derivedFromProductIds (string[], optional): Advanced/internal linkage to upstream product IDs that produced this access group. Defaults to [].

Examples

curl -X PATCH https://api.pickaxe.co/v1/studio/access-group/access-7VjA3sX2pQ9L \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "data": {
    "displayName": "Pro Plus",
    "displayDescription": "Unlock premium tools and concierge support.",
    "limit": 750,
    "upgrade": {
      "limitLink": "https://example.com/upgrade",
      "isLinkToCustomURL": true
    }
  }
}'

POST /studio/access-group/<access_group_id>/delete-preview

Preview how deleting an access group will affect users, subscriptions, deployment links, portal links, and parent upgrade paths.

  • Full URL: https://api.pickaxe.co/v1/studio/access-group/<access_group_id>/delete-preview

Request Fields

  • accessGroupId (string, required): The access-group ID you may delete.
  • data (object, optional): Deletion mode configuration. Omit the body or send an empty object to preview a delete-only flow.
    • mode ("delete-only" | "reassign", optional): delete-only removes the access group and its links. reassign moves links and users into another access group before deletion. Defaults to "delete-only".
    • newAccessGroupId (string, optional): Required when mode is reassign. It must be a different access group in the same studio and cannot be a public group.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/access-group/access-7VjA3sX2pQ9L/delete-preview \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "data": {
    "mode": "reassign",
    "newAccessGroupId": "access-2MsL0vQeR8Ty"
  }
}'

POST /studio/access-group/<access_group_id>/delete

Delete an access group, optionally reassigning users and links into another member access group first.

  • Full URL: https://api.pickaxe.co/v1/studio/access-group/<access_group_id>/delete

Request Fields

  • accessGroupId (string, required): The access-group ID to delete.
  • data (object, optional): Deletion mode configuration. Omit the body or send an empty object to perform a delete-only flow.
    • mode ("delete-only" | "reassign", optional): delete-only removes the group and associated links. reassign migrates links and user assignments to newAccessGroupId before deleting the original group. Defaults to "delete-only".
    • newAccessGroupId (string, optional): Required when mode is reassign. It must be a different member access group in the same studio.

Examples

curl -X POST https://api.pickaxe.co/v1/studio/access-group/access-7VjA3sX2pQ9L/delete \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
  "data": {
    "mode": "reassign",
    "newAccessGroupId": "access-2MsL0vQeR8Ty"
  }
}'

Previous

User