Skip to content

Genway Public API (1.0.0)

Genway's API enables you to programmatically manage various aspects of your projects, prototypes, and interviews using our AI interviewer.

  • Projects - Create and manage Contextual Interviews or Prototype Testing projects.
  • Interviews - Manage and export interview data, including transcripts, summaries, audio, and video.

Genway API overview

Authentication

Genway API uses dual-header authentication for all requests to ensure secure access and proper tenant isolation.

Required Headers:

X-Api-Key: YOUR_API_KEY
X-Tenant-Id: YOUR_TENANT_UUID

Both headers are mandatory for every API call. Missing either header will result in authentication failure.

Versioning and stability

We strongly aim for backward compatibility for the documented endpoints. If backwards-incompatible changes are made, we will aim to release a new version.

  • URLs’ entry point is https://api.genway.ai/.
  • URLs are versioned https://api.genway.ai/v1/{endpoint}, e.g. https://api.genway.ai/v1/projects.

Rate limits and API status

The Genway API enforces per-IP rate limits to keep the platform responsive:

ScopeLimitEndpoints / Examples
Global throughputUp to 50 requests per minute per IPApplies to every endpoint, including Export interview video and Activate project.
Project creation10 requests per minute per IPCreate a new project (POST /projects).

When a limit is exceeded the API responds with 429 Too Many Requests, includes a Retry-After header indicating when you can resume sending requests, and returns the rate-limit payload documented in the 429 response example for endpoints such as Create a new project.

You can subscribe to our status page.

API support

If you require help you can contact our support team at support@genway.ai.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Production environment

https://api.genway.ai/v1/

Multi-Tenancy

Genway provides a secure tenant-based authentication system that ensures strong data isolation between customers.

Tenants

Manage tenant creation and multi-tenancy setup.

Operations

Projects

Manage your projects programmatically.

Operations

Create a new project

Request

Create a new project (Contextual Interview)

Note: Prototype Testing projects creation is not yet supported.

Security
api_key and tenant_id
Bodyapplication/jsonrequired
One of:
project_typestringrequired
Value"contextual_interview"
Example: "contextual_interview"
project_namestringrequired
Example: "The Impact of Formula 1 Excitement on Fan Enthusiasm"
project_descriptionstringrequired
Example: "Forumla 1 - US based fans"
project_objectivestringrequired
Example: "The research on 'The Impact of Formula 1 Excitement on Fan Enthusiasm' is crucial for understanding how the thrill of racing influences spectator engagement and loyalty. Current insights suggest that the suspense and unpredictability of races enhance viewer excitement and attachment to the sport. This study aims to delve deeper into these aspects, providing strategies to boost fan engagement and expand the sport's audience."
research_questionsstringrequired
Example: "Our primary research questions focus on understanding the impact of remote work on employee productivity and well-being. We hope to learn how different remote work policies affect job satisfaction and efficiency across various industries. Additionally, we aim to identify key factors that contribute to a successful remote work environment."
success_criteriastringrequired
Example: "Success for this project would be clearly evidenced by its direct influence on enhancing our product features, refining our design aesthetics, and strategically informing our marketing campaigns. Ideally, the research findings will provide actionable insights that directly correlate with increased user engagement and satisfaction. Ultimately, the goal is to leverage this research to drive meaningful improvements across all departments, ensuring that every decision is data-informed and aligned with our users' needs."
recruiting_criteriastringrequired
Example: "For this project, we are targeting participants who fall within the 30-50 age range, have a background in engineering or product management, and are currently employed in the tech industry. We are specifically focusing on individuals residing in North America and Europe to capture insights from key tech hubs. This demographic and customer segment approach ensures that we obtain targeted and relevant data for our research objectives."
specific_guidelinesstring or null
Example: "Ask from the participants to mute notifications during the interview."
redirect_urlstring or null(uri)^https://.*

HTTPS URL to redirect participants after completing the interview

Example: "https://example.com/thank-you"
interview_modesArray of strings or null(InterviewMode)

Interview modes available for participants

Default ["talking"]
Enum"typing""talking"
Example: ["typing","talking"]
camera_accessstring
Default "not_allowed"
Enum"not_allowed""optional""required"
Example: "optional"
logo_urlstring or null(uri)<= 2083 characters

URL to the organization's logo for branding. Recommended: minimum resolution of 160x160px with 1:1 aspect ratio for optimal display.

