POSTMethod POST/partner/mint/batch

You send a batch of product rows, and you receive a batch identifier. We answer as soon as we accept the batch, before any processing. You then follow the progress with GET /v1/partner/mint/batch/status/{job_id}. Read the warning below before reading that status.

Full address:

POST https://api.sealtrust.io/v1/partner/mint/batch

The same endpoint also answers without the /v1 prefix, at https://api.sealtrust.io/partner/mint/batch. The two addresses call the same code. Use the /v1 form for a new integration.

#Authorization

Send your API key in the Authorization header, in the Bearer format. The key must carry the mint:batch scope. A key that does not carry this scope receives a 403 whose message names the missing scope.

Three conditions come on top of the scope of the key.

• The plan of your brand must include API access. Otherwise you receive a 403 carrying the code FEATURE_NOT_AVAILABLE.
• The plan of your brand must allow identification by QR. That is the method the server sets on every row of this endpoint. A plan that does not allow it receives a 403 carrying the code AUTH_METHOD_NOT_ALLOWED.
• All the rows of the batch must carry the brand number of the key. A single row carrying another number makes the whole batch refused with a 403.

#Rate limit

We measure the rate over a fixed 60-second window. We first apply the value set on your account, if we have set one. Otherwise the one of your plan. In the absence of both, the fallback value is 120 calls per window.

Two counters are layered, with the same cap: one per key, one for the sum of all the keys of your brand. Creating additional keys therefore does not increase the total rate allowed.

As soon as we recognize your key, the response carries four headers. They describe the more constraining of the two counters. An authentication refusal comes before the counting and carries none of these headers.

A rate refusal returns 429. It carries these four headers, describing this time the counter that refused, and it adds Retry-After, expressed in seconds remaining in the current window. This value is never lower than 1.

Two other caps can refuse the same call: the daily quota of your key, which is consumed per item, and the monthly product quota of your plan. You will find them in the error table, further down.

#Path and query parameters

This endpoint has neither path parameter nor query parameter.

#Headers

#Request body

You send the batch in one of the two formats. The content is the same in both cases.

• JSON: send a list of objects. A lone object, a number or a string at the top level makes the request fail with a 400.
• CSV: send a file as multipart/form-data, under the form field named exactly file. Encode the file in UTF-8. You may leave the byte order mark at the head of the file, we remove it. A file encoded otherwise makes the call fail with a 500. In a spreadsheet, choose the "CSV UTF-8" export. We strip the edge spaces of the cells before validating.

You can compress the CSV file in gzip or in zlib, we decompress it. If the decompressed content exceeds about 20 MiB, you receive a 413.

A batch has at most 500 items. We refuse an empty batch with a 400.

#Fields of a row

A row accepts five fields, and only five.

In CSV, the header must contain at least the four required columns. The order of the columns is free.

The server ignores no field. Any field this table does not name makes the row fail, and therefore the batch, with a 400.

#Replaying a call without doubling its effect

You can send an Idempotency-Key header. It is optional. We remember it for 24 hours.

• Replay the same idempotency key with the same batch, and you receive the response of the first call, without a second processing starting.
• Replay the same idempotency key with a different batch, and you receive a
  409. This behavior dates from 08/20/2026. Before that, the second batch was never processed and nothing reported it.
• Replay an idempotency key whose call is still being processed, and you also receive a 409. This lock expires on its own after 60 seconds.

We compare two batches on their content once read and normalized. The order of the rows, the order of the columns, the choice between CSV and JSON and the empty cells make no difference.

#Example request

A batch of two items, in JSON.

curl -i -X POST https://api.sealtrust.io/v1/partner/mint/batch \
  -H "Authorization: Bearer st_test_0000000000000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lot-exemple-0001" \
  -d '[
    {
      "product_name": "Sac Exemple 001",
      "brand_id": 12,
      "category_id": 3,
      "metadata_uri": "ipfs://exemple-metadonnees-0001",
      "external_ref": "EX-0001"
    },
    {
      "product_name": "Sac Exemple 002",
      "brand_id": 12,
      "category_id": 3,
      "metadata_uri": "ipfs://exemple-metadonnees-0002",
      "external_ref": "EX-0002"
    }
  ]'

import { SealTrustClient } from "@sealtrust-io/sdk";

const sealtrust = new SealTrustClient({
  apiKey: "st_test_0000000000000000000000000000000000000000000000",
});

