cURL Integration¶

This guide covers using SIX from the command line with cURL. Useful for testing, scripting, and CI/CD pipelines.

Prerequisites¶

Set your environment variables:

export SIX_API_KEY="your-api-key-here"
export SIX_ENDPOINT="https://six-sov.com"

Basic Inference Request¶

curl -X POST "$SIX_ENDPOINT/v1/chat/completions" \
  -H "Authorization: Bearer $SIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "user", "content": "What are HIPAA technical safeguards?"}
    ]
  }'

Response:

{
  "id": "six-abc123",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "HIPAA technical safeguards include..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 87,
    "total_tokens": 99
  },
  "receipt": {
    "receipt_id": "rcpt_f8c505ce3a...",
    "routing": "sovereign",
    "commitment": "04a7f3c2...e9b1d0f",
    "signature": "0x69c8...f98c8",
    "verified": true
  }
}

With Authentication Headers¶

API Key Only (Standard)¶

curl -X POST "$SIX_ENDPOINT/v1/chat/completions" \
  -H "Authorization: Bearer $SIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "user", "content": "Your prompt here"}
    ]
  }'

With Privacy Tier¶

curl -X POST "$SIX_ENDPOINT/v1/chat/completions" \
  -H "Authorization: Bearer $SIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "system", "content": "You are a compliance assistant."},
      {"role": "user", "content": "Summarize SOX Section 404"}
    ],
    "privacy_tier": "sovereign"
  }'

With All Optional Fields¶

curl -X POST "$SIX_ENDPOINT/v1/chat/completions" \
  -H "Authorization: Bearer $SIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "system", "content": "You are a compliance assistant."},
      {"role": "user", "content": "Summarize SOX Section 404"}
    ],
    "privacy_tier": "sovereign",
    "temperature": 0.3,
    "max_tokens": 500
  }'

Saving Receipts¶

Save Full Response¶

curl -s -X POST "$SIX_ENDPOINT/v1/chat/completions" \
  -H "Authorization: Bearer $SIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "user", "content": "What are HIPAA technical safeguards?"}
    ],
    "privacy_tier": "sovereign"
  }' | tee response.json

Extract and Save Receipt Only¶

Using jq to extract the receipt:

curl -s -X POST "$SIX_ENDPOINT/v1/chat/completions" \
  -H "Authorization: Bearer $SIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "user", "content": "What are HIPAA technical safeguards?"}
    ],
    "privacy_tier": "sovereign"
  }' | jq '.receipt' > receipt.json

Save with Dynamic Filename¶

RESPONSE=$(curl -s -X POST "$SIX_ENDPOINT/v1/chat/completions" \
  -H "Authorization: Bearer $SIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "user", "content": "What are HIPAA technical safeguards?"}
    ]
  }')

RECEIPT_ID=$(echo "$RESPONSE" | jq -r '.receipt.receipt_id')
echo "$RESPONSE" | jq '.receipt' > "receipts/${RECEIPT_ID}.json"
echo "Receipt saved: receipts/${RECEIPT_ID}.json"

Verifying Receipts¶

Verify by Receipt ID¶

curl -s "$SIX_ENDPOINT/v1/verify/rcpt_f8c505ce3a7b4d2e" \
  -H "Authorization: Bearer $SIX_API_KEY" | jq .

Response:

{
  "receipt_id": "rcpt_f8c505ce3a7b4d2e",
  "status": "verified",
  "receipt": {
    "receipt_id": "rcpt_f8c505ce3a7b4d2e",
    "routing": "sovereign",
    "commitment": "04a7f3c2...e9b1d0f",
    "signature": "0x69c8...f98c8",
    "verified": true
  },
  "attestation": {
    "integrity": "valid",
    "timestamp": "2025-01-15T14:32:00Z",
    "settlement": "anchored"
  },
  "verified_at": "2025-01-15T14:32:05Z"
}

Verify from Saved Receipt¶

RECEIPT_ID=$(jq -r '.receipt_id' receipt.json)

curl -s "$SIX_ENDPOINT/v1/verify/$RECEIPT_ID" \
  -H "Authorization: Bearer $SIX_API_KEY" | jq .

Check Verification Status Only¶

curl -s "$SIX_ENDPOINT/v1/verify/rcpt_f8c505ce3a7b4d2e" \
  -H "Authorization: Bearer $SIX_API_KEY" | jq '.status'

Output:

