API reference

Send your offers to Torgið from your web shop, product catalogue or export script. Every path, request, response and error code is listed here.

The reference itself is in Icelandic.

Base URL: /api/v1

Authentication: Every request carries an API key that always starts with mist_live_ and is sent in the Authorization header. A key is created in the dashboard and shown only once.

Authorization: Bearer mist_live_<32>

The OpenAPI document (JSON)

/me

GET Sækja upplýsingar um lykilinn og fyrirtækið

GET /api/v1/me

Skilar fyrirtækinu sem lykillinn tilheyrir ásamt lýsigögnum um lykilinn sjálfan. Gagnlegt til að staðfesta uppsetningu áður en tilboð eru send. Krefst gilds lykils með annaðhvort offers:read eða offers:write.

Parameters

No parameters.

Response example

{
  "organization": {
    "id": "3f1c2a64-8f0e-4b6a-9c31-2d5f8b7a1e90",
    "name": "Norðurljós ehf.",
    "status": "active",
    "isActive": true
  },
  "apiKey": {
    "name": "Vöruskrá, framleiðsla",
    "hint": "a1b2c3d4",
    "scopes": [
      "offers:read",
      "offers:write"
    ],
    "rateLimitPerMinute": 60,
    "createdAt": "2026-10-01T09:14:00Z",
    "lastUsedAt": "2026-10-04T11:02:31Z",
    "expiresAt": null
  }
}

Responses and error codes

200
Upplýsingar um lykil og fyrirtæki.
401
Lykil vantar eða hann er ógildur, afturkallaður eða útrunninn. Villukóðar: unauthorized, api_key_invalid, api_key_revoked, api_key_expired.
X-RateLimit-Limit og X-RateLimit-Remaining fylgja ekki með á unauthorized (hausinn vantar eða er á röngu formi) né á api_key_invalid (leyndarmálið svarar ekki til neins lykils): Torgið hefur þá ekkert til að reikna kvótann af. api_key_revoked og api_key_expired bera hausana eins og venjulega, því lykillinn er raunverulega til.
403
Lykillinn er gildur en aðgerðin er ekki leyfð. Villukóðar: scope_missing, organization_inactive.
429
Hraðatakmörkun lykilsins er fullnýtt á þessari mínútu.
500
Óvænt villa hjá Torginu. Óhætt er að reyna aftur síðar.
503
Gagnagrunnurinn svaraði ekki í tæka tíð (tímamörk, of mikið álag eða tenging náðist ekki). Svarið ber Retry-After haus. Sendu alla beiðnina aftur eftir þann tíma: endursending er hættulaus því tilboð eru uppfærð eftir externalId, líka í lotu. Hraðatakmörkunarhausarnir (X-RateLimit-*) fylgja ekki með. Færri tilboð í hverri lotu stytta vinnslutímann.

/offers

GET Sækja tilboð fyrirtækisins

GET /api/v1/offers

Skilar tilboðum fyrirtækisins í síðum. Notaðu nextCursor úr svarinu sem cursor í næstu beiðni þar til hann kemur til baka sem null. Krefst heimildarinnar offers:read.

Listinn ber aðeins tilboð sem urðu til gegnum þetta viðmót (þau sem bera externalId). Tilboð sem er stofnað beint í stjórnborði Torgsins kemur ekki fram hér.

Parameters

cursor query, string
Bendill úr nextCursor í fyrra svari. Sleppt í fyrstu beiðni.
limit query, integer
Fjöldi tilboða á síðu, frá 1 til 100.

Response example

{
  "data": [
    {
      "id": "9c4b1d70-1f2a-4d55-8b0c-6a3e9f2d4c11",
      "externalId": "SKU-1042",
      "name": "Ullarkápa, dökkgrá",
      "description": "Kápa úr íslenskri ull, fóðruð.",
      "offerType": "product",
      "originalPrice": 49900,
      "discountedPrice": 34900,
      "url": "https://nordurljos.is/vorur/ullarkapa-dokkgra",
      "imageUrls": [
        "https://cdn.nordurljos.is/vorur/1042/a.jpg"
      ],
      "categoryPathKey": "clothing/women/outerwear",
      "brand": "Norðurljós",
      "storeIds": [
        "5a8e3b21-77cc-4f10-9b2d-1e6f0a4c8d33"
      ],
      "startAt": null,
      "endAt": "2026-11-30T23:59:59Z",
      "isDraft": false,
      "isDisabled": false,
      "dealType": null,
      "dealValue": null,
      "source": "api",
      "createdAt": "2026-10-01T10:00:00Z",
      "updatedAt": "2026-10-04T08:30:00Z"
    }
  ],
  "nextCursor": null
}