const lot = await sealtrust.products.mint(
  [
    {
      product_name: "Sac Exemple 001",
      brand_id: 12,
      category_id: 3,
      metadata_uri: "ipfs://exemple-metadonnees-0001",
      external_ref: "EX-0001",
    },
    {
      product_name: "Sac Exemple 002",
      brand_id: 12,
      category_id: 3,
      metadata_uri: "ipfs://exemple-metadonnees-0002",
      external_ref: "EX-0002",
    },
  ],
  "lot-exemple-0001",
);

console.log(lot.job_id, lot.status, lot.items_count, lot.brand_id);

import requests

lot = [
    {
        "product_name": "Sac Exemple 001",
        "brand_id": 12,
        "category_id": 3,
        "metadata_uri": "ipfs://exemple-metadonnees-0001",
        "external_ref": "EX-0001",
    },
    {
        "product_name": "Sac Exemple 002",
        "brand_id": 12,
        "category_id": 3,
        "metadata_uri": "ipfs://exemple-metadonnees-0002",
        "external_ref": "EX-0002",
    },
]

response = requests.post(
    "https://api.sealtrust.io/v1/partner/mint/batch",
    headers={
        "Authorization": "Bearer st_test_0000000000000000000000000000000000000000000000",
        "Idempotency-Key": "lot-exemple-0001",
    },
    json=lot,
    timeout=30,
)

print(response.status_code)
print(response.headers["X-RateLimit-Remaining"])
print(response.json())

The same batch in CSV, sent as multipart/form-data. The lot.csv file contains:

product_name,brand_id,category_id,metadata_uri,external_ref
Sac Exemple 001,12,3,ipfs://exemple-metadonnees-0001,EX-0001
Sac Exemple 002,12,3,ipfs://exemple-metadonnees-0002,EX-0002

The TypeScript SDK does not expose CSV submission. The TypeScript tab below therefore calls the endpoint directly.

curl -i -X POST https://api.sealtrust.io/v1/partner/mint/batch \
  -H "Authorization: Bearer st_test_0000000000000000000000000000000000000000000000" \
  -H "Idempotency-Key: lot-exemple-0001" \
  -F "file=@lot.csv;type=text/csv"

import { readFile } from "node:fs/promises";

const contenu = await readFile("lot.csv");

const formulaire = new FormData();
formulaire.append("file", new Blob([contenu], { type: "text/csv" }), "lot.csv");

const reponse = await fetch("https://api.sealtrust.io/v1/partner/mint/batch", {
  method: "POST",
  headers: {
    Authorization:
      "Bearer st_test_0000000000000000000000000000000000000000000000",
    "Idempotency-Key": "lot-exemple-0001",
  },
  body: formulaire,
});

console.log(reponse.status);
console.log(reponse.headers.get("X-RateLimit-Remaining"));
console.log(await reponse.json());

import requests

with open("lot.csv", "rb") as fichier:
    response = requests.post(
        "https://api.sealtrust.io/v1/partner/mint/batch",
        headers={
            "Authorization": "Bearer st_test_0000000000000000000000000000000000000000000000",
            "Idempotency-Key": "lot-exemple-0001",
        },
        files={"file": ("lot.csv", fichier, "text/csv")},
        timeout=30,
    )

print(response.status_code)
print(response.headers["X-RateLimit-Remaining"])
print(response.json())

#Example response

HTTP code 200.

{
  "job_id": "0000a1b2c3d4e5f6",
  "status": "queued",
  "items_count": 2,
  "brand_id": 12
}

The response has four fields and nothing else.

status: "queued" means that we have accepted the batch and that it is waiting for its processing. We have processed nothing at that moment. Follow what comes next with GET /v1/partner/mint/batch/status/{job_id}.

#Errors

The body of an error response carries a detail field. Depending on the case, this field contains a sentence or an object.

A refusal that carries a sentence, here the empty batch, HTTP code 400:

{
  "detail": "Batch vide (aucun item)"
}

A refusal that carries an object, here an incomplete CSV header, HTTP code 400:

{
  "detail": {
    "error": "Colonnes manquantes",
    "missing": ["category_id", "metadata_uri"]
  }
}

#See also

• GET /partner/mint/batch/status/{job_id}, follow the progress of a batch sent to minting.
• Create products, one at a time and in batches, create a product, create a whole run, import a file.
• Partner API, overview, base address, keys, scopes, call caps and pagination.
• API errors, recognize an error code and decide whether to correct or replay.