Skip to content

API DOCUMENTATION

Integrate Sealarca into your application.

Authenticate with your Sealarca API key, discover the models available to that key, send Responses, Chat Completions or Claude Messages requests, and connect the service to your software.

The examples use a model ID returned by GET /v1/models. No model is fixed in this documentation.

First request

cURL · Responses

curl https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Summarize this confidential text in three points.\",\"max_output_tokens\":256}"

Response shape

JSON · Abbreviated response

{"id":"<response-id>","object":"response","status":"completed","model":"<model-id>","output":[{"type":"message","role":"assistant","content":[{"type":"output_text","text":"<generated text>"}]}]}

START HERE

From account to first response

Follow the order below: access first, then model discovery, then a server-side request.

  1. 01

    Create an account

    Create your Sealarca account to access the dashboard.

  2. 02

    Add credits

    Top up your prepaid CHF balance before calling the API.

  3. 03

    Create an API key

    Create a Sealarca API key and keep it on your server.

  4. 04

    List the models

    Call GET /v1/models and choose an ID visible to your key.

  5. 05

    Make the first call

    Use the returned model ID with Responses, Chat Completions or Claude Messages.

01

Authenticate every request

The public API accepts a Sealarca API key as a Bearer token or, for Claude clients, through `x-api-key` on the Messages route.

Authentication headers

Use `Authorization: Bearer ...` for Responses and Chat Completions. Claude clients may use `x-api-key: ...` with `anthropic-version` on `/v1/messages`.

Authorization: Bearer $SEALARCA_API_KEYx-api-key: $SEALARCA_API_KEYanthropic-version: 2023-06-01

Keep the key server-side

Never expose it in a public web application, distributed mobile app, repository, or NEXT_PUBLIC_* variable. Desk is a separate local client: the user provides the key and it is kept only for the tab session.

02

First request

A server-side key, the base URL, and a JSON body are enough. The canonical example uses Responses.

Base URL
https://api.sealarca.ch/v1
Bearer token
Authorization: Bearer $SEALARCA_API_KEY
Content-Type
application/json

Server-side key only. Never place the key in a public web application, browser bundle, `NEXT_PUBLIC_*` variable, Git repository, or distributed mobile app. A public web application must call your backend, which then calls Sealarca.

1. Configure and call Responsesbash
export SEALARCA_API_KEY="YOUR_SEALARCA_API_KEY"
export SEALARCA_MODEL_ID="MODEL_ID_FROM_V1_MODELS"

curl https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Summarize this confidential text in three points.\",\"max_output_tokens\":256}"

Minimal expected JSON response

Choose another model
2. Read the responsejson
{"id":"<response-id>","object":"response","status":"completed","model":"<model-id>","output":[{"type":"message","role":"assistant","content":[{"type":"output_text","text":"<generated text>"}]}]}
03

Discover models

Query the catalogue with the same key and use an exact returned `id` in `model`.

GET /v1/modelsbash
curl https://api.sealarca.ch/v1/models \
  -H "Authorization: Bearer $SEALARCA_API_KEY"
Abbreviated responsejson
{"data":[{"id":"<model-id>","object":"model"}]}

The response is scoped to the key. Use an exact returned id as the model value; do not copy a model name from this page.

Compare models, capabilities, and prices
04

Public endpoint contract

These statuses describe the published contract. Unavailable routes are intentionally not published.

GET

Models

/models
Confirmed

Discover model IDs visible to the key.

Streaming
—
Note
Key-scoped response; the example below is abbreviated.
POST

Responses

/responses
Confirmed

Recommended format for new OpenAI SDK integrations.

Streaming
SSE
Note
JSON is returned by default; set `stream: true` to request SSE.
POST

Chat Completions

/chat/completions
Confirmed

Messages format for existing clients.

Streaming
SSE
Note
JSON is returned by default; set `stream: true` to request SSE.
POST

Claude Messages

/messages
Confirmed

Messages format for Claude-compatible clients and integrations using the Messages API.

Streaming
SSE
Note
Use the exact identifier returned by `/models`. Available capabilities depend on the published model.
POST

Embeddings

/embeddings
Confirmed

Create vector representations for search and similarity.

Streaming
—
Note
Technical endpoint contract, subject to an Embedding model being returned by your catalogue. No embedding model is offered in the currently documented public catalogue. This endpoint does not support streaming.
GET

