Creates a specification in one call: identity, folder placement, its composition chapters (general/labelling — no identity outside the spec) inline, and REFERENCES to its library chapters. Atomic — everything this call creates exists after it, or nothing does (any failure returns 422 and no resource is created).
Library-chapter slots (productionChapter, testingChapter, finishedProductChapter) take a { "chapterId": ... } reference to a chapter created beforehand at its own address (POST /v2/public/library/food/{type}-chapters — born published). The referenced chapter must be a published, active version owned by your company — anything else is a 422.
requirements are likewise REFERENCES to pre-created objects (ids only).
Questionnaires are automatic, not part of this payload: at creation the server instantiates one questionnaire per published questionnaire template matching the specification (template type + the trade item's brand and categories) and attaches it to its chapter. Referencing pre-created questionnaire instances is not accepted: the member is refused (400), never dropped.
Late additions: general/labelling chapters omitted here arrive via their spec-scoped PUT (upsert). Library chapters are attached or swapped later via the .../link endpoints. The created specification is private until it is shared: POST .../share, or the share of the folder it is placed in, hands it over.
Scope: product specifications only. The specification type is server-fixed (ProductSpecification) — assortment specifications (which carry N production chapters) are out of scope. Packaging specifications have their own create (POST /v2/public/packaging/specifications).
The user of your company who owns the specification and becomes its retailer contact. Optional when your credentials identify a user: that user is taken, and a person may only name themselves (naming anyone else is a 403). Required when your credentials carry no user. The company always binds from your credentials, never from the payload.
Your company's published specification template — communicated at onboarding by Professional Services. It must be owned by your company, published and in its active version.
Write shape of the general chapter — deliberately small, because almost everything this chapter shows is derived: the whole product / trade-item block is filled from the trade item the specification points at, and the company company ids, their signatory contacts and versionInfo derive from the specification identity. Product identity is therefore READ-ONLY here (see FoodProduct): it changes by changing the specification's tradeItemId, never through a chapter payload. Production sites are a PRODUCTION chapter section. Requirements and questionnaires attach at the specification level (create references), never inside chapter payloads. What remains writable: each party's subsidiary and additional contacts, and the custom fields (either party).
Write shape of the labelling chapter, inline on the food specification create (labellingChapter) and on FoodSpecifications_PutLabellingChapter. Requirements and documents are not part of it.
DERIVED CONTENT is read-only here. The labelling chapter is built from the production chapters and the questionnaires: the generated ingredient list text, the nutrient values and the servings, the nutri-score result, the GMO rows and the automatic claims are computed by the platform and written where they come from (the production chapter, the questionnaire answers). This shape carries the labelling inputs only.
OWNERSHIP RULE — replace scope = ownership scope: a PUT is a full replace OF WHAT THE CALLER'S COMPANY OWNS. Counterpart-owned fields are untouchable both ways: carrying a VALUE = 422 (never silently dropped); null or absent = ignored, never cleared. The only mixed-ownership labelling section is gmoRiskAnalysis.
REPLACE RULE on the PUT, by kind of section:
- sections the labelling chapter owns outright (productInformation, consumerInstructions, sortingInstructions, additionalMarketingInformation, businessNameAndAddress): null and absent mean the same thing, the section goes back to the template defaults, as a create leaves it (full replace; no merge-patch semantics);
- customFields: its own rule (CustomFields: an entry replaces its component's values; a component not carried keeps what it holds);
- sections keyed by production chapter or recipe row (ingredientDeclaration, nutritionalInformation, nutriScore, gmoRiskAnalysis): entries are addressed, never created or removed. A section or an entry the payload does not carry keeps what it holds; within a carried entry, the section's own rule applies;
- claims: its own rule (null keeps the manual claims, [] clears them).
On the create, a section that is null or absent keeps the template defaults.
Reference to an existing library chapter. The specification links the chapter's current ACTIVE version and shares that same document with every other linked specification: in-place content updates (the library PUT) are seen by all of them immediately. A NEW chapter version does not propagate — a spec adopts it by explicit re-link (the .../link endpoints). The referenced chapter must be a PUBLISHED, ACTIVE version owned by your company (422 otherwise). chapterId must be the ONLY property in the slot: "link this chapter AND change it" is two actions — this call does one.
Reference to an existing library chapter. The specification links the chapter's current ACTIVE version and shares that same document with every other linked specification: in-place content updates (the library PUT) are seen by all of them immediately. A NEW chapter version does not propagate — a spec adopts it by explicit re-link (the .../link endpoints). The referenced chapter must be a PUBLISHED, ACTIVE version owned by your company (422 otherwise). chapterId must be the ONLY property in the slot: "link this chapter AND change it" is two actions — this call does one.
Reference to an existing library chapter. The specification links the chapter's current ACTIVE version and shares that same document with every other linked specification: in-place content updates (the library PUT) are seen by all of them immediately. A NEW chapter version does not propagate — a spec adopts it by explicit re-link (the .../link endpoints). The referenced chapter must be a PUBLISHED, ACTIVE version owned by your company (422 otherwise). chapterId must be the ONLY property in the slot: "link this chapter AND change it" is two actions — this call does one.
References to PRE-CREATED requirements (PS-owned library objects), attached per chapter at creation — same containment rule as chapter references. Changed afterwards with FoodSpecifications_PutChapterRequirements. Duplicates: repeating an id within a chapter type is tolerated (attached once); the same id under two DIFFERENT chapter types rejects the whole create (422).
Files uploaded beforehand through the document API, attached per chapter at creation, by the same rules as FoodSpecifications_PutChapterDocuments. Changed afterwards with that endpoint. Repeating an id within a chapter type is tolerated (attached once); the same id under two DIFFERENT chapter types rejects the whole create (422).
- Productionhttps://apis.traceone.com/spec/v2/food/specifications
curl -i -X POST \
https://apis.traceone.com/spec/v2/food/specifications \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"ownerUserId": "283eeac5-beea-465a-80a5-763009480d0f",
"tradeItemId": "ca25da54-cf50-4957-b1f6-2a6f444fe8a3",
"supplierId": "e01eb4c4-8eb9-4fb7-b625-61f58c6148db",
"templateId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
"languageCode": "en-US",
"reasonForThisVersion": "string",
"folderId": "5b6379a4-2a6c-4085-b184-45838a3b8e7e",
"generalChapter": {
"retailer": {
"subsidiaryCompanyId": "b1d3008c-dc97-4956-9b01-8e03b17f3f96",
"additionalContacts": [
{
"userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
}
]
},
"supplier": {
"subsidiaryCompanyId": "b1d3008c-dc97-4956-9b01-8e03b17f3f96",
"additionalContacts": [
{
"userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b"
}
]
},
"customFields": [
{
"componentId": "616ccd92-d666-4180-8349-8d125b269fac",
"sectionCode": "string",
"values": {}
}
]
},
"labellingChapter": {
"ingredientDeclaration": {
"entries": [
{
"productionChapterId": "cfcca4aa-1aec-4368-ab36-481357651a83",
"overrideText": "string",
"displayOnPack": true,
"declareAllergens": true,
"characteristicIngredients": [
{
"materialId": "30cdab3c-3e2b-44f4-8415-c6dd88ed4261",
"ingredientId": "a7a9b407-8421-41ba-937c-6c43b14e4701"
}
],
"rows": [
{
"rowId": "c4e73cac-8b0c-4e55-94d1-531330067e81",
"declarationType": "DoNotDeclare",
"declareAs": "string",
"quid": 0
}
],
"groups": [
{
"groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
"name": "string",
"declarationType": "DoNotDeclare",
"memberRowIds": [
null
]
}
]
}
]
},
"nutritionalInformation": {
"entries": [
{
"productionChapterId": "cfcca4aa-1aec-4368-ab36-481357651a83",
"servings": [
{
"servingId": "bc112818-bc5f-43a6-93e6-8e617a7c8f81",
"name": "string",
"value": 0,
"massUnitId": "63feeca3-19ff-4722-8955-6713ff5719ce",
"volumeUnitId": "9c8961f2-1e43-4bc8-95fa-bac5491cc67e",
"servingTypeCode": "string",
"automaticCalculation": true
}
],
"nutrients": [
{
"nutrientId": "ce8c0866-b8a2-4223-9b70-6737aeeac3f5",
"displayToConsumer": true,
"perServing": [
{}
]
}
],
"nutritionalAnalysisFileIds": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
]
},
"claims": [
{
"claimId": "88057929-7728-4a26-8396-f965dcc8b947",
"claimType": "Marketing"
}
],
"productInformation": {
"productName": {
"displayOnPack": true
},
"commercialName": {
"value": "string",
"subtitle": "string",
"displayOnPack": true
},
"legalName": {
"value": "string",
"subtitle": "string",
"displayOnPack": true
},
"productDescription": {
"value": "string",
"displayOnPack": true
},
"productGtin": {
"displayOnPack": true
},
"netContents": [
{
"unitId": "b3eb5f92-604a-46b9-9881-9d84000fd7ed",
"eMark": true,
"displayOnPack": true
}
],
"additionalNetContents": [
{
"unitId": "b3eb5f92-604a-46b9-9881-9d84000fd7ed",
"value": 0,
"eMark": true,
"displayOnPack": true
}
],
"variableWeight": {
"eMark": true,
"displayOnPack": true
},
"drainedNetWeight": {
"eMark": true,
"displayOnPack": true
},
"eMark": {
"displayOnPack": true
},
"alcoholVolume": {
"percentage": 0,
"displayOnPack": true
},
"finalPageProofFileIds": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
},
"nutriScore": {
"entries": [
{
"productionChapterId": "cfcca4aa-1aec-4368-ab36-481357651a83",
"displayOnPack": true,
"productType": "string",
"percentageOfFruitsVegetablesAndLegumes": 0
}
]
},
"consumerInstructions": {
"storageInstructions": {
"displayOnPack": true,
"instructions": [
{
"labellingInformationId": "6bbaaf1e-1d1c-4328-8277-50a1141d8fbe",
"placeholders": [
{}
]
}
],
"overrideText": "string"
},
"preparationInstructions": {
"displayOnPack": true,
"instructions": [
{
"labellingInformationId": "6bbaaf1e-1d1c-4328-8277-50a1141d8fbe",
"placeholders": [
{}
]
}
],
"overrideText": "string"
},
"codesAndDates": {
"displayOnPack": true,
"consumerShelfLife": {
"dateExpression": "string",
"batchLotNumber": "string"
},
"productionIndicationIds": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
},
"productOrigins": {
"displayOnPack": true,
"origins": [
{
"originTypeId": "6111779f-6cec-486d-85bf-2e8ed2686050",
"landBased": {
"countryId": "bd2b151e-bbbf-43a3-8058-286e653dfac0",
"regionId": "a29f01e1-8a8d-451e-b685-f8b0b4ec4767",
"zoneId": "c3920607-5069-4ac3-ba10-00754e7a8e8b"
},
"waterBased": {
"fishingZoneIds": [
null
],
"fishingGearIds": [
null
]
}
}
],
"overrideText": "string"
}
},
"sortingInstructions": {
"displaySortingInstructions": true,
"streams": [
{
"targetStreamId": "f9b5c8f0-959c-4c0c-95f6-ea88ef2d81fc",
"countries": [
{
"countryId": "bd2b151e-bbbf-43a3-8058-286e653dfac0",
"components": "string"
}
]
}
],
"otherLogos": {
"trimanLogo": true,
"greenDotLogo": true
}
},
"gmoRiskAnalysis": {
"rawMaterialRisks": [
{
"materialId": "30cdab3c-3e2b-44f4-8415-c6dd88ed4261",
"ingredientId": "a7a9b407-8421-41ba-937c-6c43b14e4701",
"riskLevelCode": "string",
"fileIds": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
]
},
"additionalMarketingInformation": {
"information": "string",
"displayOnPack": true
},
"businessNameAndAddress": {
"consumerServiceInformation": {
"displayOnPack": true,
"labellingInformationId": "6bbaaf1e-1d1c-4328-8277-50a1141d8fbe",
"placeholders": [
{
"variableName": "string",
"value": "string"
}
],
"value": "string"
},
"additionalInformation": {
"value": "string",
"displayOnPack": true
},
"healthMarks": {
"displayOnPack": true
},
"packerCodes": {
"displayOnPack": true
}
},
"customFields": [
{
"componentId": "616ccd92-d666-4180-8349-8d125b269fac",
"sectionCode": "string",
"values": {}
}
]
},
"productionChapter": {
"chapterId": "2a48aff7-27e7-4ab6-9471-1ee9c5632811"
},
"testingChapter": {
"chapterId": "2a48aff7-27e7-4ab6-9471-1ee9c5632811"
},
"finishedProductChapter": {
"chapterId": "2a48aff7-27e7-4ab6-9471-1ee9c5632811"
},
"requirements": [
{
"chapterType": "string",
"requirementIds": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"documents": [
{
"chapterType": "string",
"fileIds": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"questionnaires": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}'{ "specificationId": "df380d59-2906-4417-bec3-4ac4567b1960" }