Headless API Overview

The Headless API lets you run Koji interviews entirely from your own backend. Instead of sending participants to a link or embedding an iframe, you make REST API calls to start conversations, send messages, and mark interviews as complete. This is ideal for building fully custom interview experiences or integrating Koji into existing workflows.

What Is the Headless API?

Think of it as Koji without the front end. Your application controls the entire flow:

1. Start an interview by calling the start endpoint. Koji returns an interview ID, a session token, and the first message.
2. Exchange messages by sending participant responses to the message endpoint. Koji replies with follow-up questions.
3. Complete the interview by calling the complete endpoint. Koji triggers its analysis pipeline and generates insights.

Your participants never interact with Koji's interface directly — they interact with whatever UI you build.

Plan Availability

The Headless API is available on all Koji plans. Usage is controlled by your credit balance — each interview started via the API consumes credits just like any other interview. See your account settings for current credit balance and usage.

Getting Started

Authentication

All API requests require a Bearer token in the Authorization header. You can generate API keys from your project settings.

Authorization: Bearer YOUR_API_KEY

Your API key must have the appropriate permissions for the endpoints you want to use. See API Authentication for setup instructions.

Base URL

All endpoints are available at:

https://yourdomain.com/api/v1/interviews

Core Endpoints

Start an Interview

POST /api/v1/interviews/start

Creates a new interview and returns the opening message.

Request body:

{
  "respondent": {
    "external_id": "crm-contact-456",
    "display_name": "Jane Smith",
    "metadata": {
      "source": "crm-integration",
      "segment": "enterprise"
    }
  },
  "mode": "text",
  "locale": "en"
}

Response:

{
  "interview_id": "int_abc123",
  "session_token": "stk_xyz789",
  "initial_message": "Hi Jane! Thanks for taking the time..."
}

The respondent object is optional. If provided, it accepts these fields:

The mode field is optional and defaults to text. The locale field is optional and defaults to the study's configured language.

Send a Message

POST /api/v1/interviews/:id/message

Sends the participant's response and receives the next question.

Request body:

{
  "message": "I've been using the product for about six months now..."
}

Response:

{
  "message": {
    "role": "assistant",
    "content": "That's great to hear. What was your initial impression when you first started using it?"
  },
  "turn_count": 3,
  "is_complete": false
}

The is_complete flag tells you whether the interviewer has gathered enough information and is ready to wrap up. You can use this to decide when to call the complete endpoint.

Complete an Interview

POST /api/v1/interviews/:id/complete

Marks the interview as finished and triggers Koji's analysis pipeline.

Response:

{
  "status": "completed",
  "quality_score": 4.2
}

Once completed, the interview appears in your project dashboard with a full transcript, quality score, and generated insights.

Get Interview Details

GET /api/v1/interviews/:id

Retrieve the full transcript and metadata for a specific interview.

Structured Questions via API

If your study includes structured questions (scales, multiple choice, ranking, or yes/no), the AI interviewer will present these during the conversation. When using the Headless API, structured question prompts appear in the assistant's message content. Your UI should handle rendering appropriate input widgets based on the question type indicated in the response.

Common Use Cases

In-App Feedback

Embed a feedback flow inside your own product. When a user triggers a feedback prompt, your backend starts a Koji interview, then your front end presents the conversation in your own UI components.

CRM Integration

Connect Koji to your CRM pipeline. When a deal reaches a certain stage, automatically trigger an interview with the contact. Responses flow back into the CRM record.

Chatbot Handoff

Route specific conversation topics from your existing chatbot to a Koji interview. The participant continues the conversation naturally while Koji handles the research-quality follow-up questions.

Batch Research

Combine CSV import with the Headless API for large-scale studies. Import your participant list, then programmatically start and manage interviews for each person.

Rate Limiting

The API enforces a rate limit of 60 requests per minute to ensure fair usage across all customers. If you exceed the limit, you will receive a 429 Too Many Requests response. Rate limit information is included in response headers:

Build retry logic into your integration to handle rate limit responses gracefully.

Error Handling

All error responses follow a consistent format:

{
  "error": "Description of what went wrong"
}

Common status codes:

Best Practices

1. Store interview IDs. Save the interview_id returned by the start endpoint so you can continue the conversation and retrieve results later.
2. Respect the is_complete flag. When the response indicates the interview is ready to wrap up, call the complete endpoint to trigger analysis.
3. Handle errors gracefully. Implement retry logic for transient failures and surface clear error messages to your users.
4. Secure your API key. Never expose your API key in client-side code. All API calls should go through your backend.

Next Steps

• API Authentication — generate and manage API keys
• Sharing Your Interview Link — alternative ways to collect responses
• Structured Questions Guide — add interactive question types to your study