API reference

The custom GraphQL operations at /api/graphql, with access, effects, and errors.

GraphQL is served at /api/graphql by GraphQL Yoga with Keystone. Custom operations are in features/keystone/mutations. Most return a JSON scalar named AgencyJSON. See schema.graphql for the full schema.

Errors from custom operations are masked. The API returns "Unexpected error." to the client and logs the real message on the server. The dashboard shows a short message for known cases.

Idempotency

Every money or status command takes an idempotencyKey. Reuse the key to retry. Reusing a key with different arguments is refused. A completed key returns the stored result.

Staff commands

All need a signed-in user with the permission shown, and access to the athlete.

OperationPermissionEffect
signRepresentationAgreement(agreementId)canManageContractsdraft or sent to signed. Refuses a rate above the cap or a clash with another active agreement
recordContractSigned(contractId)canManageContractsnegotiating to signed. Needs an active playing agreement. Snapshots the rate
generatePaymentSchedule(contractId, dealId, idempotencyKey)canManageCommissionsPass one of the two ids. Creates scheduled payments, skipping existing periods
markPaymentReceived(scheduledPaymentId)canManageCommissionsscheduled or late to received. Posts an accrual entry
draftCommissionInvoice(athleteId, scheduledPaymentIds)canManageCommissionsCreates a draft invoice and snapshot lines from received, uninvoiced payments in one currency
sendCommissionInvoice(invoiceId)canManageCommissionsdraft to sent
voidCommissionInvoice(invoiceId, reason)canManageCommissionsdraft or sent with no payments to void. Frees its payments
recordInvoicePayment(invoiceId, amountCents, reference)canManageCommissionsPosts a receipt and agent splits. Moves to partially_paid or paid
reverseLedgerEntry(entryId, reason)canManageCommissionsPosts an exact reversal, once
writeOffCommissionInvoice(invoiceId, reason, approvalId)canManageCommissionsApproval required. Posts a write_off entry and moves to written_off
postTrustEntry(accountId, entryType, amountCents, reference, invoiceId, reversesId)canManageTrustPosts a trust entry. Balance never goes below zero
moveRecruitingStage(athleteId, stage)canManageAthletesChanges the stage. Refuses before the contact window opens
completeDeliverable(deliverableId, proofLink)canManageEndorsementsscheduled or missed to completed. HTTPS proof link required
activateEndorsementDeal(dealId, approvalId)canManageEndorsementsActivates. Blocks on an exclusivity clash unless a valid approval is given
requestManagerApproval(actionType, targetId, amountCents, reason)By action typeFiles a request. Expires in one hour
decideManagerApproval(approvalId, decision)canApproveActionsapproved or rejected. Not the requester
generateAutoTaskscanManageAthletesCreates reminder tasks once per record

Query:

OperationEffect
checkEndorsementConflicts(athleteId, category, start, end)Returns clashing signed or active deals for the term

Public operations

No sign-in is needed for the roster, athlete, inquiry, and lookup operations. Invoice operations need the proof described in Public site and invoice payment.

OperationTypeNeeds
agencyNameQueryNothing
agencyRosterQueryNothing. Published clients only
agencyAthlete(athleteId)QueryNothing. Published clients only
submitInquiry(...)MutationNothing. Creates a contact, an interaction, and a task
lookupInvoice(email, number)QueryMatching email and number. Returns a proof
guestInvoice(invoiceId, proof)QueryThe proof, or the owning signed-in client
payCommissionInvoice(invoiceId, proof, idempotencyKey)MutationThe proof. Returns the Stripe client secret
confirmCommissionPayment(paymentId, proof)MutationThe proof. Verifies with Stripe and posts the receipt

Client portal queries

myAthleteSummary, myDeliverables, and myInvoices need a signed-in user who is the portalUser of an athlete. They return that athlete's contracts, deals, deliverables, and sent or paid invoices.

Setup

OperationNeeds
ensureOnboardingRecord(entity, data)canManageOnboarding
updateActiveUser(data)Signed in. Only email, name, phone, password, onboardingStatus
redirectToInitQuery. true when there are no users

Auth

authenticatedItem, authenticateUserWithPassword, createInitialUser, createUser, sendUserPasswordResetLink, validateUserPasswordResetToken, redeemUserPasswordResetToken, endSession.

Generated CRUD

Generated queries exist for every list, filtered by list access and athlete scope. Money lists have no generated create or delete. Example:

query {
  commissionInvoices(where: { status: { in: [sent, partially_paid] } }, take: 20) {
    number
    status
    totalCents
    paidCents
    athlete { fullName }
  }
}

A command example:

mutation {
  markPaymentReceived(scheduledPaymentId: "...", idempotencyKey: "payment-received-001")
}

The dashboard uses KsFetchAdminMeta, KsFetchItem, and GetListItems for the generic screens.

On this page