Vault proof

/vault/proofs/{receiptId}
Confirmed

Consult the status and checks associated with a Vault receipt.

Streaming
—
Note
Authentication required; 202 for pending, 200 for the verdict, 404 if missing or unauthorized, 410 if expired.
GET

Signed proof bundle

/vault/proofs/{receiptId}/bundle
Confirmed

Download the signed JWS for a terminal Vault proof.

Streaming
—
Note
Same user isolation; 202 while pending, 200 when signed, 404 or 410 as applicable, 503 if signing is unavailable.
GET

Vault signing keys

/vault/proofs/signing-keys
Confirmed

Retrieve the public JWKS of active and retired keys.

Streaming
—
Note
Public and unauthenticated; retain the reference fingerprint specified by your contract.
GET

Vault attestation

/vault/attestation?nonce=…
Confirmed

Request a fresh attestation bound to a client nonce.

Streaming
—
Note
The nonce must contain exactly 64 lowercase hexadecimal characters.
05

Language examples

Four examples: three use Responses and the fourth uses Messages. Select a model authorised for the relevant endpoint.

cURLbash
curl https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Analyze this document and return three risks.\"}"
06

Stream a response

Responses, Chat Completions and Claude Messages can request server-sent events with stream: true.

Activate streaming

Set stream to true and use curl -N or an equivalent streaming HTTP client. The response uses text/event-stream.

Read the stream

Process data: records separated by blank lines. Event payloads and termination depend on the route contract; do not assume names beyond it.

POST /v1/responses · stream=truebash
curl -N https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Summarize this file.\",\"stream\":true}"
POST /v1/messages · stream=truebash
curl -N https://api.sealarca.ch/v1/messages \
  -H "x-api-key: $SEALARCA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"max_tokens\":256,\"stream\":true,\"messages\":[{\"role\":\"user\",\"content\":\"Summarize this file.\"}]}"
Illustrative framingtext
Content-Type: text/event-stream

data: <JSON event>

GLM 5.3 Flash — Shield

A confidential multimodal route for text, images, tools and structured outputs, with streaming.

  • Shield combines a protected execution environment with a receipt signed by Sealarca. This receipt documents the exchange observed by our gateway.
  • Hashes cover JSON bodies and SSE streams between the Sealarca gateway and the encryption proxy, before response conversions. They do not identify the original client HTTP bytes. Manifest digests are deployment observations without an independent hardware binding to the response.
  • Supply the conversation in every request. store=true, background, previous_response_id, conversation and cache_salt are rejected. Server-executed tools are unavailable.
  • reasoning_effort accepts low, high or max. The default is low; reasoning cannot be disabled. Reasoning tokens are billed as output tokens, including when a stream is interrupted before an answer is displayed.
  • Model context: up to 1,048,576 tokens. Output cap configured by Sealarca: 131,072 tokens per request. Route quotas and effective limits may reduce this cap. Responses is bridged to Chat Completions. Preview route.
  • Signed receipts and metadata are retained for 90 days. Receipts and logs contain no prompts, responses or images. Shared caching is disabled.
POST /v1/responsesbash
curl https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "glm.5.3-flash-shield",
  "input": "Reply with OK.",
  "reasoning": {
    "effort": "low"
  },
  "store": false,
  "max_output_tokens": 256
}'
POST /v1/chat/completionsbash
curl https://api.sealarca.ch/v1/chat/completions \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "glm.5.3-flash-shield",
  "messages": [
    {
      "role": "user",
      "content": "Reply with OK."
    }
  ],
  "reasoning_effort": "low",
  "max_tokens": 256,
  "stream": true
}'
POST /v1/messagesbash
curl https://api.sealarca.ch/v1/messages \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "glm.5.3-flash-shield",
  "max_tokens": 256,
  "messages": [
    {
      "role": "user",
      "content": "Reply with OK."
    }
  ]
}'

Read X-Sealarca-Receipt-ID and X-Sealarca-Receipt-URL from the response. The receipt becomes available after finalization and delivery; a 404 may be temporary. complete, interrupted and failed describe the observed exchange.

