> ## Documentation Index > Fetch the complete documentation index at: https://print.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Test a connector > Plays a connector (saved, or one you are about to create) against a design for every choice of its field: what the product page sends, which mapping matches, and what the editor then does, such as the pages it shows or the design it opens. With `url`, the field and its choices are read from your product page, and the test also checks the selector finds it, the design is assigned to the product, and no other connector on the design fights it. Nothing is saved. ## OpenAPI ````yaml openapi.json POST /v2/connectors/test openapi: 3.1.0 info: title: Print.App API version: 2.1.0 description: >- Server-to-server API for Print.App integrations: designs and their page content, folders, files, fonts, palettes, product assignments, projects and editor links. Authenticate every request with a secret key: `Authorization: Bearer sk_…`. Never call it from a browser. servers: - url: https://api.print.app description: Production security: - bearerAuth: [] tags: - name: Account description: The account a secret key belongs to. - name: Designs description: >- The designs (templates) your customers start from: create them at a size, manage their pages, and place text, images and shapes on them. - name: Design folders description: >- Folders that organise your designs. A design can sit in more than one folder. - name: Files description: >- Your own images and graphics, used in designs and offered to customers in the editor. - name: Graphic folders description: >- Folders of files, shown in the editor under Pictures, Backgrounds, Textures or Frames. - name: Fonts description: >- The fonts your designs and customers can use: the built-in set, imported Google fonts and fonts you upload. - name: Palettes description: Colour palettes offered in the editor. - name: Products description: Which designs open for each product (and variant) in your store. - name: Projects description: Your customers' saved designs. - name: Links description: Shareable editor links that open a design or project at create.print.app. - name: Connectors description: >- Links between the options on a store's product page and the editor: the choice a customer makes shows the right pages, opens the right design, or sets the size, orientation or colour. Read a product page for what a connector can point at, and test one against a design before customers meet it. - name: Resource profiles description: >- Limits on the fonts, colour palettes and graphic folders the editor offers, for the designs that use them. - name: PDF profiles description: >- The settings print PDFs are made with: colour conversion, PDF standard, cut lines, image resolution, fonts. paths: /v2/connectors/test: post: tags: - Connectors summary: Test a connector description: >- Plays a connector (saved, or one you are about to create) against a design for every choice of its field: what the product page sends, which mapping matches, and what the editor then does, such as the pages it shows or the design it opens. With `url`, the field and its choices are read from your product page, and the test also checks the selector finds it, the design is assigned to the product, and no other connector on the design fights it. Nothing is saved. operationId: testConnector parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectorTest' example: connectorId: 01KADX3Q7M2B8C4D5E6F7G8H9J designId: design_01J8Z9K2M3N4P5Q6R7S8T9V0W1 url: https://shop.example.com/products/custom-tee responses: '200': description: OK. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ConnectorTestResult' '400': description: >- A parameter or body field is malformed: `param` names it and `details` lists every problem found. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true code: invalid_request message: width is required. param: width requestId: FZn-uhymjoEEJow= '401': description: Missing, unknown, revoked or expired secret key. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true code: unauthorized message: >- Missing or invalid secret key. Send it as "Authorization: Bearer sk_…". requestId: FZn-uhymjoEEJow= '403': description: The account is suspended for an unpaid invoice. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true code: account_suspended message: >- This account is suspended. Settle the outstanding invoice in the Print.App dashboard. requestId: FZn-uhymjoEEJow= '404': description: >- Not found in your account. Another account's resources answer 404 too. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true code: not_found message: Not found. requestId: FZn-uhymjoEEJow= '415': description: The body is not JSON. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true code: unsupported_media_type message: >- Send the request body as JSON, with "Content-Type: application/json". requestId: FZn-uhymjoEEJow= '429': description: >- Rate limited by the API gateway. Back off and retry. This response comes from the gateway, so its body is `{ "message": "Too Many Requests" }`, not the standard error. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: message: Too Many Requests '500': description: >- Something failed on our side. Retry; quote the requestId to support if it persists. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true code: internal_error message: >- Something went wrong on our side. Retry the request; if it keeps failing, contact support with the requestId. requestId: FZn-uhymjoEEJow= components: schemas: ConnectorTest: title: ConnectorTest description: >- A connector to play against a design: a saved one (`connectorId`) or one to try before saving (`connector`). type: object additionalProperties: false required: - designId properties: connectorId: type: string minLength: 1 maxLength: 100 description: A saved connector. connector: type: object additionalProperties: false required: - title - mode - source properties: title: type: string minLength: 1 maxLength: 200 description: The connector's name, shown in the dashboard. mode: type: string enum: - pageIndex - designSelector - pageClone - pageCount - printedPageCount - pageWidth - pageHeight - pageOrientation - textValue - underlayColor - event description: >- What the connector does: - `pageIndex`: Shows only the pages a choice maps to (`to`: page numbers such as `1` or `1,2`). The other pages are set aside: not shown, printed or saved. - `designSelector`: Opens another design for each choice (`to`: a design id). Every design it can open must be assigned to the product and carry this connector too. - `pageClone`: Repeats one page (`page`, default the first) as many times as the number chosen, when the editor opens. - `pageCount`: Sends the number of pages to the field as the customer adds or removes pages (editor to product page). - `printedPageCount`: Sends the number of pages (sides) that carry a print to the field, so the price can follow (editor to product page). The field takes a number. - `pageWidth`: Sets the page width from a number field, in the design's unit (a Print Options size field carries its own). With twoWay, a resize in the editor is sent back. - `pageHeight`: Sets the page height from a number field, in the design's unit (a Print Options size field carries its own). With twoWay, a resize in the editor is sent back. - `pageOrientation`: Turns the pages (or `page` alone) landscape or portrait, from the choice's wording or its mapping (`to`: landscape or portrait). - `textValue`: Puts what the customer types into the text item titled `text`. With twoWay, edits in the editor are sent back. - `underlayColor`: Sets the product colour of an underlay design (a T-shirt, a mug): `to` is a hex colour, or leave the choice unmapped when it is the colour's name in the design. - `event`: Fires an editor event (`event.name`, with `event.data`) when the field changes. For integrations that listen to editor events. source: type: object additionalProperties: false minProperties: 1 description: >- Where on the product page the connector reads (and, for two-way modes, writes): a CSS selector for a control of the store's theme, or a Print Options field by `role` (preferred: one connector then works on every product) or by `field` id. `GET /v2/product-page` lists both for a page. properties: selector: type: string minLength: 1 maxLength: 500 description: >- A CSS selector for the control, as `GET /v2/product-page` gives it: `select[name="options[Size]"]`, or `input[name="Color"]:checked` for a group of radio choices. role: type: string minLength: 1 maxLength: 50 description: >- A Print Options field role: `size`, `pages`, `material`, `orientation`, or the field types `quantity`, `dimensions` and `file`. field: type: string minLength: 1 maxLength: 100 description: A Print Options field id, when the field has no role. axis: type: string enum: - w - h description: >- For a Print Options `dimensions` field: the width (`w`) or the height (`h`). mappings: type: array maxItems: 200 description: >- What each choice on the product page becomes in the editor. `from` is the choice as the page sends it: its value, or for dropdowns and Print Options choices also the text the customer sees (case and surrounding spaces ignored). Radio choices send their value only. items: type: object additionalProperties: false required: - from - to properties: from: type: string minLength: 1 maxLength: 200 description: >- The choice: its value or (dropdowns, Print Options) its label. to: type: string minLength: 1 maxLength: 200 description: >- What it means to the editor: page numbers such as `1` or `1,2` (pageIndex), a design id (designSelector), a hex colour (underlayColor), or landscape / portrait (pageOrientation). twoWay: type: boolean default: true description: >- For pageWidth, pageHeight, textValue and underlayColor: also send changes made in the editor back to the product page. page: type: - integer - 'null' minimum: 1 maximum: 500 description: >- For pageClone, pageWidth, pageHeight and pageOrientation: the page (from 1) it acts on. Default: the first page (pageOrientation: every page). text: type: - string - 'null' minLength: 1 maxLength: 200 description: 'For textValue: the title of the text item it fills.' event: type: - object - 'null' additionalProperties: false required: - name description: 'For event: the editor event to fire.' properties: name: type: string pattern: ^[\w:.-]{1,100}$ description: The event name, for example `page:select`. data: type: - string - 'null' maxLength: 2000 description: Data sent with the event. description: >- A connector to try without saving it, as `POST /v2/connectors` takes it. designId: type: string minLength: 1 maxLength: 200 description: The design it is (or will be) attached to. url: type: string format: uri maxLength: 2000 description: >- The product page, to read the field and its choices from it. A page of your store only. values: type: array maxItems: 100 description: >- The choices to play, when there is no page to read them from (or to play others than the page has): a value, or `{ value, label }` for a choice whose label differs. items: anyOf: - type: string maxLength: 200 - type: object additionalProperties: false required: - value properties: value: type: string maxLength: 200 label: type: string maxLength: 200 examples: - connectorId: 01KADX3Q7M2B8C4D5E6F7G8H9J designId: design_01J8Z9K2M3N4P5Q6R7S8T9V0W1 url: https://shop.example.com/products/custom-tee ConnectorTestResult: title: ConnectorTestResult description: What a connector does for each choice, and what stands in its way. type: object required: - object - ok - connector - design - page - results - issues properties: object: type: string const: connector_test ok: type: boolean description: Every choice does what it should and nothing blocks it. connector: $ref: '#/components/schemas/Connector' design: type: object required: - id - title - editor - attached - pages properties: id: type: string title: type: - string - 'null' editor: type: string enum: - new - classic description: >- The editor the design opens in. They differ for pageIndex: the classic one applies it only when it opens. attached: type: boolean description: The connector is attached to the design. pages: type: array items: type: object required: - index - title - previewUrl properties: index: type: integer title: type: - string - 'null' previewUrl: type: - string - 'null' page: anyOf: - type: 'null' - type: object required: - url - productId - passwordProtected - control - field properties: url: type: string productId: type: - string - 'null' passwordProtected: type: boolean control: anyOf: - type: 'null' - type: object required: - kind - name - label - selector - matches - inProductForm - sends - choices properties: kind: type: string enum: - select - radio - fieldset - checkbox - text - number - textarea - element name: type: - string - 'null' description: Its form name. label: type: - string - 'null' description: Its label on the page. selector: type: string description: The selector to give as `source.selector`. matches: type: integer description: >- How many elements the selector finds as the page loads. The client uses the first; 0 for radio choices means none is selected by default. inProductForm: type: boolean description: It is part of the add-to-cart form. sends: type: string description: >- What the client sends for it: `value and text`, `value`, or `its text`. value: type: - string - 'null' description: Its value as the page loads (inputs). choices: type: array items: type: object required: - value - label - selected properties: value: type: string description: What the page sends for it. label: type: - string - 'null' description: What the customer sees. selected: type: boolean description: Selected when the page loads. notes: type: array items: type: string description: What could stop a connector working with it. description: The control the selector finds. field: anyOf: - type: 'null' - type: object required: - id - label - type - role - source - reference - sends - choices properties: id: type: string label: type: - string - 'null' type: type: - string - 'null' description: >- select-one, select-many, quantity, dimensions, number, text, file… role: type: - string - 'null' description: >- Its role, explicit or from its type (quantity, dimensions, file). source: type: object description: >- What to give as `source`: `{ role }` when it has one, else `{ field }`. properties: role: type: string field: type: string reference: type: string description: >- The stored query: `po:role/` or `po:field/`. sends: type: string choices: type: array items: type: object required: - value - label - selected properties: value: type: string description: What the page sends for it. label: type: - string - 'null' description: What the customer sees. selected: type: boolean description: Selected when the page loads. description: The Print Options field the source finds. results: type: array description: >- One per choice played (pageCount and printedPageCount: one per page count). items: type: object required: - outcome - result - ok properties: choice: type: object required: - value - label properties: value: type: string label: type: - string - 'null' count: type: integer description: 'pageCount, printedPageCount: the count the editor writes.' sends: type: object required: - value properties: value: type: string text: type: string mapping: anyOf: - type: 'null' - type: object required: - from - to properties: from: type: string to: type: string outcome: type: string description: >- pages, design, orientation, color, copies, size, text, event, sets_field, no_mapping or nothing. result: type: string description: What the editor does, in words. ok: type: boolean problem: type: string note: type: string pages: type: array items: type: object required: - index - number - title properties: index: type: integer number: type: integer description: From 1, as mappings count. title: type: - string - 'null' description: 'pageIndex: the pages shown.' designId: type: string description: 'designSelector: the design opened.' orientation: type: - string - 'null' color: anyOf: - type: 'null' - type: object required: - title - hex properties: title: type: - string - 'null' hex: type: - string - 'null' issues: type: array items: type: object required: - level - code - message properties: level: type: string enum: - error - warning code: type: string message: type: string Error: title: Error description: >- Every error the API itself returns. Match on `code`; `message` is for people and may be reworded. type: object required: - error - code - message - requestId properties: error: type: boolean const: true code: type: string enum: - unauthorized - account_suspended - invalid_request - not_found - route_not_found - idempotency_key_reused - idempotency_in_progress - folder_not_empty - builtin_folder - builtin_palette - editor_not_supported - design_changed - payload_too_large - unsupported_media_type - ops_failed - internal_error - service_unavailable description: >- `unauthorized` (401): missing, unknown, revoked or expired secret key. `account_suspended` (403): the account has an unpaid invoice. `invalid_request` (400): a parameter or body field is malformed — see `param` and `details`. `not_found` (404): no such resource in your account. `route_not_found` (404): no such endpoint. `idempotency_key_reused` (409): the Idempotency-Key was used for a different request. `idempotency_in_progress` (409): the first request with that key is still running. `folder_not_empty` (409): the folder still holds designs or folders. `builtin_folder`, `builtin_palette` (409): Print.App's own folders and palettes cannot be changed. `editor_not_supported` (409): page content can only be edited on accounts that use the new editor. `design_changed` (409): the design was saved elsewhere while the batch ran; read it again and retry. `payload_too_large` (413): a body or file over the limit. `unsupported_media_type` (415): send JSON. `ops_failed` (422): an operation in the batch failed, nothing was saved — see `details`. `internal_error` (500): retry; contact support with the `requestId` if it persists. `service_unavailable` (503): retry in a few seconds. message: type: string param: type: string description: The parameter or body field at fault, as a path (`pages[0].title`). details: type: array description: >- Every problem found, when there was more than one (`invalid_request`), or each operation's result (`ops_failed`). items: type: object requestId: type: string description: >- Also sent as the `x-request-id` header. Quote it when contacting support. examples: - error: true code: invalid_request message: limit must be an integer from 1 to 100. param: limit requestId: FZn-uhymjoEEJow= GatewayError: type: object properties: message: type: string description: Returned by the API gateway itself (429). Connector: title: Connector description: >- Links an option on a store's product page to the editor: the choice a customer makes shows the right pages, opens the right design, sets the size or the colour. type: object required: - object - id - title - mode - source - query - mappings - twoWay - page - text - event - created - modified properties: object: type: string const: connector id: type: - string - 'null' description: '`null` for a connector tried in a test without saving it.' title: type: - string - 'null' mode: type: string description: >- One of: pageIndex, designSelector, pageClone, pageCount, printedPageCount, pageWidth, pageHeight, pageOrientation, textValue, underlayColor, event. source: type: object required: - type properties: type: type: string enum: - selector - printOptions selector: type: string description: The CSS selector (type selector). role: type: - string - 'null' description: The Print Options role (type printOptions). field: type: - string - 'null' description: The Print Options field id (type printOptions). name: type: - string - 'null' description: >- A Print Options field id or role, from connectors made before roles (type printOptions). axis: type: - string - 'null' enum: - w - h - null query: type: string description: >- The source as the editor stores it: the selector, or `po:role/`, `po:field/`. mappings: type: array items: type: object required: - from - to properties: from: type: string to: type: string twoWay: type: boolean page: type: - integer - 'null' text: type: - string - 'null' event: type: - object - 'null' required: - name - data properties: name: type: string data: type: - string - 'null' created: type: - string - 'null' format: date-time modified: type: - string - 'null' format: date-time examples: - object: connector id: 01KADX3Q7M2B8C4D5E6F7G8H9J title: Print side → pages mode: pageIndex source: type: selector selector: input[name="Print side"]:checked query: input[name="Print side"]:checked mappings: - from: Front to: '1' - from: Back to: '2' - from: Front and back to: 1,2 twoWay: true page: null text: null event: null created: '2026-10-27T10:00:00Z' modified: '2026-10-27T10:00:00Z' headers: RequestId: description: Identifies the request. Quote it when contacting support. schema: type: string securitySchemes: bearerAuth: type: http scheme: bearer description: >- A secret key from Print.App admin → Domains → Secret keys, sent as `Authorization: Bearer sk_…`. Server-side only. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.