API Reference

The /api/v1 REST API contract

Overview

The Angage Marketplace exposes a versioned REST API at /api/v1. This API is consumed by the Angage ERP and authorized platform integrations. Extensions themselves do NOT typically call this API; they receive webhooks from Angage and query the ERP directly via the ERP's own extension API.

Base URL

https://marketplace.angage.com.au/api/v1

Authentication

There are three authentication modes:

  • Public endpoints: no auth required (browse, collections, manifest, public reviews).
  • Platform endpoints: require the X-Platform-Api-Key header. These are used by the ERP and authorized clients to install/uninstall and manage per-tenant state.
  • Webhook endpoints: require a valid HMAC-SHA256 signature in the X-Webhook-Signature header.

See Authentication for details.

Public Endpoints

GET /api/v1/health — Health check.
GET /api/v1/categories — List extension categories.
GET /api/v1/collections — List curated collections.
GET /api/v1/collections/{slug} — Get collection detail.
GET /api/v1/extensions — List approved extensions. Query params: category, pricing_type, search, sort, per_page (capped at 100).
GET /api/v1/extensions/{slug} — Get extension detail.
GET /api/v1/extensions/{slug}/manifest — Get the current published version's manifest.
POST /api/v1/extensions/validate-manifest — Validate a manifest JSON document against the schema. Body: {"manifest": {...}}.
GET /api/v1/extensions/{slug}/reviews — List reviews for an extension.

Platform Endpoints (Authenticated)

All endpoints below require the X-Platform-Api-Key header.

GET /api/v1/extensions/{slug}/status — Check installation status for the tenant.
POST /api/v1/extensions/{slug}/install — Install extension for the tenant. Body: tenant_id, billing_plan, configuration.
DELETE /api/v1/extensions/{slug}/uninstall — Uninstall for tenant. Body: tenant_id.
PUT /api/v1/extensions/{slug}/configuration — Update configuration for tenant.
POST /api/v1/extensions/{slug}/usage — Record a usage event.
POST /api/v1/extensions/{slug}/reviews — Submit a tenant review.
GET /api/v1/tenant/extensions — List installed extensions for the tenant. Requires X-Tenant-Id header.

Webhook Endpoints

POST /api/v1/webhooks/extensions/{slug} — Extension lifecycle webhook. Requires X-Webhook-Signature.
POST /api/v1/webhooks/billing — Billing webhook. Requires X-Webhook-Signature.

Pagination

List endpoints default to per_page=20 and are capped at 100. Responses include standard pagination metadata (current page, last page, total).

Error Responses

  • 401 Unauthorized — missing or invalid platform API key
  • 404 Not Found
  • 410 Gone — e.g. for retired /api/store/v1 endpoints
  • 422 Unprocessable Entity — validation failed
  • 500 Internal Server Error

Example Requests

Public list endpoint:

curl -X GET "https://marketplace.angage.com.au/api/v1/extensions?category=accounting&per_page=10" \
  -H "Accept: application/json"

Authenticated platform install:

curl -X POST "https://marketplace.angage.com.au/api/v1/extensions/xero-sync/install" \
  -H "Accept: application/json" \
  -H "X-Platform-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":"tenant-123","billing_plan":"free"}'