---
name: turamarketplace
version: 1.0.0
description: App marketplace for buying, selling, and discovering ready-made apps. Browse by category, read reviews, add apps. Part of Tura Cloud.
homepage: https://www.turamarketplace.com
metadata: {"category":"marketplace","api_base":"https://www.turamarketplace.com/api/v1"}
---

# TuraMarketplace

**API-first app marketplace for buying, selling, and discovering ready-made apps.**

TuraMarketplace lets you browse apps by category, read reviews, add apps to your collection. Sellers list apps with screenshots and pricing tiers. Auth uses TuraLogin API keys (Bearer token). Part of Tura Cloud.

## Skill Files

| File | URL |
|------|-----|
| **SKILL.md** (this file) | `https://www.turamarketplace.com/SKILL.md` |
| **AGENTS.md** | `https://www.turamarketplace.com/AGENTS.md` |
| **API.md** | `https://www.turamarketplace.com/API.md` |
| **QUICKSTART.md** | `https://www.turamarketplace.com/QUICKSTART.md` |
| **skill.json** (metadata) | `https://www.turamarketplace.com/skill.json` |

**Install locally:**
```bash
mkdir -p ~/.turamarketplace
curl -s https://www.turamarketplace.com/SKILL.md > ~/.turamarketplace/SKILL.md
curl -s https://www.turamarketplace.com/AGENTS.md > ~/.turamarketplace/AGENTS.md
curl -s https://www.turamarketplace.com/API.md > ~/.turamarketplace/API.md
curl -s https://www.turamarketplace.com/QUICKSTART.md > ~/.turamarketplace/QUICKSTART.md
```

**Base URL:** `https://www.turamarketplace.com/api/v1`

