OpenAPI, SDKs, CLI & MCP

TokPortal exposes public developer tools from the same API schema used for the OpenAPI spec, generated API reference, LLM assets, CLI, SDK, MCP server, and webhook helpers.

Distribution Matrix

Surface	Distribution	Install / usage	Status
OpenAPI	Public docs	`/openapi.json` or `/openapi.yaml`	Public source of truth
Node / TypeScript SDK	npm	`npm install @tokportal/node`	Public package
CLI	npm	`npm install -g @tokportal/cli`	Public package
MCP server	npm	`npx tokportal-mcp`	Public package

Python, Go, Ruby, Java, PHP, .NET, and Rust SDKs are deferred until their registry or repository release path is ready. For those languages today, use the raw HTTP API with /openapi.json or /openapi.yaml.

Node / TypeScript SDK

Install:

npm install @tokportal/node

Create a client:



const tokportal = new TokPortal({
  apiKey: process.env.TOKPORTAL_API_KEY!,
});

Create a bundle, configure webhooks, export analytics, and use media upload helpers:

const bundle = await tokportal.bundles.create({
  bundle_type: "account_and_videos",
  country: "USA",
  videos_quantity: 5,
});

const webhook = await tokportal.webhooks.create({
  url: "https://example.com/tokportal/webhook",
  events: ["bundle.created", "bundle.published"],
});

const csv = await tokportal.analytics.exportVideos({
  account: ["9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c"],
});

const image = await tokportal.uploads.imageFromUrl({
  url: "https://cdn.example.com/photo.jpg",
  bundle_id: bundle.data.id,
  purpose: "carousel",
});

await tokportal.bundles.fixVideoDownload(bundle.data.id, 1, {
  video_url: "https://cdn.example.com/replacement.mp4",
});

console.log(bundle.data.id, webhook.data.id, csv, image.data.id);

Direct multipart uploads can use either a Blob or a local file path:

const uploaded = await tokportal.uploads.videoDirectFile(
  "./video.mp4",
  bundle.data.id,
  "video/mp4",
  { idempotencyKey: "video-upload-123" },
);

console.log(uploaded.data.url);

Every OpenAPI operation is also reachable through the generated operation map:

const retry = await tokportal.requestOperation("retryWebhookDelivery", {
  path: {
    id: webhook.data.id,
    delivery_id: "7a1f3e5d-2222-4333-9444-abc123abc123",
  },
});

Webhook Signatures

Use the SDK helper with the exact raw request body received by your HTTP framework, before JSON parsing or re-serialization:



const valid = verifyWebhookSignature(
  rawBody,
  request.headers["tokportal-signature"],
  process.env.TOKPORTAL_WEBHOOK_SECRET!,
);

See Webhooks for the full event catalog, endpoint management API, manual HMAC verification examples, delivery logs, and retry behavior.

CLI

Install:

npm install -g @tokportal/cli

Use:

export TOKPORTAL_API_KEY=sk_your_key_here

tokportal get-current-user
tokportal list-bundles --page 1 --per_page 25
tokportal create-bundle --body '{"bundle_type":"account_and_videos","country":"USA","videos_quantity":5}'
tokportal upload-video-direct --file ./video.mp4 --bundle_id 00000000-0000-0000-0000-000000000000

Multipart upload commands are generated from OpenAPI too. Use --file <path> for the binary field and pass form fields such as --bundle_id or --auto_publish as regular flags.

Failed CLI commands print the original API payload plus diagnostics:

{
  "payload": {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded."
    }
  },
  "diagnostics": {
    "request_id": "req_...",
    "retry_after_seconds": 1,
    "rate_limit": {
      "limit": 120,
      "remaining": 0,
      "reset": 1779724800
    }
  }
}

Structured Errors

The Node SDK exposes structured API errors with the HTTP status, TokPortal error code, details, X-TokPortal-Request-ID, Retry-After, rate limit metadata, and a retryability helper.



try {
  await tokportal.bundles.create({
    bundle_type: "account_and_videos",
    country: "USA",
    videos_quantity: 5,
  });
} catch (error) {
  if (error instanceof TokPortalApiError) {
    console.log(error.status, error.code, error.details, error.requestId);
    if (error.retryable) {
      const waitMs = (error.retryAfterSeconds ?? 1) * 1000;
      // Retry with backoff.
    }
    console.log(error.rateLimit?.remaining, error.rateLimit?.reset);
  }
}

Idempotency Keys

Use idempotency keys for mutating requests you may retry after network failures. TokPortal stores the first response for 24 hours and returns the same response for a replay with the same key and request fingerprint.

await tokportal.bundles.create(
  {
    bundle_type: "account_and_videos",
    country: "USA",
    videos_quantity: 5,
  },
  { idempotencyKey: "bundle-create-123" },
);

Client Identification

The public Node SDK, CLI, and MCP server send X-TokPortal-Client on API requests. This does not affect API behavior; it helps TokPortal support and observability identify the integration surface and version.

Surface	Header
Node / TypeScript SDK	`X-TokPortal-Client: tokportal-node/0.1.0`
CLI	`X-TokPortal-Client: tokportal-cli/0.1.1`
MCP server	`X-TokPortal-Client: tokportal-mcp/1.8.0`

MCP

npx tokportal-mcp

Failed MCP tool calls return an error result containing the original API payload plus diagnostics.request_id, diagnostics.retry_after_seconds, and diagnostics.rate_limit when available.

{
  "mcpServers": {
    "tokportal": {
      "command": "tokportal-mcp",
      "env": {
        "TOKPORTAL_API_KEY": "sk_your_key_here"
      }
    }
  }
}

Schema Source

OpenAPI JSON: developers.tokportal.com/openapi.json
OpenAPI YAML: developers.tokportal.com/openapi.yaml
LLM summary: developers.tokportal.com/llms.txt
Full LLM context: developers.tokportal.com/llms-full.txt
Developer ecosystem: developers.tokportal.com/developer-ecosystem.json
Package release manifest: developers.tokportal.com/package-release-manifest.json

Generated Surface Verification

TokPortal keeps the public Node SDK, CLI, MCP tools, OpenAPI, and LLM assets aligned with one verification command:

npm run verify:developer-surface

The command rebuilds the public npm packages, regenerates CLI/MCP definitions, checks the public OpenAPI operation count, and rebuilds the docs AI assets when the docs repo is present.

To prepare package repository exports locally:

npm run export:developer-packages

This writes dist/developer-packages/tokportal-node, tokportal-cli, and tokportal-mcp from the package release manifest. Each export includes .tokportal-release.json with the target repo, build command, publish command, schema source, generated .github/workflows/ci.yml / .github/workflows/release.yml, plus SECURITY.md, CONTRIBUTING.md, RELEASE.md, and LICENSE.