api.shieldie.ai

A private text-generation API. Send a chat-style request, get a reply — streaming or all at once. Access is by API key issued from the admin panel.

Getting a key

Keys are issued from the password-protected admin panel. A key is shown once, at creation — copy it then. Present it on every request in the x-api-key header.

Request

A JSON body with a list of messages. The model field is optional — there is a single model, default, and it is used whether or not you name one.

field
messages	required — array of {"role":"user"|"assistant","content":"…"}
max_tokens	required — positive integer (accepted; not strictly enforced)
system	optional — a system instruction string
stream	optional — true for server-sent events
model	optional — accepted and ignored; always default

curl

curl https://api.shieldie.ai/v1/messages \
  -H "x-api-key: $SHIELDIE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Napisz jedno zdanie po polsku."}]
  }'

Response

{
  "id": "msg_…",
  "type": "message",
  "role": "assistant",
  "model": "default",
  "content": [{ "type": "text", "text": "…" }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 12, "output_tokens": 34 }
}

Python

import requests

r = requests.post(
    "https://api.shieldie.ai/v1/messages",
    headers={"x-api-key": "sk-shd-...", "content-type": "application/json"},
    json={
        "max_tokens": 256,
        "messages": [{"role": "user", "content": "Hello!"}],
    },
)
print(r.json()["content"][0]["text"])

Streaming

Set "stream": true. The response is a text/event-stream with these events: message_start → content_block_start → content_block_delta (repeated, each carrying a text_delta) → content_block_stop → message_delta → message_stop, with ping keep-alives.

curl -N https://api.shieldie.ai/v1/messages \
  -H "x-api-key: $SHIELDIE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"max_tokens":128,"stream":true,
       "messages":[{"role":"user","content":"Count to five."}]}'

Tools (function calling)

Pass tools with your request. The model may answer with a tool_use block instead of text; your client runs the tool and sends the outcome back as a tool_result in the next request. The server never executes anything.

curl https://api.shieldie.ai/v1/messages \
  -H "x-api-key: $SHIELDIE_API_KEY" -H "content-type: application/json" \
  -d '{
    "max_tokens": 512,
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "input_schema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }],
    "messages": [{ "role": "user", "content": "What is the weather in Kraków?" }]
  }'

A tool call comes back as:

{
  "stop_reason": "tool_use",
  "content": [
    { "type": "tool_use", "id": "toolu_…", "name": "get_weather", "input": { "city": "Kraków" } }
  ]
}

Run the tool, then continue the conversation with the result:

"messages": [
  { "role": "user", "content": "What is the weather in Kraków?" },
  { "role": "assistant", "content": [
      { "type": "tool_use", "id": "toolu_…", "name": "get_weather", "input": { "city": "Kraków" } } ] },
  { "role": "user", "content": [
      { "type": "tool_result", "tool_use_id": "toolu_…", "content": "18°C, sunny" } ] }
]

Use tool_choice to steer it: {"type":"auto"} (default), {"type":"any"} (must call some tool), or {"type":"tool","name":"…"} (must call that one).

Other endpoints

method / path	what
GET /v1/models	List the available model (needs a key).
POST /v1/messages/count_tokens	Approximate input token count.
GET /health	Liveness check (public).

Good to know