Skip to content
Knowledge Base

REST API

Askalot provides a REST API for programmatic access to all platform capabilities. The API enables you to automate survey workflows, integrate with external systems, and build custom applications on top of the Askalot platform.

https://portor.<tenant>.askalot.io/api/v1

Replace <tenant> with your organization’s tenant name (e.g., portor.acme.askalot.io).

All API requests require authentication using a personal API token.

Generating a Token:

  1. Log in to https://roundtable.<tenant>.askalot.io
  2. Navigate to Profile Settings
  3. Scroll to “API Tokens” section
  4. Click “Generate New Token”
  5. Copy the token (shown only once)

Using Your Token:

Include your token in the X-Api-Token header:

Terminal window
curl -H "X-Api-Token: your_token_here" \
https://portor.<tenant>.askalot.io/api/v1/projects

Token Properties:

  • Format: tokens are aslat_-prefixed (aslat_<32 characters>); the prefix lets secret scanners flag an accidental commit. Only the prefix is stored server-side for identification — the full token is shown once at creation and never again.
  • Header: send it in the X-Api-Token header. This is the REST credential path; the Authorization: Bearer header on Portor is reserved for OAuth access tokens (the ones an MCP session carries, which REST also accepts), not API tokens.
  • Scope: authenticates the REST API only and is not accepted by the MCP interface. A token belongs to the organization you were working in when you generated it: every request it makes acts in that organization, with the roles you hold there — a role you hold in another organization does not apply. To work in another organization over REST, switch to it in the browser and generate a token there. If an administrator removes you from that organization, its tokens are revoked with the membership.
  • Revocation: revoke at any time from Profile Settings; revocation takes effect immediately.

You choose an expiry when creating a token — the Profile Settings dropdown offers 30 days, 90 days (the default), or 1 year. An expiry is required; there is no “never-expiring” option for new tokens (only older, grandfathered tokens may lack one).

  • Profile Settings shows each token’s expiry date and days remaining, and flags a token for rotation once it is within 14 days of expiring.
  • To rotate: create a replacement token, update your integration to use it, then revoke the old one. Tokens do not auto-renew — an expired token returns 401 and must be replaced.

Explore the API interactively using Swagger UI at:

https://portor.<tenant>.askalot.io/api/v1/docs

The interactive documentation lets you:

  • Browse all available endpoints
  • View request/response schemas
  • Test API calls directly in your browser

Projects are top-level containers for organizing your survey research.

Method Endpoint Description
GET /api/v1/projects List all projects
POST /api/v1/projects Create a new project
GET /api/v1/projects/{id} Get project by ID
PUT /api/v1/projects/{id} Update a project
DELETE /api/v1/projects/{id} Delete a project
POST /api/v1/projects/{id}/owners Add project owners
DELETE /api/v1/projects/{id}/owners Remove project owners

Example: Create a Project

Terminal window
curl -X POST https://portor.<tenant>.askalot.io/api/v1/projects \
-H "X-Api-Token: your_token" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Satisfaction Study",
"description": "Q1 2026 customer feedback survey"
}'

Response:

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "Customer Satisfaction Study",
"description": "Q1 2026 customer feedback survey",
"created_at": "2026-01-02T10:30:00Z",
"questionnaire_ids": [],
"campaign_ids": []
}

Questionnaires define survey structure using QML (Questionnaire Markup Language).

Method Endpoint Description
GET /api/v1/questionnaires List all questionnaires
POST /api/v1/questionnaires Create a new questionnaire
GET /api/v1/questionnaires/{id} Get questionnaire by ID
PUT /api/v1/questionnaires/{id} Update a questionnaire
DELETE /api/v1/questionnaires/{id} Delete a questionnaire
GET /api/v1/questionnaires/{id}/versions/{version_id}/translations List a version’s translations, per language (complete, untranslated keys, frozen, human-edited)
GET /api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} Get one language’s translation with its source texts
PUT /api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} Save translated text (texts, base_updated_at); partial, merged over what is stored
DELETE /api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} Delete one language’s translation (refused once frozen)

Query Parameters:

  • project_id - Filter by project
  • status - Filter by status (draft, active, paused, completed)

Campaigns link questionnaires to respondents for data collection.

Method Endpoint Description
GET /api/v1/campaigns List all campaigns
POST /api/v1/campaigns Create a new campaign
GET /api/v1/campaigns/{id} Get campaign by ID
PUT /api/v1/campaigns/{id} Update a campaign
DELETE /api/v1/campaigns/{id} Delete a campaign
PUT /api/v1/campaigns/{id}/pool Assign a respondent pool to the campaign
GET /api/v1/campaigns/{id}/pool Get the campaign’s assigned pool
PUT /api/v1/campaigns/{id}/questionnaire Change the campaign’s questionnaire
POST /api/v1/campaigns/{id}/interviewers Add interviewers to the campaign
DELETE /api/v1/campaigns/{id}/interviewers Remove interviewers from the campaign

Query Parameters:

  • project_id - Filter by project
  • questionnaire_id - Filter by questionnaire
  • status - Filter by status
  • expand=true - Include related objects (project, questionnaire, respondents)

