How do you use Plugsky with cURL?

Key facts

Chat endpoint	POST https://api.plugsky.com/v1/chat/completions
Auth header	Authorization: Bearer $PLUGSKY_API_KEY
Content type	Content-Type: application/json
Streaming	stream=true returns SSE; use curl -N to disable buffering
Models list	GET /v1/models returns the live catalogue, including 30+ models
Embeddings	POST /v1/embeddings with model plugsky-embed
Errors	OpenAI-shaped error JSON; 401 key, 403 scope, 429 Retry-After, 413 over 16 MB
Product status	Live; audio, images, batch and fine-tuning are coming soon

TL;DR

• One POST, two headers, one JSON body — no SDK required.
• curl -N streams server-sent events without buffering.
• jq makes responses scriptable in shell pipelines.
• Idempotency-Key makes retried POSTs safe.
• Raw HTTP is the fastest way to debug auth and schema issues.

How it works, step by step

1. Export PLUGSKY_API_KEY so the secret never appears in shell history.
2. Send a chat completion with curl and the Authorization header.
3. Add | jq -r '.choices[0].message.content' to extract the answer.
4. Stream by setting stream=true and adding the -N flag.
5. List models with GET /v1/models to confirm model ids.
6. Generate embeddings with POST /v1/embeddings and model plugsky-embed.
7. Add -i or -w '%{http_code}' to inspect status codes when debugging.

Original data

Try it yourself

Open the OpenAI-compatible API tester →

Your first request

Keep the key in an environment variable and send the request:

export PLUGSKY_API_KEY="sk-live-…"

curl -sS https://api.plugsky.com/v1/chat/completions \
  -H "Authorization: Bearer $PLUGSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "plugsky-pro",
    "messages": [
      {"role": "user", "content": "Summarise this ticket in one line."}
    ],
    "temperature": 0.3
  }' | jq -r '.choices[0].message.content'

-sS keeps output clean while still printing errors. If jq is not installed, drop the pipe and read the full JSON. A 401 here means the header is missing or the key is wrong; a 404 means the model id is not in the catalogue.

Streaming with curl -N

Streaming uses server-sent events. The -N flag disables cURL's output buffering so chunks print as they arrive:

curl -N -sS https://api.plugsky.com/v1/chat/completions \
  -H "Authorization: Bearer $PLUGSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "plugsky-lite",
    "messages": [{"role": "user", "content": "Count to ten slowly."}],
    "stream": true
  }'

Each line starts with data: and contains a JSON chunk with choices[0].delta.content. The stream ends with a data: [DONE] sentinel. To watch tokens as words instead of raw JSON, pipe through jq and strip the prefix:

... | sed -u 's/^data: //' | jq -r '.choices[0].delta.content // empty'

Models, embeddings and token accounting

Discover the live catalogue before hard-coding ids:

curl -sS https://api.plugsky.com/v1/models \
  -H "Authorization: Bearer $PLUGSKY_API_KEY" | jq -r '.data[].id'

Embeddings use the same pattern with a different route and model:

curl -sS https://api.plugsky.com/v1/embeddings \
  -H "Authorization: Bearer $PLUGSKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "plugsky-embed", "input": "Refunds take five business days"}' \
  | jq '.data[0].embedding | length'

Non-streaming chat responses include a usage object with prompt and completion token counts — useful when you need to meter internal cost allocation without an SDK.

Headers, errors and idempotency

When something fails, ask cURL to show you everything: -i prints response headers, and -w '\n%{http_code}\n' appends the status code for scripts. The codes that matter:

• 401: missing or invalid key — check the Authorization header.
• 403: the key lacks the required scope.
• 429: fair-use rate limit — read Retry-After and sleep before retrying.
• 413: body larger than 16 MB — trim history or split the request.

Errors use the OpenAI schema: {"error":{"message","type","code","param"}}. For POSTs that might be retried, add an idempotency header so a repeated request returns the cached result for 24 hours:

-H "Idempotency-Key: $(uuidgen)"

Honest comparison

Capability	Plugsky + cURL	OpenAI SDKs	Custom HTTP wrapper
Setup	No dependencies	pip install or npm install	You write and maintain it
Streaming	curl -N and data: lines	Typed stream iterators	Your own parser
Tools	Verbose JSON but full control	Typed helpers	Your schema
Debugging	Raw headers and bodies by default	Enable SDK debug logging	Add your own instrumentation
Portability	Runs anywhere cURL exists	Language runtime required	Not applicable
Ops	Managed API	Managed API	You maintain the wrapper

Frequently asked questions

What is the minimum cURL request for Plugsky?

A POST to https://api.plugsky.com/v1/chat/completions with Authorization: Bearer sk-live-…, Content-Type: application/json and a body containing model and messages.

How do I stream with cURL?

Set stream=true in the JSON body and pass -N to cURL so it does not buffer the server-sent event output.

How do I extract just the answer text?

Pipe through jq -r '.choices[0].message.content' for non-streaming responses.

How can I check the HTTP status code?

Add -i to see response headers, or -w '\n%{http_code}\n' to print the status at the end of the output.

Why did I get a 403 when my key works elsewhere?

The key is valid but lacks the scope for that endpoint. Check the key's scopes in the dashboard and create one with the required permission.

Can I retry a POST safely?

Yes. Send an Idempotency-Key header so a retried request returns the cached result for 24 hours instead of duplicating work.

How do I list available models?

Call GET /v1/models with your bearer token; the response lists every model id currently available on your account.

Does plain HTTP work?

No. Use HTTPS. TLS 1.3 is enforced, and bearer keys must never travel over an unencrypted connection.