API Documentation

Authentication

Pass your API key as a Bearer token in the Authorization header. Keys begin with cruc_ and are shown once at generation time.

Authorization: Bearer cruc_YOUR_KEY_HERE

Keep your key secret. Revoke and regenerate it from your account page if compromised. Each API call consumes one session from your monthly allocation.

Endpoint

Runs your question through the multi-stage analysis pipeline and streams the result as Server-Sent Events (SSE).

Request Body

Content-Type: application/json

Response (SSE Stream)

The response is a text/event-stream. Each event is a JSON object on a data: line.

data: {"type":"phase_start"}
data: {"type":"phase_complete"}
data: {"type":"phase_start"}
data: {"type":"phase_complete"}
data: {"type":"phase_start"}
data: {"type":"phase_complete"}
data: {"type":"phase_start"}
data: {"type":"phase_complete"}
data: {"type":"session_complete","revelationId":"uuid","output":"...","liveDataUsed":false}

Output Shape

The session_complete event has these fields:

{
  "type":          "session_complete",
  "revelationId":  "uuid — store this to retrieve the revelation later",
  "output":        "string — the full analysis as markdown text",
  "liveDataUsed":  "boolean — true if web search was used in this session"
}

output is a plain markdown string, not a structured object. If live web search was active and sources were used, the output ends with a ◈ Sources: line listing the domains consulted.

Example — curl

curl -X POST https://thecrusible.systems/api/crucible \
  -H "Authorization: Bearer cruc_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"question": "Should I expand into a new market this year?"}' \
  --no-buffer

Example — JavaScript (SSE)

const response = await fetch('https://thecrusible.systems/api/crucible', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer cruc_YOUR_KEY_HERE',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    question: 'Should I expand into a new market this year?',
    supportingContext: 'We are a 12-person SaaS company, 3 years old, profitable.',
  }),
})

const reader = response.body.getReader()
const decoder = new TextDecoder()
let buffer = ''

while (true) {
  const { done, value } = await reader.read()
  if (!done) buffer += decoder.decode(value)

  const lines = buffer.split('\n')
  buffer = done ? '' : lines.pop()

  for (const line of lines) {
    if (!line.startsWith('data: ')) continue
    const event = JSON.parse(line.slice(6))

    if (event.type === 'session_complete') {
      console.log(event.output)        // full markdown string
      console.log(event.liveDataUsed)  // boolean
    }
  }

  if (done) break
}

Error Codes