Responses and error codes

200
Síða af tilboðum.
401
Lykil vantar eða hann er ógildur, afturkallaður eða útrunninn. Villukóðar: unauthorized, api_key_invalid, api_key_revoked, api_key_expired.
X-RateLimit-Limit og X-RateLimit-Remaining fylgja ekki með á unauthorized (hausinn vantar eða er á röngu formi) né á api_key_invalid (leyndarmálið svarar ekki til neins lykils): Torgið hefur þá ekkert til að reikna kvótann af. api_key_revoked og api_key_expired bera hausana eins og venjulega, því lykillinn er raunverulega til.
403
Lykillinn er gildur en aðgerðin er ekki leyfð. Villukóðar: scope_missing, organization_inactive.
422
Beiðnin er á réttu formi en efnið stenst ekki reglur.
429
Hraðatakmörkun lykilsins er fullnýtt á þessari mínútu.
500
Óvænt villa hjá Torginu. Óhætt er að reyna aftur síðar.
503
Gagnagrunnurinn svaraði ekki í tæka tíð (tímamörk, of mikið álag eða tenging náðist ekki). Svarið ber Retry-After haus. Sendu alla beiðnina aftur eftir þann tíma: endursending er hættulaus því tilboð eru uppfærð eftir externalId, líka í lotu. Hraðatakmörkunarhausarnir (X-RateLimit-*) fylgja ekki með. Færri tilboð í hverri lotu stytta vinnslutímann.

/offers/batch

POST Stofna eða uppfæra mörg tilboð í einu

POST /api/v1/offers/batch

Sendir að hámarki 100 tilboð í einni beiðni. Hver færsla er meðhöndluð sjálfstætt og fær sína eigin niðurstöðu, svo ein ógild færsla fellir ekki hinar. Svarið er 200 þótt einstakar færslur mistakist. Krefst heimildarinnar offers:write.

Parameters

No parameters.

Request example

Listi tilboða, að hámarki 100.

{
  "offers": [
    {
      "externalId": "SKU-1042",
      "name": "Ullarkápa, dökkgrá",
      "originalPrice": 49900,
      "discountedPrice": 34900,
      "url": "https://nordurljos.is/vorur/ullarkapa-dokkgra",
      "categoryPathKey": "clothing/women/outerwear",
      "brand": "Norðurljós",
      "storeIds": "all"
    },
    {
      "externalId": "SKU-1043",
      "name": "Ullarhúfa",
      "originalPrice": 6900,
      "discountedPrice": 4900,
      "url": "https://nordurljos.is/vorur/ullarhufa",
      "categoryPathKey": "clothing/unisex/accessories",
      "brand": "Norðurljós",
      "storeIds": "all"
    }
  ]
}

Response example

{
  "summary": {
    "total": 2,
    "created": 1,
    "updated": 0,
    "failed": 1
  },
  "results": [
    {
      "externalId": "SKU-1042",
      "status": "created",
      "offerId": "9c4b1d70-1f2a-4d55-8b0c-6a3e9f2d4c11"
    },
    {
      "externalId": "SKU-1043",
      "status": "failed",
      "offerId": null,
      "error": {
        "type": "/api/v1/errors/validation_failed",
        "title": "Beiðnin stóðst ekki staðfestingu",
        "status": 422,
        "code": "validation_failed",
        "detail": "Afsláttarverð verður að vera lægra en upphaflegt verð.",
        "fields": [
          {
            "field": "offers.1.discountedPrice",
            "code": "must_be_lower_than_original",
            "message": "Afsláttarverð verður að vera lægra en upphaflegt verð."
          }
        ]
      }
    }
  ]
}

Responses and error codes

