Getting Started

The Pincast Marketplace API allows you to programmatically submit apps and experiences for review and publication on pincast.fm.

Authentication

All API requests require authentication using an API key. Include your API key in the X-API-Key header.

Apps API

{
  "title": "My Awesome App",
  "description": "A great app for Pincast users",
  "link": "https://example.com/app",
  "imageUrl": "/uploads/app-icon.png"
}

{
  "apps": [
    {
      "title": "App 1",
      "description": "First app",
      "link": "https://example.com/app1",
      "imageUrl": "/uploads/app1.png"
    },
    {
      "title": "App 2",
      "description": "Second app",
      "link": "https://example.com/app2",
      "imageUrl": "/uploads/app2.png"
    }
  ]
}

Experiences API

The Experiences API works similarly to the Apps API with the same endpoints and structure.

• POST /api/external/experiences - Create experience
• GET /api/external/experiences - List experiences
• GET /api/external/experiences/:id - Get experience
• GET /api/external/experiences/:id/status - Check status
• POST /api/external/experiences/batch - Batch create

File Upload

Upload images for your apps and experiences.

Webhooks

Configure webhooks to receive real-time notifications when your submissions are approved or rejected.

Setup

Add a webhook URL and secret to your API key in the admin panel. We'll send POST requests to your URL with HMAC-SHA256 signatures.

Events

• app.published - App approved and published
• app.rejected - App rejected
• experience.published - Experience approved and published
• experience.rejected - Experience rejected

Payload Example

{
  "event": "app.published",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "id": "abc123",
    "title": "My App",
    "status": "PUBLISHED",
    "publishedAt": "2024-01-15T10:30:00.000Z"
  }
}

Signature Verification

Verify webhook signatures using the X-Webhook-Signature header:

const crypto = require('crypto');

const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
const secret = 'your_webhook_secret';

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (signature === expected) {
  // Signature valid
}

Rate Limits

API requests are rate limited to ensure fair usage and system stability.

Rate limit information is included in response headers:

Error Codes

All errors follow a standard format with error codes for easier handling.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}

Common Error Codes