{"openapi":"3.1.0","info":{"title":"TikTok Sourcing Requests","version":"1.0.0","description":"Create and update multi-item SRs. These endpoints save data; they do not start sourcing, send callbacks, or create quotations. Bearer authentication is required when API_TOKEN is configured; localhost development may omit it."},"servers":[{"url":"https://dev.ttk-agent.sourcy.ai","description":"Development"},{"url":"https://ttk-agent.sourcy.ai","description":"Production"},{"url":"http://127.0.0.1:4062","description":"Local development"}],"paths":{"/api/v1/sourcing-requests":{"post":{"operationId":"createSourcingRequest","summary":"Create an SR","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSourcingRequest"},"example":{"external_id":"rec_8841","merchant":{"id":"m_onelovedbabe","name":"One Loved Babe"},"destination":{"country":"US","city":"Los Angeles","region":"California"},"items":[{"name":"Velvet wrap maxi dress","description":"Long-sleeve velvet maxi dress with a wrap front and tie waist.","quantity":50,"images":[],"specs":[{"name":"Fabric","value":"Velvet","required":true},{"name":"Length","value":"Maxi","required":true}]},{"name":"Satin midi skirt","description":"Bias-cut satin skirt.","quantity":25,"specs":[{"name":"Length","value":"Midi","required":true}]}]}}}},"responses":{"201":{"description":"Complete saved SR with integer id, public sr_id, version, timestamps, and all items (including integer item IDs and revisions).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcingRequest"}}}},"400":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}},"409":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}},"413":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}},"415":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}},"500":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}}}}},"/api/v1/sourcing-requests/{srId}":{"patch":{"operationId":"updateSourcingRequest","summary":"Update an SR","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSourcingRequest"},"example":{"version":1,"notes":"Confirm both items before quotation.","items":[{"id":1,"selected":true,"quantity":75,"customization":{"colour":"Navy","packaging":"Gift box"}}]}}}},"responses":{"200":{"description":"Complete saved SR with integer id, public sr_id, version, timestamps, and all items (including integer item IDs and revisions).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourcingRequest"}}}},"400":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}},"404":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}},"409":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}},"413":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}},"415":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}},"500":{"description":"Request rejected; no changes saved.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"issues":{"type":"array","items":{"type":"object"}}}}}}}},"description":"version is required. Omitted fields/items are preserved. An item with an id is patched; an item without an id is added and requires name and description. Quantity and destination may remain unknown until later. selected records merchant choice; customization stores logo_url, packaging, colour and notes. Provided customization replaces that object; specs and images replace their arrays. No deletion. Merchant/destination objects, when supplied, replace the whole object. Duplicate item IDs and updates without changes are rejected. Maximum 100 total items. Item edits increment revision; old search results retain their original item_revision. Save the returned version for your next update.","parameters":[{"name":"srId","in":"path","required":true,"schema":{"type":"string","pattern":"^TTS-[1-9]\\d*$"},"example":"TTS-1"}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"CreateSourcingRequest":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":200},"merchant":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"name":{"type":"string","minLength":1,"maxLength":300}},"required":["id","name"],"additionalProperties":false},"destination":{"anyOf":[{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$"},"city":{"type":"string","minLength":1,"maxLength":200},"region":{"type":"string","minLength":1,"maxLength":200},"postal_code":{"type":"string","minLength":1,"maxLength":30},"address":{"type":"string","minLength":1,"maxLength":2000}},"required":["country","city"],"additionalProperties":false},{"type":"null"}]},"callback_url":{"anyOf":[{"type":"string","maxLength":4000,"format":"uri"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"needed_by":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"items":{"default":[],"maxItems":100,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","minLength":1,"maxLength":2000},"quantity":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},{"type":"null"}]},"selected":{"default":false,"type":"boolean"},"customization":{"anyOf":[{"type":"object","properties":{"logo_url":{"type":"string","maxLength":4000,"format":"uri"},"packaging":{"type":"string","minLength":1,"maxLength":2000},"colour":{"type":"string","minLength":1,"maxLength":2000},"notes":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},{"type":"null"}]},"images":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","maxLength":4000,"format":"uri"}},"reference_url":{"anyOf":[{"type":"string","maxLength":4000,"format":"uri"},{"type":"null"}]},"specs":{"default":[],"maxItems":100,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":2000},"value":{"type":"string","minLength":1,"maxLength":2000},"required":{"default":false,"type":"boolean"}},"required":["name","value"],"additionalProperties":false}},"notes":{"anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]}},"required":["name","description"],"additionalProperties":false}}},"required":["external_id","merchant"],"additionalProperties":false},"UpdateSourcingRequest":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":200},"merchant":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"name":{"type":"string","minLength":1,"maxLength":300}},"required":["id","name"],"additionalProperties":false},"destination":{"anyOf":[{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$"},"city":{"type":"string","minLength":1,"maxLength":200},"region":{"type":"string","minLength":1,"maxLength":200},"postal_code":{"type":"string","minLength":1,"maxLength":30},"address":{"type":"string","minLength":1,"maxLength":2000}},"required":["country","city"],"additionalProperties":false},{"type":"null"}]},"callback_url":{"anyOf":[{"type":"string","maxLength":4000,"format":"uri"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"needed_by":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"items":{"minItems":1,"maxItems":100,"type":"array","items":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","minLength":1,"maxLength":2000},"quantity":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},{"type":"null"}]},"selected":{"type":"boolean"},"customization":{"anyOf":[{"type":"object","properties":{"logo_url":{"type":"string","maxLength":4000,"format":"uri"},"packaging":{"type":"string","minLength":1,"maxLength":2000},"colour":{"type":"string","minLength":1,"maxLength":2000},"notes":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},{"type":"null"}]},"images":{"maxItems":20,"type":"array","items":{"type":"string","maxLength":4000,"format":"uri"}},"reference_url":{"anyOf":[{"type":"string","maxLength":4000,"format":"uri"},{"type":"null"}]},"specs":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":2000},"value":{"type":"string","minLength":1,"maxLength":2000},"required":{"default":false,"type":"boolean"}},"required":["name","value"],"additionalProperties":false}},"notes":{"anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"id":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647}},"required":["id"],"additionalProperties":false},{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","minLength":1,"maxLength":2000},"quantity":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},{"type":"null"}]},"selected":{"default":false,"type":"boolean"},"customization":{"anyOf":[{"type":"object","properties":{"logo_url":{"type":"string","maxLength":4000,"format":"uri"},"packaging":{"type":"string","minLength":1,"maxLength":2000},"colour":{"type":"string","minLength":1,"maxLength":2000},"notes":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},{"type":"null"}]},"images":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","maxLength":4000,"format":"uri"}},"reference_url":{"anyOf":[{"type":"string","maxLength":4000,"format":"uri"},{"type":"null"}]},"specs":{"default":[],"maxItems":100,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":2000},"value":{"type":"string","minLength":1,"maxLength":2000},"required":{"default":false,"type":"boolean"}},"required":["name","value"],"additionalProperties":false}},"notes":{"anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]}},"required":["name","description"],"additionalProperties":false}]}}},"required":["version"],"additionalProperties":false},"SourcingRequest":{"type":"object","required":["id","sr_id","version","external_id","merchant","destination","items","created_at","updated_at"],"properties":{"external_id":{"type":"string","minLength":1,"maxLength":200},"merchant":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":200},"name":{"type":"string","minLength":1,"maxLength":300}},"required":["id","name"],"additionalProperties":false},"destination":{"anyOf":[{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$"},"city":{"type":"string","minLength":1,"maxLength":200},"region":{"type":"string","minLength":1,"maxLength":200},"postal_code":{"type":"string","minLength":1,"maxLength":30},"address":{"type":"string","minLength":1,"maxLength":2000}},"required":["country","city"],"additionalProperties":false},{"type":"null"}]},"callback_url":{"anyOf":[{"type":"string","maxLength":4000,"format":"uri"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"needed_by":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","minLength":1,"maxLength":2000},"quantity":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":2147483647},{"type":"null"}]},"selected":{"default":false,"type":"boolean"},"customization":{"anyOf":[{"type":"object","properties":{"logo_url":{"type":"string","maxLength":4000,"format":"uri"},"packaging":{"type":"string","minLength":1,"maxLength":2000},"colour":{"type":"string","minLength":1,"maxLength":2000},"notes":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},{"type":"null"}]},"images":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","maxLength":4000,"format":"uri"}},"reference_url":{"anyOf":[{"type":"string","maxLength":4000,"format":"uri"},{"type":"null"}]},"specs":{"default":[],"maxItems":100,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":2000},"value":{"type":"string","minLength":1,"maxLength":2000},"required":{"default":false,"type":"boolean"}},"required":["name","value"],"additionalProperties":false}},"notes":{"anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"id":{"type":"integer"},"sourcing_request_id":{"type":"integer"},"revision":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["name","description"],"additionalProperties":false}},"id":{"type":"integer","minimum":1},"sr_id":{"type":"string","example":"TTS-1"},"version":{"type":"integer","minimum":1},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}