Shield receiptbash
# X-Sealarca-Receipt-ID / X-Sealarca-Receipt-URL / X-Sealarca-Proof-Profile
curl https://api.sealarca.ch/v1/vault/proofs/$RECEIPT_ID/bundle \
  -H "Authorization: Bearer $SEALARCA_API_KEY"
# JWKS: https://api.sealarca.ch/v1/vault/proofs/signing-keys
07

Consult the proof for a Vault inference

Every accepted Vault inference provides a receipt that links the response to the route and session verified by Sealarca.

Check before any execution

Before forwarding any request for execution, Sealarca checks that the trust environment and channel associated with the route meet Vault requirements. If this check fails or is unavailable, the inference is refused without fallback to an unprotected route. The Vault receipt then links the response to the verified route and session.

Inference and proof headersbash
curl -i https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Summarize this file.\"}"

Three headers to retain

The initial status is pending. Keep the receipt identifier and use the provided URL to consult the final verdict.

  • X-Sealarca-Vault-Receipt-ID
  • X-Sealarca-Vault-Proof-Status
  • X-Sealarca-Vault-Proof-URL
GET /v1/vault/proofs/{receiptId}bash
export SEALARCA_VAULT_PROOF_URL="<X-Sealarca-Vault-Proof-URL>"

curl "$SEALARCA_VAULT_PROOF_URL" \
  -H "Authorization: Bearer $SEALARCA_API_KEY"
sealarca-vault-proof/1json
{
  "schema": "sealarca-vault-proof/1",
  "receipt_id": "<receipt-id>",
  "status": "verified",
  "model": "<model-id>",
  "created_at": "<ISO-8601>",
  "updated_at": "<ISO-8601>",
  "verified_at": "<ISO-8601>",
  "expires_at": "<ISO-8601>",
  "admission": {
    "status": "verified",
    "checked_at": "<ISO-8601>",
    "attested_at": "<ISO-8601>",
    "expires_at": "<ISO-8601>",
    "evidence_digest": "sha256:<hex>",
    "keyset_digest": "sha256:<hex>"
  },
  "checks": [
    { "id": "attestation", "status": "verified" },
    { "id": "receipt", "status": "verified" }
  ],
  "hashes": {
    "request": "sha256:<hex>",
    "response": "sha256:<hex>",
    "request_received": "sha256:<hex>",
    "request_forwarded": "sha256:<hex>",
    "response_returned": "sha256:<hex>",
    "keyset": "sha256:<hex>",
    "evidence": "sha256:<hex>",
    "runtime": "sha256:<hex>"
  }
}

202 · pending

Verification is still in progress. Try again after a short delay.

200 · verified

Admission, the receipt, and the referenced Vault session satisfied the required checks.

200 · failed

The proof was not verified. Do not treat the result as verified.

404 / 410

404 means the proof is missing or inaccessible; 410 means it has expired.

503 · VAULT_VERIFICATION_UNAVAILABLE

Vault verification is unavailable. The inference is refused without falling back to unprotected execution.

The standard interface exposes the result of Sealarca’s verification. It is not a complete export of raw artifacts for independent cryptographic verification; access remains subject to the applicable contractual process.

Any active key belonging to the same user can consult their history. Never place an API key in the URL.

For streaming, the receipt is announced with the response; the final verdict becomes available after the stream ends.

Proofs are retained for 90 days and contain no prompt, response or API key.

Advanced Vault environment check

Provide a unique nonce of 64 lowercase hexadecimal characters to request a fresh, authenticated attestation.

GET /v1/vault/attestation?nonce=…bash
export SEALARCA_VAULT_NONCE="<64-lowercase-hex-characters>"

curl "https://api.sealarca.ch/v1/vault/attestation?nonce=$SEALARCA_VAULT_NONCE" \
  -H "Authorization: Bearer $SEALARCA_API_KEY"

sealarca-vault-attestation/1 schema

The standard response contains status, nonce, verification and expiry times, normalized checks, evidence, runtime and keyset digests, and the useful environment-key fingerprints. Complete artifacts remain restricted to contractually authorized audit export.

