Plugsky Documentation

Getting started

Five minutes from zero to your first model response. The Plugsky API is 100% OpenAI-compatible — change your base_url and your existing code, SDK, and prompts keep working.

Install

# Python (OpenAI SDK — works as-is)
pip install openai

# Node.js / TypeScript
npm install openai

# Go
go get github.com/sashabaranov/go-openai

# Or use raw HTTP — no SDK required

Your first API call

from openai import OpenAI

client = OpenAI(
    api_key="sk-live-…",                          # your Plugsky key
    base_url="https://plugsky.com/v1",         # the only line that changes
)

resp = client.chat.completions.create(
    model="plugsky-pro",
    messages=[{"role": "user", "content": "Say hello in 5 languages"}],
    max_tokens=200,
)
print(resp.choices[0].message.content)

That's it. Same request shape, same response shape, same streaming, same function-calling, same JSON mode. Full OpenAI-compatibility reference →

Core concepts

• Model. The inference engine. plugsky-micro through plugsky-frontier, plus third-party providers behind the same API (NVIDIA NIM, OpenCode, OpenRouter, and fal.ai FLUX for images).
• Request. A single API call. Token-counted. Priced.
• Thread / Run. Stateful multi-turn conversation (Assistants API).
• Tool. A function you expose to the model for function-calling.
• Knowledge base / Vector store. Indexed documents the model can retrieve from (RAG).
• Endpoint / Region. Where the model runs. me-central-1 (UAE), eu-west-1, us-east-1, plus customer VPC and on-prem.

Authentication

Plugsky uses bearer-token API keys. Keys are project-scoped, role-scoped, and rotatable without downtime.

API keys

Generate keys in the Dashboard → API keys. Every key is tied to your workspace and inherits its plan. Create separate keys per project or environment and revoke them independently. MCP usage can be limited with fine-grained scopes (mcp.read, mcp.write, mcp.web, mcp.media, mcp.memory, mcp.compute) — see the MCP section.

Environment variables

export PLUGSKY_API_KEY="sk-live-…"
export PLUGSKY_BASE_URL="https://plugsky.com/v1"
export PLUGSKY_PROJECT="prj_8x2…"   # optional, defaults to your first project
export PLUGSKY_REGION="me-central-1"

Scopes & roles

Each key has a comma-separated scope list. Examples: chat:write,embeddings:write,files:read. Use the narrowest scope that works — production keys should never have admin.

OAuth 2.0 (3rd-party apps)

