Skip to content
☰
Documentation navigation +
betaMay change before the API is declared stable.

Manual sponsor pilot API

The M12 manual-program API is implemented behind ALIVE_SPONSOR_API_ENABLED=false by default. It returns SPONSOR_NOT_CONFIGURED (503) until the operator enables a reviewed pilot. This is not a live institutional offering. A separate default-disabled one-time checkout candidate can fund program pools. Paid plans, invitation issuance UI, broader enrollment abuse controls and final privacy/billing review remain pending. Manual funding is a service-only database operation.

Operator prerequisites

  • Apply the current migrations, including 20261013000001_sponsor_api.sql, in the intended environment. Git pushes/site deployments do not apply production database migrations.
  • Provision the institution and sponsor administrator assignments through the operator path. Program activation requires the institution's verified_at record; an API caller cannot self-assign that verification or administrator role.
  • Review the pilot's eligibility, reporting and operational terms before enabling the flag. Root AGENTS.md requires Isaac's sign-off for billing policy and privacy/security statements; implementation and default thresholds do not constitute that sign-off.
  • Fund the program through the existing service-only manual function after the grant is approved. No program create/status request issues credits, charges a card or chooses a monetary price.

Institution administration

Use an authenticated user-session JWT belonging to an assigned sponsor administrator. Organization-scoped API tokens are rejected for institution management. These endpoints operate on sponsor assignments rather than broad organization membership. Beneficiary redemption uses an organization admin with write scope and a token restricted to that organization where applicable.

Endpoint Body / result
GET /v1/sponsors/institutions Assigned institution ids/names/verification dates for draft creation; at most 200.
GET /v1/sponsors/programs?offset=0&limit=50 Assigned institution programs; limit is 1–200; follow next_offset.
POST /v1/sponsors/programs Create a draft program (example below).
GET /v1/sponsors/programs/{program_id} Program configuration and status.
POST /v1/sponsors/programs/{program_id}/status {"status":"active"} or {"status":"closed"}; closed programs cannot reopen.
POST /v1/sponsors/programs/{program_id}/members/decide {"org_id":"…","approve":true,"note":"…"} for a pending enrollment.
POST /v1/sponsors/programs/{program_id}/allocate {"org_id":"…","credits":100}; returns ledger transaction id.
GET /v1/sponsors/programs/{program_id}/report Fixed whole-program aggregation (below).
POST /v1/sponsors/redeem Beneficiary admin: {"org_id":"…","code":"…"}; returns pending/active enrollment status.

All POST requests require an Idempotency-Key. Keep it and the body unchanged after an ambiguous failure; a different body or endpoint needs a new key. Institutions have a separate sponsor-key replay scope; recipient redemption uses the existing organization-key scope. Mutation/replay records commit in the same transaction. Codes are not echoed in redemption responses; the replay hash uses a digest of the supplied code, rather than its redacted SecretStr representation.

Create-program example (identifiers/dates are placeholders; the credit cap is illustrative):

{
  "sponsor_id": "00000000-0000-0000-0000-000000000001",
  "name": "Innovation cohort",
  "ends_at": "2027-04-01T00:00:00Z",
  "per_recipient_cap": 100,
  "max_recipients": 50,
  "eligible_email_domains": ["university.edu"],
  "requires_approval": true,
  "report_min_cohort": 10
}

starts_at defaults to creation time; ends_at must be after the start and in the future. Email domains are normalized and must be full domains, without @; a matching domain alone does not prove student affiliation. Pending enrollment does not issue credits. Approval and allocation are separate actions. Allocation requires an active program within its date window, an active member, sufficient pool balance and room under the per-recipient cap. Enrollment decisions require a current active program. JSON credit inputs are bounded to the exact integer range supported by JavaScript (at most 9,007,199,254,740,991).

Redemption uses an operator-issued existing code, expiry/use limits and the program's eligibility rules. It is one redemption per person/program and per organization/program. Wrong/expired codes return NOT_FOUND; ineligible/full/inactive programs return VALIDATION_FAILED; duplicate enrollment returns CONFLICT. Scheduled programs cannot redeem/allocate before their start.

Reading reports

Reports expose one fixed program grouping. Below report_min_cohort active recipients, the response has suppressed: true, reason, pool_balance and credits_allocated; usage/recipient counts are omitted. The configured threshold defaults to 10 and cannot be less than 5.

Above the threshold, the response adds active_recipients, credits_used, credits_reserved and evaluations_funded. Used credits are settled sponsored consumption; reserved credits are still held for unfinished work. evaluations_funded counts distinct evaluation subjects with sponsored reservations, including failed/canceled attempts. It is not a count of completed evaluations, distinct innovations, interventions or clinical outcomes. No recipient filter or trace/result selection is accepted by this report endpoint.

Reporting thresholds are an implementation mechanism, not a blanket anonymity/security claim. Direct database cohort access and institutional enrollment/data-sharing terms require the remaining privacy review before a pilot is enabled. No beneficiary project/file/result is included in this API report shape.

Errors and current limits

Unauthenticated requests use 401. Missing assignments/inaccessible programs use 404; an organization token on institution endpoints uses 403. Activation before institution verification uses APPROVAL_REQUIRED; empty pools use QUOTA_EXCEEDED; cap/date/state failures use validation or conflict errors. See errors and limits.

Use the HTTP API reference for exact generated request schemas. Both SDKs can call these paths through their generic request surfaces. Dedicated client helpers, dedicated sponsor helpers, refund/subscription behavior and full hosted sponsor acceptance remain M12 work. One-time checkout has an operator reconciliation command. No monetary prices are chosen by this implementation.

App workspace

When the pilot is enabled, Settings shows invitation redemption for organization owners/admins. Enrollment confirmation distinguishes pending review from active enrollment and does not imply credits were allocated. The account card can copy the organization id for an approved roster. Assigned program administrators can open the institution program list from Settings, inspect fixed report counters and record pending-member decisions or funded allocations. The API supports closing programs; the UI now exposes assigned-institution draft creation and closure with the program name required for confirmation. Closed programs cannot reopen. Operator-issued invitation codes and an approved roster remain prerequisites; no affiliation verification is inferred from a matching email domain.

Forms retain the same key for an unchanged failed request and generate a new one for changed inputs. A completed action refreshes the server's state. Below the report threshold, usage cards show a dash and the suppression reason. Default-disabled environments show no invitation form or institution link. This workspace has not had an authenticated browser acceptance review.