200
Niðurstaða fyrir hverja færslu.
401
Lykil vantar eða hann er ógildur, afturkallaður eða útrunninn. Villukóðar: unauthorized, api_key_invalid, api_key_revoked, api_key_expired.
X-RateLimit-Limit og X-RateLimit-Remaining fylgja ekki með á unauthorized (hausinn vantar eða er á röngu formi) né á api_key_invalid (leyndarmálið svarar ekki til neins lykils): Torgið hefur þá ekkert til að reikna kvótann af. api_key_revoked og api_key_expired bera hausana eins og venjulega, því lykillinn er raunverulega til.
403
Lykillinn er gildur en aðgerðin er ekki leyfð. Villukóðar: scope_missing, organization_inactive.
413
Fleiri en 100 tilboð voru send í einni lotu.
422
Beiðnin er á réttu formi en efnið stenst ekki reglur.
429
Hraðatakmörkun lykilsins er fullnýtt á þessari mínútu.
500
Óvænt villa hjá Torginu. Óhætt er að reyna aftur síðar.
503
Gagnagrunnurinn svaraði ekki í tæka tíð (tímamörk, of mikið álag eða tenging náðist ekki). Svarið ber Retry-After haus. Sendu alla beiðnina aftur eftir þann tíma: endursending er hættulaus því tilboð eru uppfærð eftir externalId, líka í lotu. Hraðatakmörkunarhausarnir (X-RateLimit-*) fylgja ekki með. Færri tilboð í hverri lotu stytta vinnslutímann.

/offers/{externalId}

PUT Stofna eða uppfæra tilboð

PUT /api/v1/offers/{externalId}

Gagnvirk (idempotent) aðgerð sem er lykluð á externalId, þitt eigið stöðuga vörunúmer. Fyrsta beiðnin stofnar tilboðið, næstu beiðnir uppfæra það. Að senda sama efni tvisvar er hættulaust. Krefst heimildarinnar offers:write.

Reiturinn brand er heiti vörumerkisins, ekki auðkenni þess. Brandi sem lítur út eins og auðkenni er hafnað með brand_is_id; sæktu heitin með GET /brands.

Parameters

externalId path, string, required
Þitt eigið stöðuga auðkenni vörunnar eða tilboðsins, til dæmis vörunúmer úr vöruskránni þinni. Torgið notar það sem lykil á tilboðið. Gildið batch er frátekið: slóðin /offers/batch er lotuvinnslan, svo tilboð með externalId sem er nákvæmlega batch verður hvorki skrifað með PUT né afvirkjað með DELETE.

Request example

Tilboðið eins og það á að líta út eftir aðgerðina.

{
  "name": "Ullarkápa, dökkgrá",
  "description": "Kápa úr íslenskri ull, fóðruð.",
  "offerType": "product",
  "originalPrice": 49900,
  "discountedPrice": 34900,
  "url": "https://nordurljos.is/vorur/ullarkapa-dokkgra",
  "imageUrls": [
    "https://cdn.nordurljos.is/vorur/1042/a.jpg"
  ],
  "categoryPathKey": "clothing/women/outerwear",
  "brand": "Norðurljós",
  "storeIds": "all",
  "endAt": "2026-11-30T23:59:59Z"
}

Responses and error codes

200
Tilboðið var uppfært.
201
Tilboðið var stofnað.
401
Lykil vantar eða hann er ógildur, afturkallaður eða útrunninn. Villukóðar: unauthorized, api_key_invalid, api_key_revoked, api_key_expired.
X-RateLimit-Limit og X-RateLimit-Remaining fylgja ekki með á unauthorized (hausinn vantar eða er á röngu formi) né á api_key_invalid (leyndarmálið svarar ekki til neins lykils): Torgið hefur þá ekkert til að reikna kvótann af. api_key_revoked og api_key_expired bera hausana eins og venjulega, því lykillinn er raunverulega til.
403
Lykillinn er gildur en aðgerðin er ekki leyfð. Villukóðar: scope_missing, organization_inactive.
413
Beiðnihlutinn er stærri en 1 MB.
422
Beiðnin er á réttu formi en efnið stenst ekki reglur.
429
Hraðatakmörkun lykilsins er fullnýtt á þessari mínútu.
500
Óvænt villa hjá Torginu. Óhætt er að reyna aftur síðar.
503
Gagnagrunnurinn svaraði ekki í tæka tíð (tímamörk, of mikið álag eða tenging náðist ekki). Svarið ber Retry-After haus. Sendu alla beiðnina aftur eftir þann tíma: endursending er hættulaus því tilboð eru uppfærð eftir externalId, líka í lotu. Hraðatakmörkunarhausarnir (X-RateLimit-*) fylgja ekki með. Færri tilboð í hverri lotu stytta vinnslutímann.

DELETE Afvirkja tilboð

