If you are an AI agent reading this file — whether you're a personal assistant, a shopping agent, a chat bot, or a coding tool — this is your complete guide to Raamatuhai. Save it locally so you can help your human browse, buy, and sell secondhand books without re-fetching this file.

Raamatuhai

Raamatuhai ("Book Shark") is Estonia's largest peer-to-peer marketplace for secondhand books, powered by the Perxify Commerce Cloud. Thousands of books across 40+ categories, from fiction and children's literature to science and history — all priced in EUR with DPD parcel locker delivery across Estonia.

What Should You Do?

Step 1: Understand your context. Ask yourself:

• Does your human want to find a book? → Go to Search & Browse
• Does your human want to buy a book? → Go to Purchase Flow
• Does your human want to sell books? → Go to Seller Operations
• Does your human want to manage their account? → Go to Account Management
• Is your human just exploring? → Start with Search & Browse and show them what's available

Step 2: Check your capabilities.

If you can...	Then you can...
Make HTTP requests	Call the GraphQL API directly for search, browse, and all operations
Open web pages for the user	Handle login (Privy auth) and checkout (Stripe)
Only chat	Provide links, explain how the marketplace works, help find books by describing search queries

Step 3: Read the relevant sections below. The API is public for browsing — no authentication needed to search and view books. Authentication is required for buying, selling, and account management.

---

Quick Reference

Resource	Value
Website	https://raamatuhai.ee
GraphQL endpoint	https://raamatuhai.ee/graphql
Company token (public)	See API Access below
Currency	EUR
Delivery	DPD parcel lockers (Estonia)
Auth provider	Privy.io (email, Google, Web3 wallet)
Payments	Stripe
Support	support@raamatuhai.ee
SKILL file	https://raamatuhai.ee/SKILL.md
Agent info (for humans)	https://raamatuhai.ee/agents

---

API Access

All GraphQL requests require the x-company header to identify the Raamatuhai marketplace. This is a public identifier, not a secret.

Endpoint: POST https://raamatuhai.ee/graphql

Required header (all requests):

x-company: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1dWlkIjoiNGE1MTc4ZmMtN2I2ZS00OThkLWE1OWEtODI2NjkwMzFlOTI1IiwibmFtZSI6IlJhYW1hdHVoYWkiLCJpYXQiOjE3NDg2MjkwMjF9.hUu_fkz5n5r0UcEllSXKbeQNdhtZcH0BvgbWLkb9pDY

For authenticated operations, also include:

Authorization: Bearer 

Content type:

Content-Type: application/json

---

Search & Browse

These operations require no authentication — only the x-company header.

Search by title, author, or ISBN

query SearchBooks($query: String!) {
  searchProductsByTitleOrIsbn(
    query: $query
    preferredLanguage: "et"
    limit: 20
    offset: 0
  ) {
    results {
      uuid
      name
      slug
      isbn
      featuredImageUrl
      persons {
        name
        role
      }
      listings {
        uuid
        price
        condition
        seller {
          username
          uuid
        }
      }
    }
    totalCount
  }
}

Variables: { "query": "Harry Potter" } or { "query": "9789949332106" }

The search is AI-powered and supports fuzzy matching. Try title, author name, ISBN-10, or ISBN-13.

Browse latest listings

