List profile groups

Prev Next
Get
/platform/api/profiles/preview/groups

Returns one page of the profile groups of the caller's client, ordered by name. name and nameContains filter by group name. An entry carries id, name and parentId (absent on the top level) but not its groups and profiles; GET /groups/{id} returns them. meta.total counts the matching groups; a page past the last one returns an empty data array.

Security
OAuth

OAuth2 client-credentials flow for machine-to-machine access. Exchange a client id/secret at /dw/register/oauth/token for a bearer token, then send it as Authorization: Bearer <access_token>. Client credentials are provisioned in the Lobster administration UI.

This is the client-credentials token endpoint of the Platform API. /oauth/token, the token_endpoint advertised at /.well-known/oauth-authorization-server, serves the authorization code flow of the OAuth2AuthorizationCode scheme.

FlowClient Credentials
Token URL/dw/register/oauth/token
Refresh URL/dw/register/oauth/token
OAuth

OAuth 2.1 authorization code flow with PKCE, for acting as a signed-in user. It works with Microsoft and other single sign-on providers: the provider only confirms the user's identity to the platform, which then issues its own token.

  1. POST /oauth/register (no authentication) with the JSON body {"redirect_uris": ["<redirect URI>"]} returns a client_id. The user's browser has to reach the redirect URI.
  2. Open /oauth/authorize in the user's browser with response_type=code, client_id, redirect_uri, state and a code_challenge with code_challenge_method=S256. state is a fresh unguessable value per request, and code_challenge is the S256 hash of a code_verifier freshly generated per request from a cryptographically secure random source (43 to 128 characters, RFC 7636). The user signs in on the platform's login page, and the browser is redirected to the redirect URI with code and state; a callback whose state differs from the one sent is to be rejected.
  3. The code is valid for 30 seconds. Exchange it at POST /oauth/token, form-encoded, with grant_type=authorization_code, code, redirect_uri, code_verifier and client_id.
  4. The answer carries access_token (valid 30 minutes), refresh_token (valid 48 hours) and expires_in in milliseconds. Refresh with grant_type=refresh_token, refresh_token and client_id.
FlowAuthorization Code
Authorization URL/oauth/authorize
Token URL/oauth/token
Refresh URL/oauth/token
HTTP
Type bearer

Bearer token obtained from an authenticated browser or guest-user session.

Flow 1 — UI login: Log in via the Lobster web UI at /, then call GET /auth/sessionBearerToken to exchange the session cookie for a bearer token.

Flow 2 — Guest user login token: Append a GuestUser loginToken as a URL query parameter to the base URL to establish a password-free session:

GET <host>?loginToken=<GuestUser token>

Then call GET /auth/sessionBearerToken to obtain the bearer token.

Query parameters
page
integer (int32)

Zero-based index of the page to return.

Minimum0
Default0
size
integer (int32)

Number of entries per page; a value out of range is rejected, not clamped.

Minimum1
Maximum200
Default20
name
array of string

Exact, case-sensitive match on the group name. Repeatable — repeated values OR.

nameContains
string

Case-insensitive substring match on the group name.

Responses
200

Groups returned.

One page of groups

The envelope as returned: the page in data, the paging state in meta.

{
  "data": [
    {
      "class": "core.ProfileGroup",
      "id": "6bb76781_199702d94be_2714_9a14992bf4897187_6bb76781_1996f5f952f_-8000",
      "name": "Archive",
      "parentId": "6bb76781_199702d94be_2714_9a14992bf4897187_6bb76781_1996f5f9530_-8000"
    },
    {
      "class": "core.ProfileGroup",
      "id": "6bb76781_199702d94be_2714_9a14992bf4897187_6bb76781_1996f5f9530_-8000",
      "name": "Orders"
    }
  ],
  "meta": {
    "page": 0,
    "size": 20,
    "total": 2
  }
}
Expand All
object

Standard Platform API success envelope. Every response carries exactly one of data (success) or error (failure) at top level.

data
Array of object (core.ProfileGroup)
object

A profile group, a node of the profile tree. A profile's group holds its id.

class
string

The type of this object, always core.ProfileGroup. Required where the member it is sent in accepts several types.

Valid values[ "core.ProfileGroup" ]
groups
Array of object (core.ProfileTreeRef)

The groups directly in this group, by name. Present on a single-group response only; a sent value is ignored.

object

A reference to a subgroup or a profile of a group: its id, name and the path to fetch it.

class
string

The type of this object, always core.ProfileTreeRef. Required where the member it is sent in accepts several types.

Valid values[ "core.ProfileTreeRef" ]
href
string

The server-relative path that returns the referenced group or profile.

id
string

The identifier of the referenced group or profile.

name
string

The name of the referenced group or profile.

Exampleacme-order-import
id
string