DELETE /api/v1/offers/{externalId}

Afvirkjar tilboðið svo það hverfur af neytendavefnum. Tilboðinu er ekki eytt: verðsagan og tölfræðin haldast, og PUT á sama externalId vekur það aftur. Krefst heimildarinnar offers:write.

Parameters

externalId path, string, required
Þitt eigið stöðuga auðkenni vörunnar eða tilboðsins, til dæmis vörunúmer úr vöruskránni þinni. Torgið notar það sem lykil á tilboðið. Gildið batch er frátekið: slóðin /offers/batch er lotuvinnslan, svo tilboð með externalId sem er nákvæmlega batch verður hvorki skrifað með PUT né afvirkjað með DELETE.

Responses and error codes

200
Tilboðið er afvirkjað.
401
Lykil vantar eða hann er ógildur, afturkallaður eða útrunninn. Villukóðar: unauthorized, api_key_invalid, api_key_revoked, api_key_expired.
X-RateLimit-Limit og X-RateLimit-Remaining fylgja ekki með á unauthorized (hausinn vantar eða er á röngu formi) né á api_key_invalid (leyndarmálið svarar ekki til neins lykils): Torgið hefur þá ekkert til að reikna kvótann af. api_key_revoked og api_key_expired bera hausana eins og venjulega, því lykillinn er raunverulega til.
403
Lykillinn er gildur en aðgerðin er ekki leyfð. Villukóðar: scope_missing, organization_inactive.
404
Tilboð með þessu externalId finnst ekki hjá fyrirtækinu.
429
Hraðatakmörkun lykilsins er fullnýtt á þessari mínútu.
500
Óvænt villa hjá Torginu. Óhætt er að reyna aftur síðar.
503
Gagnagrunnurinn svaraði ekki í tæka tíð (tímamörk, of mikið álag eða tenging náðist ekki). Svarið ber Retry-After haus. Sendu alla beiðnina aftur eftir þann tíma: endursending er hættulaus því tilboð eru uppfærð eftir externalId, líka í lotu. Hraðatakmörkunarhausarnir (X-RateLimit-*) fylgja ekki með. Færri tilboð í hverri lotu stytta vinnslutímann.

/brands

GET Sækja vörumerki fyrirtækisins

GET /api/v1/brands

Skilar vörumerkjum sem eru skráð á fyrirtækið. Vísað er í vörumerki með nafni í tilboðum, og Torgið stofnar það innan fyrirtækisins ef það er ekki til. Krefst annaðhvort offers:read eða offers:write.

Parameters

No parameters.

Response example

{
  "data": [
    {
      "id": "71b0c4e9-3d5a-4f88-a2c6-9e17b3d05f42",
      "name": "Norðurljós",
      "slug": null
    }
  ]
}

Responses and error codes

200
Listi vörumerkja.
401
Lykil vantar eða hann er ógildur, afturkallaður eða útrunninn. Villukóðar: unauthorized, api_key_invalid, api_key_revoked, api_key_expired.
X-RateLimit-Limit og X-RateLimit-Remaining fylgja ekki með á unauthorized (hausinn vantar eða er á röngu formi) né á api_key_invalid (leyndarmálið svarar ekki til neins lykils): Torgið hefur þá ekkert til að reikna kvótann af. api_key_revoked og api_key_expired bera hausana eins og venjulega, því lykillinn er raunverulega til.
403
Lykillinn er gildur en aðgerðin er ekki leyfð. Villukóðar: scope_missing, organization_inactive.
429
Hraðatakmörkun lykilsins er fullnýtt á þessari mínútu.
500
Óvænt villa hjá Torginu. Óhætt er að reyna aftur síðar.
503
Gagnagrunnurinn svaraði ekki í tæka tíð (tímamörk, of mikið álag eða tenging náðist ekki). Svarið ber Retry-After haus. Sendu alla beiðnina aftur eftir þann tíma: endursending er hættulaus því tilboð eru uppfærð eftir externalId, líka í lotu. Hraðatakmörkunarhausarnir (X-RateLimit-*) fylgja ekki með. Færri tilboð í hverri lotu stytta vinnslutímann.

/stores

GET Sækja verslanir fyrirtækisins

GET /api/v1/stores

Skilar verslunum (staðsetningum) fyrirtækisins. Auðkennin hér eru þau sem þú setur í storeIds þegar tilboð á aðeins við hluta verslana. Krefst annaðhvort offers:read eða offers:write.

