Gateway

Headers

• x-pulse-conversationstring
  Continue an existing agent conversation (agent: addresses only). Omit to start a new one. An unknown id is a 404 conversation_not_found.

Request body

• modelstringdefault pulse-auto
  A model address. See Model addressing. Any other name is accepted, recorded in the certificate, and still routed.
• messagesobject[]required
  The conversation. Must be a non-empty array containing at least one user message.
  Show 4 properties
• streambooleandefault false
  Return Server-Sent Events. The proof id is in the response headers from the first byte.
• temperaturenumber
  Sampling temperature, forwarded to the model.
• max_tokensinteger
  Output ceiling. Values above the Gateway cap (16000 by default) are clamped instead of rejected, so agent loops do not fail. max_completion_tokens is accepted as an alias.
• toolsobject[]
  OpenAI function definitions. Their presence marks the call as agentic and routes it to the full model. Ignored on agent: addresses, which run the agent tools server-side.
• response_formatobject
  Set { "type": "json_object" } for JSON mode. Ignored on agent: addresses.

Request examples

curl https://api.subsidia.protypa.fr/v1/chat/completions \
  -H "Authorization: Bearer $SUBSIDIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pulse-auto",
    "messages": [
      {"role": "system", "content": "You are a careful legal assistant."},
      {"role": "user", "content": "Summarise the termination clause for Jean Dupont."}
    ]
  }'

Responses

A chat.completion object plus a pulse block. Headers: x-pulse-proof (certificate id), x-pulse-provider (ollama, openai...), x-pulse-pii-masked (number of values masked), and x-pulse-conversation for agent: calls. With stream: true the body is text/event-stream of chat.completion.chunk events ending with data: [DONE]; only x-pulse-proof is sent as a header, and the final chunk carries usage plus a pulse block (proof, conversation) for agent: calls only. The certificate is persisted before [DONE].

{
  "id": "chatcmpl-pf_a059713a5f1c4e0b8d7a3c21e9b64f10",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Either party may terminate with 30 days written notice..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 53, "completion_tokens": 38, "total_tokens": 91 },
  "pulse": {
    "proof": "pf_a059713a5f1c4e0b8d7a3c21e9b64f10",
    "provider": "openai",
    "task": "chat",
    "pii_masked": 1
  }
}

Errors

• 401No key, wrong key, revoked or expired key. Body: { "error": "..." }.
• 402insufficient_quotaThe workspace allowance is exhausted.
• 402API_KEY_BUDGET_EXCEEDEDThe key reached its own monthly question ceiling.
• 403scope_deniedThe key does not carry the engine scope.
• 429rate_limitedThe key exceeded its requests-per-minute limit. Honour retry-after.

Notes

Request body

• modelstringdefault pulse-auto
  A model address.
• messagesobject[]required
  Anthropic messages. Content may be a string or an array of content blocks.
• systemstring | object[]
  System prompt, as a string or text blocks.
• max_tokensinteger
  Output ceiling, clamped to the Gateway cap.
• temperaturenumber
  Sampling temperature.
• toolsobject[]
  Anthropic tool definitions (name, description, input_schema).
• streambooleandefault false
  Return Server-Sent Events.

Request examples

curl https://api.subsidia.protypa.fr/v1/messages \
  -H "x-api-key: $SUBSIDIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pulse-auto",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Summarise the termination clause."}]
  }'

Responses

A message object with Anthropic content blocks (text, tool_use). The certificate id is in the x-pulse-proof header.

Errors

• 401Missing, invalid or revoked key.
• 404not_found_errorThe agent:<slug> address matches no agent.
• 501invalid_request_errordebate: addresses are not served here.

Notes

Request body

• messagesobject[]required
  Same shape as POST /v1/messages.
• systemstring | object[]
  System prompt.
• toolsobject[]
  Tool definitions, counted as serialised JSON.

Request examples

curl https://api.subsidia.protypa.fr/v1/messages/count_tokens \
  -H "x-api-key: $SUBSIDIA_API_KEY" -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"How long is this?"}]}'

Responses

The estimate.

{ "input_tokens": 6 }

Request examples

curl https://api.subsidia.protypa.fr/v1/models -H "Authorization: Bearer $SUBSIDIA_API_KEY"

Responses

An OpenAI-style list.

{
  "object": "list",
  "data": [
    { "id": "pulse-auto", "object": "model", "created": 1790000000, "owned_by": "pulse-gateway" },
    { "id": "pulse-sensitive", "object": "model", "created": 1790000000, "owned_by": "pulse-gateway" },
    { "id": "pulse-agent", "object": "model", "created": 1790000000, "owned_by": "pulse-gateway" },
    { "id": "agent:demo-cfo", "object": "model", "created": 1790000000, "owned_by": "pulse-agents" }
  ]
}

Path parameters

• idstringrequired
  The value of the x-pulse-proof header, pf_ followed by 32 hex characters.

Request examples

curl https://api.subsidia.protypa.fr/v1/proofs/pf_a059713a5f1c4e0b8d7a3c21e9b64f10 \
  -H "Authorization: Bearer $SUBSIDIA_API_KEY"

Responses

The certificate: id, chain_index, prev_hash, payload, payload_hash, signature, algorithm, hash, created_at.

Path parameters

• idstringrequired
  Certificate id.

Request examples

curl https://api.subsidia.protypa.fr/v1/proofs/$PROOF_ID/verify -H "Authorization: Bearer $SUBSIDIA_API_KEY"

Responses

valid is true only when both the signature and the chain link hold.

{
  "id": "pf_a059713a5f1c4e0b8d7a3c21e9b64f10",
  "signature_valid": true,
  "chain_valid": true,
  "valid": true,
  "reason": null
}

Request examples

curl https://api.subsidia.protypa.fr/v1/gateway/public-key

Responses

The key in SPKI PEM format.

{ "algorithm": "Ed25519", "format": "spki-pem", "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n" }