The group's identifier: the value a profile's group holds and the path parameter of GET /groups/{id}; root for the top level. Assigned by the server; a sent value is ignored.

name
string

The name the Lobster UI shows for the group; unique among the groups of one parent.

ExampleOrders
parentId
string

The id of the group this group sits in; absent for a group on the top level. On create, the group to create it in. Send null in a patch to move the group to the top level.

profiles
Array of object (core.ProfileTreeRef)

The profiles directly in this group the caller may view, by name. Present on a single-group response only; a sent value is ignored.

object

A reference to a subgroup or a profile of a group: its id, name and the path to fetch it.

class
string

The type of this object, always core.ProfileTreeRef. Required where the member it is sent in accepts several types.

Valid values[ "core.ProfileTreeRef" ]
href
string

The server-relative path that returns the referenced group or profile.

id
string

The identifier of the referenced group or profile.

name
string

The name of the referenced group or profile.

Exampleacme-order-import
meta
object (Meta)

Everything about the response that is not the resource itself. Members may be added over time; ignore the ones you do not recognize.

page
integer (int32)

Zero-based index of the returned page.

size
integer (int32)

Number of entries per page.

total
integer (int64)

Number of entries across all pages.

400

The request could not be understood. BAD_REQUEST for a body that does not decode — its message names the property at fault — and VALIDATION_FAILED with one details entry per offending parameter for a malformed request target (an unknown query parameter or sort key). Also BAD_REQUEST for a response unit naming a channel this client cannot reference.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
Expand All
object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error
object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code
string

Stable machine-readable UPPER_SNAKE error code for programmatic handling, e.g. PARTNER_NOT_FOUND, VALIDATION_FAILED or FORBIDDEN. New codes may be added over time; treat an unknown code according to the HTTP status class. The HTTP status itself is carried by the status line only, never duplicated here.

message
string

Human-readable, non-localized explanation. Branch on code, never on this text.

details
Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code
string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message
string

Human-readable, non-localized explanation of this individual failure.

target
string

What this failure refers to, e.g. the violated field.

401

Authentication is required or the supplied credentials are invalid.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource."
  }
}
Expand All
object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error
object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code
string

Stable machine-readable UPPER_SNAKE error code for programmatic handling, e.g. PARTNER_NOT_FOUND, VALIDATION_FAILED or FORBIDDEN. New codes may be added over time; treat an unknown code according to the HTTP status class. The HTTP status itself is carried by the status line only, never duplicated here.

message
string

Human-readable, non-localized explanation. Branch on code, never on this text.

details
Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code
string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message
string

Human-readable, non-localized explanation of this individual failure.

target
string

What this failure refers to, e.g. the violated field.

403

The caller lacks the permission for this operation on this resource (FORBIDDEN).

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Access to this resource is denied."
  }
}
Expand All
object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error
object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code
string

Stable machine-readable UPPER_SNAKE error code for programmatic handling, e.g. PARTNER_NOT_FOUND, VALIDATION_FAILED or FORBIDDEN. New codes may be added over time; treat an unknown code according to the HTTP status class. The HTTP status itself is carried by the status line only, never duplicated here.

message
string

Human-readable, non-localized explanation. Branch on code, never on this text.

details
Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code
string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message
string

Human-readable, non-localized explanation of this individual failure.

target
string

What this failure refers to, e.g. the violated field.

404

The requested resource does not exist. The code is resource-specific, e.g. PARTNER_NOT_FOUND, PROFILE_NOT_FOUND or CHANNEL_NOT_FOUND.

{
  "error": {
    "code": "PARTNER_NOT_FOUND",
    "message": "Partner not found: 42"
  }
}
Expand All
object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error
object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code
string

Stable machine-readable UPPER_SNAKE error code for programmatic handling, e.g. PARTNER_NOT_FOUND, VALIDATION_FAILED or FORBIDDEN. New codes may be added over time; treat an unknown code according to the HTTP status class. The HTTP status itself is carried by the status line only, never duplicated here.

message
string

Human-readable, non-localized explanation. Branch on code, never on this text.

details
Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code
string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message
string

Human-readable, non-localized explanation of this individual failure.

target
string

What this failure refers to, e.g. the violated field.

500

An unexpected server error occurred.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred."
  }
}
Expand All
object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error
object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code
string

Stable machine-readable UPPER_SNAKE error code for programmatic handling, e.g. PARTNER_NOT_FOUND, VALIDATION_FAILED or FORBIDDEN. New codes may be added over time; treat an unknown code according to the HTTP status class. The HTTP status itself is carried by the status line only, never duplicated here.

message
string

Human-readable, non-localized explanation. Branch on code, never on this text.

details
Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code
string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message
string

Human-readable, non-localized explanation of this individual failure.

target
string

What this failure refers to, e.g. the violated field.