ZSK Web API

Returns the thread weight and the full color list of one thread cone series (thread chart).

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

Send the request as JSON with POST to https://<ZSKAddress>/StitchJob. Pick the series with ThreadCone.ConeSeries. Use an id exactly as GetThreadConeSeries returns it, for example Amann-Isacord 40. Series ids have no fixed pattern (for example Madeira-FIRE FIGHTER or Candle Polyester Shade), so don't build them from the manufacturer name and the weight.

Response

The request returns a JobResponseType. When it succeeds, Success is true and RequestData holds a JSON object as a string (indented JSON text), so you have to parse RequestData a second time. ServerVersion.Major is the ServerVersion from the request. All other fields are empty strings.

Response (formatted for readability and shortened to the first two colors; the full Amann-Isacord 40 list has 391 colors):

{
  "Info": "",
  "NeedleColor": "",
  "NeedleSequence": "",
  "PreviewData": "",
  "RequestData": "{\u000d\u000a  \"Weight\": 40,\u000d\u000a  \"Colors\": [\u000d\u000a    {\u000d\u000a      \"Index\": 0,\u000d\u000a      \"ColorNumber\": \"3\",\u000d\u000a      \"R\": 235,\u000d\u000a      \"G\": 236,\u000d\u000a      \"B\": 238,\u000d\u000a      \"ColorName\": \"Ghost White\"\u000d\u000a    },\u000d\u000a    {\u000d\u000a      \"Index\": 1,\u000d\u000a      \"ColorNumber\": \"10\",\u000d\u000a      \"R\": 234,\u000d\u000a      \"G\": 240,\u000d\u000a      \"B\": 255,\u000d\u000a      \"ColorName\": \"Silky White\"\u000d\u000a    }\u000d\u000a  ]\u000d\u000a}",
  "ServerVersion": {
    "Major": 3,
    "Minor": 0
  },
  "Success": true,
  "Time": ""
}

RequestData after parsing:

{
  "Weight": 40,
  "Colors": [
    {
      "Index": 0,
      "ColorNumber": "3",
      "R": 235,
      "G": 236,
      "B": 238,
      "ColorName": "Ghost White"
    },
    {
      "Index": 1,
      "ColorNumber": "10",
      "R": 234,
      "G": 240,
      "B": 255,
      "ColorName": "Silky White"
    }
  ]
}

RequestData fields

• Weight (integer): thread weight of the series, for example 40. Read the weight from this field and don't parse it from the series id.
• Colors (array): every color of the series, in the order of the thread chart. Each entry has these fields:
  • Index (integer): position of the color in the thread chart, starting at 0. The numbering can have gaps, and some series store the value as a string, so accept both.
  • ColorNumber (string): the manufacturer's color number. It is always a string, even when it looks like a number (for example "20"), and it can contain letters (for example "10CG3"). Pass this value unchanged to GetThreadCone.
  • R, G, B (integer, 0-255): RGB value of the color.
  • ColorName (string, optional): name of the color. Most series have no color names, and some have names for only part of their colors. A color without a name either has no ColorName field, for example {"Index": 5, "ColorNumber": "21", "R": 40, "G": 41, "B": 44}, or has "ColorName": "".
  • ScanCode (integer, optional): scan code of the thread cone. It has up to 12 digits, so read it into a 64-bit integer. Only some series include it (for example A&E).

The response contains only Weight and Colors. It does not include the manufacturer; take that from GetThreadConeManufacturer.

Using the colors

To use a color in the Needle block of CreatePNG or CreateTC, map it like this:

• R, G, B go to Red, Green, Blue.
• ColorNumber and ColorName keep their names. Send "" when the color has no name.
• Weight goes to ThreadSize as a string, for example "40".

The same series id also works as ThreadTable in ACEParaOptimize.

Errors

• Unknown series, or ThreadCone.ConeSeries missing: Success is false and RequestData is Thread cone series not found: <ConeSeries>. The HTTP status is still 200, so always check Success.
• Server error while reading the thread chart: Success is false and RequestData is GetThreadConeList:<error message> (HTTP 200).
• Missing or misspelled RequestType: Success is false and RequestData is Error: unknown command! (HTTP 200).
• Missing or invalid license: HTTP 400, Success is false and RequestData is No licence token found. or Invalid licence token. See ZSK Web API License.
• "ThreadCone": null: the server can't read the request and answers with an error instead of a JobResponseType. Send the object with ConeSeries.

Notes

• This request is not billed and does not count against the license quota. You still need a valid WebApiLicense.
• This request only reads ThreadCone.ConeSeries. It ignores ThreadCone.Manufacturer and ThreadCone.ColorNumber.
• Put the lookup parameter inside the ThreadCone object, not at the top level. RequestType and all key names are case-sensitive, and the server silently ignores keys it doesn't recognize (a misspelled ThreadCone leads to "Thread cone series not found"). Matching of the series id itself is not case-sensitive.
• Leave out Client. With "Client": "ACE" the server handles the request as an ACE picture/vector job and answers with HTTP 400.
• Large series have several thousand colors (for example Candle Polyester Shade with about 4000). Thread charts rarely change, so cache the result on the client.