Parameters

No parameters.

Response example

{
  "data": [
    {
      "id": "5a8e3b21-77cc-4f10-9b2d-1e6f0a4c8d33",
      "name": "Norðurljós, Kringlan",
      "address": "Kringlan 4, 103 Reykjavík",
      "city": null
    }
  ]
}

Responses and error codes

200
Listi verslana.
401
Lykil vantar eða hann er ógildur, afturkallaður eða útrunninn. Villukóðar: unauthorized, api_key_invalid, api_key_revoked, api_key_expired.
X-RateLimit-Limit og X-RateLimit-Remaining fylgja ekki með á unauthorized (hausinn vantar eða er á röngu formi) né á api_key_invalid (leyndarmálið svarar ekki til neins lykils): Torgið hefur þá ekkert til að reikna kvótann af. api_key_revoked og api_key_expired bera hausana eins og venjulega, því lykillinn er raunverulega til.
403
Lykillinn er gildur en aðgerðin er ekki leyfð. Villukóðar: scope_missing, organization_inactive.
429
Hraðatakmörkun lykilsins er fullnýtt á þessari mínútu.
500
Óvænt villa hjá Torginu. Óhætt er að reyna aftur síðar.
503
Gagnagrunnurinn svaraði ekki í tæka tíð (tímamörk, of mikið álag eða tenging náðist ekki). Svarið ber Retry-After haus. Sendu alla beiðnina aftur eftir þann tíma: endursending er hættulaus því tilboð eru uppfærð eftir externalId, líka í lotu. Hraðatakmörkunarhausarnir (X-RateLimit-*) fylgja ekki með. Færri tilboð í hverri lotu stytta vinnslutímann.

/categories

GET Sækja flokkatréð

GET /api/v1/categories

Skilar flokkatré Torgsins. Tilboð verða að vísa í laufflokk (isLeaf: true) með categoryPathKey. Vöruflokkar og veitingaflokkar eru aðgreindir með offerType. Krefst annaðhvort offers:read eða offers:write.

Parameters

No parameters.

Response example

{
  "data": [
    {
      "pathKey": "clothing/women",
      "name": "Dömufatnaður",
      "offerType": "product",
      "isLeaf": false,
      "parentPathKey": "clothing"
    },
    {
      "pathKey": "clothing/women/outerwear",
      "name": "Yfirhafnir",
      "offerType": "product",
      "isLeaf": true,
      "parentPathKey": "clothing/women"
    }
  ]
}

Responses and error codes

200
Listi flokka.
401
Lykil vantar eða hann er ógildur, afturkallaður eða útrunninn. Villukóðar: unauthorized, api_key_invalid, api_key_revoked, api_key_expired.
X-RateLimit-Limit og X-RateLimit-Remaining fylgja ekki með á unauthorized (hausinn vantar eða er á röngu formi) né á api_key_invalid (leyndarmálið svarar ekki til neins lykils): Torgið hefur þá ekkert til að reikna kvótann af. api_key_revoked og api_key_expired bera hausana eins og venjulega, því lykillinn er raunverulega til.
403
Lykillinn er gildur en aðgerðin er ekki leyfð. Villukóðar: scope_missing, organization_inactive.
429
Hraðatakmörkun lykilsins er fullnýtt á þessari mínútu.
500
Óvænt villa hjá Torginu. Óhætt er að reyna aftur síðar.
503
Gagnagrunnurinn svaraði ekki í tæka tíð (tímamörk, of mikið álag eða tenging náðist ekki). Svarið ber Retry-After haus. Sendu alla beiðnina aftur eftir þann tíma: endursending er hættulaus því tilboð eru uppfærð eftir externalId, líka í lotu. Hraðatakmörkunarhausarnir (X-RateLimit-*) fylgja ekki með. Færri tilboð í hverri lotu stytta vinnslutímann.

/openapi.json

GET Sækja OpenAPI lýsinguna

GET /api/v1/openapi.json · No key needed.

Skilar þessari lýsingu á JSON formi. Endapunkturinn er opinn og krefst ekki API-lykils, svo hægt sé að smíða biðlara áður en lykill er gefinn út.

Parameters

No parameters.

Responses and error codes

200
OpenAPI 3.1 skjalið.
500
Óvænt villa hjá Torginu. Óhætt er að reyna aftur síðar.