Clients/Magpie

Use the Wokey API with Magpie

Get a Wokey API key, point Magpie at the Wokey base URL, then confirm the connection with one curl request.

Updated

On this pageexpand_more

Get an API key and the base URLlink

Every client uses the same Wokey API key and the same base URL.

Create an API key

Sign in and create a platform key on the API page. Keys in one account share its balance.

Create an API keykey

Use the Wokey base URL

Set the client base URL to the gateway domain; the configuration below shows whether to append /v1.

Configure the clientlink

Magpie is a model gateway that runs on your machine. Once Wokey is added as a provider, every agent on the machine can call Wokey models through it. Magpie stores one address per API format, and a single command sets all three.

  1. 1

    Add the provider

    Run the magpie provider add command below with your Wokey API key in place of YOUR_API_KEY. url and responses take https://api.wokey.ai/v1; anthropic takes https://api.wokey.ai with no /v1. Without a models argument, Magpie reads the model list from Wokey.

  2. 2

    Or use an import link

    On Magpie 0.1.8 or later, open https://usemagpie.ai/import#name=Wokey&chat=https://api.wokey.ai/v1&anthropic=https://api.wokey.ai, paste your API key in the dialog, and confirm.

  3. 3

    Pick a model in your agent

    Write the model as wokey/model-id, for example wokey/claude-opus-5-5.

Magpie
magpie provider add "Wokey" \
  url=https://api.wokey.ai/v1 \
  responses=https://api.wokey.ai/v1 \
  anthropic=https://api.wokey.ai \
  key=YOUR_API_KEY

API formats and base URLslink

When one client switches API format, whether the base URL ends in /v1 can change.

FormatBase URLUse it for
OpenAI Chat Completionshttps://api.wokey.ai/v1DeepSeek, GLM, Kimi, and other models
OpenAI Responseshttps://api.wokey.ai/v1GPT models
Anthropic Messageshttps://api.wokey.aiClaude models

Where it is configured: magpie provider add or an import link (file ~/.config/magpie/providers.json)

Verify with curllink

If the client reports an error, rule out the key and base URL with curl first.

Magpie uses the OpenAI Chat Completions format by default. A 200 from this request means the key and base URL are right. Replace YOUR_API_KEY with your key before sending it.

cURL
curl https://api.wokey.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'

Errors & Troubleshootinglink

Separate auth, balance, rate limit, model availability, and upstream timeout cases first.

401

invalid api key

The key is missing, mistyped, deleted, or Authorization / x-api-key headers conflict.

402

insufficient balance

The account balance is too low. Top up before sending more requests.

403

model_denylisted / account_restricted

Calls to the model, or to every model on the account, are paused after repeated violations. See Violation Handling Fees & Restrictions.

403

request_blocked

This request was blocked before reaching the upstream and is not charged, for example an unchanged resend of a request the model just refused, or a paused end user (X-End-User-Id). The error message says what is blocked; change the request as it says or retry later. Other requests are not affected.

429

rate limited

Traffic is too frequent. Retry later or reduce concurrency. If only one model, or one end user (X-End-User-Id), keeps returning 429, it may be a temporary limit after violations.

499

client disconnected

The client closed the connection before the response finished (code downstream_aborted). This is free by default. Once an account has at least 50 client disconnects in the past 24 hours and they make up 10% or more of its requests, later disconnected requests are billed for the usage the upstream reported: the processed input, including cache reads and writes, and output only when the upstream counted it. A disconnect before the upstream reported any usage stays free. The account is notified when billing starts, and billing stops automatically within an hour once the disconnect rate is back to normal. The usual cause is a client or proxy timeout that is too short, or a program that cancels requests before they finish.

502

upstream unavailable

The upstream model service is temporarily unavailable. Switch models or retry later.

504

upstream timeout

The upstream response timed out. Shorten context, reduce max_tokens, or retry.

529

upstream overloaded

The upstream model is temporarily overloaded and Wokey already retried on other routes (code upstream_overloaded). It is unrelated to your balance. Retry shortly or switch models.

Frequently asked questionslink

Should the Wokey address in Magpie end in /v1?
Magpie stores one address per format. Use https://api.wokey.ai/v1 for chat and responses, and https://api.wokey.ai with no /v1 for anthropic. The address must be https.
What if the import link does nothing?
Import links need Magpie 0.1.8 or later. Upgrade first, or add the provider with the magpie provider add command instead.
How do I write the model name in an agent?
As provider id/model name. A provider named Wokey gets the id wokey, so Claude Opus 5.5 is wokey/claude-opus-5-5.
Where do I enter the Wokey API key?
Paste the key in the import dialog or pass it as key= to magpie provider add. Magpie stores it in ~/.config/magpie/providers.json.
Can I share an import link that contains my key?
Do not. The key parameter is plain text, so anyone with the link can spend your balance. Remove the key parameter before sharing; the other person enters their own key in the import dialog.