SteelGaze API Guide

1. Base URL

All endpoints are prefixed with:

https://api.steelgaze.app/api/v1

2. Authentication

• Every request must include an API key in the Authorization header.
• Format: Authorization: Bearer <YOUR_API_KEY>
• Generate keys from Dashboard → API Keys. Store them securely – they’re shown once.

3. Content-Type

POST /predict expects text/plain containing the raw RFC-822 email (headers + body). JSON endpoints use application/json.

4. Endpoints

POST /predict — Analyze an email

Request body (text/plain): raw email MIME.

{
  "is_phishing": true,
  "confidence": 0.97,
  "explanations": {
    "roberta": { "sentences": [...], "tokens": [...] },
    "traditional": { "features": [...], "insights": [...] }
  }
}

POST /feedback — Report an incorrect result

POST /feedback
Content-Type: application/json
{
  "prediction_id": "abc123",
  "feedback": "This was actually safe."
}

5. Error Codes

• 401 — missing/invalid API key
• 415 — wrong Content-Type
• 429 — quota exhausted
• 5xx — server error (retry with back-off)

6. Plans & Limits

• Free trial: 50 predictions total
• Pro: 1000/month (resets each billing cycle)
• Enterprise: custom
• Rate limit: 30 req/min/key

7. Quick Examples

Curl

curl -X POST https://api.steelgaze.app/api/v1/predict   -H "Authorization: Bearer $STEELGAZE_KEY"   -H "Content-Type: text/plain"   --data-binary @email.eml

Node.js

import fs from 'fs/promises';
const email = await fs.readFile('email.eml', 'utf8');

const res = await fetch('https://api.steelgaze.app/api/v1/predict', {
  method: 'POST',
  headers: {
    'Content-Type': 'text/plain',
    Authorization: 'Bearer ' + process.env.STEELGAZE_KEY,
  },
  body: email,
});
console.log(await res.json());

Python

import requests, os, pathlib
email = pathlib.Path('email.eml').read_text()
resp = requests.post(
  'https://api.steelgaze.app/api/v1/predict',
  headers={
    'Authorization': f'Bearer {os.environ["STEELGAZE_KEY"]}',
    'Content-Type': 'text/plain',
  },
  data=email,
)
print(resp.json())

8. Best Practices

• Strip personal info you don’t want stored before sending.
• Handle 429 by backing off until quota resets.
• Never expose your API key client-side.

9. Changelog

• v1 – Initial release (/predict, /feedback)
• v2 – Webhooks & bulk upload (roadmap)