Default "https://app.genway.ai/assets/images/logoa1.svg"
Example: "https://example.com/logo.png"
primary_colorstring or null^#[0-9A-F]{6}$

Primary brand color in hex format

Default "#6759DF"
Example: "#FF6B35"
secondary_colorstring or null^#[0-9A-F]{6}$

Secondary brand color in hex format

Default "#3B337F"
Example: "#004E89"
text_colorstring or null^#[0-9A-F]{6}$

Text color in hex format

Default "#1C1842"
Example: "#FFFFFF"
interview_languagesArray of strings or null

List of languages supported for the interview using ISO 639-1 codes

Default ["en"]
Enum"en""fr""de""es""it""ar""ru""ja""he""el"
Example: ["en","fr","es"]
interview_lengthinteger or null

Duration of the interview in minutes

Default 10
Enum101520
Example: 15
curl -i -X POST \
  https://api.genway.ai/v1/projects \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Tenant-Id: YOUR_API_KEY_HERE' \
  -d '{
    "project_type": "contextual_interview",
    "project_name": "The Impact of Formula 1 Excitement on Fan Enthusiasm",
    "project_description": "Forumla 1 - US based fans",
    "project_objective": "The research on '\''The Impact of Formula 1 Excitement on Fan Enthusiasm'\'' is crucial for understanding how the thrill of racing influences spectator engagement and loyalty. Current insights suggest that the suspense and unpredictability of races enhance viewer excitement and attachment to the sport. This study aims to delve deeper into these aspects, providing strategies to boost fan engagement and expand the sport'\''s audience.",
    "research_questions": "Our primary research questions focus on understanding the impact of remote work on employee productivity and well-being. We hope to learn how different remote work policies affect job satisfaction and efficiency across various industries. Additionally, we aim to identify key factors that contribute to a successful remote work environment.",
    "success_criteria": "Success for this project would be clearly evidenced by its direct influence on enhancing our product features, refining our design aesthetics, and strategically informing our marketing campaigns. Ideally, the research findings will provide actionable insights that directly correlate with increased user engagement and satisfaction. Ultimately, the goal is to leverage this research to drive meaningful improvements across all departments, ensuring that every decision is data-informed and aligned with our users'\'' needs.",
    "recruiting_criteria": "For this project, we are targeting participants who fall within the 30-50 age range, have a background in engineering or product management, and are currently employed in the tech industry. We are specifically focusing on individuals residing in North America and Europe to capture insights from key tech hubs. This demographic and customer segment approach ensures that we obtain targeted and relevant data for our research objectives.",
    "specific_guidelines": "Ask from the participants to mute notifications during the interview.",
    "redirect_url": "https://example.com/thank-you",
    "interview_modes": [
      "typing",
      "talking"
    ],
    "camera_access": "optional",
    "logo_url": "https://example.com/logo.png",
    "primary_color": "#FF6B35",
    "secondary_color": "#004E89",
    "text_color": "#FFFFFF",
    "interview_languages": [
      "en",
      "fr",
      "es"
    ],
    "interview_length": 15
  }'

Responses

Project created successfully

Bodyapplication/json
project_idstring(uuid)
Example: "123e4567-e89b-12d3-a456-426614174000"
Response
application/json
{
  "project_id": "123e4567-e89b-12d3-a456-426614174000"
}

Update project details

Request

Update the details of a project by its projectId.

Security
api_key and tenant_id
Path
project_idstring(uuid)required

The ID of the project to update

Bodyapplication/jsonrequired
project_namestring or null
Example: "The Impact of Formula 1 Excitement on Fan Enthusiasm"
project_descriptionstring or null
Example: "Forumla 1 - US based fans"
project_objectivestring or null
Example: "The research on 'The Impact of Formula 1 Excitement on Fan Enthusiasm' is crucial for understanding how the thrill of racing influences spectator engagement and loyalty. Current insights suggest that the suspense and unpredictability of races enhance viewer excitement and attachment to the sport. This study aims to delve deeper into these aspects, providing strategies to boost fan engagement and expand the sport's audience."
research_questionsstring or null
Example: "Our primary research questions focus on understanding the impact of remote work on employee productivity and well-being. We hope to learn how different remote work policies affect job satisfaction and efficiency across various industries. Additionally, we aim to identify key factors that contribute to a successful remote work environment."
success_criteriastring or null
Example: "Success for this project would be clearly evidenced by its direct influence on enhancing our product features, refining our design aesthetics, and strategically informing our marketing campaigns. Ideally, the research findings will provide actionable insights that directly correlate with increased user engagement and satisfaction. Ultimately, the goal is to leverage this research to drive meaningful improvements across all departments, ensuring that every decision is data-informed and aligned with our users' needs."
recruiting_criteriastring or null
Example: "For this project, we are targeting participants who fall within the 30-50 age range, have a background in engineering or product management, and are currently employed in the tech industry. We are specifically focusing on individuals residing in North America and Europe to capture insights from key tech hubs. This demographic and customer segment approach ensures that we obtain targeted and relevant data for our research objectives."
specific_guidelinesstring or null
Example: "Ask from the participants to mute notifications during the interview."
redirect_urlstring or null(uri)^https://.*

