API guide

Base URL

Everything is at https://api.ai.globalstake.io, over HTTPS only. OpenAI-format clients use https://api.ai.globalstake.io/v1 as their base URL. Anthropic and Gemini clients use https://api.ai.globalstake.io on its own, because they add /v1 or /v1beta themselves.

Getting a key

Personal keys

1. Sign in at chat.globalstake.io with your @globalstake.io account.
2. Open Settings > Account > API keys.
3. Create a key and copy it. It starts with sk-.

The key acts as you and can use every model the API serves. You have one key: regenerating it replaces the old one, and deleting it stops it. Either change takes effect within a minute. If your GlobalStake AI account is removed, the key stops working too.

Service keys

Service keys are for CI and other automation, so that a pipeline does not depend on one person's key. Trevor (tksmith@globalstake.io) issues them. Each has a name, a person responsible for it, the models it may use and its own limits. They start with gsk_. A revoked service key stops working within 30 seconds.

Keeping keys safe

Treat a key like a password. Keep it in an environment variable or a CI secret, never in code or a repository. If a key may have leaked, regenerate it (personal) or ask Trevor to revoke it (service).

Sending the key

Send the key the way your SDK does. Any of these works:

• Authorization: Bearer <key> (OpenAI SDK, curl, most tools)
• x-api-key: <key> (Anthropic SDK)
• x-goog-api-key: <key> or ?key=<key> (Gemini SDK)

Routes

Every answer carries an X-Request-Id header. Quote it when you report a problem.

Examples

The examples read the key from the environment variable GSAI_API_KEY. The model qwen3.8-27b is the platform's default chat model; any id from GET /v1/models works the same way.

curl

curl https://api.ai.globalstake.io/v1/chat/completions \
  -H "Authorization: Bearer $GSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3.8-27b", "messages": [{"role": "user", "content": "Say hello."}]}'

OpenAI Python SDK

import os

from openai import OpenAI

client = OpenAI(base_url="https://api.ai.globalstake.io/v1", api_key=os.environ["GSAI_API_KEY"])
reply = client.chat.completions.create(
    model="qwen3.8-27b",
    messages=[{"role": "user", "content": "Say hello."}],
)
print(reply.choices[0].message.content)

Anthropic Python SDK

import os

import anthropic

client = anthropic.Anthropic(base_url="https://api.ai.globalstake.io", api_key=os.environ["GSAI_API_KEY"])
message = client.messages.create(
    model="qwen3.8-27b",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Say hello."}],
)
print("".join(block.text for block in message.content if block.type == "text"))

Claude Code

export ANTHROPIC_BASE_URL=https://api.ai.globalstake.io
export ANTHROPIC_AUTH_TOKEN="$GSAI_API_KEY"
export ANTHROPIC_MODEL=qwen3.8-27b
export ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3.8-27b
claude

ANTHROPIC_AUTH_TOKEN sends the key as Authorization: Bearer. ANTHROPIC_MODEL chooses the model, and ANTHROPIC_DEFAULT_HAIKU_MODEL the model for background tasks such as session titles. Claude Code is built for Claude models, so some of its features may not work with an open model.

Waiting for a model

A model that is not running yet is loaded when you ask for it, which can take several minutes. Ask for a streamed answer ("stream": true, or stream=True in the SDKs) to see progress while it loads, and allow up to an hour before your client gives up.

Clef decisions

Clef answers questions about a piece of text, JSON or an image with probabilities instead of prose. Send POST /v1/systemone with "model": "clef", the material in state, and named questions. A noul question is yes or no; a choice question picks one of its criteria. The answer has an entry under answers for each question, by the name you gave it, with Clef's probabilities.

curl

curl https://api.ai.globalstake.io/v1/systemone \
  -H "Authorization: Bearer $CLEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "clef",
    "state": "Checkout has been failing for every customer for the last hour.",
    "questions": {
      "outage": {"type": "noul", "instructions": "Is this a customer-facing outage?"},
      "urgency": {
        "type": "choice",
        "instructions": "How urgent is this?",
        "criteria": {"now": "Customers are affected right now", "later": "It can wait for working hours"}
      }
    }
  }'

GitHub Actions step

Store the service key as the repository secret CLEF_TOKEN (Settings > Secrets and variables > Actions), then add a step like this to a workflow that runs on pull requests:

- name: Ask Clef about this pull request
  env:
    GH_TOKEN: ${{ github.token }}
    GH_REPO: ${{ github.repository }}
    CLEF_TOKEN: ${{ secrets.CLEF_TOKEN }}
    PR: ${{ github.event.pull_request.number }}
  run: |
    gh pr diff "$PR" > pr.diff
    jq -n --rawfile diff pr.diff '{
      "model": "clef",
      "state": $diff,
      "questions": {
        "leak": {"type": "noul", "instructions": "Does this diff add a real secret, such as an API key, token, password or private key?"}
      }
    }' > request.json
    curl --fail-with-body -sS https://api.ai.globalstake.io/v1/systemone \
      -H "Authorization: Bearer $CLEF_TOKEN" \
      -H "Content-Type: application/json" \
      --data @request.json

Input limit

Clef reads at most 16,384 tokens per request, the questions included. Split bigger diffs, for example by file, into parts of about 30,000 characters (roughly 10,000 tokens) and ask about each part.

Clef answers one request at a time. Others wait their turn rather than fail, so give your client a timeout of several minutes.

Models

GET /v1/models lists every model your key can use right now, with the id to send as model. A service key sees only its own models. The live state of each model (ready, loading, or loaded on demand) is on ai.globalstake.io.

Clef 27B (clef) is a decision model: typed decisions with probabilities (yes or no, a choice, a score) over text, JSON or images. It is listed with "kind": "decision". It answers only POST /v1/systemone and cannot chat.

Limits

• Each person: 8 requests at a time and 120 requests a minute. Service keys have their own limits, set when the key is made.
• Request bodies: up to 64 MiB.
• From one network address, 30 requests with a missing or wrong key within a minute block that address for 5 minutes.

Over a limit, the answer is 429 at once, with a Retry-After header giving the seconds to wait. Requests over a limit are never queued.

Errors

Errors from the API itself look like this:

{"error": {"message": "The API key is missing or not valid. ...", "type": "gsai_api_error", "code": "invalid_api_key"}}

Errors from a model or the model service, such as a malformed request or an unknown model, come back as that service sends them.

Privacy

Request and response bodies are not stored. Prompts and answers pass through the API without being written to disk or to any log.

For each request the API records who made it (your email, or the service key's name), the first characters of the key, the route, the model, the status, how long it took, its size and, when the model reports them, the token counts. These records are kept for 180 days. Your network address is used only to count requests with a wrong key.