Creating a campaign: POST /api/v1/campaigns requires name, project_id, questionnaire_id and offers_ai_channel. offers_ai_channel (boolean) states whether respondents may also take the survey in their own AI assistant. It has no default, and a request without it is refused. When it is true, intro_text and consent_text are required as well. See AI-Assisted Self-Interview.

Campaign Modes:

Askalot supports two campaign modes:

  • Direct Mode: Respondents complete surveys independently via unique links
  • Interviewer-Assisted Mode: Interviewers administer surveys to respondents by phone or in person

The mode is determined automatically based on whether interviewers are assigned to the campaign.

Each survey also records its own mode (direct, ai_assisted or field_interview) in its mode field. A survey is ai_assisted when the campaign offers the AI assistant and the respondent consented there before answering.

Respondents are the survey targets—the people being surveyed.

Method Endpoint Description
GET /api/v1/respondents List all respondents
POST /api/v1/respondents Create a new respondent
GET /api/v1/respondents/{id} Get respondent by ID
PUT /api/v1/respondents/{id} Update a respondent
DELETE /api/v1/respondents/{id} Delete a respondent

Query Parameters:

  • source_system - Filter by source (e.g., crm, panel_provider)
  • campaign_id - Filter by campaign

Note: Interviewers are Users with the interviewer role. They are managed through the /api/v1/users endpoint.

Example: Import a Respondent

Terminal window
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondents \
-H "X-Api-Token: your_token" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"email": "[email protected]",
"age": 35,
"gender": "female",
"location": "New York",
"external_id": "CRM-12345",
"source_system": "salesforce",
"custom_attributes": {"state": "NY", "zip_code": "10001"}
}'

Demographics Fields:

Respondents support demographic data for targeting and analysis:

  • age - Respondent age
  • gender - Gender identity
  • location - Geographic location (free text, typically "City, Country")
  • external_id - Your system’s identifier
  • source_system - Source of the respondent data
  • preferred_language - Optional preferred language (en, es, fr, de, hu), used for the invitation and the survey’s preselected language when the campaign offers it

Geography finer than location — street, city, state, postal code, country as separate values — goes in custom_attributes, and is addressable as custom_attributes.<key> wherever a respondent attribute can be named (sampling factors, external-input mappings). A calibration target names the dataset column the attribute was extracted into, _custom_<key>. Extra top-level keys are ignored rather than stored, so a CRM export that sends city as its own field loses that value silently.

Surveys track individual survey sessions and responses.

Method Endpoint Description
GET /api/v1/surveys List all surveys
POST /api/v1/surveys Create a new survey session
GET /api/v1/surveys/{id} Get survey by ID
PUT /api/v1/surveys/{id} Update survey status
DELETE /api/v1/surveys/{id} Delete a survey
GET /api/v1/surveys/{id}/current-step Current question + options + status (Survey Presentation Format)
POST /api/v1/surveys/{id}/responses Submit an answer; the next step is folded into the response
POST /api/v1/surveys/{id}/finish Explicitly complete the survey (idempotent)

Query Parameters:

  • questionnaire_id - Filter by questionnaire
  • campaign_id - Filter by campaign
  • respondent_id - Filter by respondent
  • status - Filter by status (pending, in_progress, completed)
  • expand=true - Include related objects

Survey responses carry status plus a derived, read-only completed boolean (true exactly when status is completed). Completion is expressed by updating status — there is no completed input or filter parameter.

Answering a survey through POST /api/v1/surveys/{id}/responses is limited to testing and simulation: a survey that has had an invitation sent is refused, so a live fielded interview cannot be written to programmatically. Answers submitted this way are recorded as machine-produced and their response times are excluded from speeder detection.

Respondent pools organize respondents into reusable groups for campaigns.

Method Endpoint Description
GET /api/v1/respondent-pools List all respondent pools
POST /api/v1/respondent-pools Create a new pool
GET /api/v1/respondent-pools/{id} Get pool by ID
DELETE /api/v1/respondent-pools/{id} Delete a pool
POST /api/v1/respondent-pools/{id}/respondents Add respondents to pool
DELETE /api/v1/respondent-pools/{id}/respondents Remove respondents from pool
POST /api/v1/respondent-pools/generate Draw a pool from a sampling strategy (requested_size required); the pool stores its draw settings
POST /api/v1/respondent-pools/preview Preview a draw without creating a pool
POST /api/v1/respondent-pools/{id}/refresh Redraw a strategy pool with its own stored draw settings

Query Parameters:

  • project_id - Filter by project

Sampling strategies define target demographic distributions for creating representative samples, and how fit to them is graded. A strategy carries no size or selection settings: those are inputs to POST /api/v1/respondent-pools/generate and are stored on the pool it creates.

Method Endpoint Description
GET /api/v1/sampling-strategies List all strategies
POST /api/v1/sampling-strategies Create a new strategy
GET /api/v1/sampling-strategies/{id} Get strategy by ID
PUT /api/v1/sampling-strategies/{id} Update a strategy
DELETE /api/v1/sampling-strategies/{id} Delete a strategy

