Voxco AICoder API
The AICoder API from Voxco — 15 operation(s) for aicoder.
OpenAPI Specification
openapi: 3.0.4
info:
title: Ascribe Coder AICoder API
description: <br/> To import this API to Postman, copy the URL from the top of this page.<br/> Open Postman, and select Import.<br/> In the dialog select 'Import From Link'.<br/> Paste the URL and click Import.<br/><br/> To use this API interactively from this page, open the POST Sessions operation below.<br/> Click the Example Value in the Parameters section to move it to the request.<br/> Modify the request with your credentials, then click "Try it out!"<br/> Copy the value of the bearerToken returned in the response to the api_key text box at the top of this page.<br/> You can now interact with the other resources on this page.<br/> You can save the bearer token for future use without needing to POST to the Sessions resource again.
contact:
email: support@goascribe.com
version: v2
servers:
- url: https://api.goascribe.us/coder/v2
description: US Servers
- url: https://api.goascribe.eu/coder/v2
description: EU Servers
- url: https://api-ca.goascribe.com/coder/v2
description: CA Servers
security:
- Bearer: []
tags:
- name: AICoder
paths:
/AICoder/Export/Excel:
post:
tags:
- AICoder
summary: Initiates a new task to export AI Coder project data into an Excel file.
description: "This method exports AI Coder project data into an Excel file.\r\n\r\nAfter the method triggers an export task, it returns a unique task key.\r\n\r\nThis key can be used for tracking the status of exporting through the API endpoint: **AICoder/Export/Excel/{taskStatusKey:long}**."
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderExcelExportRequest'
example:
aiCoderKey: 39999
text/json:
schema:
$ref: '#/components/schemas/AICoderExcelExportRequest'
example:
aiCoderKey: 39999
application/*+json:
schema:
$ref: '#/components/schemas/AICoderExcelExportRequest'
example:
aiCoderKey: 39999
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderExcelExportResponse'
example:
taskStatusKey: 1020309999
errorMessage: null
/AICoder/Export/Excel/{taskStatusKey}:
get:
tags:
- AICoder
summary: Retrieves the current status of an Excel file export task.
description: "This method requires a task key as an input parameter, which is obtained from the response of the **AICoder/Export/Excel** method.\r\n \r\nIt returns the current status of the export task, including its result if completed.\r\n\r\nIf the task is not yet completed, the method should be called again after a delay.\r\n\r\nContinue calling this method until the task is either completed or rejected due to an error."
parameters:
- name: taskStatusKey
in: path
description: The key associated with the ongoing task.
required: true
schema:
type: integer
format: int64
example: 1020309999
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderExcelExportGetStatusOfTaskResponse'
example:
isCompleted: true
fileUrl: https://goascribe.com/xfjfoejgreo.xls
errorMessage: null
/AICoder/Export/Codebook:
post:
tags:
- AICoder
summary: Initiates a new task to export the generated codebook from an AI Coder project to a Coder study.
description: "It allows to export generated codebook in AI Coder back into Coder codebook by using some export strategy (Append, Overwrite, or Merge)\r\n\r\nand determine whether responses should be coded automatically after the export.\r\n\r\nAfter the method triggers generating codebook task, it returns a unique task key.\r\n\r\nThis key can be used for tracking the status of generating codebook through the API endpoint: **AICoder/Export/Codebook/{taskStatusKey:long}**.\r\n\r\nParameter **ExportType:** Specifies the strategy to be used for exporting the codebook.\r\n\r\nCommon options include:\r\n - **Append**: Adds the new codebook data into the existing codebook of Coder study.\r\n - **Overwrite**: Fully replaces the existing codebook in the Coder study with the new one.\r\n - **Merge**: Combines the new codebook with the existing one, replacing any existing codes with the same name and input/output IDs while adding new information"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCodebookExportRequest'
example:
aiCoderKey: 39999
analyzedVariable: 203399
exportType: Append
skipResponcesCoding: false
text/json:
schema:
$ref: '#/components/schemas/AICoderCodebookExportRequest'
example:
aiCoderKey: 39999
analyzedVariable: 203399
exportType: Append
skipResponcesCoding: false
application/*+json:
schema:
$ref: '#/components/schemas/AICoderCodebookExportRequest'
example:
aiCoderKey: 39999
analyzedVariable: 203399
exportType: Append
skipResponcesCoding: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCodebookExportResponse'
example:
taskStatusKey: 1020309999
errorMessage: null
/AICoder/Export/Codebook/{taskStatusKey}:
get:
tags:
- AICoder
summary: Retrieves the current status of Codebook export task.
description: "This method requires a task key as an input parameter, which is obtained from the response of the **AICoder/Export/Codebook** method.\r\n\r\nIt returns the current status of the export task, including its result if completed.\r\n\r\nIf the task is not yet completed, the method should be called again after a delay.\r\n\r\nContinue calling this method until the task is either completed or rejected due to an error."
parameters:
- name: taskStatusKey
in: path
description: The key associated with the ongoing task.
required: true
schema:
type: integer
format: int64
example: 1020309999
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCodebookExportGetStatusOfTaskResponse'
example:
isCompleted: true
errorMessage: null
/AICoder/Analyze/v3:
post:
tags:
- AICoder
summary: Initiates a new task for analyzing study using Codebook Builder (UI-aligned v3 contract).
description: "This method analyzes responses from some study questions using Codebook Builder: prompt embeddings and clustering to build a prototype codebook.\r\n\r\nRequest `CodebookBuilder` options match the AI Coder app defaults and ranges (granularity 25–150, creation method AI vs data-driven,\r\nminimum responses per code 1–250 default 3, classification strictness 75–95%, optional topic-based code cap 1–50 when enabled,\r\noptional analyze-by closed-ended question).\r\n\r\nGiven codebook prototype can be used in applications such as Ascribe Coder with pre-editing it in AI Coder or without it.\r\n\r\nAdditionally, this process generates a structured dataset that can be utilized for: \r\n- Comprehensive analysis of the content of survey responses;\r\n- Creation of detailed reports based on the analyzed data; \r\n\r\nThis method enhances the efficiency of processing textual data and facilitates its interpretation."
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyV3Request'
example:
questionKeys:
- 100
- 101
- 102
- 103
codebookBuilder:
codebookGranularity: 100
creationMethod: AIGenerated
minimumResponsesPerCode: 3
classificationStrictness: 80
maxTopicBasedCodesEnabled: false
maxTopicBasedCodes: 10
analyzeByClosedEnd: null
includeCodedResponses: false
wordsToIgnore:
- some
- words
- to
- ignore
generativeAIOptions:
dataIsAbout: null
codebookLanguage: en
nonGenerativeAIOptions:
splitCharacters: .!?|
splitWords:
- but
- however
- nevertheless
- nonetheless
- yet
- thus
- also
- additionally
- nor
- and
responsesAreAllEnglish: true
useGenerativeAI: true
text/json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyV3Request'
example:
questionKeys:
- 100
- 101
- 102
- 103
codebookBuilder:
codebookGranularity: 100
creationMethod: AIGenerated
minimumResponsesPerCode: 3
classificationStrictness: 80
maxTopicBasedCodesEnabled: false
maxTopicBasedCodes: 10
analyzeByClosedEnd: null
includeCodedResponses: false
wordsToIgnore:
- some
- words
- to
- ignore
generativeAIOptions:
dataIsAbout: null
codebookLanguage: en
nonGenerativeAIOptions:
splitCharacters: .!?|
splitWords:
- but
- however
- nevertheless
- nonetheless
- yet
- thus
- also
- additionally
- nor
- and
responsesAreAllEnglish: true
useGenerativeAI: true
application/*+json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyV3Request'
example:
questionKeys:
- 100
- 101
- 102
- 103
codebookBuilder:
codebookGranularity: 100
creationMethod: AIGenerated
minimumResponsesPerCode: 3
classificationStrictness: 80
maxTopicBasedCodesEnabled: false
maxTopicBasedCodes: 10
analyzeByClosedEnd: null
includeCodedResponses: false
wordsToIgnore:
- some
- words
- to
- ignore
generativeAIOptions:
dataIsAbout: null
codebookLanguage: en
nonGenerativeAIOptions:
splitCharacters: .!?|
splitWords:
- but
- however
- nevertheless
- nonetheless
- yet
- thus
- also
- additionally
- nor
- and
responsesAreAllEnglish: true
useGenerativeAI: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyResponse'
example:
taskStatusKey: 1020309999
errorMessage: null
/AICoder/Analyze:
post:
tags:
- AICoder
summary: Initiates a new task for analyzing study.
description: "This method analyzes responses from some study questions by applying artificial intelligence (AI)\r\n\r\nor special algorithms for automatically constructing a hierarchical model of a prototype codebook.\r\n \r\nGiven codebook prototype can be used in applications such as Ascribe Coder with pre-editing it in AI Coder or without it.\r\n\r\nAdditionally, this process generates a structured dataset that can be utilized for: \r\n- Comprehensive analysis of the content of survey responses;\r\n- Creation of detailed reports based on the analyzed data; \r\n\r\nThis method enhances the efficiency of processing textual data and facilitates its interpretation.\r\n\r\nNote: For Codebook Builder (prompt embeddings) analysis aligned with the AI Coder app, use `POST /AICoder/Analyze/v3`."
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyRequest'
example:
questionKeys:
- 100
- 101
- 102
- 103
existingCodebookKey: -1
existingCodebookSuggestNewCodes: false
existingCodebookOptions: null
codebook:
initial:
minProximity: 75
minSegmentsPerCode: 3
approxMaxCodes: 100
mergeSimilar:
enabled: true
minProximity: 85
assignSegmentSiblings:
enabled: true
minProximity: 75
minSiblings: 3
assignTopSegments:
enabled: true
minProximity: 75
topSegments: 10
generativeAIOptions:
dataIsAbout: null
codebookLanguage: en
nonGenerativeAIOptions:
splitCharacters: .!?|
splitWords:
- but
- however
- nevertheless
- nonetheless
- yet
- thus
- also
- additionally
- nor
- and
responsesAreAllEnglish: true
useGenerativeAI: false
wordsToIgnore:
- some
- words
- to
- ignore
includeCodedResponses: false
useEnhancedThemeExtractor: false
enhancedThemeExtractor:
maxNumberOfNets: 10
maxNumberOfCodes: 100
codebookBuilderPrompt: null
analyzeByClosedEnd: null
codebookGranularity: null
text/json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyRequest'
example:
questionKeys:
- 100
- 101
- 102
- 103
existingCodebookKey: -1
existingCodebookSuggestNewCodes: false
existingCodebookOptions: null
codebook:
initial:
minProximity: 75
minSegmentsPerCode: 3
approxMaxCodes: 100
mergeSimilar:
enabled: true
minProximity: 85
assignSegmentSiblings:
enabled: true
minProximity: 75
minSiblings: 3
assignTopSegments:
enabled: true
minProximity: 75
topSegments: 10
generativeAIOptions:
dataIsAbout: null
codebookLanguage: en
nonGenerativeAIOptions:
splitCharacters: .!?|
splitWords:
- but
- however
- nevertheless
- nonetheless
- yet
- thus
- also
- additionally
- nor
- and
responsesAreAllEnglish: true
useGenerativeAI: false
wordsToIgnore:
- some
- words
- to
- ignore
includeCodedResponses: false
useEnhancedThemeExtractor: false
enhancedThemeExtractor:
maxNumberOfNets: 10
maxNumberOfCodes: 100
codebookBuilderPrompt: null
analyzeByClosedEnd: null
codebookGranularity: null
application/*+json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyRequest'
example:
questionKeys:
- 100
- 101
- 102
- 103
existingCodebookKey: -1
existingCodebookSuggestNewCodes: false
existingCodebookOptions: null
codebook:
initial:
minProximity: 75
minSegmentsPerCode: 3
approxMaxCodes: 100
mergeSimilar:
enabled: true
minProximity: 85
assignSegmentSiblings:
enabled: true
minProximity: 75
minSiblings: 3
assignTopSegments:
enabled: true
minProximity: 75
topSegments: 10
generativeAIOptions:
dataIsAbout: null
codebookLanguage: en
nonGenerativeAIOptions:
splitCharacters: .!?|
splitWords:
- but
- however
- nevertheless
- nonetheless
- yet
- thus
- also
- additionally
- nor
- and
responsesAreAllEnglish: true
useGenerativeAI: false
wordsToIgnore:
- some
- words
- to
- ignore
includeCodedResponses: false
useEnhancedThemeExtractor: false
enhancedThemeExtractor:
maxNumberOfNets: 10
maxNumberOfCodes: 100
codebookBuilderPrompt: null
analyzeByClosedEnd: null
codebookGranularity: null
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyResponse'
example:
taskStatusKey: 1020309999
errorMessage: null
/AICoder/Analyze/Incremental:
post:
tags:
- AICoder
summary: Initiates a new task for incremental analyzing study.
description: "This method does the same as **/AICoder/Analyze**, but for newly loaded responses only.\r\nOptional `SuggestNewCodes` on the request body matches the AI Coder **Suggest new codes** checkbox when adding a load\r\n(`addNewCodesWhenAddAICoderLoad`); default is `false`."
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyIncrementallyRequest'
example:
key: 19999
suggestNewCodes: false
text/json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyIncrementallyRequest'
example:
key: 19999
suggestNewCodes: false
application/*+json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyIncrementallyRequest'
example:
key: 19999
suggestNewCodes: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyIncrementallyResponse'
example:
taskStatusKey: 1020309999
errorMessage: null
/AICoder/Analyze/{taskStatusKey}:
get:
tags:
- AICoder
summary: Retrieves a status of analyzing (incremental analyzing) study task.
description: "This method expects a task key as an input parameter from the **/AICoder/Analyze** or **/AICoder/Analyze/Incremental**.\r\n\r\nIt returns information about current status of the analyzing task or result."
parameters:
- name: taskStatusKey
in: path
description: The key of the executing task.
required: true
schema:
type: integer
format: int64
example: 1020309999
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCodeStudyStatusOfTaskResponse'
example:
isCompleted: true
project: null
errorMessage: null
/AICoder/Analyze/Codebooks:
get:
tags:
- AICoder
summary: Retrieves a list of available codebooks from AI Coder projects.
description: "This method scans AI Coder projects for non-deleting codebooks and returns list of their defenitions.\r\n\r\nIf value of **id** property ends with \"GAI\" it means that codebook was created by using generative artificial intelligence.\r\n\r\nIf value of **id** property ends with \"AI\" it means that codebook was created by using simple artificial intelligence.\r\n\r\nIf value of **id** property does not include \"GAI\" or \"AI\" in the tail it means that codebook was created without using any kind of artificial intelligence."
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderAnalyzeGetCodebooksResponse'
example:
codebooks:
- key: -1
id: New Codebook
- key: 190001
id: Test Codebook 1
- key: 190002
id: Test Codebook 2 - GAI
- key: 190003
id: Test Codebook 3
errorMessage: null
/AICoder/NetCodes:
post:
tags:
- AICoder
summary: Initiates a new task for grouping codes into target net.
description: "This method re-builds the entire codebook of specified AI Coder project or its part.\r\n\r\nParameter **NetKey** allows specifying a child net as the root of a branch and rebuilding only that part.\r\n \r\nIf **NetKey** is set to **0**, the entire codebook will be processed.\r\n\r\nSetting the **NetLevel** parameter to **0** removes all nets, otherwise this value must be positive and can be less than or greater than the current net level of the codebook."
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderGroupCodesRequest'
example:
aiCoderKey: 1
netKey: 1005
netLevel: 2
text/json:
schema:
$ref: '#/components/schemas/AICoderGroupCodesRequest'
example:
aiCoderKey: 1
netKey: 1005
netLevel: 2
application/*+json:
schema:
$ref: '#/components/schemas/AICoderGroupCodesRequest'
example:
aiCoderKey: 1
netKey: 1005
netLevel: 2
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderGroupCodesResponse'
example:
taskStatusKey: 1020309999
errorMessage: null
/AICoder/NetCodes/{taskStatusKey}:
get:
tags:
- AICoder
summary: Retrieves a status of grouping codes to target net task.
description: "This method expects a task key as an input parameter from the **/AICoder/NetCodes** method.\r\n\r\nIt returns information about current status of the grouping nets task or result."
parameters:
- name: taskStatusKey
in: path
description: The key of the executing task.
required: true
schema:
type: integer
format: int64
example: 1020309999
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderGroupCodesStatusOfTaskResponse'
example:
isCompleted: true
errorMessage: null
/AICoder/Projects:
get:
tags:
- AICoder
summary: Retrieves a list of all AI Coder projects that available to current user.
description: "This method prepares a list of AI Coder project defenitions which available for the current user.\r\n\r\nThe result list includes deleted projects as well."
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderGetProjectsTaskResponse'
example:
aiCoderProjects:
- key: 29999
description: ''
questionKeys:
- 18999
- 20000
- 20001
responsesCount: 100
responsesCodedCount: 200
codesAppliedCount: 200
owner: some.user
createDate: '2026-06-13T20:21:47.08939+00:00'
updateDate: '2026-06-13T20:21:47.0893906+00:00'
deleteDate: null
isPublic: false
errorMessage: null
/AICoder/Links:
post:
tags:
- AICoder
summary: Create new link(s) to an AI Coder project
description: This method generates temporary short link(s) for sharing. The link(s) leads to specified AI Coder project's page.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCreateLinkRequest'
example:
projectKey: 29999
distributionQuestionKey: 39999
expirationDateUtc: '2026-06-13T20:21:47.0923631Z'
text/json:
schema:
$ref: '#/components/schemas/AICoderCreateLinkRequest'
example:
projectKey: 29999
distributionQuestionKey: 39999
expirationDateUtc: '2026-06-13T20:21:47.0923631Z'
application/*+json:
schema:
$ref: '#/components/schemas/AICoderCreateLinkRequest'
example:
projectKey: 29999
distributionQuestionKey: 39999
expirationDateUtc: '2026-06-13T20:21:47.0923631Z'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderCreateLinkResponse'
example:
links:
- distributionQuestionValue: Some value
link: https://goascribe.com/xfjfoejgreo
expirationDateUtc: '2026-06-13T20:21:47.0940103Z'
errorMessage: null
/AICoder/Export/Dichotomous:
post:
tags:
- AICoder
summary: Initiates a new task for exporting of dichotomous report
description: "After the method triggers exporting of dichotomous report task, it returns a unique task key.\r\n\r\nThis key can be used for tracking the status of generating of dichotomous report through the API endpoint: **AICoder/Export/Dichotomous/{taskStatusKey:long}**."
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderDichotomousExportRequest'
example:
projectKey: 29999
removeEmptyColumns: true
useAverageSentimentPerRow: false
text/json:
schema:
$ref: '#/components/schemas/AICoderDichotomousExportRequest'
example:
projectKey: 29999
removeEmptyColumns: true
useAverageSentimentPerRow: false
application/*+json:
schema:
$ref: '#/components/schemas/AICoderDichotomousExportRequest'
example:
projectKey: 29999
removeEmptyColumns: true
useAverageSentimentPerRow: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderDichotomousExportResponse'
example:
taskStatusKey: 1020309999
errorMessage: null
/AICoder/Export/Dichotomous/{taskStatusKey}:
get:
tags:
- AICoder
summary: Retrieves a status of exporting of dichotomous report task.
description: "This method expects a task key as an input parameter from the **/AICoder/Export/Dichotomous** method.\r\n\r\nIt returns information about current status of exporting of dichotomous report task or result.\r\n\r\nIf the task is not yet completed, the method should be called again after a delay.\r\n\r\nContinue calling this method until the task is either completed or rejected due to an error."
parameters:
- name: taskStatusKey
in: path
description: The key of the executing task.
required: true
schema:
type: integer
format: int64
example: 1020309999
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AICoderDichotomousExportGetStatusOfTaskResponse'
example:
isCompleted: true
fileUrl: https://goascribe.com/xfjfoejgreo.xls
errorMessage: null
components:
schemas:
GenerativeAIOptions:
type: object
properties:
dataIsAbout:
type: string
description: String that describing common sense of analyzing data
nullable: true
codebookLanguage:
type: string
description: Language of codes in codebook
nullable: true
additionalProperties: false
description: Generative AI options
CodebookGranularityOption:
enum:
- Low
- Medium
- High
type: string
description: Defines the desired level of granularity (detail) for the automatically generated codebook themes.
format: ''
AICoderDichotomousExportRequest:
required:
- projectKey
type: object
properties:
projectKey:
type: integer
description: Key of target AI Coder project which data should be exported into Excel file
format: int32
removeEmptyColumns:
type: boolean
description: Removes empty columns from the report (i.e. columns that don't have any 1 value in its cells).
useAverageSentimentPerRow:
type: boolean
description: Adds a column with the average sentiment per row.
additionalProperties: false
description: Contains request data of the exporting to dichotomous report file task
AICoderProjectAPI:
required:
- owner
- questionKeys
type: object
properties:
key:
type: integer
description: Key of AI Coder project
format: int32
description:
type: string
description: Description of AI Coder project
nullable: true
questionKeys:
type: array
items:
type: integer
format: int32
description: Keys
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/voxco/refs/heads/main/openapi/voxco-aicoder-api-openapi.yml