"verified"

Inference + Verify Pipeline¶

A single pipeline that makes an inference, saves the receipt, and verifies it:

#!/bin/bash
set -euo pipefail

# Make inference
echo "Making inference..."
RESPONSE=$(curl -s -X POST "$SIX_ENDPOINT/v1/chat/completions" \
  -H "Authorization: Bearer $SIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "user", "content": "What are HIPAA technical safeguards?"}
    ],
    "privacy_tier": "sovereign"
  }')

# Extract receipt ID
RECEIPT_ID=$(echo "$RESPONSE" | jq -r '.receipt.receipt_id')
echo "Receipt ID: $RECEIPT_ID"

# Save receipt
mkdir -p receipts
echo "$RESPONSE" | jq '.receipt' > "receipts/${RECEIPT_ID}.json"
echo "Receipt saved."

# Verify
echo "Verifying..."
VERIFY=$(curl -s "$SIX_ENDPOINT/v1/verify/$RECEIPT_ID" \
  -H "Authorization: Bearer $SIX_API_KEY")

STATUS=$(echo "$VERIFY" | jq -r '.status')
INTEGRITY=$(echo "$VERIFY" | jq -r '.attestation.integrity')
SETTLEMENT=$(echo "$VERIFY" | jq -r '.attestation.settlement')

echo "Status:     $STATUS"
echo "Integrity:  $INTEGRITY"
echo "Settlement: $SETTLEMENT"

if [ "$STATUS" = "verified" ]; then
  echo "PASS: Receipt verified successfully."
else
  echo "FAIL: Verification failed."
  exit 1
fi

Batch Operations¶

Verify Multiple Receipts¶

#!/bin/bash
set -euo pipefail

PASS=0
FAIL=0

for receipt_file in receipts/rcpt_*.json; do
  RECEIPT_ID=$(jq -r '.receipt_id' "$receipt_file")

  STATUS=$(curl -s "$SIX_ENDPOINT/v1/verify/$RECEIPT_ID" \
    -H "Authorization: Bearer $SIX_API_KEY" | jq -r '.status')

  if [ "$STATUS" = "verified" ]; then
    echo "PASS: $RECEIPT_ID"
    PASS=$((PASS + 1))
  else
    echo "FAIL: $RECEIPT_ID ($STATUS)"
    FAIL=$((FAIL + 1))
  fi
done

echo ""
echo "Results: $PASS passed, $FAIL failed"

Error Handling¶

Check for Errors¶

RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$SIX_ENDPOINT/v1/chat/completions" \
  -H "Authorization: Bearer $SIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "default",
    "messages": [
      {"role": "user", "content": "Your prompt"}
    ]
  }')

HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | head -n -1)

if [ "$HTTP_CODE" -ge 400 ]; then
  echo "Error ($HTTP_CODE):"
  echo "$BODY" | jq '.error'
  exit 1
fi

Handle Rate Limiting¶

make_request() {
  local retries=3
  local attempt=0

  while [ $attempt -lt $retries ]; do
    RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "$SIX_ENDPOINT/v1/chat/completions" \
      -H "Authorization: Bearer $SIX_API_KEY" \
      -H "Content-Type: application/json" \
      -d "$1")

    HTTP_CODE=$(echo "$RESPONSE" | tail -1)

    if [ "$HTTP_CODE" = "429" ]; then
      RETRY_AFTER=$(echo "$RESPONSE" | head -n -1 | jq -r '.error.retry_after // 5')
      echo "Rate limited. Waiting ${RETRY_AFTER}s..."
      sleep "$RETRY_AFTER"
      attempt=$((attempt + 1))
    elif [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
      echo "$RESPONSE" | head -n -1
      return 0
    else
      echo "Error ($HTTP_CODE)" >&2
      return 1
    fi
  done

  echo "Max retries exceeded" >&2
  return 1
}

Useful `jq` Filters¶

Purpose	Command
Extract AI response	`jq -r '.choices[0].message.content'`
Extract receipt	`jq '.receipt'`
Get receipt ID	`jq -r '.receipt.receipt_id'`
Check routing	`jq -r '.receipt.routing'`
Check verified	`jq '.receipt.verified'`
Get token usage	`jq '.usage'`
Pretty print	`jq .`

Next Steps¶

Python Integration -- For application-level integration
API Reference -- Complete endpoint documentation
Verification Guide -- Detailed verification walkthrough