ZSK Web API

Returns one thread color (cone) of a thread cone series, looked up by the manufacturer's color number. Use it when you already know the series and the color number, for example from an earlier order, and need the RGB value and color name without loading the whole color list.

Lookup chain

1. GetThreadConeManufacturer: all manufacturers (e.g. A&E, Amann, Madeira)
2. GetThreadConeSeries: series ids of one manufacturer (e.g. Amann-Isacord 40)
3. GetThreadConeList: weight and all colors of one series
4. GetThreadCone: one color of one series, looked up by its color number

Take ConeSeries from GetThreadConeSeries and ColorNumber from GetThreadConeList. Series ids have no fixed pattern (for example Amann-Isacord 40, Madeira-FIRE FIGHTER, Candle Polyester Shade), so do not build them yourself from the manufacturer, name and weight.

Request

Send the request as JSON in the body of POST https://<ZSKAddress>/StitchJob, with ServerVersion 3 and your WebApiLicense. The lookup values go inside the ThreadCone object, not at the top level. Leave out the Client field: a request sent with "Client": "ACE" is rejected.

Response

The response is a standard JobResponseType. On success, Success is true and RequestData holds the color object as a JSON string, which you must parse a second time. ServerVersion.Major repeats the version you requested. Info, NeedleColor, NeedleSequence, PreviewData and Time are empty strings.

The service sends the response on one line. It is indented here to make it easier to read. Line breaks inside RequestData arrive escaped as \u000d\u000a, and any JSON parser decodes them.

{
  "Info": "",
  "NeedleColor": "",
  "NeedleSequence": "",
  "PreviewData": "",
  "RequestData": "{\u000d\u000a  \"Index\": 4,\u000d\u000a  \"ColorNumber\": \"20\",\u000d\u000a  \"R\": 39,\u000d\u000a  \"G\": 40,\u000d\u000a  \"B\": 42,\u000d\u000a  \"ColorName\": \"Black\"\u000d\u000a}",
  "ServerVersion": { "Major": 3, "Minor": 0 },
  "Success": true,
  "Time": ""
}

RequestData after parsing:

{
  "Index": 4,
  "ColorNumber": "20",
  "R": 39,
  "G": 40,
  "B": 42,
  "ColorName": "Black"
}

The color object is returned exactly as it is stored in the series, so it has the same fields as one entry of Colors in GetThreadConeList:

• Index (integer): position of the color within its series. Some series store the value as a string, so accept both.
• ColorNumber (string): the manufacturer's color number
• R, G, B (integer, 0-255): RGB color value
• ColorName (string, optional): color name. Most series have no color names, so the field is often missing or empty ("").
• ScanCode (integer, optional): scan code of the cone, up to 12 digits, so use a 64-bit type. Only some series include it (for example A&E).

The series weight is not part of this response. Get it from Weight in GetThreadConeList. To use the color for a needle in CreatePNG or CreateTC, copy R, G, B, ColorName and ColorNumber into Red, Green, Blue, ColorName and ColorNumber of the Needle entry. Send the series Weight as ThreadSize, as a string (e.g. "40").

Errors

On failure, Success is false and RequestData holds the error message. Lookup errors come back with HTTP status 200, so always check Success.

• Thread cone series not found: <ConeSeries>: there is no series with this id. You also get this when ThreadCone or ConeSeries is missing or misspelled.
• Thread cone not found: <ConeSeries> / <ColorNumber>: the series exists but has no color with this number. You also get this when ColorNumber is missing.
• GetThreadCone:<message>: ConeSeries contains characters that are not allowed in a file name, or the series data could not be read. The text after the colon comes from the server and may be in the server's language.
• Error: unknown command!: RequestType is misspelled. The value is case-sensitive.
• No licence token found. / Invalid licence token.: WebApiLicense is missing or invalid. These come back with HTTP status 400.

Notes

• The request is not billed and does not count against your license quota, but it still needs a valid WebApiLicense.
• ColorNumber is matched case-insensitively ("10cg3" finds 10CG3 in Fil-Tec-Glide 40). Apart from that the match must be exact. Nothing is trimmed or zero-padded, so "0020" does not find 20. Send the number as a JSON string.
• If more than one color matches, the first one is returned.
• ThreadCone.Manufacturer and ThreadCone.DataZip are ignored by this request.
• Field names are case-sensitive and must be spelled exactly as shown. Unknown fields are ignored without a warning. For example, "Series" instead of "ConeSeries", or "threadCone" instead of "ThreadCone", leads to Thread cone series not found.
• Send ThreadCone as an object. "ThreadCone": null is not accepted. The call then fails with an HTTP error instead of returning a JobResponseType.
• The same series ids are used by ThreadTable in ACEParaOptimize.