ZSK Web API

GetThreadConeSeries

POST

Returns the thread cone series (color charts) that are installed on the server for one thread manufacturer.

This is step 2 of the thread cone lookup: GetThreadConeManufacturer → GetThreadConeSeries → GetThreadConeList (all colors of a series) or GetThreadCone (one color).

Request

POST the request as JSON to https://<ZSKAddress>/StitchJob with ServerVersion 3 and your WebApiLicense.

The manufacturer goes inside the ThreadCone object, not at the top level. Key names are case-sensitive and unknown keys are ignored. A top-level Manufacturer or a key spelled manufacturer has no effect.

ThreadCone.Manufacturer must be a name returned by GetThreadConeManufacturer, e.g. Amann, Madeira or A&E. The value is case-insensitive (amann works), but the whole name must match. Partial names do not match, and leading or trailing spaces are not removed.

Response

A JobResponseType. On success, RequestData is a string that holds a JSON array of series ids, sorted alphabetically. Parse RequestData a second time to get the array. The other fields are empty. On failure, RequestData holds a plain error text instead (see Errors).

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

{
  "Info": "",
  "NeedleColor": "",
  "NeedleSequence": "",
  "PreviewData": "",
  "RequestData": "[\u000d\u000a  \"Amann-Isacord 40\",\u000d\u000a  \"Amann-Saba 40\",\u000d\u000a  \"Amann-Serafil 60\"\u000d\u000a]",
  "ServerVersion": {
    "Major": 3,
    "Minor": 0
  },
  "Success": true,
  "Time": ""
}

Parsed RequestData:

[
  "Amann-Isacord 40",
  "Amann-Saba 40",
  "Amann-Serafil 60"
]

Using the series id

Pass it unchanged as ThreadCone.ConeSeries to GetThreadConeList or GetThreadCone.
Pass it as ThreadTable in ACEParaOptimize to map image colors to this thread chart.
Always take ids from this response. Do not build them yourself, because they do not follow a fixed pattern (e.g. Madeira-FIRE FIGHTER, Candle Polyester Shade). Do not read the thread weight from the id either. GetThreadConeList returns Weight.

Errors

An unknown, misspelled or missing ThreadCone.Manufacturer is not reported as an error. Success is true and RequestData is "[]", so treat an empty array as "manufacturer not found".
If the server cannot read its thread cone folder, the response is HTTP 200 with Success false and RequestData "GetThreadConeSeries:<message>".
A missing or invalid license returns HTTP 400 with Success false and RequestData "No licence token found." or "Invalid licence token.".
RequestType is case-sensitive. A misspelled value returns HTTP 200 with Success false and RequestData "Error: unknown command!".
Invalid JSON or "ThreadCone": null is rejected with an HTTP error instead of a JobResponseType. Always send ThreadCone as an object.

Notes

Not billed: the request needs a valid WebApiLicense but does not count as API usage.
Do not set Client for this request. With "ACE" (any case), the request is sent to the ACE endpoint, which does not serve thread cone requests and returns HTTP 400.
The result lists the color charts currently installed on the server. Charts that cannot be read are skipped. The list changes rarely, so clients may cache it.

Parameters

Parameter	Type	Description	Required
`RequestType`	string	Must be "GetThreadConeSeries" (case-sensitive).	Yes
`ServerVersion`	int	API version. Use 3.	Yes
`WebApiLicense`	string	Your ZSK Web API license key, format xxxxx-xxxxx-xxxxx-xxxxx-xxxxx. The request is not billed.	Yes
`ThreadCone.Manufacturer`	string	Manufacturer name as returned by GetThreadConeManufacturer, e.g. "Amann". It must be inside the ThreadCone object, and key names are case-sensitive. The value is case-insensitive, but the whole name must match. An unknown or missing name returns an empty array "[]".	Yes

Example

{
  "RequestType": "GetThreadConeSeries",
  "ServerVersion": 3,
  "WebApiLicense": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
  "ThreadCone": {
    "Manufacturer": "Amann"
  }
}