> ## Documentation Index > Fetch the complete documentation index at: https://docs.lobstersoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # List structure templates > Returns one page of the structure templates this instance bundles: the values of the `template` member of `mappingSettings.sourceStructure` and `mappingSettings.targetStructure`, which builds that tree the way the editor's "Load template" does. `format` and `side` narrow the list, `search` finds a template by the words of its name and tolerates typos, best match first; without `search` the list is ordered by name. `meta.total` counts the templates matching the filters. A `page` past the last one answers 200 with an empty `data` array. An IDoc basic type usually comes in several SAP releases (`IDOC_IN_DELVRY03`, `V7IDOC_IN_DELVRY03`, `V75IDOC_IN_DELVRY03`) whose segments differ; see the Profiles guide for choosing one. ## OpenAPI ````json GET /platform/api/profiles/preview/templates { "openapi": "3.1.0", "info": { "title": "Lobster Platform API", "description": "**PREVIEW:** This API is in preview and under active development. Endpoints and schemas are subject to breaking changes, and backward compatibility is not guaranteed until the API is promoted to a stable version.\n\nREST API of the Lobster Platform for headless clients. Every operation, schema and member of this document carries a description, and the create operations carry complete examples. Each tag links the page of the Lobster documentation that explains its resources.\n\n## Authentication\nFour authentication flows are available. All of them produce a bearer token that must be sent as `Authorization: Bearer ` on every request.\n\n1. **Authorization code with PKCE** (acting as a user; works with Microsoft and other SSO): the steps are in the `OAuth2AuthorizationCode` security scheme.\n2. **OAuth2 Client Credentials** (machine-to-machine): exchange a client id/secret provisioned in the Lobster administration UI at `POST /dw/register/oauth/token` with `grant_type=client_credentials&client_id=&client_secret=`.\n3. **UI Session Bearer Token**: log in via the Lobster web UI, then exchange the session cookie for a token at `GET /auth/sessionBearerToken`.\n4. **Guest User Login Token**: append a GuestUser `loginToken` as a URL query parameter (`?loginToken=`) to establish a session without a password, then retrieve the bearer token the same way.", "version": "preview" }, "servers": [ { "url": "https://platform-beta-test.lobster-cloud.com" } ], "security": [ { "OAuth2": [] }, { "OAuth2AuthorizationCode": [] }, { "SessionBearer": [] } ], "tags": [ { "name": "Channels", "description": "The channels of a partner, the concrete connections a profile uses to receive or send.", "externalDocs": { "description": "Lobster documentation", "url": "https://docs.lobstersoftware.com/docs/en/manage-partners-channels" } }, { "name": "Functions", "description": "The catalogue of mapping functions a profile's mapping can call.", "externalDocs": { "description": "Lobster documentation", "url": "https://docs.lobstersoftware.com/docs/en/functions" } }, { "name": "Partners", "description": "Integration partners, the business parties profiles exchange data with.", "externalDocs": { "description": "Lobster documentation", "url": "https://docs.lobstersoftware.com/docs/en/manage-partners" } }, { "name": "Profiles", "description": "Integration profiles: what data comes in, how it is mapped and where the result goes.", "externalDocs": { "description": "Lobster documentation", "url": "https://docs.lobstersoftware.com/docs/en/profiles" } } ], "externalDocs": { "description": "Lobster documentation", "url": "https://docs.lobstersoftware.com/docs/en/profiles" }, "paths": { "/platform/api/profiles/preview/templates": { "get": { "tags": [ "Profiles" ], "summary": "List structure templates", "description": "Returns one page of the structure templates this instance bundles: the values of the `template` member of `mappingSettings.sourceStructure` and `mappingSettings.targetStructure`, which builds that tree the way the editor's \"Load template\" does. `format` and `side` narrow the list, `search` finds a template by the words of its name and tolerates typos, best match first; without `search` the list is ordered by name. `meta.total` counts the templates matching the filters. A `page` past the last one answers 200 with an empty `data` array. An IDoc basic type usually comes in several SAP releases (`IDOC_IN_DELVRY03`, `V7IDOC_IN_DELVRY03`, `V75IDOC_IN_DELVRY03`) whose segments differ; see the Profiles guide for choosing one.", "operationId": "listTemplates", "parameters": [ { "name": "page", "in": "query", "description": "Zero-based index of the page to return.", "schema": { "type": "integer", "format": "int32", "default": 0, "minimum": 0 } }, { "name": "size", "in": "query", "description": "Number of entries per page; a value out of range is rejected, not clamped.", "schema": { "type": "integer", "format": "int32", "default": 20, "maximum": 200, "minimum": 1 } }, { "name": "format", "in": "query", "description": "The template format. Repeatable; repeated values OR.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "EDI", "TRADACOMS", "FIX", "IDOC", "X12", "CSV", "EXCEL", "XML", "BWA", "JSON", "CARGO" ] } } }, { "name": "side", "in": "query", "description": "Only templates that can be sent on this structure: `SOURCE` for `sourceStructure.template`, `TARGET` for `targetStructure.template`. Only IDoc templates belong to one side; every other template is listed for both.", "schema": { "type": "string", "enum": [ "SOURCE", "TARGET" ] } }, { "name": "search", "in": "query", "description": "Words to find in the template name or its format, case-insensitive; every word must match, as a whole word of the name, as part of it, or with one typo (two for a word of eight characters or more). The best matches come first.", "schema": { "type": "string" }, "example": "DESADV D07A" } ], "responses": { "200": { "description": "Templates returned.", "content": { "application/json": { "schema": { "type": "object", "description": "Standard Platform API success envelope. Every response carries exactly one of `data` (success) or `error` (failure) at top level.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/core.StructureTemplate", "title": "StructureTemplate" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data" ] }, "examples": { "The SAP releases of one IDoc": { "description": "`?format=IDOC&side=SOURCE&search=DELVRY03`: the envelope as returned, the page in `data`, the paging state in `meta`.", "value": { "data": [ { "name": "IDOC_IN_DELVRY03", "format": "IDOC", "side": "SOURCE" }, { "name": "V75IDOC_IN_DELVRY03", "format": "IDOC", "side": "SOURCE" }, { "name": "V7IDOC_IN_DELVRY03", "format": "IDOC", "side": "SOURCE" } ], "meta": { "page": 0, "size": 20, "total": 3 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "schemas": { "core.StructureTemplate": { "type": "object", "description": "A structure template this instance bundles; send its `name` as the `template` of `mappingSettings.sourceStructure` or `mappingSettings.targetStructure`. Read-only.", "properties": { "class": { "type": "string", "const": "core.StructureTemplate", "description": "The type of this object, always `core.StructureTemplate`. Required where the member it is sent in accepts several types." }, "format": { "$ref": "#/components/schemas/core.TemplateFormat", "description": "The format; the `format` query parameter filters on it.", "title": "TemplateFormat" }, "name": { "type": "string", "description": "The value for `template`.", "examples": [ "V7IDOC_IN_DELVRY03" ] }, "side": { "$ref": "#/components/schemas/core.TemplateSide", "description": "Which structure the template can be sent on; the `side` query parameter filters on it.", "title": "TemplateSide" } }, "title": "StructureTemplate" }, "Meta": { "type": "object", "additionalProperties": true, "description": "Everything about the response that is not the resource itself. Members may be added over time; ignore the ones you do not recognize.", "properties": { "page": { "type": "integer", "format": "int32", "description": "Zero-based index of the returned page." }, "size": { "type": "integer", "format": "int32", "description": "Number of entries per page." }, "total": { "type": "integer", "format": "int64", "description": "Number of entries across all pages." } } }, "core.TemplateFormat": { "type": "string", "description": "The format of a bundled structure template.\n\n- `EDI`: UN/EDIFACT messages, `_` (`DESADV_D07A`).\n- `TRADACOMS`: TRADACOMS messages.\n- `FIX`: Fixed-length formats (`VDA_4913`).\n- `IDOC`: SAP IDocs, `[V7|V75]IDOC_IN|OUT_`.\n- `X12`: ANSI X12 transactions, `_` (`850_004060`).\n- `CSV`: CSV layouts (`Datanorm4`).\n- `EXCEL`: Excel layouts.\n- `XML`: XML documents (`XRechnung_Standard_3.0.2_UBL`).\n- `BWA`: BWA records (`Bestellsatz`).\n- `JSON`: JSON documents.\n- `CARGO`: IATA Cargo-IMP air cargo messages (`FWB`).", "enum": [ "EDI", "TRADACOMS", "FIX", "IDOC", "X12", "CSV", "EXCEL", "XML", "BWA", "JSON", "CARGO" ], "title": "TemplateFormat" }, "core.TemplateSide": { "type": "string", "description": "Which `template` member a bundled structure template can be sent on.\n\n- `SOURCE`: Only `mappingSettings.sourceStructure.template` (an `IDOC_IN_` template).\n- `TARGET`: Only `mappingSettings.targetStructure.template` (an `IDOC_OUT_` template).\n- `BOTH`: Either side; on the source side its format must match the profile's `parsing.documentType`.", "enum": [ "SOURCE", "TARGET", "BOTH" ], "title": "TemplateSide" }, "ErrorResponse": { "type": "object", "description": "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.", "properties": { "error": { "$ref": "#/components/schemas/Error", "description": "What went wrong: branch on its `code`, show its `message`, and read `details` for one entry per failed member." } }, "required": [ "error" ] }, "Error": { "type": "object", "description": "The error that made the request fail.", "properties": { "code": { "type": "string", "description": "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": { "type": "string", "description": "Human-readable, non-localized explanation. Branch on `code`, never on this text." }, "details": { "type": "array", "description": "Individual failures within the request, e.g. one entry per violated field.", "items": { "$ref": "#/components/schemas/ErrorDetail" } } }, "required": [ "code", "message" ] }, "ErrorDetail": { "type": "object", "description": "A single failure within the request.", "properties": { "code": { "type": "string", "description": "Stable machine-readable `UPPER_SNAKE` code of this individual failure, e.g. `FIELD_REQUIRED`, `FIELD_INVALID` or `VALUE_OUT_OF_RANGE`." }, "message": { "type": "string", "description": "Human-readable, non-localized explanation of this individual failure." }, "target": { "type": "string", "description": "What this failure refers to, e.g. the violated field." } }, "required": [ "code", "message" ] } }, "responses": { "BadRequest": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "BAD_REQUEST", "message": "The request is invalid." } } } } }, "Unauthorized": { "description": "Authentication is required or the supplied credentials are invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "UNAUTHORIZED", "message": "Authentication is required to access this resource." } } } } }, "Forbidden": { "description": "The caller lacks the permission for this operation on this resource (`FORBIDDEN`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "FORBIDDEN", "message": "Access to this resource is denied." } } } } }, "NotFound": { "description": "The requested resource does not exist. The code is resource-specific, e.g. `PARTNER_NOT_FOUND`, `PROFILE_NOT_FOUND` or `CHANNEL_NOT_FOUND`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "PARTNER_NOT_FOUND", "message": "Partner not found: 42" } } } } }, "ServerError": { "description": "An unexpected server error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred." } } } } } }, "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "OAuth2 client-credentials flow for machine-to-machine access.\nExchange a client id/secret at `/dw/register/oauth/token` for a bearer token, then send it\nas `Authorization: Bearer `. Client credentials are provisioned in the\nLobster administration UI.\n\nThis is the client-credentials token endpoint of the Platform API. `/oauth/token`, the\n`token_endpoint` advertised at `/.well-known/oauth-authorization-server`, serves the authorization\ncode flow of the `OAuth2AuthorizationCode` scheme.", "flows": { "clientCredentials": { "tokenUrl": "/dw/register/oauth/token", "refreshUrl": "/dw/register/oauth/token", "scopes": {} } } }, "OAuth2AuthorizationCode": { "type": "oauth2", "description": "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.\n\n1. `POST /oauth/register` (no authentication) with the JSON body `{\"redirect_uris\": [\"\"]}` returns a `client_id`. The user's browser has to reach the redirect URI.\n2. 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.\n3. 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`.\n4. 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`.", "flows": { "authorizationCode": { "authorizationUrl": "/oauth/authorize", "tokenUrl": "/oauth/token", "refreshUrl": "/oauth/token", "scopes": {} } } }, "SessionBearer": { "type": "http", "description": "Bearer token obtained from an authenticated browser or guest-user session.\n\n**Flow 1 — UI login:** Log in via the Lobster web UI at `/`, then call\n`GET /auth/sessionBearerToken` to exchange the session cookie for a bearer token.\n\n**Flow 2 — Guest user login token:** Append a GuestUser `loginToken` as a URL\nquery parameter to the base URL to establish a password-free session:\n```\nGET ?loginToken=\n```\nThen call `GET /auth/sessionBearerToken` to obtain the bearer token.", "scheme": "bearer" } } } } ````