Query Parameters:

  • project_id - Filter by project

Example: Create a Sampling Strategy

Terminal window
curl -X POST https://portor.<tenant>.askalot.io/api/v1/sampling-strategies \
-H "X-Api-Token: your_token" \
-H "Content-Type: application/json" \
-d '{
"name": "Representative Sample",
"project_id": "550e8400-e29b-41d4-a716-446655440000",
"factors": [
{
"name": "Gender",
"attribute_path": "gender",
"target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02}
},
{
"name": "Age Group",
"attribute_path": "age",
"factor_type": "bucketed",
"target_distribution": {"18-34": 0.35, "35-54": 0.40, "55+": 0.25}
}
]
}'

Example: Draw a Pool from the Strategy

Terminal window
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondent-pools/generate \
-H "X-Api-Token: your_token" \
-H "Content-Type: application/json" \
-d '{
"strategy_id": "<strategy id>",
"pool_name": "Pilot wave",
"requested_size": 100,
"oversample_factor": 1.2
}'

requested_size is required; oversample_factor (default 1.0), selection_algorithm (greedy or random_constrained, default greedy), require_email (default false) and exclude_respondent_ids (default none) are optional. Draw a second pool from the same strategy at a different size whenever you need one.

A Bundle binds one Project → one Questionnaire → a selected Campaign subset to a single linear Bronze → Silver → Gold dataset chain — the unit the Balansor pipeline board organizes around.

Method Endpoint Description
GET /api/v1/bundles List all bundles
POST /api/v1/bundles Create a new bundle
GET /api/v1/bundles/{id} Bundle detail, including its stage recipes (Silver Calibration Targets, Gold operations)
DELETE /api/v1/bundles/{id} Delete a bundle (and its dataset chain)
POST /api/v1/bundles/{id}/clone Clone a bundle — deep copy: ready datasets and stage recipes carry over
GET /api/v1/bundles/{id}/quality The bundle’s Representativeness story (selection, fielded, weighted, fielding shift, response)
GET /api/v1/bundles/{id}/comparison Bronze-vs-Silver comparison (409 conflict until both stages are ready)
GET /api/v1/bundles/{id}/coding Open-end coding state — the coding candidates the Bronze offers, the analyst’s question selection, and per question the proposed dimensions with their categories and selection state (deciding which dimensions become columns stays in the Balansor UI)
PUT /api/v1/bundles/{id}/coding/selection Set which open-text units this bundle codes — full replacement set of unit keys (manager role, identified user required)
POST /api/v1/bundles/{id}/strategy Assign or clear the bundle’s current sampling strategy (manager role, identified user required)
PUT /api/v1/bundles/{id}/targets Edit the bundle’s Calibration Targets — the Silver weighting spec, each target raked or benchmark (manager role, identified user required)
GET /api/v1/bundles/{id}/targets/copy-preview?source_bundle_id={source} Preview copying another bundle’s Calibration Targets into this one: addable and rejected with reasons; writes nothing (manager role)

Query Parameters:

  • project_id - Filter by project

Stage operations (extraction, coding + weighting, refinement, export) are driven through the MCP Bundle/Dataset tools — see mcp-bundle-tools.md and mcp-dataset-tools.md for the full quality and stage parameter reference.

All successful responses return JSON with standard HTTP status codes:

Status Meaning
200 OK Request succeeded (including resource creation — the created object is returned in the body)
204 No Content Resource deleted successfully

Errors use a single envelope: a machine-readable error code plus a human-readable detail:

{
"error": "not_found",
"detail": "bundle 'abc123' not found"
}
Status error code Meaning
401 unauthenticated Missing, invalid, or expired credentials
403 forbidden You lack the capability, or you don’t own the target resource
404 not_found The resource does not exist (or is not visible to you)
409 conflict Valid request, but the resource isn’t ready yet (e.g. comparing a bundle whose chain is still processing) — retry after the pipeline finishes
422 validation_error Malformed input; detail carries a list of field-level issues

The complete API specification is available in OpenAPI 3.0 format:

GET /api/v1/openapi.json

Use this specification to generate typed API clients in your preferred programming language.

Terminal window
# 1. Create a project
PROJECT_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/v1/projects \
-H "X-Api-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Q1 Survey"}' | jq -r '.id')
# 2. Create a questionnaire (the QML itself is the payload — there is no file to stage)
QUESTIONNAIRE_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/v1/questionnaires \
-H "X-Api-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg p "$PROJECT_ID" --rawfile c feedback.qml \
'{name: "Customer Feedback", project_id: $p, content: $c}')" | jq -r '.id')
# 3. Create a campaign
curl -X POST https://portor.<tenant>.askalot.io/api/v1/campaigns \
-H "X-Api-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d "{\"name\": \"Q1 Campaign\", \"project_id\": \"$PROJECT_ID\", \"questionnaire_id\": \"$QUESTIONNAIRE_ID\", \"offers_ai_channel\": false}"
Terminal window
# Import respondents from a CSV or your CRM system
for respondent in "${RESPONDENTS[@]}"; do
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondents \
-H "X-Api-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d "$respondent"
done