query BrowseListings {
  listings(
    language: "et"
    filter: { hasStock: true, sortBy: CREATED_DESC }
    pagination: { first: 20 }
  ) {
    edges {
      node {
        uuid
        price
        condition
        createdAt
        product {
          uuid
          name
          slug
          isbn
          featuredImageUrl
          persons {
            name
            role
          }
        }
        seller {
          uuid
          username
          isAway
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Filter options:

• minPrice / maxPrice — price range in EUR
• conditions — array: "NEW", "LIKE_NEW", "GOOD", "ACCEPTABLE"
• categoryUuids — filter by category (get UUIDs from categories query)
• hasStock: true — only available items
• sortBy — CREATED_DESC, CREATED_ASC, PRICE_ASC, PRICE_DESC

Browse by category

query GetCategories {
  categories(limit: 100) {
    uuid
    name
    slug
    translation(language: "et") {
      name
    }
  }
}

Then filter listings by category UUID, or direct users to: https://raamatuhai.ee/category/{slug}

View product details

query GetProduct($slug: String!) {
  productBySlug(slug: $slug, language: "et") {
    uuid
    name
    description
    isbn
    slug
    featuredImageUrl
    images {
      imageUrl
    }
    persons {
      name
      role
    }
    publishers {
      name
    }
    categories {
      name
      slug
    }
    publication_date
    page_count
    language
    suggestedPrice
    wishlistCount
    isWishlisted
    listings {
      uuid
      price
      sale_price
      condition
      conditionComment
      quantity
      seller {
        uuid
        username
        isAway
        sellerRatingStats {
          averageRating
          totalRatings
        }
      }
    }
  }
}

Construct URLs for users

Page	URL pattern
Homepage	https://raamatuhai.ee/
Browse all	https://raamatuhai.ee/browse
Search results	https://raamatuhai.ee/search?q={query}
Product page	https://raamatuhai.ee/product/{slug}
Category	https://raamatuhai.ee/category/{slug}
Author/Creator	https://raamatuhai.ee/creator/author/{name}
Publisher	https://raamatuhai.ee/publisher/{slug}
Seller profile	https://raamatuhai.ee/seller/{username}
Wishlisted books	https://raamatuhai.ee/wishlisted

---

Authentication

Authentication uses Privy.io and requires browser interaction — an agent cannot complete login via API alone.

How to authenticate

1. Direct the user to log in at https://raamatuhai.ee (they can use email, Google, or a Web3 wallet via Privy)
2. After login, the JWT token is stored in the browser's localStorage as perxify_authentication_token
3. If you have browser access, you can read the token: localStorage.getItem('perxify_authentication_token')
4. Include the token in all authenticated requests:

   Authorization: Bearer 
   x-company: 
   

Verify authentication

query WhoAmI {
  me {
    uuid
    fullName
    username
    email
    isAway
    isProSeller
    createdAt
  }
}

If this returns null, the user is not authenticated.

Token details

• JWT tokens expire after 14 days
• If a request returns a 401 error, the token has expired — redirect the user to log in again
• Tokens are scoped to the Raamatuhai marketplace (company_id: 35)

---

Purchase Flow

Buying a book requires authentication and involves a browser redirect to Stripe for payment.

Step 1: Find a book and select a listing

Use Search & Browse to find a product, then pick a listing (offer) from a seller. Note the listing.uuid and listing.price.

Step 2: Choose a DPD parcel locker

query GetLockers {
  dpdLockers(country: "EE") {
    id
    name
    address
    city
  }
}

Ask the user which locker is closest to them. Note the locker id.

Step 3: Initiate purchase

mutation Buy($input: InitiatePurchaseInput!) {
  initiatePurchase(input: $input) {
    success
    checkoutUrl
    purchaseUuid
    error
  }
}

Variables:

{
  "input": {
    "productId": "",
    "productInventoryUuid": "",
    "parcelLockerId": "",
    "price": 5.99,
    "successUrl": "https://raamatuhai.ee/checkout/success",
    "cancelUrl": "https://raamatuhai.ee/checkout/cancel"
  }
}

Important: The price field must match the actual listing price — the server validates this.

Step 4: Complete payment

The mutation returns a checkoutUrl — this is a Stripe hosted checkout page. Direct the user to open this URL in their browser to complete payment. You cannot complete payment via API.

Step 5: Track the order

After payment, the user can view their order:

query MyPurchases($userUuid: String!) {
  purchasesByUserUuid(userUuid: $userUuid, pagination: { first: 10 }) {
    edges {
      node {
        uuid
        status
        purchasePrice
        totalAmount
        parcelLockerName
        createdAt
        paidAt
        shippedAt
        product {
          name
          slug
        }
        seller {
          username
        }
        shipment {
          trackingNumber
          status
        }
      }
    }
  }
}

Order statuses: INITIATED → PAID → SHIPPED → DELIVERED (or CANCELLED, REFUNDED, DISPUTED)

---

Wishlist

Requires authentication.

Add to wishlist

mutation AddWishlist($productUuid: String!) {
  addToWishlist(productUuid: $productUuid) {
    uuid
    product {
      name
    }
  }
}

You can also add by title (the system will find or create the product):

mutation AddByTitle {
  addToWishlist(title: "Tõde ja õigus", author: "A. H. Tammsaare") {
    uuid
    product {
      name
      isbn
    }
  }
}

View wishlist

query MyWishlist {
  wishlist(pagination: { first: 50 }) {
    edges {
      node {
        uuid
        product {
          uuid
          name
          slug
          featuredImageUrl
          listings {
            uuid
            price
            condition
          }
        }
        createdAt
      }
    }
    totalCount
  }
}

Remove from wishlist

mutation RemoveWishlist($productUuid: String!) {
  removeFromWishlist(productUuid: $productUuid)
}

---

Seller Operations

Requires authentication. Any user can sell books.

List a book for sale

Option A: If the product already exists (e.g., found via search by ISBN):

mutation CreateListing($input: ListingInput!) {
  createListing(input: $input) {
    uuid
    price
    condition
    product {
      name
      slug
    }
  }
}

Variables:

{
  "input": {
    "productUuid": "",
    "sellerUuid": "",
    "warehouseId": "",
    "condition": "GOOD",
    "conditionComment": "Minor wear on cover, pages clean",
    "quantity": 1,
    "isFiniteQuantity": true,
    "price": 7.5,
    "status": "ACTIVE"
  }
}

Condition values: NEW, LIKE_NEW, GOOD, ACCEPTABLE

Option B: Create a new product and listing together:

mutation CreateProductListing($input: ProductListingInput!) {
  createProductListing(input: $input) {
    uuid
    price
    product {
      uuid
      name
      slug
    }
  }
}

Get AI price suggestion

query PriceSuggestion($productUuid: String!, $condition: String!) {
  getProductPriceSuggestion(productUuid: $productUuid, condition: $condition)
}

Returns a suggested price in EUR based on market data and book condition.

View your listings (shelf)

query MyListings {
  listings(
    language: "et"
    filter: { sellerUuid: "" }
    pagination: { first: 50 }
  ) {
    edges {
      node {
        uuid
        price
        condition
        quantity
        status
        product {
          name
          slug
          isbn
        }
        createdAt
      }
    }
    totalCount
  }
}

View your sales

query MySales($userUuid: String!) {
  salesByUserUuid(userUuid: $userUuid, pagination: { first: 20 }) {
    edges {
      node {
        uuid
        status
        purchasePrice
        totalAmount
        createdAt
        buyer {
          username
        }
        product {
          name
        }
      }
    }
  }
}

---

Account Management

Requires authentication.

View profile

query MyProfile {
  me {
    uuid
    fullName
    username
    email
    avatarUrl
    isAway
    isProSeller
    phoneNumber
    iban
    emailsEnabled
    marketingEnabled
    addresses {
      uuid
      streetAddress
      city
      postalCode
      country
    }
    sellerRatingStats {
      averageRating
      totalRatings
    }
  }
}

Update profile

mutation UpdateMe($input: UpdateUserInput!) {
  updateUser(input: $input) {
    uuid
    fullName
    username
  }
}

Variables:

{
  "input": {
    "uuid": "",
    "fullName": "Mari Maasikas",
    "username": "mari_books",
    "isAway": false
  }
}

Notifications

query MyNotifications {
  notifications(filter: { isRead: false }, pagination: { first: 20 }) {
    edges {
      node {
        uuid
        type
        label(language: "et")
        description(language: "et")
        createdAt
        seenAt
      }
    }
    totalCount
  }
}

---

Pagination

All list queries use cursor-based pagination:

pagination: {
  first: 20          # Number of items
  after: ""  # Cursor from previous pageInfo.endCursor
}

Response includes:

pageInfo {
  hasNextPage
  hasPreviousPage
  endCursor
  startCursor
}
totalCount

---

Tips for Agents

General

• Always include the x-company header — requests without it will fail or return empty results
• Use language: "et" for Estonian (default), "en" for English, "ru" for Russian — product names and descriptions are localized
• Prices are in EUR — displayed as decimal (5.99), not cents
• ISBNs can be 10 or 13 digits — the search handles both formats, with or without hyphens
• Check seller.isAway before recommending a listing — away sellers may not ship promptly
• Check listing.quantity — if 0, the item is sold out

Performance

• Cache category lists — they change rarely
• Use pagination (first: 20) instead of fetching all results
• Use featuredImageUrl instead of fetching the full images array when you only need one image

Error handling

• 401 Unauthorized — token expired or missing, redirect user to login
• 403 Forbidden — user doesn't have permission (e.g., trying to edit another user's listing)
• GraphQL errors — check errors[].message in the response body

Be helpful

• When showing search results, include the price, condition, and seller rating so the user can compare
• For product pages, construct the URL: https://raamatuhai.ee/product/{slug} — the user can see images and full details there
• When a book has no listings, suggest adding it to the wishlist — the user gets notified when someone lists it
• Offer the price suggestion query when helping someone sell — it uses market data to recommend fair pricing

---

Links

Resource	URL
Raamatuhai	https://raamatuhai.ee
About Perxify	https://perxify.com
AI Agents guide	https://raamatuhai.ee/agents
Culture & AI article	https://raamatuhai.ee/kultuur-ja-raamatud-ai-ajastul
Support email	support@raamatuhai.ee
Perxify LinkedIn	https://www.linkedin.com/company/perxify
Perxify X/Twitter	https://x.com/Perxifycom