HTTPS URL to redirect participants after completing the interview

Example: "https://example.com/thank-you"
interview_modesArray of strings or null(InterviewMode)

Interview modes available for participants

Enum"typing""talking"
Example: ["typing","talking"]
camera_accessstring
Enum"not_allowed""optional""required"
Example: "optional"
logo_urlstring or null(uri)<= 2083 characters

URL to the organization's logo for branding. Recommended: minimum resolution of 160x160px with 1:1 aspect ratio for optimal display.

Example: "https://example.com/logo.png"
primary_colorstring or null^#[0-9A-F]{6}$

Primary brand color in hex format

Example: "#FF6B35"
secondary_colorstring or null^#[0-9A-F]{6}$

Secondary brand color in hex format

Example: "#004E89"
text_colorstring or null^#[0-9A-F]{6}$

Text color in hex format

Example: "#FFFFFF"
interview_languagesArray of strings or null

List of languages supported for the interview using ISO 639-1 codes

Enum"en""fr""de""es""it""ar""ru""ja""he""el"
Example: ["en","fr","es"]
interview_lengthinteger or null

Duration of the interview in minutes

Enum101520
Example: 15
curl -i -X PATCH \
  'https://api.genway.ai/v1/projects/{project_id}' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Tenant-Id: YOUR_API_KEY_HERE' \
  -d '{
    "project_name": "The Impact of Formula 1 Excitement on Fan Enthusiasm",
    "project_description": "Forumla 1 - US based fans",
    "project_objective": "The research on '\''The Impact of Formula 1 Excitement on Fan Enthusiasm'\'' is crucial for understanding how the thrill of racing influences spectator engagement and loyalty. Current insights suggest that the suspense and unpredictability of races enhance viewer excitement and attachment to the sport. This study aims to delve deeper into these aspects, providing strategies to boost fan engagement and expand the sport'\''s audience.",
    "research_questions": "Our primary research questions focus on understanding the impact of remote work on employee productivity and well-being. We hope to learn how different remote work policies affect job satisfaction and efficiency across various industries. Additionally, we aim to identify key factors that contribute to a successful remote work environment.",
    "success_criteria": "Success for this project would be clearly evidenced by its direct influence on enhancing our product features, refining our design aesthetics, and strategically informing our marketing campaigns. Ideally, the research findings will provide actionable insights that directly correlate with increased user engagement and satisfaction. Ultimately, the goal is to leverage this research to drive meaningful improvements across all departments, ensuring that every decision is data-informed and aligned with our users'\'' needs.",
    "recruiting_criteria": "For this project, we are targeting participants who fall within the 30-50 age range, have a background in engineering or product management, and are currently employed in the tech industry. We are specifically focusing on individuals residing in North America and Europe to capture insights from key tech hubs. This demographic and customer segment approach ensures that we obtain targeted and relevant data for our research objectives.",
    "specific_guidelines": "Ask from the participants to mute notifications during the interview.",
    "redirect_url": "https://example.com/thank-you",
    "interview_modes": [
      "typing",
      "talking"
    ],
    "camera_access": "optional",
    "logo_url": "https://example.com/logo.png",
    "primary_color": "#FF6B35",
    "secondary_color": "#004E89",
    "text_color": "#FFFFFF",
    "interview_languages": [
      "en",
      "fr",
      "es"
    ],
    "interview_length": 15
  }'

Responses

Project details updated successfully

Bodyapplication/json
project_idstring(uuid)
Example: "123e4567-e89b-12d3-a456-426614174000"
Response
application/json
{
  "project_id": "123e4567-e89b-12d3-a456-426614174000"
}

