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

Interviews

Manage and export interview data.

Operations

List interviews

Request

Retrieve a list of all interviews. Supports filtering by project and external metadata.

External Metadata Filtering: You can filter interviews using any external metadata field by using the pattern external_metadata[<key>]=<value>. The <key> can be any string, and the <value> can be any value that was stored as external metadata.

When multiple values are provided for the same external metadata field (e.g., external_metadata[field1]=abc&external_metadata[field1]=def), they are treated with OR logic, meaning the field should match any of the provided values.

Examples:

  • GET /interviews?project_id=12345678-1234-1234-1234-123456789012 - Get all interviews for a specific project
  • GET /interviews?external_metadata[someExternalId]=1234 - Filter by external ID
  • GET /interviews?external_metadata[field1]=abc&external_metadata[field1]=def - Filter where field1 is either "abc" OR "def"
  • GET /interviews?project_id=12345678-1234-1234-1234-123456789012&external_metadata[someExternalId]=1234&external_metadata[user_uuid]=abcd - Filter by user ID, external ID, and project ID (AND logic applied between different fields)
Security
api_key and tenant_id
Query
project_idstring(uuid)

Filter interviews by project ID

Example: project_id=12345678-1234-1234-1234-123456789012
external_metadata[<external_param>]string

Dynamic Parameter Pattern - This is not a literal parameter name but represents the pattern for filtering by external metadata.

Replace <external_param> with any external metadata key you want to filter by. You can use multiple of these parameters in a single request.

Pattern: external_metadata[<key>]=<value>

Examples:

  • external_metadata[someExternalId]=1234
  • external_metadata[userId]=abc123
  • external_metadata[source]=web
  • external_metadata[priority]=high
Example: external_metadata[<external_param>]=1234
curl -i -X GET \
  'https://api.genway.ai/v1/interviews?project_id=12345678-1234-1234-1234-123456789012&external_metadata%5B%3Cexternal_param%3E%5D=1234' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Tenant-Id: YOUR_API_KEY_HERE'

Responses

List of interviews retrieved successfully

Bodyapplication/json
dataArray of objectsrequired
data[].​interview_idstring(uuid)required

The unique identifier of the interview

Example: "87654321-4321-4321-4321-210987654321"
data[].​project_idstring(uuid)required

The unique identifier of the project this interview belongs to

Example: "12345678-1234-1234-1234-123456789012"
data[].​created_atstring(date-time)required

The timestamp when the interview was created (ISO 8601 format)

Example: "2025-11-11T10:30:00Z"
Response
application/json
{
  "data": [
    { … },
    { … },
    { … }
  ]
}

Export specific interview audio

Request

Export the audio of a specific interview.

Security
api_key and tenant_id
Path
interview_idstring(uuid)required

The ID of the interview

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

Responses

Export successful

Bodyaudio/mpeg
string(binary)
Response
No content

Export specific interview video

Request

Export the video of a specific interview.

Security
api_key and tenant_id
Path
interview_idstring(uuid)required

The ID of the interview

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

Responses

Export successful

Bodyvideo/mp4
string(binary)
Response
No content

Flag interview as fraud

Request

⚠️ Not Supported - This endpoint is not currently supported.

Flag a specific interview as fraud with a reason.

Security
api_key and tenant_id
Path
interview_idstring(uuid)required

The ID of the interview

Bodyapplication/jsonrequired
reasonstring
Example: "suspicious_behavior_detected"
curl -i -X POST \
  'https://api.genway.ai/v1/interviews/{interview_id}/flag' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY_HERE' \
  -H 'X-Tenant-Id: YOUR_API_KEY_HERE' \
  -d '{
    "reason": "suspicious_behavior_detected"
  }'

Responses

Interview flagged successfully

Bodyapplication/json
statusstring
Example: "flagged"
Response
application/json
{
  "status": "flagged"
}

Files

Upload and manage files for use in projects.

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.