Marketplace

Base URL: /v1

---

Marketplace

Browse Marketplace

GET /v1/marketplace

Returns a cursor-paginated list of published products with seller info.

Authentication: None (public)

Query Parameters

Parameter	Type	Required	Default	Description
category	string	No	—	Filter products by category ID.
cursor	string	No	—	Cursor token for pagination. Obtained from next_cursor.
limit	number	No	20	Number of results per page. Min 1, max 50.
sort	string	No	newest	Sort order. One of: newest, price_asc, price_desc.

Note

Only products with status: "published" are returned.

Response 200 OK

{
  "products": [
    {
      "id": "prod_abc123",
      "name": "UI Component Kit",
      "description": "A premium set of reusable UI components.",
      "price": 49.99,
      "category_id": "cat_design",
      "status": "published",
      "created_at": "2026-03-15T10:30:00Z",
      "user_id": "usr_seller01",
      "seller": {
        "id": "usr_seller01",
        "username": "designpro",
        "first_name": "Alex",
        "last_name": "Rivera",
        "avatar_url": "https://cdn.example.com/avatars/designpro.jpg"
      }
    }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMy0xNVQxMDozMDowMFoifQ=="
}

Field	Type	Description
products	array	Array of product objects.
products[].id	string	Unique product identifier.
products[].name	string	Product name.
products[].description	string	Product description.
products[].price	number	Product price.
products[].category_id	string	Category the product belongs to.
products[].status	string	Always "published" in this endpoint.
products[].created_at	string	ISO 8601 creation timestamp.
products[].user_id	string	ID of the seller.
products[].seller	object	Embedded seller profile.
next_cursor	string | null	Cursor for the next page. null if no more results.

---

Get Product

GET /v1/marketplace/{id}

Returns a single product with full details, seller profile, and reviews.

Authentication: None (public)

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The product ID.

Response 200 OK

{
  "product": {
    "id": "prod_abc123",
    "name": "UI Component Kit",
    "description": "A premium set of reusable UI components.",
    "price": 49.99,
    "category_id": "cat_design",
    "status": "published",
    "created_at": "2026-03-15T10:30:00Z",
    "user_id": "usr_seller01",
    "seller": {
      "id": "usr_seller01",
      "username": "designpro",
      "first_name": "Alex",
      "last_name": "Rivera",
      "avatar_url": "https://cdn.example.com/avatars/designpro.jpg"
    },
    "reviews": [
      {
        "id": "rev_001",
        "user_id": "usr_buyer42",
        "rating": 5,
        "comment": "Excellent quality components!",
        "created_at": "2026-03-20T14:00:00Z"
      }
    ]
  }
}

Error Responses

Status	Description
404	Product not found.

---

Get User Store

GET /v1/store/{userId}

Returns a user’s store profile and their listed products. If the user has no store, store is null.

Authentication: None (public)

Path Parameters

Parameter	Type	Required	Description
userId	string	Yes	The user ID.

Response 200 OK

{
  "store": {
    "id": "store_001",
    "user_id": "usr_seller01",
    "name": "DesignPro Shop",
    "description": "Premium design assets and tools.",
    "logo_url": "https://cdn.example.com/stores/designpro-logo.png",
    "created_at": "2026-01-10T08:00:00Z",
    "updated_at": "2026-03-01T12:00:00Z"
  },
  "products": [
    {
      "id": "prod_abc123",
      "name": "UI Component Kit",
      "description": "A premium set of reusable UI components.",
      "price": 49.99,
      "category_id": "cat_design",
      "status": "published",
      "created_at": "2026-03-15T10:30:00Z",
      "user_id": "usr_seller01"
    }
  ]
}

Field	Type	Description
store	object | null	The user’s store, or null if none exists.
products	array	Array of products belonging to the store.

---

Create / Update Store

POST /v1/store

Creates or updates the authenticated user’s store. Upserts on user_id — if a store already exists, it is updated.

Authentication: Required

Request Body

Field	Type	Required	Description
name	string	No	Store display name.
description	string	No	Store description.
logo_url	string	No	URL to the store logo image.

Request Example

{
  "name": "DesignPro Shop",
  "description": "Premium design assets and tools.",
  "logo_url": "https://cdn.example.com/stores/designpro-logo.png"
}

Response 200 OK

{
  "store": {
    "id": "store_001",
    "user_id": "usr_seller01",
    "name": "DesignPro Shop",
    "description": "Premium design assets and tools.",
    "logo_url": "https://cdn.example.com/stores/designpro-logo.png",
    "created_at": "2026-01-10T08:00:00Z",
    "updated_at": "2026-03-30T09:15:00Z"
  }
}

Error Responses

Status	Description
401	Unauthorized. Token missing or invalid.

---

Explore & Search

Explore

GET /v1/explore

Returns trending posts, popular verified users, and available categories for discovery.

Authentication: None (public)

Query Parameters

Parameter	Type	Required	Default	Description
limit	number	No	20	Max items per section. Max 50.

Response 200 OK

{
  "trending_posts": [
    {
      "id": "post_tr01",
      "title": "Getting Started with Edge Computing",
      "content": "A deep dive into...",
      "created_at": "2026-03-29T18:00:00Z",
      "author": {
        "id": "usr_author01",
        "username": "techwriter",
        "first_name": "Jordan",
        "last_name": "Lee",
        "avatar_url": "https://cdn.example.com/avatars/techwriter.jpg"
      }
    }
  ],
  "popular_users": [
    {
      "id": "usr_pop01",
      "username": "fullstackdev",
      "first_name": "Sam",
      "last_name": "Chen",
      "avatar_url": "https://cdn.example.com/avatars/fullstackdev.jpg",
      "verified": true
    }
  ],
  "categories": [
    {
      "id": "cat_design",
      "name": "Design"
    },
    {
      "id": "cat_dev",
      "name": "Development"
    }
  ]
}

Field	Type	Description
trending_posts	array	Posts currently trending, with embedded author.
popular_users	array	Popular verified users.
categories	array	All available categories.

---

Follow Suggestions

GET /v1/suggestions

Returns suggested users to follow. Excludes users the caller already follows and the caller themselves.

Authentication: Required

Query Parameters

Parameter	Type	Required	Default	Description
limit	number	No	10	Number of suggestions. Max 30.

Response 200 OK

{
  "suggestions": [
    {
      "id": "usr_sug01",
      "username": "creativecoder",
      "first_name": "Taylor",
      "last_name": "Brooks",
      "avatar_url": "https://cdn.example.com/avatars/creativecoder.jpg",
      "caption": "Full-stack developer and open source contributor",
      "verified": true
    }
  ]
}

Field	Type	Description
suggestions	array	Array of suggested user profiles.
suggestions[].id	string	User ID.
suggestions[].username	string	Username.
suggestions[].first_name	string	First name.
suggestions[].last_name	string	Last name.
suggestions[].avatar_url	string	Avatar image URL.
suggestions[].caption	string	User bio or caption.
suggestions[].verified	boolean	Whether the user is verified.

Error Responses

Status	Description
401	Unauthorized. Token missing or invalid.

---

Link Preview

GET /v1/link-preview

Fetches Open Graph metadata for a URL. Results are cached in link_snapshots. The server enforces a 5-second timeout when fetching the target URL.

Authentication: Required

Query Parameters

Parameter	Type	Required	Default	Description
url	string	Yes	—	The URL to generate a preview for.

Response 200 OK

{
  "preview": {
    "url": "https://example.com/article/edge-computing",
    "title": "Getting Started with Edge Computing",
    "description": "Learn the fundamentals of deploying applications at the edge.",
    "image": "https://example.com/og-image.png"
  }
}

Field	Type	Description
preview.url	string	The canonical URL.
preview.title	string	Page title from OG tags.
preview.description	string	Page description from OG tags.
preview.image	string	OG image URL.

Error Responses

Status	Description
400	Missing required url query parameter.
401	Unauthorized. Token missing or invalid.

---

Search

GET /v1/search

Full-text search across users, posts, and products. Uses case-insensitive ILIKE matching.

Authentication: None (public)

Query Parameters

Parameter	Type	Required	Default	Description
q	string	Yes	—	Search query string.
type	string	No	all	Filter results by type. One of: users, posts, products, all.
limit	number	No	20	Max results per type. Max 50.

Search Fields by Type

Type	Fields Searched
users	username, first_name, last_name
posts	title, content
products	name

Note

Only posts with status: "published" are included in search results.

Response 200 OK

{
  "users": [
    {
      "id": "usr_match01",
      "username": "designpro",
      "first_name": "Alex",
      "last_name": "Rivera",
      "avatar_url": "https://cdn.example.com/avatars/designpro.jpg"
    }
  ],
  "posts": [
    {
      "id": "post_match01",
      "title": "Design Systems at Scale",
      "content": "How we built a design system...",
      "status": "published",
      "created_at": "2026-03-10T09:00:00Z"
    }
  ],
  "products": [
    {
      "id": "prod_match01",
      "name": "Design Token Library",
      "price": 29.99,
      "category_id": "cat_design",
      "status": "published"
    }
  ]
}

Field	Type	Description
users	array	Matching user profiles. Empty array if type excludes users.
posts	array	Matching published posts. Empty array if type excludes posts.
products	array	Matching products. Empty array if type excludes products.

Error Responses

Status	Description
400	Missing required q query parameter.