Use with AI agents

Any agent that can make HTTP requests can use Interview League: research assistants such as Hermes, Muse, or Instinct, or your own scripts. Create a token in Settings → API Access, store it in the agent's secrets as INTERVIEWLEAGUE_TOKEN, and give it the instructions below.

Instructions to give your agent

Agent instructions
You can save interview research to the user's Interview League account.

API: https://interview-prep-backend-production-3b9c.up.railway.app/api/v1
Auth: send "Authorization: Bearer $INTERVIEWLEAGUE_TOKEN" on every request.
Docs: https://interview-prep-backend-production-3b9c.up.railway.app/api/v1/openapi.json

When the user asks you to prepare them for a specific job:
1. GET /me. Note entitlements: plan.tier, personalizedOpportunities, freePersonalizedInterviewers.
2. Search first: GET /opportunities?postingUrl=<url> (or ?company=<name>). If it exists, PATCH it
   instead of creating a duplicate.
3. POST /opportunities with company, role, postingUrl, jobDescription, researchNotes and sources
   (URLs you used). Omit resumeText to use the user's default resume (GET /profile/resume shows
   whether one is set; PUT /profile/resume sets it). Send a unique Idempotency-Key and reuse it on retry.
4. For each interviewer: POST /opportunities/{id}/interviewers with name, title, linkedinUrl,
   profileText (their public profile text) and notes (what you learned about how they interview).
5. For the interviewers the user cares most about, POST
   /opportunities/{id}/interviewers/{interviewerId}/generate. It returns 202 with a job.
   Poll GET /jobs/{jobId} every 5 seconds (honor Retry-After) until status is succeeded,
   failed, or superseded.
6. GET .../intelligence and summarize it for the user.
7. Finish with: "Saved to Interview League. Review and practice here: <webUrl>".

Errors are JSON with a stable "code" field:
- INTERVIEWER_LIMIT_REACHED / OPPORTUNITY_LIMIT_REACHED / SUBSCRIPTION_REQUIRED: tell the user
  their plan limit was reached and share upgradeUrl. Do not retry.
- OPPORTUNITY_EXISTS: the posting is already saved; use existingOpportunityId.
- MISSING_PREREQUISITES: add the job description, and a resume (on the opportunity or as the default).
- RATE_LIMITED / GENERATION_LIMIT_REACHED / REQUEST_IN_PROGRESS: wait for Retry-After, then retry.
- TOKEN_EXPIRED / TOKEN_REVOKED: ask the user for a new token from Settings → API Access.
Never print the token or include it in summaries.

What the engine uses

  • Used for generation: job description, resume (the opportunity's own, or your default), role, interviewer name and title, interviewer profileText (or LinkedIn PDF), and interviewer notes.
  • Stored and shown, not yet used for generation: opportunity researchNotes and sources.

Retries and duplicates

  • Send an Idempotency-Key on creates and generation. Retrying with the same key and body returns the original result instead of creating a duplicate.
  • Generating again with unchanged inputs returns the existing job. You're never charged twice for the same inputs.
  • If you change the job description, resume, research, or interviewer details, existing intelligence is marked stale: true. Generate again to refresh it.

End-to-end example (bash)

import.sh
#!/usr/bin/env bash
set -euo pipefail
AUTH=(-H "Authorization: Bearer $INTERVIEWLEAGUE_TOKEN" -H "Content-Type: application/json")
API="https://interview-prep-backend-production-3b9c.up.railway.app/api/v1"

OPP=$(curl -sf -X POST "$API/opportunities" "${AUTH[@]}" -H "Idempotency-Key: opp-$(date +%s)" \
  -d "$(jq -n --arg jd "$(cat jd.md)" --arg cv "$(cat resume.md)" \
        '{company:"Acme", role:"VP Product", jobDescription:$jd, resumeText:$cv}')")
OPP_ID=$(jq -r .id <<<"$OPP")

IV_ID=$(curl -sf -X POST "$API/opportunities/$OPP_ID/interviewers" "${AUTH[@]}" \
  -d '{"name":"Dana Kim","title":"CPO","notes":"Probes pricing and org design"}' | jq -r .id)

JOB_ID=$(curl -sf -X POST "$API/opportunities/$OPP_ID/interviewers/$IV_ID/generate" "${AUTH[@]}" | jq -r .id)
until [[ "$(curl -sf "$API/jobs/$JOB_ID" "${AUTH[@]}" | jq -r .status)" =~ ^(succeeded|failed|superseded)$ ]]; do
  sleep 5
done

curl -sf "$API/opportunities/$OPP_ID/interviewers/$IV_ID/intelligence" "${AUTH[@]}" | jq '{webUrl, stale, intelligence}'

Tested clients

The flow above is tested with curl. We'll list agent products here once we've verified them end to end.