ZSK Web API

GetNeedleSequence

POST

Returns the order in which the needles are used in an embroidery file. Supported for TC (Z00), TBF, DST and DSZ data.

Request

POST the request as JSON to https://<ZSKAddress>/StitchJob with ServerVersion 3 and your WebApiLicense. Key names are case-sensitive. Unknown keys are ignored.

EmbroideryBase64 holds the complete embroidery file, Base64 encoded. EmbroideryType names the format of that file. It is required and has no default. The value is case-sensitive: use exactly one of the values below.

EmbroideryType	File	Result
`TC`	.z00	The needle number of each needle change in the file, in stitch order. A stop command adds the current needle number again. If the file ends with a needle change or stop that has no stitches or jumps after it, that entry is not listed.
`TBF`	.tbf	The needle sequence stored in the TBF file header.
`DST`	.dst	The numbers 1, 2, 3 ... with one number for each color block. DST files contain no needle numbers.
`DSZ`	.dsz	The server first converts the file to DST. The result is the same as for DST.

For DST and DSZ, the numbers are block positions, not machine needles. No needle assignment is needed, and a Needle list in the request is ignored. A file normally returns one entry more than it has color changes. A color block with fewer than two stitches (for example a block with only jumps) is merged into the neighbouring block, so the list can be shorter.

The server does not check that the data matches EmbroideryType. Wrong data can give an error, an empty list or a meaningless list. A truncated TC or DST file can return a shorter list with Success true.

Response

A JobResponseType. On success, RequestData is a string that holds a JSON array of integers, formatted with line breaks. Parse RequestData a second time to get the list. Each entry is one color block, in stitch order. For TC and TBF, the value is the needle number of that block. For DST and DSZ, it is the position of the block (1, 2, 3 ...). The other fields are empty. The response field NeedleSequence is empty too: the result is only in RequestData. On failure, RequestData holds a plain error text instead. Some data that cannot be read returns Success true with an empty RequestData or an empty list (see Errors).

The array has the same format as the NeedleSequence field of a CreateTC or CreateTBF response.

Response (formatted for readability; the server sends it on one line):

{
  "Info": "",
  "NeedleColor": "",
  "NeedleSequence": "",
  "PreviewData": "",
  "RequestData": "[\u000d\u000a  7,\u000d\u000a  1,\u000d\u000a  24,\u000d\u000a  7,\u000d\u000a  2,\u000d\u000a  24\u000d\u000a]",
  "ServerVersion": { "Major": 3, "Minor": 0 },
  "Success": true,
  "Time": ""
}

Parsed RequestData:

[7, 1, 24, 7, 2, 24]

In this TC example, the design starts with needle 7. It changes to needle 1, then to needle 24, and then back to needle 7. For DST and DSZ, the list always counts up from 1. A DST file with three color changes normally returns [1, 2, 3, 4].

Errors

Check Success first. In the three rows with Success true, RequestData is an empty string or an empty list. An empty string is not valid JSON. Check that RequestData is not empty before you parse it, and check that the parsed list is not empty.

HTTP	Success	RequestData	Cause
200	`false`	`Error: No embroidery data!`	`EmbroideryBase64` is missing, `null` or an empty string.
200	`true`	(empty string)	`EmbroideryType` is missing or is not exactly `TC`, `TBF`, `DST` or `DSZ` (for example `tc` or `Z00`).
200	`true`	(empty string)	DST data, or DSZ data after conversion, that does not start with the DST header `LA:`, or in which every color block has fewer than two stitches.
200	`true`	`[]`	The data holds no needle sequence. Examples: a TBF file with an empty needle section, DST data without any color change or end record, or TC data where `EmbroideryBase64` holds only spaces or line breaks.
200	`false`	Error message	The data cannot be read as the given `EmbroideryType`, for example a DST file sent as `TC`, or a TBF or DST file that is too short. Example: `Index was out of range. ...`
200	`false`	`Error: GetNeedleSequence DSZ command failed!`	DSZ only: the file could not be converted. Check the file, or retry later.
200	`false`	`Error: unknown command!`	`RequestType` is missing, misspelled or has the wrong case.
400	`false`	`No licence token found.`	`WebApiLicense` is missing or empty.
400	`false`	`Invalid licence token.`	`WebApiLicense` is rejected.
500	`false`	Error message	`EmbroideryBase64` is not valid Base64 (example: `The input is not a valid Base-64 string ...`), or another unexpected server error.

Where the table says Error message, RequestData holds the text of a .NET exception. Its wording and language depend on the server, so do not compare it with a fixed text.

Notes

Difference from GetNeedleInfo: GetNeedleInfo returns the needle definitions stored in the file, one entry per needle with its color (NeedleNumber, RGB values, ColorName and more). GetNeedleSequence returns the order in which the needles are used, and a needle can appear several times. For TC and TBF, each number in the sequence refers to a NeedleNumber from GetNeedleInfo. GetNeedleInfo supports TC and TBF only. GetNeedleSequence also accepts DST and DSZ.
Do not set Client. Some values select different processing. For example, ACE rejects this request with HTTP 400.

Parameters

Parameter	Type	Description	Required
`RequestType`	string	Must be "GetNeedleSequence" (case-sensitive). A missing, misspelled or wrong-case value returns "Error: unknown command!".	Yes
`ServerVersion`	int	API version. Use 3.	Yes
`WebApiLicense`	string	Your ZSK Web API license key, format xxxxx-xxxxx-xxxxx-xxxxx-xxxxx. Missing or empty: HTTP 400 "No licence token found." Rejected: HTTP 400 "Invalid licence token."	Yes
`EmbroideryType`	string	Format of the data in EmbroideryBase64: "TC" (.z00), "TBF", "DST" or "DSZ". Case-sensitive, no default. A missing or any other value returns Success true with an empty RequestData.	Yes
`EmbroideryBase64`	string	The complete embroidery file, Base64 encoded. Missing, null or empty: "Error: No embroidery data!". Only spaces or line breaks: read as an empty file. Invalid Base64: HTTP 500.	Yes

Example

{
  "RequestType": "GetNeedleSequence",
  "ServerVersion": 3,
  "WebApiLicense": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
  "EmbroideryType": "TC",
  "EmbroideryBase64": "base64 encoded embroidery data"
}