sealarca-vault-attestation/1json
{
  "schema": "sealarca-vault-attestation/1",
  "status": "verified",
  "nonce": "<64-lowercase-hex-characters>",
  "verified_at": "<ISO-8601>",
  "expires_at": "<ISO-8601>",
  "checks": [{ "id": "<check-id>", "status": "verified" }],
  "measurements": {
    "evidence": "sha256:<hex>",
    "runtime": "sha256:<hex>",
    "keyset": "sha256:<hex>"
  },
  "key_fingerprints": {
    "receipt_signing": ["sha256:<hex>"],
    "tls": ["sha256:<hex>"],
    "e2ee": ["sha256:<hex>"]
  }
}

Hash definitions

Each value is sha256: followed by the hexadecimal digest of the bytes observed in the Vault chain. request_received covers the body received by the environment, request_forwarded the body possibly transformed before the model, and response_returned the observed response bytes, including streams. After normalization or transformation, these bytes may differ from the client’s original HTTP bytes.

Signed bundle and offline verification

A terminal verified or failed proof is available as sealarca-vault-proof-bundle/1. Its payload is canonicalized under RFC 8785 and then signed as JWS with Ed25519. The public JWKS retains active and retired keys so an archived bundle can be checked after 90 days.

The signature guarantees the bundle’s integrity and Sealarca origin. It does not extend the attestation’s validity period and, by itself, is not an independent hardware verification.

GET /v1/vault/proofs/{receiptId}/bundle · sealarca-vault-proof-bundle/1bash
curl -f "$SEALARCA_VAULT_PROOF_URL/bundle" \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -o sealarca-vault-proof.jws.json

curl -f "https://api.sealarca.ch/v1/vault/proofs/signing-keys" \
  -o sealarca-vault-jwks.json
Offline Ed25519 verification with Node.jsjavascript
import { createHash, createPublicKey, verify } from "node:crypto";
import { readFileSync } from "node:fs";

const bundle = JSON.parse(readFileSync("sealarca-vault-proof.jws.json", "utf8"));
const jwks = JSON.parse(readFileSync("sealarca-vault-jwks.json", "utf8"));
const header = JSON.parse(Buffer.from(bundle.protected, "base64url"));
if (header.alg !== "EdDSA" || header.typ !== "sealarca-vault-proof+jws") throw new Error("Unexpected JWS algorithm");
const jwk = jwks.keys.find((key) => key.kid === header.kid);
if (!jwk || jwk.kty !== "OKP" || jwk.crv !== "Ed25519") throw new Error("Signing key not found or unsupported");
// Obtain this fingerprint independently from your current Sealarca contract/guide.
// Never trust a fingerprint received alongside an untrusted bundle.
const expected = process.env.SEALARCA_VAULT_JWK_SHA256;
if (!expected) throw new Error("Trusted JWK fingerprint required");
const thumbprint = createHash("sha256")
  .update(JSON.stringify({ crv: jwk.crv, kty: jwk.kty, x: jwk.x }))
  .digest("hex");
if ("sha256:" + thumbprint !== expected) throw new Error("Unexpected signing key");
const valid = verify(
  null,
  Buffer.from(bundle.protected + "." + bundle.payload),
  createPublicKey({ key: jwk, format: "jwk" }),
  Buffer.from(bundle.signature, "base64url"),
);
if (!valid) throw new Error("Invalid Vault proof signature");
console.log(JSON.parse(Buffer.from(bundle.payload, "base64url")));
503 · VAULT_PROOF_SIGNING_UNAVAILABLE
08

Endpoint reference

Minimal fields, output format, and streaming behavior for confirmed routes.

GET

/models

Confirmed

Request

No request body. Bearer token required.

Response

Key-scoped list containing the model IDs visible to that key.

POST

/responses

Confirmed

Required

model
input

Common

max_output_tokens
stream

Output

`response` object; SDKs expose `output_text`.

Required: `model` and `input`. Common documented fields: `max_output_tokens` (positive integer) and `stream` (boolean). Other fields are model-dependent and not part of this minimal contract.

POST /v1/responsesbash
export SEALARCA_API_KEY="YOUR_SEALARCA_API_KEY"
export SEALARCA_MODEL_ID="MODEL_ID_FROM_V1_MODELS"

curl https://api.sealarca.ch/v1/responses \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"input\":\"Summarize this confidential text in three points.\",\"max_output_tokens\":256}"
POST

/chat/completions

Confirmed

Required

model
messages

Common

max_tokens
stream

Output

choices[0].message.content

Required: `model` and `messages`. Common documented fields: `max_tokens` (positive integer) and `stream` (boolean). Other fields are model-dependent and not part of this minimal contract.