Plugsky supports OAuth 2.1 with Dynamic Client Registration (RFC 7591) and PKCE (S256) for apps that connect on behalf of a workspace. Discovery: /.well-known/oauth-authorization-server · /.well-known/oauth-protected-resource. Endpoints: POST /oauth/register, GET|POST /oauth/authorize, POST /oauth/token. Browser consent opens the dashboard (/dashboard#mcp-oauth) and minted tokens act as scoped API keys.

API reference

Every endpoint, every parameter, every status code. Compatible with OpenAI's /v1/* namespace; Plugsky-specific extensions live under /v1/plugsky/*.

Chat completions

from openai import OpenAI
client = OpenAI(api_key="sk-live-…", base_url="https://plugsky.com/v1")

stream = client.chat.completions.create(
    model="plugsky-pro",
    messages=[{"role": "user", "content": "Write a haiku about GCC summers"}],
    stream=True,
    temperature=0.7,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Models

Legacy completions

Embeddings

resp = client.embeddings.create(
    model="plugsky-embed",
    input=["Plugsky is a sovereign AI cloud", "GCC banks run on us"],
)
print(len(resp.data[0].embedding), "dimensions")  # 2048

Rerank

Image generation

Audio (ASR / TTS / translation)

Moderation

Files

Batch API

Fine-tuning

Assistants

Threads & runs (executable assistants)

Function calling / tools

Pass a tools array with JSON-Schema function definitions. The model returns a structured tool_calls payload you execute, then return the result. Streaming and parallel tool calls supported. Generate your function schema →

Responses

Vector stores (file search)

Plugsky extensions

MCP & agent surface

The MCP surface exposes Plugsky's tools to ChatGPT, Claude, Cursor and any MCP client. Full details in the MCP section and on the dashboard.

Platform API (/api/*)

The dashboard is powered by a documented REST surface under /api/*, authenticated with your session token. Automation groups include: auth (signup, login, 2FA, refresh, OAuth), keys, usage + usage/budget, dashboard (summary, savings, onboarding), workspaces, team (members, invites), models (config, fusion presets, templates, preview, cost, compare), playground (run, search, tools, browser, conversations), skills, share, integrations, health/models and enterprise. All endpoints return JSON and share the same error schema as /v1/*.

Models

All models across free, paid, and embedding tiers — served behind one OpenAI-compatible endpoint, billed from one invoice, governed by one set of policies. The table is populated live from GET /v1/models (the single source of truth). Hover the ⓘ icon for full details.

Smart routing & Model Fusion

Two ways to get cost savings automatically. Set model="plugsky-fusion" to use the dashboard's default chain (sequential, parallel, cost-saver — your choice). For classifier-based routing use POST /v1/plugsky/route (it defaults to model="auto"); model="auto" is not accepted by /v1/chat/completions. Typical savings: 60-80% on production traffic. See Model Fusion in the dashboard for the full UI.

# Option 1: use your configured Fusion chain
resp = client.chat.completions.create(
    model="plugsky-fusion",   # runs the workspace's default chain
    messages=[{"role": "user", "content": "Hello!"}],
)
print(resp.model)             # which model actually answered (e.g. "plugsky-micro")

# Option 2: smart routing — dedicated endpoint
import requests
resp = requests.post(
    "https://plugsky.com/v1/plugsky/route",
    headers={"Authorization": "Bearer sk-live-…"},
    json={
        "model": "auto",           # classifier picks the best model
        "route_hint": "cost",      # cost | quality | latency
        "messages": [{"role": "user", "content": "Hello!"}],
    },
)
print(resp.json()["model"])    # the model Plugsky chose

SDKs

The OpenAI SDK works as-is — change the base URL and key. Pick your language below; official and community OpenAI SDKs plus the ecosystem frameworks are all supported.

Framework integrations

• LangChain — ChatOpenAI(base_url="https://plugsky.com/v1")
• LlamaIndex — OpenAI(base_url=…)
• Vercel AI SDK — openai("…", { baseURL: "https://plugsky.com/v1" })
• Haystack — OpenAIGenerator(api_base=…)
• Semantic Kernel — OpenAIChatCompletion(…endpoint=…)
• AutoGen — OpenAIWrapper(base_url=…)
• OpenAI Playground — Custom base URL field. Tested daily.

Example: streaming with back-pressure

import openai
client = openai.OpenAI(api_key="sk-live-…", base_url="https://plugsky.com/v1")

with client.chat.completions.stream(
    model="plugsky-pro",
    messages=[{"role":"user","content":"Tell me a 500-word story about Plugsky"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_completion()
    print("\n--- usage:", final.usage)

Official software & installers

First-party desktop, CLI, and self-hosted apps — all open-source under MIT / Apache-2.0, branded Plugsky, and pre-configured to talk to the Plugsky API. Install with one command.

Plugsky CLI

Native terminal AI coding agent — Bun-compiled single binary with built-in agent loop, file editing, shell sandbox, MCP client, RAG indexing, and auto model routing. No provider config needed — just plugsky login.

# macOS / Linux (one-line install)
curl -fsSL https://plugsky.com/install | sh

# Authenticate
plugsky login

# One-shot agentic task
plugsky "explain this project"

# Interactive TUI (REPL)
plugsky

Quick reference:

Approval modes: suggest (prompts for edits + shell) · auto-edit (auto edits, prompts shell) · full-auto (no prompts)

View on GitHub → · Full user guide → · Dashboard CLI docs →

Plugsky Desktop (Jan-based)

Native AI chat client for macOS, Linux, Windows. Built on the open-source Jan project (Apache-2.0). Branded Plugsky, pre-configured with plugsky-pro as the default model.

curl -fsSL https://plugsky.com/install-desktop | bash
plugsky-desktop

Available for macOS (Apple Silicon + Intel), Linux (x64), Windows (x64).

Plugsky Web (Open WebUI-based)

Self-hosted AI chat UI in your browser. Built on the open-source Open WebUI project. Docker or pip install, both backends supported. The plugsky-fusion model is pre-listed.

curl -fsSL https://plugsky.com/install-web | bash
plugsky-web start
# → opens http://localhost:8080

Latest releases (Plugsky CLI v0.1.2 — 2026-07-05)

All three are MIT-licensed. See NOTICE for full upstream attribution.

Operations

Rate limits & quotas

All plans include unlimited usage within fair-use rate limits — no per-token charges, no per-request charges, no overage fees. The only limit is the per-minute request rate (RPM) for your tier. Increase limits from the Dashboard or by emailing support@plugsky.com.

Same flat rate on every model — no separate pricing for plugsky-frontier vs plugsky-micro. Every model in the catalog is included on every paid plan. Hit a 429? The response includes a Retry-After header. The SDKs retry with exponential backoff automatically.

MCP (Model Context Protocol)

Plugsky ships a remote MCP endpoint and a local stdio server, so ChatGPT, Claude, Cursor, VS Code, Windsurf and Zed can use your models, web search, media ingest, memory, browser sessions and code runner directly.

• Remote (Streamable HTTP): https://plugsky.com/mcp with Authorization: Bearer sk-live-… — 20 tools, 12 prompts, 10 resources (chat, fusion, web search & fetch, YouTube transcripts, video/audio/screen/site ingest, image generation, memory, browser sessions, code runner).
• OAuth 2.1 + DCR: modern clients self-register and authenticate with PKCE — no manual key needed. Discovery at /.well-known/oauth-authorization-server.
• Fine-grained scopes: mcp.read, mcp.write, mcp.web, mcp.media, mcp.memory, mcp.compute — enforced per tool group.
• Metering: per-tool usage at GET /api/mcp/usage (raw events: GET /api/mcp/events).
• Local (stdio): npx -y @plugsky/mcp with PLUGSKY_API_KEY. Filter tools with --groups=chat,models,rag,usage,tools,files.
• Ready-made configs: Dashboard → AI → MCP Servers (Claude Desktop, Cursor, Windsurf, VS Code, ChatGPT connectors).

Retries & idempotency

All POST endpoints accept an Idempotency-Key header. Re-sending the same key returns the cached result for 24 hours. This makes your POSTs safe to retry without double-billing or double-creating resources.

curl -X POST https://plugsky.com/v1/chat/completions \
  -H "Authorization: Bearer $PLUGSKY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"model":"plugsky-pro","messages":[{"role":"user","content":"hello"}]}'

Errors & status codes

All API errors use the OpenAI error schema: {"error":{"message","type","code","param"}} — JSON only, never HTML. Oversized bodies are rejected with 413.

Webhooks

Billing webhooks are live (Stripe, provisioned automatically). Platform event webhooks (batch.completed, fine_tuning.completed, quota.warning, and similar) are on the roadmap — today, poll state with GET /v1/batches/{id}, GET /v1/fine_tuning/jobs/{id}, GET /v1/plugsky/usage, or stream MCP tool events with GET /api/mcp/events.

Logs & observability

Every request is logged with: timestamp, model, tokens, latency, status, key ID, project ID, region, request ID, optional user tag. Export to Datadog, Splunk, Grafana, New Relic, OpenTelemetry, or your SIEM.

Status & SLAs

Live status: /status. Public incident history. Uptime SLAs:

• Builder / Scale: 99.9% monthly uptime, 10% credit on miss
• Enterprise: 99.95% monthly uptime, 25% credit, 99.99% on multi-region deployments

Deployment topologies

Same API, four deployment models. Pick one, or combine them across teams.

Decision matrix

Security & compliance

Security model

• Encryption in transit: TLS 1.3 only, HSTS, modern ciphers
• Encryption at rest: AES-256-GCM, customer-managed keys available
• Network isolation: per-tenant VPC, security groups, no shared kernel
• Tenant isolation: logical (RBAC + scoped keys) or physical (your own cluster)
• Secret hygiene: keys never logged, never returned in responses, hashed at rest with Argon2id
• Pen tests: quarterly by HackerOne + an external firm. Reports under NDA.
• Bug bounty: up to $25,000. security@plugsky.com

Data residency

Choose per-request or pin globally. Regions: me-central-1 (UAE — default GCC), sa-central-1 (Riyadh — Enterprise), eu-west-1 (Dublin), eu-central-1 (Frankfurt), us-east-1, us-west-2, ap-southeast-1 (Singapore). Data never leaves the pinned region. Deep dive →

Compliance & certifications

• SOC 2 Type II — annually audited, report under NDA
• ISO 27001 — InfoSec management
• ISO 27701 — Privacy management
• ISO 27017 / 27018 — Cloud & PII
• GDPR — EU data protection
• HIPAA — Healthcare (Enterprise + BAA)
• PCI DSS — Card data safety (no inference on card data unless on-prem)
• FedRAMP Moderate — In process, available on Enterprise
• UAE PDPL — Federal Data Protection Law
• DIFC DPL — Dubai International Financial Centre
• SAMA CSF — Saudi Central Bank cyber framework
• NSD — National Security Directive alignment (Enterprise on-prem)

DPA & legal

Standard Contractual Clauses (SCCs) baked into the DPA. Sub-processor list published and updated within 30 days of any change. Read the DPA →

Audit logs

Every key action — creation, rotation, scope change, deletion — is logged with actor, timestamp, IP, and request body hash. Exportable to your SIEM (Splunk, Sentinel, QRadar, Chronicle) via webhook or Kinesis/Firehose.

BYOK / HSM

Bring Your Own Key. Plugsky never sees your key — you import it into our HSM integration (AWS KMS, GCP KMS, Azure Key Vault, HashiCorp Vault, Thales Luna, AWS CloudHSM). Key rotation, revocation, and audit all yours.

PII handling

Three modes: no-PII (strict filter, PII auto-redacted), detect-only (PII tagged but not modified), passthrough (your responsibility). Default is detect-only for inference, no-PII for embeddings. Run the residency checklist →

Billing

Plans

Flat monthly fee per workspace. Every model in the catalog included on every paid plan — no per-token charges, no per-request charges, no overage fees, no surprise bills. Cancel or downgrade anytime.

Annual billing saves 20% (Hobby: 50%). Enterprise plans are annual contracts priced to your deployment, security, and volume requirements — mustafa@plugsky.com or mustafa@plugsky.com · WhatsApp +973 3659 9909.

Free plan — what you get

The Free plan is permanent ($0, no card) and is built for trying the platform and light use:

• Free AI models — plugsky-micro and plugsky-lite (chat + JSON, unlimited fair use, 30 requests/min).
• Playground and Playground Beta — full access to chat, compare models and prompt tools.
• API access — Unlimited API keys, OpenAI-compatible endpoint, free models only.
• Usage & Analytics, models catalog, billing and account settings.

Locked until you upgrade: paid models (plugsky-plus and above), Agent Cloud, Tools & Connectors (function calling), Knowledge / RAG, Model Fusion, Marketplace, Integrations and multi-seat Teams.

Every new account also starts with a 14-day full-access trial — no card required — which unlocks models up to plugsky-plus, Tools, RAG and Integrations so you can evaluate everything before choosing a plan.

Usage & metering

Unlimited usage on every plan. No per-token charges, no per-request charges, no overage fees. The only limit is the fair-use RPM for your tier (60 trial · 300 · 600 · 1,500 · 5,000 · 10K+ on Enterprise). Token counts are still returned in every response (usage.prompt_tokens, usage.completion_tokens) for observability — but they don't drive billing.

Invoices & taxes

Monthly billing on the 1st. PDF invoices emailed automatically. VAT-compliant for UAE (5%), KSA (15%), EU (reverse charge), and US (no sales tax on SaaS in most states). Wire transfer, ACH, SEPA, and major credit cards. Annual contracts: priced per deployment, paid upfront.

Quotas & limits

Hard $ caps at the project level prevent runaway spend. Soft warning alerts at 50%, 80%, 95%. Hard block at 100% (auto-reject 402). You can set overage_behavior=allow with a finance-approved key to allow overage up to 3× the cap with auto-billing.

Migration guides

From OpenAI

1. Generate a Plugsky key in the Dashboard
2. In your code, change base_url to https://plugsky.com/v1
3. No model renames needed — OpenAI (gpt-4o, gpt-4o-mini, o1/o3), Claude (claude-3-5-sonnet, claude-3-opus), Gemini (gemini-2.5-flash) and DeepSeek model names are accepted and auto-mapped to Plugsky models (gpt-4o → plugsky-pro, gpt-4o-mini → plugsky-lite, text-embedding-3-* → plugsky-embed)
4. Run your existing evals — should pass unchanged
5. Switch DNS / cut over when ready

Need a per-language migration walkthrough? Full guide → or generate code for your stack →

From Anthropic

Roadmap: a native Anthropic-compatible /v1/messages endpoint is planned. Today, point the Anthropic SDK’s OpenAI-compatibility mode at https://plugsky.com/v1 — Claude model names (claude-3-5-sonnet-*, claude-3-opus-*, claude-3-5-haiku-*) are accepted and auto-mapped to Plugsky models (→ plugsky-pro / plugsky-max / plugsky-lite).

From Azure OpenAI

Point your Azure SDK at https://plugsky.com/v1 (Azure SDK supports custom endpoints). Models keep their Azure names with the azure/ prefix. Existing content filters and Azure-specific features have Plugsky equivalents — see the full compatibility matrix →

From AWS Bedrock

Use the Bedrock SDK's endpoint_url parameter. Roadmap: a native Bedrock Converse endpoint is planned. Today, use the Bedrock SDK’s OpenAI-compatible mode with endpoint_url=https://plugsky.com/v1 and model IDs such as plugsky-pro.

Reference

Glossary

Changelog

/changelog — full release history. Subscribe to RSS or the model.deprecated webhook.

Support

• Email: support@plugsky.com (24/5 on Builder+, 24/7 on Scale+)
• WhatsApp — instant support (paid plans): +973 3659 9909
• Slack Connect: for Enterprise customers
• Office hours: weekly community call, Thu 4pm GST — join →
• Status: /status
• Security issues: security@plugsky.com (PGP key in /.well-known/security.txt)