Publish/resume a project

Request

Publish or resume a project

Security
api_key and tenant_id
Path
project_idstring(uuid)required

The ID of the project to activate

curl -i -X POST \
  'https://api.genway.ai/v1/projects/{project_id}/activate' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Tenant-Id: YOUR_API_KEY_HERE'

Responses

Project activated successfully

Response
No content

Pause a project

Request

Pause an active project, making it inactive. This is useful for temporarily halting a project.

Security
api_key and tenant_id
Path
project_idstring(uuid)required

The ID of the project to deactivate

curl -i -X POST \
  'https://api.genway.ai/v1/projects/{project_id}/deactivate' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Tenant-Id: YOUR_API_KEY_HERE'

Responses

Project deactivated successfully

Response
No content

Export all interviews transcripts and summaries

Request

Export all interviews transcripts and summaries for a specific project.

Security
api_key and tenant_id
Path
project_idstring(uuid)required

The ID of the project

curl -i -X GET \
  'https://api.genway.ai/v1/projects/{project_id}/interviews-export' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Tenant-Id: YOUR_API_KEY_HERE'

Responses

Export successful

Bodytext/csv
string(binary)

CSV file containing interview data with the following columns:

  • interview_id: The unique identifier for the interview
  • identifier: The identifier for the interviewee (email, user_id, or external_user_id)
  • country_code: The country code of the interviewee
  • interview_status: The status of the interview (INITIATED, PARTIAL, COMPLETED)
  • opt_in_for_followup: Whether the interviewee opted in for follow-up
  • created_at: Timestamp of when the interview was started
  • external_metadata: External metadata associated with the interviewee (JSON format)
  • transcription: Transcription of the interview
  • interview_summary: Summary of the interview
Response
No content

Export all interviewees' information

Request

Export all interviewees' information for a specific project as a CSV file.

Security
api_key and tenant_id
Path
project_idstring(uuid)required

The ID of the project

curl -i -X GET \
  'https://api.genway.ai/v1/projects/{project_id}/interviewees-export' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Tenant-Id: YOUR_API_KEY_HERE'

Responses

Export successful

Bodytext/csv
string(binary)

CSV file containing interviewee data with the following columns:

  • interview_id: The unique identifier for the interview.
  • identifier: The identifier for the interviewee, which can be an email, user_id, or external_user_id.
  • country_code: The country code of the interviewee.
  • interview_status: The status of the interview (INITIATED, PARTIAL, COMPLETED).
  • opt_in_for_followup: Indicates if the interviewee has opted in for follow-up.
  • created_at: The timestamp when the interview was started.
  • external_metadata: External metadata associated with the interviewee (JSON format).
Response
No content

Get project URL for sharing with interviewees

Request

Get the URL for a project to share with interviewees. Accepts a parameter to specify sandbox or production URL.

Security
api_key and tenant_id
Path
project_idstring(uuid)required

The ID of the project

Query
environmentstringrequired

Specify whether the URL should be for a sandbox or production interview

Enum"sandbox""production"
curl -i -X GET \
  'https://api.genway.ai/v1/projects/{project_id}/url?environment=sandbox' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Tenant-Id: YOUR_API_KEY_HERE'

Responses

URL retrieved successfully

Bodyapplication/json
project_idstring(uuid)
Example: "123e4567-e89b-12d3-a456-426614174000"
urlstring(uri)
Example: "https://app.genway.ai/meet/123e4567-e89b-12d3-a456-426614174000"
Response
application/json
{
  "project_id": "123e4567-e89b-12d3-a456-426614174000",
  "url": "https://app.genway.ai/meet/123e4567-e89b-12d3-a456-426614174000"
}

Interviews

Manage and export interview data.

Operations

Webhooks

Webhooks deliver event data to your applications as it happens, offering an alternative to frequent data polling.

  • The secret created via the /webhooks/secrets endpoint is permanent and should be stored securely in your system. This secret will serve for the verifying section.
  • The x-hook-secret is temporary and should be used only once during the confirmation process.
  • Until the webhook is confirmed, no events will be sent to the subscriber's endpoint.
Operations

Errors

The Genway API uses standard HTTP response codes to indicate the success or failure of the request. Codes follow this pattern:

  • 2xx codes indicate success.
  • 4xx codes indicate a request that failed given the information provided (e.g., a required parameter was omitted).
  • 5xx codes indicate an error with Genway's platform.