Skip to main content

Portal APIs Overview

The developer portal exposes authenticated APIs for importing, managing, and publishing the content. Use these endpoints from trusted backends or admin tools; avoid exposing secrets in client-side code.

Authentication​

  • Obtain a bearer token via /api/users/login with an admin or tenant-admin account
  • For provisioning flows, use x-provisioning-secret (server-to-server only).

Sample: login for token​

TOKEN=$(curl -s -X POST https://your-portal/api/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example","password":"your-password"}' | jq -r '.token')

Behavior​

  • Draft/published and locale flags are respected where applicable.

Core endpoints​

  • APIs (Catalog)
    • POST /api/apis — import APIs via ZIP archive (requires bearer token).
    • PUT /api/apis/{slug} — update an API by slug with a new archive.
    • GET /api/apis — list APIs (supports paging).
    • GET /api/apis/{slug} — fetch API details; subroutes like /pricing, /sdks, /changelog.

API Uploads: Zip Structure and OAS Basics​

  • Download the sample ZIP, swap in your own OpenAPI/doc files, re-zip, and upload for a quick import.
  • Zip layout:
    • overview.json (required): API metadata (name, slug, version, summary, links) and pointers to spec/docs.
    • openapi.(json|yaml) (required): Valid OAS 3.x spec referenced by overview.json.
    • other filles (optional): Markdown/HTML referenced by overview.json (e.g., overview.md, changelog.md).
  • Tips:
    • Keep slugs unique per tenant; ensure paths in overview.json match the zip.
    • Trim oversized examples in the spec; include servers for accurate base URLs.

Sample: import APIs via ZIP​

curl -X POST https://your-portal/api/apis \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/zip" \
  --data-binary "@./archives/my-api.zip"

Sample: update an API by slug​

curl -X PUT https://your-portal/api/apis/my-api \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/zip" \
  --data-binary "@./archives/my-api-update.zip"

Sample: list APIs​

curl "https://your-portal/api/apis?&limit=20"

Sample: fetch API details (with subroutes)​

# Full doc
curl "https://your-portal/api/apis/my-api"

# Pricing only
curl "https://your-portal/api/apis/my-api/pricing"

# SDKs only
curl "https://your-portal/api/apis/my-api/sdks"

# Changelog
curl "https://your-portal/api/apis/my-api/changelog"

Usage tips​

  • Keep secrets server-side (provisioning secret, admin credentials).
  • For domain checks or provisioning from external systems, call via a backend proxy using the provisioning secret.
  • Prefer drafts and previews for content changes; publish when ready.

Limits and validation​

  • Rate limits apply to signup/provisioning routes.
  • OAS uploads should be valid OpenAPI 3.x; keep archives lean by trimming oversized examples.