Appearance
API Reference
Complete API documentation for the OriginalVoices API. All endpoints require authentication using a Bearer token in the Authorization header.
API for generating audience insights and topic analysis
Servers
https://api.originalvoices.aiAPI server
POST /v1/ask/choices
POST
/v1/ask/choices
Ask a choices question to the audience and get summary and themes
Authorizations
bearerAuth
TypeHTTP (bearer)
Request Body
application/json
JSON
{
"audienceId": "string",
"audiencePrompt": "string",
"question": "string",
"choices": [
"string"
],
"isMultipleChoice": false,
"sampleSize": "medium"
}
Responses
Default Response
application/json
JSON
{
"requestId": "string",
"data": {
"choices": [
{
"choice": "string",
"percentage": 0
}
]
}
}
POST /v1/ask/open
POST
/v1/ask/open
Ask an open-ended question to the audience and get raw answers
Authorizations
bearerAuth
TypeHTTP (bearer)
Request Body
application/json
JSON
{
"audienceId": "string",
"audiencePrompt": "string",
"question": "string",
"questions": [
"string"
],
"sampleSize": "medium"
}
Responses
Default Response
application/json
JSON
{
"requestId": "string",
"data": {
"answers": [
[
]
]
},
"error": null
}
Audience
GET /v1/audiences
POST /v1/audiences
POST
/v1/audiences
Create a new audience with title and prompt
Authorizations
bearerAuth
TypeHTTP (bearer)
Request Body
application/json
JSON
{
"title": "string",
"prompt": "string"
}
Responses
Default Response
application/json
JSON
{
"requestId": "string",
"data": {
"id": "string",
"title": "string"
},
"error": null
}
DELETE /v1/audiences/{id}
PATCH /v1/audiences/{id}
PATCH
/v1/audiences/{id}
Update the title of an audience
Authorizations
bearerAuth
TypeHTTP (bearer)
Parameters
Path Parameters
id*
Typestring
RequiredFormat
"uuid"Request Body
application/json
JSON
{
"title": "string"
}
Responses
Default Response
application/json
JSON
{
"requestId": "string",
"data": {
"id": "string",
"title": "string"
},
"error": null
}
GET /v1/projects
GET
/v1/projects
List all projects in the organization with their survey questions and audiences
Authorizations
bearerAuth
TypeHTTP (bearer)
Responses
Default Response
application/json
JSON
{
"requestId": "string",
"data": [
{
"id": "string",
"title": "string",
"description": "string",
"surveyQuestions": [
"string"
],
"audiences": [
{
"id": "string",
"title": "string",
"prompt": "string"
}
]
}
],
"error": null
}
POST /v1/project/{projectId}/ask
POST
/v1/project/{projectId}/ask
Ask questions to a filtered subset of a project's survey respondents
Authorizations
bearerAuth
TypeHTTP (bearer)
Parameters
Path Parameters
projectId*
Typestring
RequiredFormat
"uuid"Request Body
application/json
JSON
{
"filter": "string",
"questions": [
"string"
]
}
Responses
Default Response
application/json
JSON
{
"requestId": "string",
"data": {
"answers": [
[
]
],
"matchedTwins": 0,
"totalTwins": 0
},
"error": null
}
Authentication
All API requests require authentication using a Bearer token. Include your API key in the Authorization header:
bash
Authorization: Bearer YOUR_API_KEYWhen using the originalvoices npm package, authentication is handled automatically:
javascript
import { OriginalVoices } from "originalvoices";
const client = new OriginalVoices({
apiKey: "your-api-key-here",
});Base URL
All API requests should be made to:
https://api.originalvoices.aiRate Limits
Rate limits may apply based on your plan. Check your OriginalVoices Platform for current limits.
Error Responses
The API uses standard HTTP status codes. Error responses follow this format:
json
{
"error": {
"message": "Error description",
"type": "error_type",
"code": "error_code",
"param": null
},
"requestId": "unique-request-id"
}Common Error Codes
400- Invalid request body401- Missing or invalid API token402- Payment Required - Insufficient credits balance422- Unprocessable Entity - Insufficient matches found for the audience500- Internal server error
Support
For additional support or questions, please contact support@originalvoices.ai or visit our support portal.