This documentation is the product. There is no playground. There is no chat UI. If you want to evaluate HermesBridge, run the quickstart against a sandbox identity.

POST /v1/chat/completions

Primary completion endpoint. OpenAI-compatible request shape with two additions: the X-Hermes-Signature header and an extended usage block in the response.

Request

POST /v1/chat/completions HTTP/1.1
Host: api.hermesbridge.ai
Content-Type: application/json
X-Hermes-Signature: v1.<base64url(payload)>.<base64url(signature)>

{
  "model": "claude-sonnet-4",
  "messages": [
    {
      "role": "system",
      "content": "You are a concise technical assistant."
    },
    {
      "role": "user",
      "content": "Explain the difference between Ed25519 and ECDSA P-256."
    }
  ],
  "max_tokens": 1024,
  "temperature": 0.3,
  "routing": {
    "cost_ceiling_usd": 0.10,
    "latency_target_ms": 3000
  }
}

Request body fields

field	type	description
model	string	Model ID, or a routing mode keyword (auto, cheapest, fastest, balanced, capability:<x>).
messages	array	OpenAI-compatible message array. Standard roles: system, user, assistant, tool.
max_tokens	integer	Maximum tokens in the completion. Optional.
temperature	float	Sampling temperature 0–2. Optional, default 1.0.
routing	object	HermesBridge routing constraints. Optional. See routing fields below.
stream	boolean	Stream the response via SSE. Optional, default false.

Response

The response follows the OpenAI chat completion shape. The usage block includes HermesBridge-specific fields: agent_did, attestation_tier, cost_usd, discount_applied, and cache_hit.

HTTP/1.1 200 OK
Content-Type: application/json
X-Hermes-Request-ID: 01J8XMVK2P4Q7R9STWYZ3ABCDE
X-Hermes-Cache: MISS
X-Hermes-Latency-Ms: 847

{
  "id": "chatcmpl-01J8XMVK2P4Q7R9STWYZ3ABCDE",
  "object": "chat.completion",
  "created": 1748952847,
  "model": "claude-sonnet-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Ed25519 uses the Edwards25519 curve..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 318,
    "total_tokens": 360,
    "agent_did": "did:hermes:0x7a3f9b2e4c1d8a6f",
    "attestation_tier": "runtime-signed",
    "cost_usd": 0.00591,
    "discount_applied": 0.15,
    "cache_hit": false
  }
}

Error response

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "type": "authentication_error",
    "code": "SIGNATURE_INVALID",
    "message": "Signature verification failed for key primary on DID did:hermes:0x7a3f...",
    "request_id": "01J8XMVK2P4Q7R9STWYZ3ABCDE"
  }
}

See Error taxonomy for all error codes.