TalentSprout API

Create interviews programmatically and get a candidate-ready share link in a single request. Manual, template-based, or fully AI-generated from a job description.

Quick start#

curl https://www.talentsprout.ai/api/v1/interviews/from-job-description \
  -H "Authorization: Bearer $TALENTSPROUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_description": "We are hiring a Senior Product Designer to lead the redesign of our enterprise dashboard..."
  }'

{
  "id": "f8a4b2c1-9e3d-4f5a-b6c7-d8e9f0a1b2c3",
  "object": "interview",
  "title": "Senior Product Designer",
  "share_link": "https://www.talentsprout.ai/interview/f8a4b2c1-9e3d-4f5a-b6c7-d8e9f0a1b2c3",
  "questions": [
    { "question": "Walk us through a recent design system you shipped end-to-end." },
    { "question": "How do you balance user research with shipping velocity?" }
  ],
  "status": "active",
  "voice": "alloy",
  "languages": ["en"],
  "duration": 15,
  "passing_score": 70,
  "ai_generation": {
    "model": "gpt-4o-mini",
    "generated_at": "2026-05-08T10:24:11.421Z"
  },
  "created_at": "2026-05-08T10:24:11.421Z"
}

Authentication#

Every v1 request must include an API key in the Authorization header using the Bearer scheme. Keys are scoped to a single organization.

curl https://www.talentsprout.ai/api/v1/ping \
  -H "Authorization: Bearer tsk_aB3xKp9q..."

Key format#

• Tokens start with tsk_ followed by 32 random base62 characters (~190 bits of entropy).
• The full token is shown once, at creation time. Store it as a server-side secret -- we keep only a SHA-256 hash and the first 12 characters (the “display prefix”).
• Lost a key? Revoke it from the dashboard and create a new one.

Operations#

Operational details we want every integration to know up front. None of these are required reading for your first request, but they’ll save you debugging time once you’re in production.

Environments#

TalentSprout has no separate test mode. API calls operate against your live data, but creating an interview is free and only billable when a candidate completes a session. If you need an isolated environment, create a dedicated organization (e.g. “Acme — Staging”) and issue keys there.

Idempotency & retries#

v1 does not yet support an Idempotency-Key header. To safely retry a POST after a network failure, deduplicate on your side using your own request ID, or check for duplicates before retrying. Retrying a successful request will create a duplicate interview. Retries on 5xx responses are safe with exponential backoff (e.g. 1s, 2s, 4s, capped at 30s).

Request IDs#

Every response includes an X-Request-Id header (also echoed in error envelopes as request_id). Log it on every call — including this ID in support requests is the fastest way for us to trace what happened.

Client libraries#

We don’t ship official SDKs yet. The API is plain JSON over HTTPS and works with any HTTP client — every example on this page uses fetch (Node 18+) or requests (Python). If you’d like a first-party SDK in a specific language, let us know.

Using this API from an AI assistant#

Want Claude, ChatGPT, Cursor, or Cline to call this API for you? Use the TalentSprout MCP server — same tsk_* API key, same rate limits, same data. The MCP surface exposes a tool per endpoint on this page so an LLM can create interviews from natural language.

Rate limits#

Limits are applied per organization, per minute, on a sliding window. Every response includes the standard headroom headers.

Response headers#

When you receive a 429 rate_limit_exceeded, wait the number of seconds in Retry-After before retrying. Need higher limits? Contact us.

Errors#

Errors return a JSON envelope with stable type and code fields, a human-readable message, and a request_id to include in any support request. Every error response also includes a docs_url that deep-links to the matching code in the table below.

{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "Required",
    "param": "questions",
    "request_id": "req_2f9a3b1c4d5e6f7a8b9c0d1e",
    "docs_url": "https://www.talentsprout.ai/docs/api-reference#error-invalid_request"
  }
}

Endpoints#

curl https://www.talentsprout.ai/api/v1/ping \
  -H "Authorization: Bearer $TALENTSPROUT_API_KEY"

curl https://www.talentsprout.ai/api/v1/interviews \
  -H "Authorization: Bearer $TALENTSPROUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Product Designer",
    "job_description": "We are hiring a Senior Product Designer...",
    "questions": [
      { "question": "Walk us through a recent design system you shipped end-to-end." },
      { "question": "How do you balance research with shipping velocity?" }
    ],
    "voice": "alloy",
    "languages": ["en"],
    "passing_score": 75
  }'

curl https://www.talentsprout.ai/api/v1/interviews \
  -H "Authorization: Bearer $TALENTSPROUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Product Designer (Acme)",
    "template_id": "f8a4b2c1-9e3d-4f5a-b6c7-d8e9f0a1b2c3",
    "company_name": "Acme",
    "passing_score": 80
  }'

curl https://www.talentsprout.ai/api/v1/interviews/from-job-description \
  -H "Authorization: Bearer $TALENTSPROUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_description": "We are hiring a Senior Product Designer to...",
    "languages": ["en"],
    "passing_score": 75
  }'

The interview object#

All endpoints that return an interview return the same shape.

{
  "id": "f8a4b2c1-9e3d-4f5a-b6c7-d8e9f0a1b2c3",
  "object": "interview",
  "title": "Senior Product Designer",
  "job_description": "We are hiring a Senior Product Designer...",
  "questions": [
    { "question": "Walk us through a recent design system you shipped." },
    { "question": "How do you balance research with shipping velocity?" }
  ],
  "company_name": "Acme",
  "client_name": "",
  "template_id": null,
  "share_link": "https://www.talentsprout.ai/interview/f8a4b2c1-...",
  "status": "active",
  "voice": "alloy",
  "languages": ["en"],
  "duration": 15,
  "require_video": false,
  "max_attempts": 999,
  "passing_score": 70,
  "access_type": "public",
  "redirect_url": null,
  "ai_personality": "professional",
  "created_at": "2026-05-08T10:24:11.421Z",
  "updated_at": "2026-05-08T10:24:11.421Z"
}

Versioning#

The API is versioned in the URL path (/api/v1). We will introduce /api/v2 alongside v1 if we ever need a breaking change.

What is non-breaking#

• Adding new endpoints.
• Adding new optional request fields.
• Adding new response fields. Always treat unknown fields as additive.
• Adding new error codes within an existing error type.

What would be breaking (and trigger a v2)#

• Removing or renaming an existing field.
• Changing the type of an existing field, or making an optional field required.
• Changing the meaning of an existing error code.

Changelog#