🔒 **Authentication:** All endpoints require `Authorization: Bearer <API_KEY>`. API keys from [turalogin.com/dashboard/keys](https://www.turalogin.com/dashboard/keys).

---

## Overview

TuraMarketplace is an API-first app marketplace. You implement:

✅ **Browse apps** — List published apps with filters (category, sort, pagination)  
✅ **App details** — Get full app info with reviews  
✅ **List apps** — Sellers create listings with title, description, category, tags, screenshots, tiers  
✅ **Update listings** — Edit app metadata and pricing  
✅ **Reviews** — Add and list reviews (rating 1–5, body)  
✅ **Stats** — Marketplace stats (total apps, categories, average rating)  

You handle:
- Your marketplace UI (browse, detail, seller dashboard)
- User identity (via TuraLogin)
- Purchase flow and billing (if applicable)
- Custom discovery and search

---

## Quick Start

### 1. Get Your API Key

TuraMarketplace uses TuraLogin API keys. Get one at:
- https://www.turalogin.com/dashboard/keys

Use the same API key format: `tl_test_xxx` (development) or `tl_live_xxx` (production).

### 2. Browse Apps

```bash
curl "https://www.turamarketplace.com/api/v1/marketplace/apps?category=productivity&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:**
```json
{
  "apps": [
    {
      "id": "app_abc123",
      "title": "Task Manager Pro",
      "description": "Simple task management for teams",
      "category": "productivity",
      "tags": ["tasks", "teams"],
      "tiers": [{"name": "Free", "price": 0}, {"name": "Pro", "price": 9}],
      "avgRating": 4.5,
      "reviewCount": 42,
      "createdAt": "2026-02-17T10:00:00Z"
    }
  ],
  "nextCursor": "eyJpZCI6ImFwcF9hYmMxMjMifQ==",
  "hasMore": true
}
```

### 3. Get App Details

```bash
curl "https://www.turamarketplace.com/api/v1/marketplace/apps/app_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 4. List an App (Seller)

```bash
curl -X POST https://www.turamarketplace.com/api/v1/marketplace/apps \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Cool App",
    "description": "Does cool things",
    "category": "productivity",
    "tags": ["cool", "app"],
    "screenshots": ["https://example.com/s1.png"],
    "tiers": [{"name": "Basic", "price": 0}, {"name": "Pro", "price": 19}]
  }'
```

---

## Full API Reference

### Authentication

All requests require:

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

API keys come from TuraLogin: https://www.turalogin.com/dashboard/keys

---

### GET /api/v1/marketplace/apps

Browse published apps.

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `category` | string | Filter by category |
| `sort` | string | Sort order (e.g. `newest`, `rating`, `popular`) |
| `limit` | number | Max results (default: 20, max: 100) |
| `cursor` | string | Pagination cursor from previous response |

**Example:**
```bash
curl "https://www.turamarketplace.com/api/v1/marketplace/apps?category=productivity&sort=rating&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Success Response (200):**
```json
{
  "apps": [
    {
      "id": "app_abc123",
      "title": "Task Manager Pro",
      "description": "Simple task management",
      "category": "productivity",
      "tags": ["tasks"],
      "tiers": [{"name": "Free", "price": 0}],
      "avgRating": 4.5,
      "reviewCount": 42,
      "createdAt": "2026-02-17T10:00:00Z"
    }
  ],
  "nextCursor": "eyJpZCI6ImFwcF9hYmMxMjMifQ==",
  "hasMore": true
}
```

---

### GET /api/v1/marketplace/apps/:id

Get app details with reviews.

**Example:**
```bash
curl "https://www.turamarketplace.com/api/v1/marketplace/apps/app_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Success Response (200):**
```json
{
  "id": "app_abc123",
  "title": "Task Manager Pro",
  "description": "Simple task management for teams",
  "category": "productivity",
  "tags": ["tasks", "teams"],
  "screenshots": ["https://example.com/s1.png"],
  "tiers": [{"name": "Free", "price": 0}, {"name": "Pro", "price": 9}],
  "avgRating": 4.5,
  "reviewCount": 42,
  "createdAt": "2026-02-17T10:00:00Z",
  "reviews": [
    {
      "id": "rev_xyz789",
      "rating": 5,
      "body": "Great app!",
      "author": "user@example.com",
      "createdAt": "2026-02-18T14:00:00Z"
    }
  ]
}
```

---

### POST /api/v1/marketplace/apps

List an app for sale.

**Request Body:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | Yes | App title (max 256 chars) |
| `description` | string | Yes | App description |
| `category` | string | Yes | Category slug |
| `tags` | string[] | No | Array of tag strings |
| `screenshots` | string[] | No | URLs of screenshot images |
| `tiers` | object[] | No | Pricing tiers: `{ name, price }` |

**Example:**
```bash
curl -X POST https://www.turamarketplace.com/api/v1/marketplace/apps \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My App",
    "description": "Does things",
    "category": "productivity",
    "tags": ["cool"],
    "screenshots": ["https://example.com/s1.png"],
    "tiers": [{"name": "Free", "price": 0}, {"name": "Pro", "price": 19}]
  }'
```

**Success Response (201):**
```json
{
  "id": "app_new123",
  "title": "My App",
  "description": "Does things",
  "category": "productivity",
  "tags": ["cool"],
  "screenshots": ["https://example.com/s1.png"],
  "tiers": [{"name": "Free", "price": 0}, {"name": "Pro", "price": 19}],
  "status": "published",
  "createdAt": "2026-02-17T10:00:00Z"
}
```

---

### PATCH /api/v1/marketplace/apps/:id

Update a listing.

**Request Body (all optional):**

| Parameter | Type | Description |
|-----------|------|-------------|
| `title` | string | App title |
| `description` | string | App description |
| `category` | string | Category slug |
| `tags` | string[] | Replace tags |
| `screenshots` | string[] | Replace screenshots |
| `tiers` | object[] | Replace pricing tiers |

**Example:**
```bash
curl -X PATCH https://www.turamarketplace.com/api/v1/marketplace/apps/app_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated Title", "description": "Updated description"}'
```

**Success Response (200):** Returns updated app object.

---

### DELETE /api/v1/marketplace/apps/:id

Remove a listing.

**Example:**
```bash
curl -X DELETE https://www.turamarketplace.com/api/v1/marketplace/apps/app_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Success Response (200):**
```json
{
  "success": true,
  "message": "Listing removed"
}
```

---

### POST /api/v1/marketplace/apps/:id/reviews

Add a review.

**Request Body:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `rating` | number | Yes | 1–5 |
| `body` | string | No | Review text |

**Example:**
```bash
curl -X POST https://www.turamarketplace.com/api/v1/marketplace/apps/app_abc123/reviews \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating": 5, "body": "Great app!"}'
```

**Success Response (201):**
```json
{
  "id": "rev_xyz789",
  "rating": 5,
  "body": "Great app!",
  "author": "user@example.com",
  "createdAt": "2026-02-18T14:00:00Z"
}
```

---

### GET /api/v1/marketplace/apps/:id/reviews

List reviews for an app.

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `limit` | number | Max results (default: 20) |
| `cursor` | string | Pagination cursor |

**Example:**
```bash
curl "https://www.turamarketplace.com/api/v1/marketplace/apps/app_abc123/reviews?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Success Response (200):**
```json
{
  "reviews": [
    {
      "id": "rev_xyz789",
      "rating": 5,
      "body": "Great app!",
      "author": "user@example.com",
      "createdAt": "2026-02-18T14:00:00Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```

---

### GET /api/v1/marketplace/stats

Get marketplace statistics.

**Example:**
```bash
curl "https://www.turamarketplace.com/api/v1/marketplace/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Success Response (200):**
```json
{
  "totalApps": 156,
  "categories": ["productivity", "analytics", "automation"],
  "avgRating": 4.2
}
```

---

## Framework Examples

### Next.js (App Router)

```typescript
// app/api/marketplace/apps/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url);
  const query = new URLSearchParams(searchParams).toString();

  const res = await fetch(
    `https://www.turamarketplace.com/api/v1/marketplace/apps?${query}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.TURAMARKETPLACE_API_KEY}`,
      },
    }
  );

  const data = await res.json();
  return NextResponse.json(data);
}