POST /v1/chat/completionsbash
curl https://api.sealarca.ch/v1/chat/completions \
  -H "Authorization: Bearer $SEALARCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"Summarize this file.\"}],\"max_tokens\":256}"
POST

/messages

Confirmed

Required

model
messages

Common

max_tokens
stream

Output

content

Required: `model`, `max_tokens`, and `messages`. `stream` enables SSE events. Other fields depend on the published contract.

POST /v1/messagesbash
curl https://api.sealarca.ch/v1/messages \
  -H "x-api-key: $SEALARCA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"$SEALARCA_MODEL_ID\",\"max_tokens\":256,\"messages\":[{\"role\":\"user\",\"content\":\"Summarize this file.\"}]}"
09

Errors and retry rules

Do not retry blindly. Fix deterministic 4xx errors and apply bounded backoff to temporary failures.

400
Cause
Invalid JSON, missing field, or unsupported parameter.
Action
Fix the request before retrying.
Retry
No, not unchanged
Retry-After
—
401
Cause
Missing, invalid, or revoked Bearer token.
Action
Check and replace the key.
Retry
No, not without a new key
Retry-After
—
402
Cause
Insufficient credit balance.
Action
Top up credits in the dashboard.
Retry
After top-up
Retry-After
—
403
Cause
The API key is not allowed to use the requested route or model.
Action
Check access and use a model ID returned for this key.
Retry
No, not without changing access or the request.
Retry-After
—
404
Cause
Unknown public route or model ID; model unavailability may also be reported as 503.
Action
Read `/models`, verify the path, and correct the model or route before retrying.
Retry
No, not unchanged
Retry-After
—
408
Cause
The gateway timed out before the request completed.
Action
Reduce input or output size, then retry with bounded backoff.
Retry
Yes, limited
Retry-After
When present
409
Cause
The request is temporarily unavailable.
Action
Wait briefly, then retry with bounded backoff.
Retry
Yes, limited
Retry-After
When present
422
Cause
A request parameter is invalid for the selected model.
Action
Check the documented fields and correct the request.
Retry
No, not unchanged
Retry-After
—
429
Cause
Rate limit or temporary capacity reached.
Action
Reduce concurrency and apply backoff.
Retry
Yes
Retry-After
Honor when present
500
Cause
Internal Sealarca service error.
Action
Retry with bounded backoff and retain the request or error ID.
Retry
Yes, limited
Retry-After
—
502
Cause
Invalid route response.
Action
Retry with bounded backoff.
Retry
Yes
Retry-After
When present
503
Cause
Selected model temporarily unavailable.
Action
Retry with a cap and use another model if necessary.
Retry
Yes
Retry-After
When present
504
Cause
The gateway timed out before the request completed.
Action
Reduce input or output size, then retry with bounded backoff.
Retry
Yes, limited
Retry-After
When present

Request ID. Every `/v1/` contract response includes an `x-request-id` header generated by Sealarca. An error body may also include a separate `(id=…)` identifier; retain both when present.

10

Operational best practices

These practices follow the current authentication, model access, billing, and request tracing behavior.

  • Protect the secret

    Load the API key from an environment variable or secret manager and rotate it if exposed.

  • Discover model IDs

    Call /v1/models with the same key and avoid hardcoding a model ID in deployed code.

  • Retry selectively

    Correct deterministic 4xx errors. Use bounded backoff for 429, 5xx, and gateway timeouts.

  • Keep request IDs

    Retain x-request-id and any error ID returned with a failure for support and diagnosis.

`store` and retention The public contract does not define `store` as a retention control. Do not rely on `store: false` instead of Sealarca's no-content-logging and no-response-cache guarantees; operational metadata remains subject to the applicable terms.
11

Credits and limits

The API uses prepaid CHF credits. The balance is checked before a request and usage is charged from the actual call.

No subscription required

The balance is funded through credit top-ups.

Per-model cost

Input and output may have different rates. The catalogue shows each model’s public prices.

HTTP 402

Top up the balance before retrying.

View models and prices
12

Continue with the right Sealarca page

Use these links for account access, model consumption, protections, and the technical service boundary.

Ready to integrate Sealarca?

Create access, discover a permitted model, and send your first server-side request.