Connect to Helpable

Build a doctor-office intake, a community kiosk, an interview recorder, or an AI helper on top of the Helpable mutual-aid network. Get a key in 30 seconds — no email gate, no credit card.

1 · Get a key

One POST. The key is returned immediately — send it on every agent call as X-API-Key or Authorization: Bearer.

# register your integrator
curl -X POST https://helpable.org/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "My Clinic Intake",
    "agent_type": "doctor_office",
    "app_name": "City Clinic",
    "app_url": "https://clinic.example",
    "sandbox": true
  }'

Response:

{
  "id": "4c78a621-…",
  "api_key": "hb_c8649e53…",   // keep this secret
  "api_key_prefix": "hb_c8649e53…78b6",
  "sandbox": true
}

2 · The flow

3 · The interview pattern (Your Last Prayer)

The documentary film Your Last Prayer is the reference integrator — a question-driven recorder that speaks this exact API. Steal its pattern:

// 1. upload the recording
const fd = new FormData();
fd.append('file', blob, 'answer.webm');
const media = await fetch('/v1/media', { method: 'POST', body: fd }).then(r => r.json());

// 2. create the request with interview context
const req = await fetch('/v1/help/request', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Interview answer: ' + question.kicker,
    description: question.text,
    category: 'last_prayer',
    media_ids: [media.id]
  })
}).then(r => r.json());

// 3. let the AI listen & extract needs
const analysis = await fetch('/v1/media/' + media.id + '/analyze', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ request_id: req.id, context: 'question ' + question.id })
}).then(r => r.json());
// → analysis.transcript, analysis.analysis.needs[]

4 · SDKs

Official clients that wrap the whole flow:

# pip install helpable  (or copy sdk/python/helpable.py)
from helpable import Helpable

client = Helpable("https://helpable.org", api_key="hb_...")  # key optional

media  = client.upload("interview.webm")
req    = client.create_request("Medical help", category="last_prayer", media_ids=[media["id"]])
result = client.analyze(media["id"], request_id=req["id"])
print(result["transcript"])
for need in result["analysis"]["needs"]:
    print(need["type"], need["description"])

// <script src="https://helpable.org/sdk/helpable.js"></script>
const client = new Helpable({ apiKey: 'hb_...' });  // key optional

const media  = await client.upload(blob);
const req    = await client.createRequest('Medical help', { category: 'last_prayer', mediaIds: [media.id] });
const result = await client.analyze(media.id, { requestId: req.id });
console.log(result.transcript);
result.analysis.needs.forEach(n => console.log(n.type, n.description));

# upload
MEDIA=$(curl -X POST https://helpable.org/v1/media -F "file=@recording.webm" | jq -r .id)

# create request
REQ=$(curl -X POST https://helpable.org/v1/help/request \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"Need help\",\"category\":\"last_prayer\",\"media_ids\":[\"$MEDIA\"]}" | jq -r .id)

# analyze (transcribe + extract needs)
curl -X POST https://helpable.org/v1/media/$MEDIA/analyze \
  -H "Content-Type: application/json" \
  -d "{\"request_id\":\"$REQ\"}"

5 · Endpoints you'll use

Full reference: /docs (interactive) · /openapi.json (machine-readable, generated from the live API).

6 · Good citizenship

Questions?

Read INTEGRATION.md in the repo, open an issue, or email hello@helpable.org. Built for all life — by all life.