Feedback Flows API

Getting started

1. Get a key (see below). Store it as a secret; it is shown once.
2. Send it on every request: X-API-Key: YOUR_KEY.
3. Call GET /account/status to confirm the key and remaining credits.
4. Call a cheap analysis endpoint, or list students, then move on to jobs.

How to get a key

• Site admin still issues keys at /admin/api-keys (the existing flow). Use this for non-enterprise integrators and onboarding sandbox keys.
• Enterprise Owners and Managers with the Integrations feature enabled can issue, scope, rotate and revoke keys for their own organisation on the console Integrations tab. Site admin still sees every key.
• Keys are hashed at rest. Copy the secret immediately; we cannot show it again.
• Sandbox keys skip billing and return canned responses for AI and job endpoints, so you can wire an integration without spending credits.

Scopes on a key: marking, integrity, analytics, media, admin. The admin scope implies the others. A missing scope returns 403 with SCOPE_FORBIDDEN.

First call

curl -X GET 'https://feedbackflows.org/api/v1/account/status' \
  -H 'X-API-Key: YOUR_API_KEY'

import requests

r = requests.get(
    "https://feedbackflows.org/api/v1/account/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(r.status_code, r.json())

Credits, limits, and idempotency

• Usage is billed in credits against the account that owns the key. credits_remaining of -1 means unlimited.
• Synchronous routes: 60 requests per minute per key. Job submissions: 10 per hour. A 429 includes Retry-After. Rejected calls are not counted.
• Async job POSTs accept an Idempotency-Key header. Retry the same key for 24 hours and you get the original 202 instead of a second charge.
• JSON responses include a request_id you can quote to support.

Try it

Paste a key and send a real request from this page. Live keys spend credits; use a sandbox key while you are wiring things up. The key is kept in sessionStorage in this browser only.

{ }

Dedicated testers

Standalone pages with forms for ZIP uploads and longer workflows. Each page can be downloaded and run against production or a local server.

API v2 testers: style comparison · cost estimate · exports · AI tutor jobs · worksheet jobs · reference-check jobs · interactive-feedback jobs

Marking

Integrity

Jobs

LMS / data

Endpoint reference

Paths below are relative to https://feedbackflows.org/api/v1. Field names match the live handlers.

Account

{
  "business_name": "Northbridge College",
  "api_key_status": "active",
  "credits_remaining": 985
}

Marking

{
  "student_text": "The industrial revolution was a turning point...",
  "marking_criteria": ["Clarity of argument", "Use of evidence"]
}

{
  "essay_text": "The full essay...",
  "marking_criteria": ["Clarity of argument", "Use of evidence"]
}

Integrity

Jobs

All create endpoints return 202 with job_id and a status path. Optional callback_url (HTTPS) and Idempotency-Key header apply unless noted. ZIP bodies use zip_base64.

{
  "student_id": 41,
  "template_id": 3,
  "selected_result_refs": [
    {"kind": "auto", "id": 120},
    {"kind": "rubric", "id": 88}
  ],
  "callback_url": "https://example.edu/hooks/feedback-flows"
}

Exports

Illustrative credit costs

Defaults: style comparison 1/file; rubric and automarking 10/student; media 20; exam 5/student; learner pack 3; smart essay 10; AI detector 1; worksheet 3; reference check 5. Server configuration may override these values.

Roster and results

{
  "add_student_ids": [41, 42],
  "remove_student_ids": [17]
}

Also: GET /classes/{class_id}/assignments, GET /question-templates, GET /students/{id}/ai-history, POST /students/{id}/progress-report, POST /classes/{id}/assignments/{id}/analyze (analytics scope).

List endpoints accept ?page=, ?per_page=, and ?search=.

Webhooks

Pass callback_url when you create a job. When the job finishes we POST JSON to that URL.

• Header X-FeedbackFlows-Signature in the form t=<unix>,v1=<hex>.
• HMAC-SHA256 over <timestamp>.<raw-body> using the key’s webhook secret.
• Reject deliveries whose timestamp is more than five minutes old. That is what stops a captured request being replayed.
• Header X-FeedbackFlows-Delivery is a UUID; use it to ignore retries.
• Callback URLs must be public HTTPS. We re-resolve DNS at delivery time and refuse private or loopback addresses.

import hashlib, hmac, time

def verify(header, raw_body, secret, tolerance=300):
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    timestamp = int(parts["t"])
    if abs(time.time() - timestamp) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(parts["v1"], expected)

Errors

Error bodies are JSON: error, code, status, request_id. They are never HTML.