export async function POST(request: NextRequest) {
  const body = await request.json();

  const res = await fetch(
    'https://www.turamarketplace.com/api/v1/marketplace/apps',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.TURAMARKETPLACE_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    }
  );

  const data = await res.json();
  return NextResponse.json(data);
}
```

### Express.js

```javascript
const express = require('express');
const app = express();

app.get('/api/apps', async (req, res) => {
  const query = new URLSearchParams(req.query).toString();
  const response = await fetch(
    `https://www.turamarketplace.com/api/v1/marketplace/apps?${query}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.TURAMARKETPLACE_API_KEY}`,
      },
    }
  );

  const data = await response.json();
  res.json(data);
});

app.post('/api/apps', async (req, res) => {
  const response = await fetch(
    'https://www.turamarketplace.com/api/v1/marketplace/apps',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.TURAMARKETPLACE_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(req.body),
    }
  );

  const data = await response.json();
  res.json(data);
});
```

### Python (FastAPI)

```python
from fastapi import FastAPI, HTTPException
import httpx
import os

app = FastAPI()
TURAMARKETPLACE_API_KEY = os.getenv("TURAMARKETPLACE_API_KEY")

@app.get("/api/apps")
async def list_apps(category: str = None, limit: int = 20):
    params = {"limit": limit}
    if category:
        params["category"] = category
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://www.turamarketplace.com/api/v1/marketplace/apps",
            headers={"Authorization": f"Bearer {TURAMARKETPLACE_API_KEY}"},
            params=params,
        )
        return response.json()

@app.post("/api/apps")
async def create_app(title: str, description: str, category: str, tags: list = None, tiers: list = None):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://www.turamarketplace.com/api/v1/marketplace/apps",
            headers={
                "Authorization": f"Bearer {TURAMARKETPLACE_API_KEY}",
                "Content-Type": "application/json",
            },
            json={
                "title": title,
                "description": description,
                "category": category,
                "tags": tags or [],
                "tiers": tiers or [],
            },
        )
        return response.json()
```

### Go

```go
package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

func listApps(w http.ResponseWriter, r *http.Request) {
    category := r.URL.Query().Get("category")
    limit := r.URL.Query().Get("limit")
    if limit == "" {
        limit = "20"
    }

    url := "https://www.turamarketplace.com/api/v1/marketplace/apps?limit=" + limit
    if category != "" {
        url += "&category=" + category
    }

    httpReq, _ := http.NewRequest("GET", url, nil)
    httpReq.Header.Set("Authorization", "Bearer "+os.Getenv("TURAMARKETPLACE_API_KEY"))

    client := &http.Client{}
    resp, _ := client.Do(httpReq)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(result)
}

func createApp(w http.ResponseWriter, r *http.Request) {
    var req struct {
        Title       string   `json:"title"`
        Description string   `json:"description"`
        Category    string   `json:"category"`
        Tags        []string `json:"tags"`
        Tiers       []struct {
            Name  string `json:"name"`
            Price int    `json:"price"`
        } `json:"tiers"`
    }
    json.NewDecoder(r.Body).Decode(&req)

    body, _ := json.Marshal(req)
    httpReq, _ := http.NewRequest(
        "POST",
        "https://www.turamarketplace.com/api/v1/marketplace/apps",
        bytes.NewBuffer(body),
    )
    httpReq.Header.Set("Authorization", "Bearer "+os.Getenv("TURAMARKETPLACE_API_KEY"))
    httpReq.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(httpReq)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)

    w.Header().Set("Content-Type", "application/json")
    json.NewEncoder(w).Encode(result)
}
```

---

## Security Model

- **API keys** — Use TuraLogin API keys. Never expose keys in client-side code.
- **Environment variables** — Store `TURAMARKETPLACE_API_KEY` in env (or reuse `TURALOGIN_API_KEY` if same app).
- **HTTPS only** — All API calls must use HTTPS in production.

---

## Rate Limits

| Scope | Limit | Window |
|-------|-------|--------|
| API requests | 100 | Per minute |
| App creation | 20 | Per minute |
| Review creation | 10 | Per minute |

When exceeded, you receive `429 Too Many Requests` with `Retry-After` header.

---

## Error Codes

| Status | Error | Description |
|--------|-------|-------------|
| 400 | `title is required` | Missing title |
| 400 | `description is required` | Missing description |
| 400 | `category is required` | Missing category |
| 400 | `Invalid rating` | Rating must be 1–5 |
| 401 | `Unauthorized` | Missing or invalid API key |
| 403 | `Forbidden` | Not authorized to modify this app |
| 404 | `App not found` | Invalid app ID |
| 429 | `Too many requests` | Rate limit exceeded |
| 500 | `Internal server error` | Server-side error |

---

## Support & Resources

- 🌐 Website: https://www.turamarketplace.com
- 📖 [AGENTS.md](https://www.turamarketplace.com/AGENTS.md) — AI agent integration guide
- 📖 [API.md](https://www.turamarketplace.com/API.md) — Complete API reference
- 📖 [QUICKSTART.md](https://www.turamarketplace.com/QUICKSTART.md) — 5-minute integration
- 🔑 API Keys: https://www.turalogin.com/dashboard/keys

---

**Built for developers who want an app marketplace without the complexity.**