Kaiva API

Bulk import & export listings for Pro sellers

REST APIJSON + XMLPro Plan Only

Contents

Authentication Create Listings (JSON)Create Listings (XML)Update Listings Delete Listings Export Listings API Key Management

Base URL: https://kaiva.eu/api/api-import

Authentication

All endpoints require authentication. You can use either a Bearer JWT token or an API key. API keys are recommended for automated systems.

Using API Key

curl -X GET https://kaiva.eu/api/api-import/listings \
  -H "X-Api-Key: kaiva_pro_abc123def456..."

Using JWT Token

curl -X GET https://kaiva.eu/api/api-import/listings \
  -H "Authorization: Bearer eyJhbGciOiJIUz..."

Note: API access requires an active Pro subscription.

Create Listings (JSON)

POST /api-import/listings

Create up to 50 listings in one request.

Request

curl -X POST https://kaiva.eu/api/api-import/listings \
  -H "X-Api-Key: kaiva_pro_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
  "listings": [
    {
      "title": {"lv": "Samsung Galaxy S24", "en": "Samsung Galaxy S24"},
      "description": {"lv": "Jauns, neatvērts", "en": "New, unopened"},
      "price": 899.00,
      "condition": "new",
      "category_id": 17,
      "country": "LV",
      "city": "Riga",
      "quantity": 5,
      "weight": 0.3,
      "parcel_size": "small",
      "photos": ["/files/listings/phone1.jpg", "/files/listings/phone2.jpg"],
      "attributes": {"brand": "Samsung", "color": "Black"}
    }
  ]
}'

Response

{
  "created": 1,
  "errors": []
}

Required Fields

Field	Type	Description
title	object	Multilingual: {lv: "...", en: "...", ru: "...", lt: "...", et: "..."}
price	number	Price in EUR (e.g., 99.99)
category_id	integer	Category ID (see GET /api/categories)
country	string	Country code: LV, LT, or EE
photos	array	Array of photo URLs (minimum 1). Upload photos first via /api/upload

Optional Fields

Field	Type	Description
description	object	Multilingual description (same format as title)
condition	string	"new" or "used" (default: "new")
city	string	City name
quantity	integer	Stock quantity
weight	number	Weight in kg
parcel_size	string	small / medium / large / custom
attributes	object	Key-value pairs: {"brand": "Samsung", "color": "Black"}

Create Listings (XML)

POST /api-import/xml

Upload an XML file with listings (multipart/form-data, field name: file).

XML Format

<?xml version="1.0" encoding="UTF-8"?>
<listings>
  <listing>
    <title lang="lv">Samsung Galaxy S24</title>
    <title lang="en">Samsung Galaxy S24</title>
    <description lang="lv">Jauns, neatvērts</description>
    <description lang="en">New, unopened</description>
    <price>899.00</price>
    <condition>new</condition>
    <category_id>17</category_id>
    <country>LV</country>
    <city>Riga</city>
    <quantity>5</quantity>
    <weight>0.3</weight>
    <parcel_size>small</parcel_size>
    <photos>
      <photo url="/files/listings/phone1.jpg" sort_order="0"/>
      <photo url="/files/listings/phone2.jpg" sort_order="1"/>
    </photos>
    <attributes>
      <attr key="brand">Samsung</attr>
      <attr key="color">Black</attr>
    </attributes>
  </listing>
</listings>

Upload with curl

curl -X POST https://kaiva.eu/api/api-import/xml \
  -H "X-Api-Key: kaiva_pro_abc123..." \
  -F "file=@listings.xml"

Update Listings

PUT /api-import/listings

Update existing listings. Include id + fields to change.

Request

curl -X PUT https://kaiva.eu/api/api-import/listings \
  -H "X-Api-Key: kaiva_pro_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
  "listings": [
    {"id": "uuid-of-listing", "price": 799.00, "quantity": 3}
  ]
}'

Delete Listings

DELETE /api-import/listings

Request

curl -X DELETE https://kaiva.eu/api/api-import/listings \
  -H "X-Api-Key: kaiva_pro_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"ids": ["uuid-1", "uuid-2"]}'

Export Listings

GET /api-import/listings — JSON
GET /api-import/listings/xml — XML download

Export JSON

curl https://kaiva.eu/api/api-import/listings?status=active&page=1&limit=50 \
  -H "X-Api-Key: kaiva_pro_abc123..."

Export XML

curl -o listings.xml https://kaiva.eu/api/api-import/listings/xml \
  -H "X-Api-Key: kaiva_pro_abc123..."

API Key Management

Manage API keys from your Dashboard → API tab, or via these endpoints (JWT auth required):

POST /api-import/keys — Create new key

GET /api-import/keys — List keys

DELETE /api-import/keys/:id — Delete key

Security: API keys are shown only once on creation. Store them securely. Max 5 keys per account.

Rate Limits

200 requests per minute (general)
50 listings per bulk request
500 listings per XML export

Kaiva API Support

api@kaiva.eu